Architecture · Decisions
Decision Records.
Design rationale behind every major technical choice in the kit.
| # | Title | Status |
|---|---|---|
| K1 | CF-native runtime & deployment topology | Accepted |
| K2 | Ctx-injection dependency seam | Accepted |
| K3 | Expansions architecture (core/addon, severability, headless) | Accepted |
| K4 | Identity, membership & tenancy model | Accepted |
| K5 | Data model & persistence conventions | Accepted |
| K6 | Typed error channel (`Result`) | Accepted |
| K7 | Satellite service seam (Worker↔sidecar) | Accepted |
| K8 | Expansion contribution seams (kernel reads the union, forks never edit the kernel) | Accepted |
| P1 | Authorization (`ctx.can`) | Accepted |
| P2 | Money — integer minor units + per-row currency | Accepted |
| P3 | Notification email channel | Accepted |
| P4 | Per-record resource sharing (`resource_shares`, `decideOwnedResource`) | Accepted |
| C1 | Frontend stack & design system | Accepted |
| C2 | i18n — Paraglide + ALS bridge + locale chain | Accepted |
| C3 | Testing strategy | Accepted |
| C4 | Toolchain — OXC (oxlint + oxfmt) | Accepted |
| C5 | CI pipeline + local rehearsal | Accepted |
| C6 | Fork setup baseline | Accepted |
| C7 | Fork maintenance: sync + rebrand | Accepted |
| C8 | Rate-limit architecture | Accepted |
| C9 | Routing & error-page conventions | Accepted |
| C10 | Dev orchestration (superpowers + /workflows) | Accepted |
| C11 | Free-tier graceful degradation | Accepted |
| C12 | Page header & breadcrumb conventions | Accepted |
| C13 | Page Kit composition layer (new primitives, templates, AuthShell) | Accepted |
| C14 | Cloudflare setup automation: token isolation + tier-aware doctor gate | Accepted |
| C15 | CI deploy gating: provisioned repo variable + explicit operator consent | Accepted |
| C16 | Script surface (manifest, not a CLI) | Accepted |
| C17 | Tenant nav sections are contributed, not special-cased | Accepted |
| C18 | The keyset cursor codec belongs to the kernel package, not the app layer | Accepted |
| C19 | Account settings surface: host-branching layout, not a per-host route split | Accepted |
| C20 | Notifications surface consolidation | Accepted |
| C21 | Settings pages may commit several groups at once | Accepted |
| C22 | Self-service workspace deletion for the sole member | Accepted |
| C23 | Profile and avatar commit through one endpoint, amending C21 | Accepted |
| C24 | Core migrations as a discovered source | Accepted |
| C25 | Tokens are surface-relative, not ramp-indexed | Accepted |
| C26 | Branding page commits marks and palette through one endpoint, amending C21/C23 | Accepted |
| X1 | Versioning & breaking-change policy | Accepted |
| X2 | Public-seam stability contract | Accepted |
| X3 | Security & tenant-isolation guarantees | Accepted |