11 — Decisions, corrections and open questions
Decision records
| ID | Decision | Status | Rationale / consequences |
|---|---|---|---|
| ADR-001 | Control plane in TypeScript/Node (Fastify, pg-boss, Pulumi Automation API, TanStack Start console) | Accepted (D1) | Matches Pulumi Automation API and console; supersedes Go CP of the discussions. go-meet stays Go. |
| ADR-002 | Chat = Tuwunel (Matrix) per tenant | Proposed — confirm | AGENTS.md still lists Rocket.Chat; Matrix discussion is the deeper one. Affects DB design (Mongo vs RocksDB) |
| ADR-003 | Zitadel, single multi-tenant instance, org per tenant | Accepted (D3) | Replaces Keycloak. Dedicated instance for Tier-1 only. |
| ADR-004 | Infisical shared, folder + machine identity per tenant | Accepted (D2) | Per-tenant Infisical too heavy. |
| ADR-005 | Coolify project per tenant + core-infra + tenant-data-pool | Accepted (D4) | Atomic teardown, clear scope. |
| ADR-006 | LiveKit shared; token broker signs exact-room tokens; tenants never hold the API secret | Proposed | LiveKit has no prefix grants or per-key authZ. Cost: CP on the join path. |
| ADR-007 | Webhook router in CP re-signs to tenant go-meet | Proposed | One LiveKit webhook stream; custom per-egress callback not relied on. |
| ADR-008 | Bucket per tenant + scoped key; presigned URLs; lifecycle expiry | Accepted | Hard boundary, instant erase. |
| ADR-009 | Encryption: SSE-S3 first; per-tenant keys via a RustFS-supported KMS later | Proposed | Infisical is not a documented RustFS KMS backend. |
| ADR-010 | DB per tenant on sharded Postgres pool; separate core Postgres | Accepted | Hard boundary; blast radius per shard. |
| ADR-011 | Pulumi stack per tenant, state in Postgres backend, dynamic providers over adapters | Proposed | Single lifecycle model; adapters keep Coolify authoritative for runtime. |
| ADR-012 | go-meet per tenant (container), Redis per tenant | Accepted | ~20 MB, process isolation. |
| ADR-013 | Persistent in-call chat via Matrix room; LiveKit data channels not used for chat | Proposed | Single text record; guest bridge open (Q-06). |
| ADR-014 | Orchestrator references stored generically (orchestrator_type, resource_id) | Accepted | Coolify → Dokploy/K8s is an adapter. |
Corrections to the discussions
These points were stated in the exploratory chats and are not carried over because they conflict with vendor documentation or with later decisions.
| Claim in discussion | Reality / resolution |
|---|---|
LiveKit tokens support RoomPrefix (so one tenant admin token can cover tenant-*) | No: room is an exact match. → broker with exact-room tokens (ADR-006) |
Per-key webhook routing/limits in livekit.yaml give tenant isolation | Official docs do not establish per-key authZ or per-key webhook routing; multiple keys only distinguish signers. → CP owns tenant authZ |
Egress CustomBaseUrl delivers egress events to the tenant | Not verified in current docs. → router for all events (ADR-007) |
| LiveKit tokens can be refreshed/revoked server-side | Self-hosted removal/permission changes do not revoke issued tokens. → short TTLs |
| Infisical can serve as RustFS's KMS for SSE | RustFS documents local, Vault KV2 and Vault Transit KMS backends. → Q-07 |
| Keycloak orgs/claims; Go control plane; Infisical per tenant | Superseded by Zitadel, TypeScript control plane, shared Infisical |
Coolify API at /api/v4/... | Coolify's REST API is /api/v1 |
| Pulumi state "in PostgreSQL" vs "S3 bucket" (both said) | Postgres DIY backend is documented; use it (no dependency on RustFS for control state) |
Zitadel org claim urn:zitadel:iam:org:id as "the tenant id" | Home-org is …user:resourceowner:id; org:id:{id} is a scope enforcing membership; role grants are separate claims |
| Rocket.Chat and Tuwunel both planned | Reconcile via ADR-002 |
Open questions
| ID | Question | Needed by | Owner/next step |
|---|---|---|---|
| Q-01 | Platform domain, regions, hosting provider(s) for public VPS + private host | before staging | product |
| Q-02 | Pricing tiers ↔ isolation tiers (Standard / Dedicated data / Enterprise) | before provisioning code | product |
| Q-03 | Is a pulumiverse/community Zitadel provider good enough, or write a dynamic provider over the management API? | CP spike | engineering spike |
| Q-04 | Zitadel role/group → go-meet team_ids mapping format (project roles vs organization metadata) | go-meet Zitadel adapter | go-meet |
| Q-05 | Tuwunel OIDC: native vs delegated; supported appservice features and admin API surface; backup method | before chat work | spike |
| Q-06 | Guest in-call chat: bridge (data channel → Matrix) or no chat | with Matrix work | product |
| Q-07 | Per-tenant SSE keys: OpenBao/Vault Transit KMS for RustFS, or SSE-S3 only | before recordings in prod | security |
| Q-08 | Files/storage product: build on RustFS directly or integrate an open-source drive? Euro-Office storage backend? | roadmap | product |
| Q-09 | Mail: Stalwart per tenant or shared multi-domain? Public SMTP ports/IP reputation under frp | roadmap | engineering |
| Q-10 | Billing/metering source of truth (Zitadel, CP, usage events) | later | product |
| Q-11 | pg-boss vs Temporal for sagas as complexity grows | after first saga | engineering |
| Q-12 | Pulumi CLI availability/packaging inside the worker image and state-locking behavior with Postgres backend under concurrency | CP spike | engineering spike |
| Q-13 | Broker SLO/replica policy and whether to give Enterprise tenants a dedicated LiveKit key + node | broker design | engineering |
| Q-14 | Rocket.Chat retained for any customer segment? | ADR-002 | product |
Suggested sequence
- Spikes (1–2 weeks): Pulumi Automation + dynamic provider against Coolify; Zitadel org/grant/service-account via API; broker + one go-meet joining through it; Tuwunel OIDC.
- Walking skeleton: provision one tenant end to end (Zitadel org → DB → bucket → Coolify stack → login → call → recording).
- Harden: reconciler, suspension/offboarding, observability, backups with a restore drill.
- Chat integration, then SSO self-service, then modules (mail, files).
Mapping to the repository
| Concern | Today | Change |
|---|---|---|
| Docs | AGENTS.md, go-meet/*.md | This folder is the architecture reference; AGENTS.md points here |
| Deployment drafts | deployment/ | See table in 09 |
| Prototype | go-meet/ | See table in 06 |
| New code | — | control-plane/ (TS monorepo: api, worker, console, packages/ports) |