Architecture¶
This is the Software Architecture Document (SAD) for racket-book V2 (RBO V2). It describes the application that runs on top of the keystone platform — the tenancy model, data shape, auth, receipt pipeline, integrations, and i18n strategy.
Owner: Theo (Solution Architect) Status: initial pass, accepted (2026-04-27) Companion docs:
- Requirements & scope:
../requirements/index.md— Iris (BA). - Platform (host, ingress, DB, auth runtime):
https://gitlab.com/wagen/keystone/-/blob/main/docs/index.md— Atlas (PE). - Decisions log:
../adr/index.md.
The architecture below assumes Atlas's locked platform decisions (Caddy ingress, self-hosted Postgres 16 with PgBouncer, self-hosted gotrue, db-per-app + db-per-env). RBO consumes those as services; it does not own them.
Table of contents¶
| Section | Confidence | Notes |
|---|---|---|
| System overview | High | Stack and component layout. Drops cleanly onto Atlas's platform. |
| Data model | High | Entity sketch matches every Topic-3 lock-in. Schema-level details (column names, FK cascades) are implementation work, not architecture. |
| Auth & tenancy | High | Row-level tenancy is the central architectural commitment. Magic-link slot is reserved (V3). |
| Receipts | High on layout constraint and tooling; Medium on the language-selection rule (open question — see i18n). | |
| Notification preferences | High | Single source of truth for the Person.notification_prefs JSONB key set — V2 reads email only, V3 channels add to the same blob. |
| Integrations | High | Email-only via Resend SMTP (per keystone ADR-0005). No payments. |
| i18n | High | EN+DE strategy is settled; UI locale-source rule locked 2026-04-27 (saved account preference wins; browser Accept-Language is fallback for unauthenticated requests). |
| Testing | High | Real-DB rule, fixture API, test pyramid, golden-file slot. Owned by Quill (QA); commitments recorded in ADR-0010. |
| Catalogue imports | High (Phase 1) | External-feed catalogue staging surface + admin moderation queue. Phase 1 of #164 (the accepted #146 sibling proposal). Mirrors the V1-upload stage/dry-run/approve pattern. |
How to read this set¶
- Start with System overview for the 30-second mental model.
- Auth & tenancy is the load-bearing chapter — almost every other chapter assumes its rules.
- Data model is the schema sketch; no SQL DDL, just entities + key constraints.
- The three SA-owned ADRs (0001, 0002, 0003) pin the decisions; the architecture chapters explain how those decisions are realized.
Confidence legend¶
- High — decision is locked or backed by Stefan's direct answers; reversing it is non-trivial.
- Medium — decision is defensible given current information; one or two open questions could nudge it.
- Low — placeholder or speculative; flagged here so a reader doesn't mistake it for a commitment. (No section is currently Low.)