Skip to main content

01 — System architecture

System overview

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:

ComponentRoleIsolation mechanism
Zitadel (+ login v2 UI)OIDC provider, user directory, org-level IdP federationOrganizations, project grants
Control plane API + workersTenant registry, provisioning, token broker, webhook router, admin APIRow-level tenant_id, per-request tenant verification
Admin consoleOperators and tenant admins UIAuthZ in every server function
InfisicalSecrets for tenant stacks and the platformFolder path per tenant, one machine identity per tenant stack
LiveKit SFU + EgressWebRTC media and recording/compositingRoom-name namespace + room-scoped tokens (enforced by broker)
RustFSS3 storage for recordings, transcripts, later filesBucket + scoped key per tenant
Core Postgres / RedisZitadel, control plane, Infisical, Pulumi state; LiveKit routingSeparate DB/role per product (see AGENTS.md conventions)
CoolifyDocker orchestration + Traefik proxyn/a — operator-only API token

Tenant plane — one Coolify project per tenant, plus tenant-data-pool Postgres shards:

ComponentRole
go-meetMeet 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
TuwunelMatrix homeserver for chat, RocksDB on a tenant volume
(future) Stalwart, Bulwark, Euro-OfficeMail, 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​

PathRoute
Browser → appCloudflare DNS → frp → Traefik → tenant go-meet / Tuwunel
LoginBrowser → Zitadel login v2 → (optional customer IdP) → go-meet OIDC callback
Call mediaBrowser ⇄ LiveKit UDP 7882 / TCP 7881, bypassing Traefik
Call signalingBrowser → Traefik → LiveKit :7880 (WSS)
RecordingLiveKit Egress → RustFS (direct S3 multipart)
AdminOperator → admin console → control plane API
Tenant stack ↔ shared servicesInternal Docker network office-suite-net (see 09)

Trust boundaries​

  1. Internet ↔ edge — Traefik terminates TLS; only HTTP(S) and the two LiveKit media ports are exposed.
  2. 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.
  3. Tenant ↔ tenant — no network path between tenant networks other than via shared services that authorize per tenant.
  4. 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).