70 lines
4.3 KiB
JSON
70 lines
4.3 KiB
JSON
{
|
|
"_meta": {
|
|
"updated_at": "2026-06-09T00:00:00Z",
|
|
"commit": "01f7456b81dd55d477d0bd7530df818f61a873c2",
|
|
"version": 1
|
|
},
|
|
"entries": {
|
|
"broker-cache-api-pattern": {
|
|
"title": "Broker-Cache-API pattern (two planes never cross)",
|
|
"decision": "Backend split into a broker plane (apps/api/src/broker/) that owns all Fastmail I/O and an API plane (apps/api/src/routes/) that reads only from MariaDB. Broker crons are not reachable from the HTTP layer.",
|
|
"files": ["apps/api/src/broker/poller.ts", "apps/api/src/broker/outboxWorker.ts", "apps/api/src/routes/"]
|
|
},
|
|
"write-broker-boundary": {
|
|
"title": "Write-broker boundary invariant",
|
|
"decision": "No route file imports tsdav or createFastmailClient; no broker file handles HTTP requests. Routes enqueue calendar_outbox rows and return 202 (optimistic-accept); the outbox worker performs the Fastmail write asynchronously.",
|
|
"files": ["apps/api/src/routes/events.ts", "apps/api/src/broker/write.ts"]
|
|
},
|
|
"identity-keying": {
|
|
"title": "Identity keyed on oidc_iss + oidc_sub",
|
|
"decision": "Users are keyed on oidc_iss + oidc_sub (never email). A hex color from the palette is auto-assigned on first login.",
|
|
"files": ["apps/api/src/routes/me.ts", "apps/api/src/auth/middleware.ts"]
|
|
},
|
|
"D-03-writable-set": {
|
|
"title": "D-03 calendar ownership / writable-set predicate",
|
|
"decision": "Every writable-set query uses WHERE userId = currentUser.id OR isShared = true. Another member's personal calendar is a read-only overlay.",
|
|
"files": ["apps/api/src/routes/events.ts"]
|
|
},
|
|
"D-13-dual-field-dtstart": {
|
|
"title": "D-13 all-day vs timed events (dual dtstart fields)",
|
|
"decision": "dtstart_utc is NULL for all-day events; dtstart_date is NULL for timed events. Never coerce DATE to DATETIME.",
|
|
"files": ["apps/api/src/db/schema.ts"]
|
|
},
|
|
"D-16-shared-fastmail-account": {
|
|
"title": "D-16 shared Fastmail account, per-member credentials",
|
|
"decision": "Both members share one Fastmail account. Calendar identity in DB is (userId, url) — the same collection URL appears once per member credential. CalDAV credential per member is stored AES-256-GCM encrypted in member_credentials.",
|
|
"files": ["apps/api/src/db/schema.ts", "apps/api/src/broker/poller.ts"]
|
|
},
|
|
"outbox-status-machine": {
|
|
"title": "Outbox status machine",
|
|
"decision": "calendar_outbox rows transition pending -> done | failed | dead. failed rows retry up to a limit; dead is terminal. The sync-status endpoint surfaces worst-status-first per uid.",
|
|
"files": ["apps/api/src/broker/outboxWorker.ts", "apps/api/src/routes/events.ts"]
|
|
},
|
|
"oidc-behind-pangolin": {
|
|
"title": "OIDC behind Pangolin requires OIDC_AUTH_EXTERNAL_URL",
|
|
"decision": "OIDC_AUTH_EXTERNAL_URL must be set to the public HTTPS URL to construct a correct redirect_uri; without it the callback resolves to the internal container address.",
|
|
"files": ["apps/api/src/auth/middleware.ts", "apps/api/src/index.ts"]
|
|
},
|
|
"dev-auth-bypass": {
|
|
"title": "Dev auth bypass",
|
|
"decision": "DEV_AUTH_BYPASS=true with NODE_ENV!=production injects DEV_USER via Hono context; OIDC middleware is never mounted in this mode.",
|
|
"files": ["apps/api/src/auth/devBypass.js", "apps/api/src/index.ts"]
|
|
},
|
|
"pwa-static-serving": {
|
|
"title": "PWA static serving + SPA fallback",
|
|
"decision": "Hono serveStatic serves ./public (Vite build output); SPA routes fall through to an index.html catch-all registered after /health, /api/*, and /callback so those win.",
|
|
"files": ["apps/api/src/index.ts"]
|
|
},
|
|
"schedule-x-routing": {
|
|
"title": "Schedule-X calendar routing",
|
|
"decision": "Events are routed to Schedule-X calendars by isShared ? 'shared' : String(ownerUserId) — never by calendarId. hydrateEvents.ts enforces this.",
|
|
"files": ["apps/pwa/src/hydrateEvents.ts", "apps/pwa/src/components/CalendarShell.tsx"]
|
|
},
|
|
"state-ownership": {
|
|
"title": "Client state ownership split",
|
|
"decision": "Server state is owned by TanStack Query; UI-only state (selected range, color map, drawer) by Zustand. Schedule-X renders the calendar UI.",
|
|
"files": ["apps/pwa/src/store/calendarStore.ts", "apps/pwa/src/components/CalendarShell.tsx"]
|
|
}
|
|
}
|
|
}
|