Last Updated: 2026-04-12 Architecture Decision Records (ADRs) document significant architectural choices — the context, options considered, decision made, and consequences. They are permanent records; superseded ADRs are never deleted. Template:Documentation Index
Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt
Use this file to discover all available pages before exploring further.
specs/_templates/ADR_TEMPLATE.md
When to Write an ADR
Write an ADR when:- Choosing between multiple viable approaches with significant trade-offs
- The decision will outlast a single sprint or affect multiple cores
- A new dependency, pattern, or cross-core boundary is introduced
- Reversing the decision would take more than a sprint
ADR Index
| # | Title | Status | Date | Summary |
|---|---|---|---|---|
| ADR-001 | Form Analytics Architecture | Accepted | 2025-12-05 | FW-27 extends PF-09 rather than replacing it; two-tier form analytics architecture |
| ADR-002 | CL–PM Cross-Core Foreign Keys | Accepted | 2026-02-25 | CL tables may reference pm_encounters.id via DB FK; all other cross-core refs use UUID columns only |
| ADR-003 | MCP PF-72 Phase 4 | Accepted | 2026-03-15 | MCP server baseline committed to .cursor/mcp.json (shadcn, fallow); user-local plugins for Supabase, Context7 |
| ADR-004 | CL–FW Event Patterns | Proposed | 2026-03-01 | Clinical workflow event contract patterns between CL and FW cores (pending final acceptance) |
| ADR-005 | Cross-Core FK: PM Patients | Accepted | 2026-03-20 | HR core may reference pm_patients.id via UUID column only; no DB-level FK |
| ADR-006 | Cross-Core FK: HR Employees | Accepted | 2026-03-20 | PM/CL cores reference hr_employees.id via UUID column; no DB-level FK |
| ADR-007 | Multi-Tenant via Supabase RLS | Accepted | 2026-04-12 | All tenant isolation via Postgres RLS + organization_id; no application-layer sharding |
| ADR-008 | Vite SPA vs Next.js SSR | Accepted | 2026-04-12 | Vite-based SPA chosen over Next.js for this ERP platform; PWA with Workbox for offline |
| ADR-009 | Biome as Primary Formatter | Accepted | 2026-04-12 | Biome replaces Prettier + ESLint for formatting and import organization; ESLint retained for custom rules |
| ADR-010 | Core–PF Dependency Boundary | Accepted | 2026-04-12 | Domain cores depend only on Platform Foundation (PF); no direct core-to-core imports |
| ADR-011 | Edge Functions on Deno | Accepted | 2026-04-12 | Supabase Edge Functions use Deno runtime; _shared/ for cross-function utilities |
| ADR-012 | PF-96 Jurisdiction Profile Architecture | Accepted | 2026-04-12 | State Medicaid rules via jurisdiction profiles (PF-96); Arizona AHCCCS is the first profile, not a global default |
| ADR-013 | PWA Strategy | Accepted | 2026-04-12 | Platform is a Progressive Web App with Workbox service worker; CacheFirst for assets, NetworkFirst for REST, NetworkOnly for auth |
| ADR-016 | Workspace packages overlay | Accepted | 2026-04-22 | Per-package package.json under packages/ declares dependency surface; source files stay in src/ (no physical migration in Phase 2) |
| ADR-017 | PWA scoping under Microfrontends | Proposed | 2026-04-22 | Phase 3 amendment to ADR-013: the public zone disables its SW; only the authenticated zone owns scope /. Preserves today’s PWA install base unchanged |
| ADR-018 | TypeScript 7.0 (Go compiler) Evaluation and Adoption | Proposed | 2026-04-23 | Adopt @typescript/native-preview (tsgo) as opt-in typecheck:fast now (validated: cold typecheck 478s → 53s, zero diagnostic delta). Cut over CI gate in Phase 2 once TS 7.0 reaches RC/GA and typescript-eslint peer range supports TS 7.x; use npm:@typescript/typescript6 alias to keep linter/audit scripts/ts-node working. |
| ADR-020 | Two-Phase Partition Strategy for Audit and Event Tables | Accepted | 2026-05-13 | High-growth PF/FW audit/event tables use non-cutover shadow partition phase first, then explicit backfill/parity/cutover with retention runbook controls. |
Process
- Propose: Create a new ADR file (next sequential number) from the template. Set status
Proposed. - Review: Open a PR; relevant stakeholders review. Add as PR checklist item when introducing new patterns.
- Accept: Merge the PR; set status
Accepted. Update this index. - Supersede: If a decision changes, write a new ADR that supersedes the old one. Update the old ADR’s status to
Superseded by ADR-NNN.
Related
- Constitution §1 Architecture & Module Boundaries — module boundary rules
- Constitution §8.2 Material Decisions — when to write an ADR
- docs/architecture/integrations/CROSS_CORE_INTEGRATIONS.md — integration patterns