Skip to main content

Fortspace — Architecture

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:

#DecisionReplaces
D1The control plane is TypeScript (Node)Go control plane in the discussions
D2Infisical is shared, tenants separated by path + machine identityInfisical per tenant (too heavy)
D3Zitadel, one multi-tenant instance, one organization per tenantKeycloak
D4One isolated Coolify project per tenant + a shared core-infra project(confirmed from discussions)

Reading order​

DocCoversDiagram(s)
01 System architectureComponents, planes, status, request paths01-system-overview
02 Tenancy & isolationWhat is shared vs per tenant, and why02-tenancy-isolation
03 Identity & accessZitadel model, login flow, claims, authorization03-identity-flow
04 Control planeTS modules, data model, APIs, jobs, reconciliation04-control-plane
05 Tenant lifecycleProvisioning saga, offboarding, shards05-tenant-provisioning
06 Calls (go-meet + LiveKit)Token broker, webhooks, recording pipeline06-call-flow, 07-recording-pipeline
07 Chat & integrationMatrix/Tuwunel, call↔chat coupling08-chat-meet-integration
08 Data, storage & secretsPostgres sharding, RustFS, Infisical, keys09-data-secrets-keys
09 InfrastructureCoolify, frp, Traefik, Pulumi, networking10-infrastructure-topology
10 Security & operationsThreat model, GDPR, backup, observability—
11 Decisions & open questionsADRs, 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​

  1. 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.
  2. 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.
  3. Everything is idempotent and reconcilable. Provisioning is a resumable saga; drift is detected by a loop, not by hope.
  4. The orchestrator is replaceable. Coolify specifics stay behind an adapter; the tenant record stores generic references only.
  5. Short-lived credentials over long-lived ones. LiveKit tokens, presigned URLs and machine-identity tokens expire in minutes to hours.
  6. Env vars over hardcoded values; secrets never in git or in Postgres in the clear.
  7. Sovereignty is a feature. Component choices favor EU-hostable, open-source software (Apache-2.0 / AGPL-aware).

Glossary​

TermMeaning
TenantOne customer company. Maps to one Zitadel org, one Coolify project, one bucket, one DB, one Infisical path.
SlugImmutable DNS-safe tenant identifier (^[a-z][a-z0-9-]{1,30}$), used in hostnames, room-name prefixes, bucket names.
Shared planecore-infra Coolify project: Zitadel, control plane, Infisical, LiveKit, RustFS, core Postgres/Redis.
Tenant planePer-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 brokerCP module that signs LiveKit tokens scoped to an exact room for a verified tenant.
ShardA Postgres node (+ PgBouncer) hosting several tenant databases.
SagaThe ordered, compensatable provisioning workflow.
ModuleAn optional product in a tenant stack (meet, chat, mail, …).

Component status (2026-11)​

ComponentStateNotes
go-meetprototype, source-level complete for most Meet APIstaging acceptance pending; callbacks/files partly stubbed
LiveKit + Egressdeployed (single node, behind frp)egress still uses a global S3 credential in compose.livekit.yaml
PostgreSQL / Redisdeployed (shared)will split into core vs tenant pool
Zitadelcompose draft (compose.zitadel.yaml, v4.16)replaces Keycloak draft
Keycloakcompose draftdeprecated, kept for reference until Zitadel is live
Control plane, admin consolenot startedthis design
Infisical, RustFSplanned/partialRustFS used as S3 target in drafts
Tuwunel (Matrix)plannedsee 07 and ADR-002
Stalwart, Bulwark, Euro-Office, filesfutureextension points only