Skip to main content

02 — Tenancy and isolation

Tenancy isolation map

Model​

Tenant (company)
├─ Zitadel organization (identity boundary, logical)
├─ Coolify project tenant-<slug> (runtime boundary, process/network)
├─ Database meet_<slug> on shard N (data boundary, hard DB)
├─ Bucket tenant-<slug> (object boundary, scoped key + SSE)
├─ Infisical path /tenants/<slug> (secret boundary, machine identity)
└─ LiveKit room namespace <slug>__* (media boundary, enforced by broker)
Teams → Zitadel project roles / groups → claims → go-meet `team_ids`
Users → belong to exactly one Zitadel org (the tenant); guests have no account

Teams are inside a tenant and are authorization data (roles/claims), never an isolation boundary.

Shared vs per-tenant matrix​

ComponentScopeBoundaryWhy
ZitadelsharedOrganization + project grantAuth is token-based; orgs isolate users, IdPs, branding, policies
Control plane + admin consolesharedtenant_id in every row; verified caller identityOwns lifecycle; must see all tenants
Infisicalshared (D2)Path /tenants/<slug> + per-tenant machine identityA per-tenant Infisical is too heavy
LiveKit SFU/Egress + its RedissharedExact-room tokens minted by broker, <slug>__ room prefixStateless media router
RustFS enginesharedBucket per tenant, scoped access key, SSECentral disk pools
Core PostgressharedDB/role per productLow-volume platform data
Postgres shardsshared engine, DB per tenantDatabase + roleCost vs hard boundary; drop-database erase
go-meetper tenantContainer + env + networkMemory/log/bug isolation, ~20 MB RSS
Redis (go-meet)per tenantContainer + volumeNo shared-key bugs, trivially erased
Tuwunel (Matrix)per tenantContainer + RocksDB volume, federation offAvoid logical multi-tenant chat bugs
Future modulesper tenantSame pattern—

Isolation tiers​

TierWhoDifferences
Standard (default SMB)Most tenantsMatrix above; shared Zitadel instance; shared LiveKit; shared Postgres shard
Dedicated dataLarger SMBTenant gets a dedicated Postgres node (shard with max_tenants=1)
EnterpriseCustomers needing CMEK, network isolation, own audit scopeDedicated Zitadel instance (virtual instance or deployment), dedicated LiveKit key + node pool, dedicated bucket KMS key

The control plane models the tier as data on the tenant row so the provisioning program can branch without code forks.

Naming conventions​

ResourcePatternExample
Slug[a-z][a-z0-9-]{1,30} — immutableacme
Hostnames<module>.<slug>.<platform-domain>meet.acme.…, chat.acme.…
Coolify projecttenant-<slug>tenant-acme
Postgres DB / rolemeet_<slug> / meet_<slug>_appmeet_acme
Buckettenant-<slug> (prefixes recordings/, transcripts/, files/)tenant-acme
Infisical path/tenants/<slug>/<module>/tenants/acme/meet
Zitadel orgname = slug, id stored in tenants.zitadel_org_id—
LiveKit room<slug>__<room-uuid> (__ is forbidden in slugs)acme__3f9c…
Pulumi stackfortspace/tenant/<slug>—

Slugs are never reused for 90 days after erasure so room prefixes and presigned URLs cannot collide with a previous tenant.

What the shared plane must never contain​

  • Chat messages, attachments, meeting titles/participants, transcripts, recordings (bucket contents are in RustFS but encrypted, per-tenant keyed, and unreadable via shared credentials — see 08).
  • Any tenant's LiveKit API secret (there is one platform key held by the broker only).

Failure-containment summary​

FailureBlast radius
go-meet bug or OOMone tenant
Runaway SQLone shard; core Postgres unaffected
Redis flush/lossone tenant's sessions/lobby
Compromised tenant stackits own data + room-scoped tokens (minutes) + its bucket key; not other tenants
Compromised control planeeverything — hence minimal surface, separate worker/API roles, Infisical audit, no inbound from tenant stacks except token/event endpoints
LiveKit node lossall live calls, no data loss