Fortspace is a B2B SaaS "company hub" for European SMBs: chat, calls, mail,
storage, and later an office suite, sold on data sovereignty (EU residency,
per-tenant isolation, instant erasure). It is assembled from open-source
components behind one identity provider and one control plane.
This folder is the architecture baseline. It consolidates the exploration in
discussions/ (in the main repo), the go-meet prototype, and the draft
deployment/ stacks, and applies four decisions made after those discussions:
| # | Decision | Replaces |
|---|
| D1 | The control plane is TypeScript (Node) | Go control plane in the discussions |
| D2 | Infisical is shared, tenants separated by path + machine identity | Infisical per tenant (too heavy) |
| D3 | Zitadel, one multi-tenant instance, one organization per tenant | Keycloak |
| D4 | One isolated Coolify project per tenant + a shared core-infra project | (confirmed from discussions) |
Reading order
| Doc | Covers | Diagram(s) |
|---|
| 01 System architecture | Components, planes, status, request paths | 01-system-overview |
| 02 Tenancy & isolation | What is shared vs per tenant, and why | 02-tenancy-isolation |
| 03 Identity & access | Zitadel model, login flow, claims, authorization | 03-identity-flow |
| 04 Control plane | TS modules, data model, APIs, jobs, reconciliation | 04-control-plane |
| 05 Tenant lifecycle | Provisioning saga, offboarding, shards | 05-tenant-provisioning |
| 06 Calls (go-meet + LiveKit) | Token broker, webhooks, recording pipeline | 06-call-flow, 07-recording-pipeline |
| 07 Chat & integration | Matrix/Tuwunel, call↔chat coupling | 08-chat-meet-integration |
| 08 Data, storage & secrets | Postgres sharding, RustFS, Infisical, keys | 09-data-secrets-keys |
| 09 Infrastructure | Coolify, frp, Traefik, Pulumi, networking | 10-infrastructure-topology |
| 10 Security & operations | Threat model, GDPR, backup, observability | — |
| 11 Decisions & open questions | ADRs, corrections to the discussions, unknowns | — |
Diagrams are Excalidraw sources in diagrams/ (.excalidraw,
open at excalidraw.com or in the editor extension) with rendered .png
alongside. Edit the source, re-render, commit both.
Design principles
- Isolate the data layer hard, share the stateless layer. Chat history,
meeting metadata, recordings and caches live in per-tenant resources.
Identity, media routing and orchestration are shared and hold no tenant
content.
- Authorization is enforced by the owner of the data, not inferred from
names. LiveKit tokens, S3 credentials and DB roles are minted per tenant
and scoped as tightly as each system allows.
- Everything is idempotent and reconcilable. Provisioning is a resumable
saga; drift is detected by a loop, not by hope.
- The orchestrator is replaceable. Coolify specifics stay behind an
adapter; the tenant record stores generic references only.
- Short-lived credentials over long-lived ones. LiveKit tokens, presigned
URLs and machine-identity tokens expire in minutes to hours.
- Env vars over hardcoded values; secrets never in git or in Postgres in
the clear.
- Sovereignty is a feature. Component choices favor EU-hostable,
open-source software (Apache-2.0 / AGPL-aware).
Glossary
| Term | Meaning |
|---|
| Tenant | One customer company. Maps to one Zitadel org, one Coolify project, one bucket, one DB, one Infisical path. |
| Slug | Immutable DNS-safe tenant identifier (^[a-z][a-z0-9-]{1,30}$), used in hostnames, room-name prefixes, bucket names. |
| Shared plane | core-infra Coolify project: Zitadel, control plane, Infisical, LiveKit, RustFS, core Postgres/Redis. |
| Tenant plane | Per-tenant Coolify projects plus the tenant-data-pool of Postgres shards. |
| Control plane (CP) | TypeScript service owning tenant state, provisioning, the LiveKit token broker and the webhook router. |
| Token broker | CP module that signs LiveKit tokens scoped to an exact room for a verified tenant. |
| Shard | A Postgres node (+ PgBouncer) hosting several tenant databases. |
| Saga | The ordered, compensatable provisioning workflow. |
| Module | An optional product in a tenant stack (meet, chat, mail, …). |
Component status (2026-11)
| Component | State | Notes |
|---|
| go-meet | prototype, source-level complete for most Meet API | staging acceptance pending; callbacks/files partly stubbed |
| LiveKit + Egress | deployed (single node, behind frp) | egress still uses a global S3 credential in compose.livekit.yaml |
| PostgreSQL / Redis | deployed (shared) | will split into core vs tenant pool |
| Zitadel | compose draft (compose.zitadel.yaml, v4.16) | replaces Keycloak draft |
| Keycloak | compose draft | deprecated, kept for reference until Zitadel is live |
| Control plane, admin console | not started | this design |
| Infisical, RustFS | planned/partial | RustFS used as S3 target in drafts |
| Tuwunel (Matrix) | planned | see 07 and ADR-002 |
| Stalwart, Bulwark, Euro-Office, files | future | extension points only |