Skip to main content

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.

​
ADR-012: PF-96 Jurisdiction Profile Architecture for Multi-State Medicaid Compliance

Status: Accepted
Date: 2026-04-12
Participants: Platform Architecture Team, Jeremy Bloom

​
Context

Encore Health OS initially served Arizona-based behavioral health organizations operating under AHCCCS (Arizona Medicaid). Several Arizona-specific rules (clinical timeliness requirements, assessment elements per AHCCCS Policy 320-O, billing thresholds, modifier conventions, filing deadlines) were hardcoded as constants throughout the codebase. As the platform expands to additional states, each with its own Medicaid program (name, rules, rates, assessment requirements), hardcoded Arizona values become incorrect defaults for non-Arizona organizations. The platform needed a data-driven approach to manage state-specific Medicaid compliance rules without code changes per new state.

​
Options Considered

​
Option A: Per-state feature flags

  • How it works: Environment variables or org settings flags like IS_ARIZONA, IS_COLORADO conditionally activate state-specific logic in code.
  • Pros: Simple to implement initially.
  • Cons: Combinatorial explosion of flags as states increase; flags scattered across codebase; adding a new state requires code changes; not data-driven; doesn’t scale past 2-3 states.
  • Why not chosen: Unscalable. Creates the same hardcoding problem with extra indirection.

​
Option B: Hardcoded state-specific constants (status quo before PF-96)

  • How it works: Arizona-specific values (AHCCCS deadlines, 320-O elements, billing thresholds) stored as global constants.
  • Pros: Zero implementation cost initially.
  • Cons: All constants are wrong for non-Arizona orgs; requires code changes per new state; violates YAGNI in the opposite direction (now we have YAGNI debt).
  • Why not chosen: This was the problem being solved. Not viable for multi-state operation.

​
Option C: PF-96 Jurisdiction Profiles ✓

  • How it works: A pf_jurisdiction_profiles table (owned by PF) stores state-specific Medicaid compliance parameters as JSONB. Each organization links to a jurisdiction profile via their site configuration. APIs: useJurisdictionProfile(siteId?) (frontend), pf_resolve_jurisdiction_profile(p_org_id, p_site_id) (server/SQL), getJurisdictionProfile(supabaseClient, orgId, siteId?) (edge functions). Arizona AHCCCS is the first profile but explicitly not the universal default.
  • Pros: Data-driven; adding a new state is configuration, not code; profiles can be versioned; AI compliance checking uses profiles as context (GR-06-EN-01); jurisdiction-scoped rules (deadlines, rates, assessment elements) read from profile at runtime.
  • Cons: Requires upfront design of the jurisdiction profile schema; existing hardcoded values must be migrated (tracked in PF-96-MIGRATION-PLAN-ahcccs-to-jurisdiction-profiles.md); profile schema must be flexible enough for all states’ requirements.
  • Why chosen: Only scalable approach for a multi-state healthcare platform. Configuration over code is the correct model for regulatory parameterization.

​
Decision

State Medicaid compliance rules (filing deadlines, assessment elements, billing thresholds, modifier conventions, UI labels, timeliness requirements) are stored in pf_jurisdiction_profiles and accessed via the three jurisdiction profile APIs. No new state-specific schema columns (e.g., ahcccs_*) are added without routing through the jurisdiction profile system. Arizona AHCCCS is the default profile for NorthSight Recovery, not a universal constant. AI compliance checking (GR-06-EN-01) uses jurisdiction metadata + RAG, never hardcoded state rules.

​
Consequences

​
Positive

  • Adding a new state is database configuration, not a code release
  • AI compliance checker (GR-06-EN-01) is state-aware via profile context
  • Existing hardcoded values are being systematically migrated (migration plan tracked)
  • useJurisdictionProfile() provides clean frontend API

​
Negative

  • Migration of existing hardcoded Arizona values takes time (tracked in migration plan)
  • Profile schema must anticipate state rule variations (may need evolution)
  • Developers must remember to use profile APIs instead of constants

​
Mitigations

  • Migration plan: specs/cross-cutting/PF-96-MIGRATION-PLAN-ahcccs-to-jurisdiction-profiles.md
  • Enhancement catalog: specs/cross-cutting/MULTI-STATE-COMPLIANCE-ENHANCEMENT-CATALOG.md
  • AGENTS.md “What AI Must Never Do” explicitly prohibits hardcoding state Medicaid rules
  • Constitution §5 documents the jurisdiction profile pattern