> ## 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 > Architecture Decision Records (ADRs) document significant architectural choices — the context, options considered, decision made, and consequences. They are pe… **Last Updated:** 2026-06-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`](https://github.com/Encore-OS/encoreos/blob/development/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](/architecture/decisions/ADR-001-form-analytics-architecture) | Form Analytics Architecture | Accepted | 2025-12-05 | FW-27 extends PF-09 rather than replacing it; two-tier form analytics architecture | | [ADR-002](/architecture/decisions/ADR-002-cl-pm-cross-core-foreign-keys) | 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](/architecture/decisions/ADR-003-mcp-pf72-phase4) | 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](/architecture/decisions/ADR-004-cl-fw-event-patterns) | CL–FW Event Patterns | Proposed | 2026-03-01 | Clinical workflow event contract patterns between CL and FW cores (pending final acceptance) | | [ADR-005](/architecture/decisions/ADR-005-cross-core-fk-pm-patients) | 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](/architecture/decisions/ADR-006-cross-core-fk-hr-employees) | 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](/architecture/decisions/ADR-007-multi-tenant-rls-architecture) | Multi-Tenant via Supabase RLS | Accepted | 2026-04-12 | All tenant isolation via Postgres RLS + `organization_id`; no application-layer sharding | | [ADR-008](/architecture/decisions/ADR-008-vite-spa-vs-ssr) | 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](/architecture/decisions/ADR-009-biome-formatter) | Biome as Primary Formatter | Accepted | 2026-04-12 | Biome replaces Prettier + ESLint for formatting and import organization; ESLint retained for custom rules | | [ADR-010](/architecture/decisions/ADR-010-core-pf-dependency-boundary) | Core–PF Dependency Boundary | Accepted | 2026-04-12 | Domain cores depend only on Platform Foundation (PF); no direct core-to-core imports | | [ADR-011](/architecture/decisions/ADR-011-edge-functions-deno) | Edge Functions on Deno | Accepted | 2026-04-12 | Supabase Edge Functions use Deno runtime; `_shared/` for cross-function utilities | | [ADR-012](/architecture/decisions/ADR-012-pf96-jurisdiction-profiles) | 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](/architecture/decisions/ADR-013-pwa-strategy) | 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-014](/architecture/decisions/ADR-014-training-ownership-gr-02-canonical) | GR-02 Canonical Training Substrate; HR-22/HR-27 Overlays | Proposed | 2026-04-19 | GR-02 owns the canonical training tables; HR-22/HR-27 are HR-side overlays on the same surface, not competing schemas | | [ADR-015](/architecture/decisions/ADR-015-pm-refund-recoupment-decision) | PM Refund / Recoupment / Takeback Path | Accepted | 2026-04-20 | Lite-first refund/recoupment path under the PM-53 umbrella; avoids duplicate `pm_refunds`/`pm_payer_takebacks` tables and event publishers | | [ADR-016](/architecture/decisions/ADR-016-workspace-packages-overlay) | Workspace packages overlay | Superseded by ADR-022 | 2026-04-22 | Per-package `package.json` under `packages/` declares dependency surface; source files stay in `src/` (no physical migration in Phase 2). **Torn down 2026-05-25 — never wired up.** | | [ADR-017](/architecture/decisions/ADR-017-microfrontends-pwa-scoping) | PWA scoping under Microfrontends | Superseded by ADR-022 | 2026-04-22 | Phase 3 amendment to ADR-013: the public zone disables its SW; only the authenticated zone owns scope `/`. **Torn down 2026-05-25 — never activated.** | | [ADR-025](/architecture/decisions/ADR-025-typescript-7-go-compiler-evaluation) | 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-018](/architecture/decisions/ADR-018-pf-pm-encounter-reference-no-fk) | PF→PM Encounter Reference Posture (No DB FK) | Proposed | 2026-04-23 | PF columns referencing PM-owned entities (e.g. `pf_transcription_sessions.encounter_id`) use UUID with no DB FK or trigger; validation happens in the originating Edge Function/RPC with a background reconciliation job. Reaffirms ADR-002's narrow CL→PM exception. | | [ADR-019](/architecture/decisions/ADR-019-nextjs-turbopack-deferral) | Defer Next.js / Turbopack for the authenticated ERP shell | Accepted | 2026-04-24 | Do not migrate the authenticated shell to Next.js for Turbopack/RSC; stay on the Vite + React Router SPA (ADR-008) and keep investing in Vite/Rolldown chunking, route-level lazy loading, and Turborepo caching. | | [ADR-020](https://github.com/Encore-OS/encoreos/blob/development/docs/architecture/decisions/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. | | [ADR-021](/architecture/decisions/ADR-021-migration-edit-exception-rls-helper-collision) | One-Time Exception to "Never Edit Existing Migrations" | Accepted | 2026-05-23 | Documents a one-time, criteria-bound exception to the never-edit-migrations rule to resolve the `20260513225500` timestamp/RLS-helper collision, and codifies the bar future exceptions must meet. | | [ADR-022](/architecture/decisions/ADR-022-workspace-microfrontends-teardown) | Tear down workspace-packages + microfrontends overlay | Accepted | 2026-05-25 | Supersedes ADR-016/ADR-017. Removes never-activated empty `packages/` stubs, `microfrontends.json`, and their audit gates; architecture stays enforced by the import-scan layer. `packages/docs` retained. | | [ADR-023](/architecture/decisions/ADR-023-agent-harness-and-eval-tooling-direction) | Agent Harness, Skills & Eval-Tooling Direction | Accepted | 2026-06-04 | Grounded response to 2026-06 external research: defer Mastra/product agent harness (no product agent; no SOC 2); reject `@AGENTS.md` import (documented local choice); Promptfoo C4 + self-hosted Langfuse C3 already shipped (#814/#815); accept skill-regression evals + Claude Code OTEL→Langfuse next; command→skill consolidation + context-file audit on backlog. | | [ADR-024](/architecture/decisions/ADR-024-platform-workflow-execution-seam) | `@/platform/workflow` Execution Seam (IG-06) | Proposed | 2026-06-07 | Adds a tenant-scoped execution API (`enqueueWorkflowExecution`/`getThrottleStatus`/`subscribeKpiSnapshot`) to the diagram-only `@/platform/workflow`, wrapping FW's pgmq enqueue behind an edge fn so HR/FA/RH can run FW workflows without importing FW; unblocks the 19 cross-core templates. Surfaces FW-53 throttle/hold state; idempotency-keyed; fire-and-durable. | | [ADR-026](/architecture/decisions/ADR-026-langchain-ecosystem-and-agent-os) | LangChain Ecosystem & Agent OS — Not Adopted | Accepted (directional) | 2026-06-11 | Do not adopt LangChain, LangGraph, LangSmith, or Agent OS — each duplicates the existing provider-agnostic `AIProvider` seam (PF-111), pgmq/ADR-024 durable execution, self-hosted Langfuse evals, or `eos-spec`, while widening the HIPAA dependency surface. Enshrines "extend the seam, don't adopt a framework"; revisit only on a funded product-agent feature (per ADR-023). | | [ADR-027](/architecture/decisions/ADR-027-picklist-naming-and-tier-classification) | Picklist Naming & Three-Tier Value-Set Classification | Proposed | 2026-06-12 | New PF-15 picklist names use dot-namespace `{core}.{domain}.{field}` (legacy flat names grandfathered); every picklist is classified Tier A (workflow state, code-owned), B (org vocabulary, fully editable), or C (constraint-mirrored, `metadata.value_set_locked` blocks add/delete/deactivate while labels/colors/order/aliases stay editable). | | [ADR-028](/architecture/decisions/ADR-028-claude-cursor-rules-parity) | `.claude/rules` ↔ `.cursor/rules` parity model | Accepted | 2026-06-16 | The two IDE rule sets are intentionally divergent (different formats, granularity, filenames; some single-IDE by design), not a byte-for-byte mirror. Canonical model = a documented per-IDE allowlist keyed by rule topic (`automation/_platform/rules-parity.json`) + a drift gate (`check:rules-parity`, in `validate:governance`) enforcing on-disk completeness, no undeclared drift, and cross-IDE topic coverage unless documented `exempt`. `sync.ts` stays scoped to skills/commands/agents. | | [ADR-029](/architecture/decisions/ADR-029-hti1-dsi-scope-billing-rcm-ai) | ONC HTI-1 §170.315(b)(11) DSI scope for billing / RCM AI | Accepted | 2026-06-23 | Records the determination that Encore adopts §170.315(b)(11) DSI transparency as a **platform-wide control covering billing/RCM AI** (PM-64 coding, PM-50 denial, PM-66 PA, PM-29-EN-01 appeals), not just clinical AI — a deliberate, defensible over-compliance choice (the criterion is administrative-DSS-ambiguous) that also mitigates FCA + bias risk. Disclosures are tiered by `dsi_type` so generative/evidence-based features publish without fabricating predictive metrics, while predictive features (PM-50/66) stay unpublishable until externally validated. Ratified by the owner 2026-06-23 — clears CL-65's compliance-review gate and closes PM-64 G-3. | ## 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](https://github.com/Encore-OS/encoreos/blob/development/constitution.md) — module boundary rules * [Constitution §8.2 Material Decisions](https://github.com/Encore-OS/encoreos/blob/development/constitution.md) — when to write an ADR * [docs/architecture/integrations/CROSS\_CORE\_INTEGRATIONS.md](/architecture/integrations/CROSS_CORE_INTEGRATIONS) — integration patterns