Architecture Decisions
Summaries of key Control Plane architectural decisions — full ADRs remain in the product repository.
Groundfloor records architectural decisions in the Control Plane product repo (DECISIONS.md). This page summarizes decisions most relevant to integrators and operators.
Full decision records with rationale and lore links stay in the engineering repository. Treat this page as an index, not the source of truth.
Platform boundaries
| ID | Decision | Summary |
|---|---|---|
| D-019 | Control Plane separates from Dataplane | Platform metadata in dedicated Postgres (gf_controlplane); customer data stays in Dataplane |
| D-003 | SpiceDB for ReBAC | All authorization checks use SpiceDB with portal_* types |
| D-004 | Closed action vocabulary | Handlers may only call predefined actions (read, write, administer, …) |
| D-007 | Environment model | Enterprise workspaces get dev/staging/prod; ISV sub-tenants typically do not |
| D-039 | Per-env namespace pattern | Coderunner deploy targets map to environment namespaces |
Identity and auth
| ID | Decision | Summary |
|---|---|---|
| D-017 | Universal access pattern | Dataplane access always through Control Plane proxies — no direct browser calls |
| — | Two identity planes | Platform Keycloak ≠ optional workspace site auth |
| — | Shared SpiceDB instance | portal_* prefix isolates Control Plane types from tenant schemas |
Storage and secrets
| ID | Decision | Summary |
|---|---|---|
| D-040 | Pluggable secret backend | SecretBackend protocol; Infisical default, memory fallback in dev |
| — | Object store | S3-compatible presigned URLs for files and Shell app releases |
| — | No projection for CP | Permission projection is a customer-data feature, not platform metadata |
Operations
| ID | Decision | Summary |
|---|---|---|
| — | SpiceDB DLQ | Postgres commit first, SpiceDB write after; DLQ + drain on failure |
| — | Audit retention | 30-day default on audit_events |
| — | Offboarding retention | 30-day freeze window before hard delete |
Full ADR index
Engineers should read the complete log:
- Repository:
groundfloor-client-portal/DECISIONS.md - Frozen topics:
FROZEN.md
Related
- Control Plane overview — stack and vocabulary
- SpiceDB schema — D-003, D-004 in code
- Dataplane authz brief — projection scope