# Architecture

Samsar is organized as a deployable Docker mono-repo. The top-level `samsar` package is the wrapper that syncs source projects into `apps/*` and `services/*`, renders runtime configuration, and starts the Compose stack.

Start with [hosted Samsar.js](https://docs.samsar.one/) if you want managed workflows. This page describes the standalone architecture used when you deploy those workflows yourself. Follow the [model matrix](model-matrix.md) into [provider configuration](providers-and-models.md) to choose compatible adapters. The client API contract remains documented at [docs.samsar.one](https://docs.samsar.one/v2).

## Runtime Shape

![Docker Deployment Architecture](../assets/docker-deployment-architecture.png)

The default Docker deployment keeps the Studio client, processor API, workers, local infrastructure, and optional logging inside the Compose runtime. The client UI calls the processor over REST; the processor and workers consume the rendered runtime config, persist state through MongoDB, write media through the configured object storage adapter, and call only the external providers enabled by the user.

## Compose Profiles

| Profile | Services | Role |
| --- | --- | --- |
| `core` | `client`, `processor` | Browser app and API. |
| `workers` | `generator`, `audio-generator`, `frames-processor`, `video-generator`, `ai-video-layer-generator`, `express-video-listener`, `assistant-query-processor`, `task-processor` | Async media and assistant work. |
| `local-mongo` | `mongo` | Local MongoDB for users, sessions, requests, credits, embeddings, and status records. |
| `minio` | `minio` | Local S3-compatible media bucket. |
| `local-media` | `media-gateway` | Nginx gateway for `/assets` and `/assets_v2`. |
| `logger` | `loki`, `promtail`, `grafana` | Local container log collection and dashboarding. |
| `reverse-proxy` | `reverse-proxy` | Optional public or intranet nginx entrypoint for Studio and the processor API on ports `80` and `443`. |

## Request Flow

1. Studio or an API client calls the processor API on `http://localhost:3002`.
2. The processor validates auth, credits, request shape, and model availability.
3. The processor writes session/request state to MongoDB and stores media in MinIO or the configured external S3-compatible store.
4. Workers pick up queued work through MongoDB-backed state and provider-specific task records.
5. Media outputs are written to Docker volumes and served to browsers through the configured processor API (`http://localhost:3002` by default), or through its optional reverse proxy URL. The internal `media-gateway` is used only as the origin for provider tunnels.
6. Clients poll status endpoints or receive webhook callbacks when provided by the request.

## Runtime Config

The primary runtime file is `runtime/config/samsar.config.json`. It is copied from `samsar.config.example.json` for local setup and edited manually or through the setup wizard.

`npm run config:render` generates:

| File | Purpose |
| --- | --- |
| `runtime/secrets/root.env` | Env file consumed by Docker services. Contains provider keys, DB/storage settings, public URLs, mail settings, and generated setup values. |
| `runtime/secrets/application.env` | Durable generated application signing and custom-adapter encryption secrets. |
| `runtime/secrets/mongo.env` | Durable generated local MongoDB root and application credentials. |
| `runtime/secrets/minio.env` | Durable generated local MinIO administrator credentials. |
| `runtime/secrets/grafana.env` | Durable generated Grafana administrator credentials. |
| `runtime/config/available-models.json` | Provider/model/action availability derived from enabled providers. Used by the API to filter public model responses. |

The `runtime/` directory is gitignored because it contains local credentials and generated deployment state.

## Storage and Media

Local Docker defaults to:

| Setting | Default |
| --- | --- |
| Database | Authenticated MongoDB at `mongo:27017`, using generated application credentials and `authSource=admin` |
| Object storage | MinIO at `http://minio:9000` |
| Bucket | `samsar-resources` |
| Browser media base | `http://localhost:3002/` |
| Secure asset prefix | `assets_v2` |

Completed local render URLs normally look like:

```text
http://localhost:3002/assets_v2/video/output/<session-id>/<file>.mp4
```

External S3-compatible storage can be selected in the setup wizard or configured directly in `runtime/config/samsar.config.json`. When external media publishing is enabled, provider-visible URLs come from `storage.staticCdnUrl`.

The Docker reverse proxy controls browser-facing Studio and processor/media URLs. Public/private IP installs use one machine IP: Studio is served at `http://<ip>` and the processor/media base is `http://<ip>/api`. External adapter requests use the separately managed media tunnel whenever external S3/CloudFront publishing is disabled.

## Provider Calls

Provider credentials are loaded from `root.env`. In standalone Docker, inference uses each model’s compatible provider chain and saved model-adapter preferences. Native inference can take precedence, with Samsar.js and optional mapped providers available according to the model registry. Qwen is the exception in hosted deployments: `production`, `external-production`, `staging`, and other non-Docker runtimes always route `QWEN3.8` through `OPENROUTER_API_KEY`, regardless of saved provider provenance or an available Alibaba credential. Native Alibaba Qwen is allowed only when `CURRENT_ENV=docker`; `SAMSAR_QWEN_OPENROUTER_ONLY=true` can force the hosted rule in Docker.

The processor, generator, audio generator, AI video layer generator, express video listener, and assistant query processor use the same inference-adapter policy. OpenRouter Qwen text and vision requests map to `qwen/qwen3.8-max`; native Alibaba text and vision use `qwen3.8-max`. In Docker, a validated Alibaba Token Plan endpoint sets the shared `ALIBABA_QWEN_MODEL=qwen3.8-max` override. `ALIBABA_QWEN_TEXT_MODEL` is emitted with the same value only for rolling-container compatibility.

## Assistant Billing and Recovery

Session assistant APIs, public chat/assistant APIs, and hosted queued assistant requests use the [final token prices](assistant-billing.md#final-token-prices) for the listed model and adapter routes. Production agent pipeline inference keeps its flat stage pricing. The standalone Studio assistant worker retains its local-credit waiver; hosted API calls made through a Samsar adapter still incur the hosted endpoint charge.

Reuse the same request key when retrying. Completed replays return the original response and charge without another debit. Requests awaiting billing confirmation or completion after a timeout can remain pending; continue checking the existing request. See [Assistant billing and retries](assistant-billing.md) for the client contract and verification commands.

## Observability

The logger profile starts Loki, Promtail, and Grafana. Grafana is available only on loopback at `http://localhost:4000` by default and requires the generated administrator credentials from `runtime/secrets/grafana.env`.

Useful log command:

```bash
docker compose -f deploy/compose/docker-compose.yml logs -f processor express-video-listener video-generator
```

## Deployment Modes

| Mode | When to use | Notes |
| --- | --- | --- |
| Docker Compose | Default local install and demos | Uses local Mongo, MinIO, media gateway, and local logs unless configured otherwise. |
| Bare-metal local | Service-level development | Source Node services run on the host; Mongo/MinIO/media gateway can still run in Docker. |
| Kubernetes | Cluster deployment planning | Helm chart scaffold lives under `deploy/helm/samsar`; production templates, probes, ingress, PVCs, ConfigMaps, and Secrets still need to be added before real use. |