> ## 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. # Architecture Decision Records > Last Updated: 2026-04-12 **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:** [`specs/_templates/ADR_TEMPLATE.md`](../../../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 Skip ADRs for: obvious single-option choices, reversible single-function decisions, or purely cosmetic changes. ## ADR Index | # | Title | Status | Date | Summary | | --------------------------------------------------------- | ------------------------------------------------------- | -------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [ADR-001](ADR-001-form-analytics-architecture.md) | Form Analytics Architecture | Accepted | 2025-12-05 | FW-27 extends PF-09 rather than replacing it; two-tier form analytics architecture | | [ADR-002](ADR-002-cl-pm-cross-core-foreign-keys.md) | 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](ADR-003-mcp-pf72-phase4.md) | 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](ADR-004-cl-fw-event-patterns.md) | CL–FW Event Patterns | Proposed | 2026-03-01 | Clinical workflow event contract patterns between CL and FW cores (pending final acceptance) | | [ADR-005](ADR-005-cross-core-fk-pm-patients.md) | 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](ADR-006-cross-core-fk-hr-employees.md) | 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](ADR-007-multi-tenant-rls-architecture.md) | Multi-Tenant via Supabase RLS | Accepted | 2026-04-12 | All tenant isolation via Postgres RLS + `organization_id`; no application-layer sharding | | [ADR-008](ADR-008-vite-spa-vs-ssr.md) | 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](ADR-009-biome-formatter.md) | Biome as Primary Formatter | Accepted | 2026-04-12 | Biome replaces Prettier + ESLint for formatting and import organization; ESLint retained for custom rules | | [ADR-010](ADR-010-core-pf-dependency-boundary.md) | Core–PF Dependency Boundary | Accepted | 2026-04-12 | Domain cores depend only on Platform Foundation (PF); no direct core-to-core imports | | [ADR-011](ADR-011-edge-functions-deno.md) | Edge Functions on Deno | Accepted | 2026-04-12 | Supabase Edge Functions use Deno runtime; `_shared/` for cross-function utilities | | [ADR-012](ADR-012-pf96-jurisdiction-profiles.md) | 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](ADR-013-pwa-strategy.md) | 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](ADR-016-workspace-packages-overlay.md) | 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](ADR-017-microfrontends-pwa-scoping.md) | 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](ADR-018-typescript-7-go-compiler-evaluation.md) | 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](ADR-020-partitioned-event-and-audit-tables.md) | 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 1. **Propose:** Create a new ADR file (next sequential number) from the template. Set status `Proposed`. 2. **Review:** Open a PR; relevant stakeholders review. Add as PR checklist item when introducing new patterns. 3. **Accept:** Merge the PR; set status `Accepted`. Update this index. 4. **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`. **Tip:** Each ADR should take 10–30 minutes to write. If it takes longer, the decision likely needs to be split. ## Related * [Constitution §1 Architecture & Module Boundaries](../../../constitution.md) — module boundary rules * [Constitution §8.2 Material Decisions](../../../constitution.md) — when to write an ADR * [docs/architecture/integrations/CROSS\_CORE\_INTEGRATIONS.md](../integrations/CROSS_CORE_INTEGRATIONS.md) — integration patterns