01 — System architecture

Two planes
Shared platform plane — Coolify project core-infra. Runs software that is
either stateless with respect to tenant content or holds only orchestration
and key material:
| Component | Role | Isolation mechanism |
|---|---|---|
| Zitadel (+ login v2 UI) | OIDC provider, user directory, org-level IdP federation | Organizations, project grants |
| Control plane API + workers | Tenant registry, provisioning, token broker, webhook router, admin API | Row-level tenant_id, per-request tenant verification |
| Admin console | Operators and tenant admins UI | AuthZ in every server function |
| Infisical | Secrets for tenant stacks and the platform | Folder path per tenant, one machine identity per tenant stack |
| LiveKit SFU + Egress | WebRTC media and recording/compositing | Room-name namespace + room-scoped tokens (enforced by broker) |
| RustFS | S3 storage for recordings, transcripts, later files | Bucket + scoped key per tenant |
| Core Postgres / Redis | Zitadel, control plane, Infisical, Pulumi state; LiveKit routing | Separate DB/role per product (see AGENTS.md conventions) |
| Coolify | Docker orchestration + Traefik proxy | n/a — operator-only API token |
Tenant plane — one Coolify project per tenant, plus tenant-data-pool
Postgres shards:
| Component | Role |
|---|---|
| go-meet | Meet control plane: rooms, lobby, teams, recordings, files metadata. OIDC resource server and session owner for the browser app |
| Redis (per tenant) | go-meet sessions, lobby cache, creation callbacks, throttling |
| Tuwunel | Matrix homeserver for chat, RocksDB on a tenant volume |
| (future) Stalwart, Bulwark, Euro-Office | Mail, webmail, documents |
Why this split
The discussions converged on a rule: share what is stateless or merely routes; isolate what stores tenant content. Concretely:
- Auditors ask where PII and business communications live. Chat history, meeting records and recordings are therefore per-tenant: process (go-meet, Tuwunel), cache (Redis), database (DB per tenant) and object storage (bucket per tenant).
- A shared LiveKit cluster is acceptable because it is a media router that keeps no durable content, as long as nothing tenant-side can act on another tenant's rooms (see 06).
- A shared Zitadel is acceptable because auth is token-based and orgs give a logical boundary; a dedicated instance is reserved for Tier-1 customers demanding customer-managed keys or network isolation.
Request paths
| Path | Route |
|---|---|
| Browser → app | Cloudflare DNS → frp → Traefik → tenant go-meet / Tuwunel |
| Login | Browser → Zitadel login v2 → (optional customer IdP) → go-meet OIDC callback |
| Call media | Browser ⇄ LiveKit UDP 7882 / TCP 7881, bypassing Traefik |
| Call signaling | Browser → Traefik → LiveKit :7880 (WSS) |
| Recording | LiveKit Egress → RustFS (direct S3 multipart) |
| Admin | Operator → admin console → control plane API |
| Tenant stack ↔ shared services | Internal Docker network office-suite-net (see 09) |
Trust boundaries
- Internet ↔ edge — Traefik terminates TLS; only HTTP(S) and the two LiveKit media ports are exposed.
- Tenant stack ↔ shared plane — tenant stacks authenticate to the control plane with a Zitadel service-account JWT carrying the tenant org id; they never hold LiveKit's API secret or RustFS root credentials.
- Tenant ↔ tenant — no network path between tenant networks other than via shared services that authorize per tenant.
- Operator plane — Coolify API token, Pulumi state and Infisical root are reachable only from the control plane workers.
Extension points (future modules)
A module is a Compose fragment + a DB (or none) + a Zitadel application + an Infisical sub-path + optional bucket. Adding mail or documents means adding a module definition to the control plane's catalog and a template to the stack program; no shared-plane change is required except LiveKit-independent services (Stalwart needs public SMTP ports and MX records — see 09).