> ## 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. # Engineering Constitution > Non-negotiable architecture, security, database, testing, and definition-of-done guardrails for Encore OS. When documents conflict, this wins. > **This page is synced from `/constitution.md` at the repository root.** Edit the source file — this published copy is regenerated by `npm run docs:sync-canonical`. See the [governance index](/governance/index) for related documents. # Encore OS Platform – Engineering & Product Constitution **Version:** 1.18.0\ **Last Updated:** 2026-06-15 This constitution defines the **non‑negotiable guardrails** for designing, building, and operating the Encore OS platform and its modules. It applies to everyone: engineers, product, data, and any AI assistants. **When documents conflict, this constitution wins.** Full document hierarchy: `constitution.md` → `AI_GUIDE.md` → `AGENTS.md` → `.cursor/rules/` *** ## Table of Contents * [§1 Architecture & Module Boundaries](#1-architecture--module-boundaries) * [§1.1 Platform & Cores](#11-platform--cores) * [§1.2 Rules](#12-rules) * [§1.3 Integration Patterns](#13-integration-patterns) * [§1.4 Form Ownership Pattern](#14-form-ownership-pattern) * [§2 Specification-First Delivery](#2-specification-first-delivery) * [§2.1 Requirements](#21-requirements) * [§2.2 Process](#22-process) * [§2.3 Spec Template](#23-spec-template) * [§3 Testing & Quality Discipline](#3-testing--quality-discipline) * [§3.1 Principles](#31-principles) * [§3.2 Expectations](#32-expectations) * [§3.3 Test File Naming Conventions](#33-test-file-naming-conventions) * [§3.4 Public API Documentation Coverage](#34-public-api-documentation-coverage) * [§4 Data, Security & Privacy](#4-data-security--privacy) * [§4.1 Security](#41-security) * [§4.2 PHI / PII Handling](#42-phi--pii-handling) * [§4.3 AI Integration Security](#43-ai-integration-security) * [§4.4 Permissions System Architecture (PF-30)](#44-permissions-system-architecture-pf-30) * [§5 Database, Naming & Environment Guardrails](#5-database-naming--environment-guardrails) * [§5.1 Multi-Tenant Data Model](#51-multi-tenant-data-model) * [§5.2 Database Naming Conventions](#52-database-naming-conventions) * [§5.3 Migrations & Change Management](#53-migrations--change-management) * [§5.4 Environment Separation](#54-environment-separation) * [§5.5 Production Deployment & Rollback](#55-production-deployment--rollback) * [§5.6 Performance & Monitoring Standards](#56-performance--monitoring-standards) * [§5.7 RLS Anti-Patterns & Security Definer Functions](#57-rls-anti-patterns--security-definer-functions) * [§5.8 Edge Function Patterns](#58-edge-function-patterns) * [§5.9 Scheduled Task Pattern](#59-scheduled-task-pattern) * [§5.10 Bulk Import & Data Migration Standards](#510-bulk-import--data-migration-standards) * [§6 PWA & Mobile-First Requirements](#6-pwa--mobile-first-requirements) * [§6.1 PWA Requirements](#61-pwa-requirements) * [§6.2 Mobile-First Design Principles](#62-mobile-first-design-principles) * [§6.3 Navigation Requirements](#63-navigation-requirements) * [§6.4 Dashboard Standards](#64-dashboard-standards) * [§6.5 Frontend Performance Patterns](#65-frontend-performance-patterns) * [§6.6 Authentication State Management](#66-authentication-state-management) * [§6.7 UI/UX Guardrails](#67-uiux-guardrails) * [§6.8 Wizard & Help UX Requirements](#68-wizard--help-ux-requirements) * [§7 Finance & Clinical Guardrails](#7-finance--clinical-guardrails) * [§7.1 Finance (FA)](#71-finance-fa) * [§7.2 Clinical (CL)](#72-clinical-cl---clinical--ehr) * [§7.3 Medical Terminology Governance](#73-medical-terminology-governance) * [§8 Simplicity, Pragmatism & Decisions](#8-simplicity-pragmatism--decisions) * [§8.1 Simplicity Rules](#81-simplicity-rules) * [§8.2 Decision Discipline](#82-decision-discipline) * [§8.3 Code Review & Pull Request Standards](#83-code-review--pull-request-standards) * [§8.4 Deprecation & Legacy Code Policy](#84-deprecation--legacy-code-policy) * [§9 Documentation & Ownership](#9-documentation--ownership) * [§9.1 What Must Be Documented](#91-what-must-be-documented) * [§9.2 Ownership](#92-ownership) * [§9.3 Implementation Log Requirements](#93-implementation-log-requirements) * [§10 Governance, Versions & AI Alignment](#10-governance-versions--ai-alignment) * [§10.1 Changes to the Constitution](#101-changes-to-the-constitution) * [§10.2 Relationship to AI Guidelines](#102-relationship-to-ai-guidelines) * [§10.3 Annual Constitution Review](#103-annual-constitution-review) * [§11 Project Structure & Code-Level Naming](#11-project-structure--code-level-naming) * [§11.1 Directory Structure](#111-directory-structure) * [§11.2 Code-Level Naming](#112-code-level-naming) * [§12 Automation Governance](#12-automation-governance) * [§12.1 Approval for High-Risk Automations](#121-approval-for-high-risk-automations) * [§12.2 Circuit Breaker for Reliability](#122-circuit-breaker-for-reliability) * [§12.3 Testing Requirements](#123-testing-requirements) * [§12.4 Audit & Monitoring](#124-audit--monitoring) * [§12.5 Rate Limiting & Resource Protection](#125-rate-limiting--resource-protection) * [§13 Definition of Done](#13-definition-of-done) *** ## 1. Architecture & Module Boundaries The platform is structured as a **Platform Foundation** plus **domain cores**. Boundaries are hard rules, not suggestions. ### 1.1 Platform & Cores * **Platform Foundation (PF)**\ Identity, tenancy, access control, navigation, audit, shared UX, cross‑cutting services, PWA infrastructure, jurisdiction/compliance configuration (PF-96), and integration glue. PF owns the **jurisdiction profile system** that provides state-specific Medicaid compliance rules as structured, versioned configuration data consumed by CL and PM. * **Domain Cores** * **RH – Recovery Housing & Operations** * **FA – Finance & Revenue** * **HR – Workforce & HRIS** * **GR – Governance, Compliance & Learning** * **FW – Forms & Workflow** * **FM – Facilities, Inventory & Vendors** * **LO – Leadership Operating System** * **CE – Community Engagement** * **IT – IT & Security** * **CL – Clinical & EHR** (never a base dependency) * **PM – Practice Management** (healthcare revenue cycle; distinct from FA general accounting) ### 1.2 Rules * All code, tables, APIs, and UI features MUST declare an owning core/module (e.g., `RH-01`, `FA-01`). * Platform Foundation is the only shared base layer. **Cores may depend on PF, but not on each other**, except via explicit, documented integration contracts. * CL (Clinical) is **architecturally downstream**: * No other core may depend on CL. * No "hidden clinical" logic in RH/FA/HR. * PM (Practice Management) and CL (Clinical) are **tightly integrated operationally** but **architecturally independent**: * Both depend only on PF, never on each other. * Integration via Platform Integration Layer (`@/platform/clinical`, `@/platform/scheduling`), events, and shared type definitions in PF. * The **encounter** (`pm_encounters`, owned by PM) is the canonical entity linking scheduling, clinical documentation, and billing. CL reads encounter context via `@/platform/scheduling`. * PM handles healthcare revenue cycle (claims, eligibility, ERA); FA handles general accounting (GL, AP, AR). * Encounter-to-billing pipeline: CL note finalization triggers PM charge capture via events. * **Cross-core database references:** * By default, cross-core table references use UUID columns validated at the application layer (no database FK constraints). * **Exception (CL-PM only):** The encounter entity (`pm_encounters`) is the canonical joint between clinical documentation and revenue cycle. CL tables MAY reference `pm_encounters.id` via a database FK with `ON DELETE RESTRICT` to preserve referential integrity. This exception is scoped to the encounter entity and documented in ADR-002. No other cross-core FK is permitted without an ADR. * Cross‑core integrations MUST be: * Defined as explicit contracts (events, APIs, or data feeds). * Documented in architecture diagrams and specs. **Rationale:** Clear domain boundaries avoid monolith creep, enable parallel delivery, and keep clinical complexity from contaminating operational systems. ### 1.3 Integration Patterns When one core needs to interact with another (e.g., RH needing forms from FW), the integration MUST follow these patterns: #### Integration Pattern Decision Tree ```text theme={null} Core A needs functionality from Core B: │ ├─ Is it a cross-cutting capability used by multiple cores? │ └─ YES → Pattern 1: Platform Integration Layer │ Example: Forms, Notifications, Documents, Reports │ Location: /src/platform/{capability}/ │ ├─ Is it asynchronous (fire-and-forget, audit trail)? │ └─ YES → Pattern 2: Event-Based Integration │ Example: "resident_admitted", "form_submitted" │ Use: pg_notify or Platform Integration Layer │ ├─ Is it synchronous request-response? │ └─ YES → Pattern 3: API Contracts │ Example: Balance queries, permission checks │ Document in: docs/architecture/integrations/API_CONTRACTS.md │ └─ Is it triggered by database changes? └─ YES → Pattern 2c: Database Trigger → Edge Function Example: AI processing, external API calls Use: pg_net to invoke edge function asynchronously ``` **See:** `docs/architecture/integrations/index.md` for complete integration documentation. **Pattern 1: Platform Integration Layer** * For cross-cutting capabilities used by multiple cores (like Forms & Workflow), create an integration layer within Platform Foundation. * Example: `/src/platform/forms/` provides simple hooks and components that wrap FW functionality. * Other cores interact with this integration layer, NOT directly with `/src/cores/fw/`. **Pattern 2: Event-Based Integration** * Cores publish domain events (e.g., "resident admitted", "form submitted"). * Subscribing cores listen and react without direct coupling. * Events MUST be documented in a central registry. **Pattern 2b: Event Registry Pattern (FW-16)** * For workflow triggers based on domain events, cores register events in `fw_workflow_events` table. * Event registry stores: event\_name, display\_name, description, owning\_core, category, payload\_schema. * Workflow designers browse available events by core (HR, RH, FA, etc.) in the trigger configuration UI. * Cores publish events via Platform Integration Layer: `import { publishEvent } from '@/platform/events';` * FW Automation Engine subscribes to events and triggers matching workflows. * Constitutional compliance: Events remain within Pattern 2 (event-based integration). **Pattern 2c: Database Trigger → Edge Function** * For automated processing triggered by database changes (INSERT, UPDATE, DELETE). * Database trigger calls `pg_net` to invoke edge function asynchronously. * Edge function performs complex processing (AI, external API calls, multi-step workflows). * Constitutional compliance: Async processing without blocking database transactions. ```sql theme={null} -- Example: Trigger edge function on insert CREATE OR REPLACE FUNCTION {core}_trigger_edge_function() RETURNS TRIGGER LANGUAGE plpgsql SECURITY DEFINER SET search_path = public AS $$ BEGIN PERFORM net.http_post( url := current_setting('app.settings.supabase_url') || '/functions/v1/{function-name}', headers := jsonb_build_object( 'Content-Type', 'application/json', 'Authorization', 'Bearer ' || current_setting('app.settings.service_role_key') ), body := jsonb_build_object( 'record_id', NEW.id, 'organization_id', NEW.organization_id, 'action', TG_OP ) ); RETURN NEW; END; $$; CREATE TRIGGER {core}_{entity}_after_insert AFTER INSERT ON {core}_{entity} FOR EACH ROW EXECUTE FUNCTION {core}_trigger_edge_function(); ``` **Pattern 3: API Contracts** * Well-defined, versioned APIs with clear request/response schemas. * Documented in OpenAPI specs or equivalent. * Breaking changes require version bumps and migration paths. **When to Use Which:** * Use **Platform Integration Layer** for shared utilities that multiple cores need (forms, notifications, file uploads). * Use **Event-Based** for asynchronous workflows and loose coupling. * Use **API Contracts** for synchronous, request-response interactions. **Example Integrations:** * **Form Submission → Entity Creation:** FW `map_to_entity` action uses `process-entity-mapping` Edge Function to create/update records in FA, HR, RH tables from form submissions. Configuration maps form fields to entity columns + `custom_fields` JSONB. * **Picklist Integration:** FW Form Builder can use PF-15 picklists as data source for select fields, managed centrally in Platform Settings. **Prohibited:** * Direct imports from one core into another (e.g., `import { something } from '@/cores/fa/...'` inside RH code). * Shared database tables between cores without explicit ownership. **Architecture Decision Records (ADRs):** * Any exception to the above integration patterns MUST be documented as an ADR in `docs/architecture/decisions/`. * ADR format: Use `specs/_templates/ADR_TEMPLATE.md`. * ADRs are permanent records; they may be superseded but never deleted. **Rationale:** Clear integration patterns prevent hidden dependencies and make the system easier to test, deploy, and evolve independently. ### 1.4 Form Ownership Pattern The platform's Forms & Workflow (FW) core provides form infrastructure used across all domain cores. To maintain clear ownership and enable module-specific views: **Database:** * All forms MUST have an `owning_core` column (type `core_code` enum) * Values: `'pf'`, `'rh'`, `'fa'`, `'hr'`, `'gr'`, `'fw'`, `'fm'`, `'ce'`, `'cl'`, `'pm'` * Default: `'pf'` (Platform Foundation / shared forms) **Module-Specific Views:** * Each core SHOULD have a dedicated forms page at `/{core}/forms` * Example: `/hr/forms` shows only forms where `owning_core = 'hr'` * Platform admins can access all forms via `/fw/forms` **Form Creation:** * Forms created within a core's context default to that core's `owning_core` * Example: Creating a form from `/hr/forms/new` defaults to `owning_core = 'hr'` **Platform Integration Layer:** * `useFormList` accepts `owningCore` filter * `FormSelector` accepts `owningCore` prop * `ModuleFormsPage` provides reusable filtered list **Rationale:** Explicit form ownership enables module-specific administration, improves user experience by showing only relevant forms, and maintains architectural clarity without violating core boundaries. *** ## 2. Specification‑First Delivery No meaningful feature is built without a written specification. ### 2.1 Requirements Every feature with non‑trivial impact MUST have a spec that: * **Uses the spec template:** `specs/_templates/SPEC_TEMPLATE.md` (see Section 2.3) * Names the **core and module** (e.g., `RH-01: Census & Beds`). * Articulates: * Business context and problem statement. * In‑scope / out‑of‑scope. * User stories and acceptance criteria. * Functional and non‑functional requirements. * Performance requirements (p50, p95, p99 targets). * Security considerations (PHI/PII, RLS, permissions). * Testing strategy (unit, integration, RLS, E2E). * Rollback strategy (for breaking changes). * Known limitations (deferred features, technical debt). * Defines: * Data model changes (entities, relationships). * Integration points and dependencies (documented in `/docs/architecture/integrations/`). * Success metrics (how we know it worked). ### 2.2 Process * **Spec → Implementation Plan → Tasks → Delivery → Completion Report.** * Any deviation from architecture or this constitution MUST be called out in the spec with rationale. **Rationale:** Spec‑first delivery reduces rework, aligns stakeholders, and creates institutional memory. ### 2.3 Spec Template All new specifications MUST use the template at `specs/_templates/SPEC_TEMPLATE.md`, which includes: * **Required Sections:** Business Context, Objectives, Scope, User Stories, Functional Requirements, Data Model, Integration Points, Performance Requirements, Security Considerations, Testing Strategy, Rollback Strategy, Known Limitations, Success Metrics, Implementation Plan. * **Integration Documentation:** All cross-core integrations must be documented in `/docs/architecture/integrations/` with event schemas or API contracts. See `docs/architecture/integrations/index.md` for overview. * **Constitutional Compliance:** Each spec includes a checklist ensuring compliance with architecture, database, security, testing, and documentation requirements. * **Implementation Plans:** For complex features requiring multi-phase implementation, data migrations, breaking changes, or cross-module coordination, create a separate implementation plan using `specs/_templates/PLAN_TEMPLATE.md`. The spec template includes guidance on when a separate plan is needed. *** ## 3. Testing & Quality Discipline Testing is a first‑class deliverable, not an afterthought. ### 3.1 Principles * Every business rule MUST be covered by automated tests. * Critical flows (auth, tenancy, billing, clinical, data movement) MUST have integration or end‑to‑end coverage. * No feature is “done” if tests are missing or flaky. * **“Done” means reachable capability, not artifact‑existence.** A spec is not complete because its files, tasks, or acceptance criteria exist on disk — it is complete when the terminal user action actually works. Dogfood it: stand the stack up and exercise the real path before claiming completion. * **A skipped test is unproven, not passing.** Treat green‑by‑skip (tests that `skipIf` a missing stack/seed/capability) as zero coverage for that claim, never as a pass. Prefer an honest failing result over a misleadingly green artifact, and state which path you actually ran. ### 3.2 Expectations * **Unit tests:** Core logic, utilities, hooks, isolated components. * **Integration tests:** Cross‑component flows, API contracts, RLS behavior, key DB workflows. * **E2E tests:** Priority journeys (e.g., admit resident → assign bed → bill → reconcile). Suggested targets (to be tuned as we mature): * New modules: \~80%+ coverage for core logic. * Platform and cross‑cutting utilities: \~80%+. * Overall baseline: a sustainable bar agreed by engineering leadership. **Rationale:** High‑risk domains (housing, finance, clinical, compliance) demand a strong testing posture to avoid regressions and production risk. ### 3.3 Test File Naming Conventions Consistent test file naming enables automatic discovery and clear organization. **File Naming Standards:** | Test Type | Pattern | Example | | ---------------- | ---------------------------- | ------------------------------- | | Unit - Hook | `{hookName}.test.ts` | `useEmployees.test.ts` | | Unit - Utility | `{utilityName}.test.ts` | `validation.test.ts` | | Unit - Component | `{ComponentName}.test.tsx` | `EmployeeForm.test.tsx` | | RLS | `{core}-{table}.rls.test.ts` | `hr-employees.rls.test.ts` | | Integration | `{core}-{workflow}.test.ts` | `hr-employee-lifecycle.test.ts` | | E2E | `{core}/{feature}.spec.ts` | `hr/employee-profile.spec.ts` | **Directory Structure:** ``` tests/ ├── unit/{core}/ # Unit tests by core ├── rls/ # RLS tests (flat, by table name) ├── integration/{core}/ # Integration tests by core ├── e2e/{core}/ # E2E tests (Playwright) ├── utils/ # Shared test utilities └── README.md # Testing documentation ``` ### 3.4 Public API Documentation Coverage Public function-like exports are part of product quality and maintainability and MUST be documented. * In-scope exported declarations (function declarations, classes, and function-valued exported constants) MUST include TSDoc/JSDoc comments. * Changed-file no-regression MUST be enforced before merge using `npm run docs:comments:audit:changed`. * Repository baseline coverage for in-scope declarations MUST be maintained at 100% unless an approved exception is documented in a spec/errata with owner and expiry. * Documentation comments MUST be meaningful (describe behavior and intent), not placeholder boilerplate. **Rationale:** API-level documentation reduces onboarding friction, review ambiguity, and regression risk when ownership changes or cross-core integration evolves. **Required Test Coverage by Feature Type:** | Feature Type | Unit | RLS | Integration | E2E | | --------------- | ---- | -------- | ----------- | -------- | | Database schema | - | Required | - | - | | CRUD operations | 80% | Required | Optional | - | | Business logic | 80% | Required | Required | - | | Critical flows | 80% | Required | Required | Required | **Test Templates:** Use templates from `specs/_templates/tests/` for consistent structure: * `RLS_TEST_TEMPLATE.ts` - Row-Level Security tests * `UNIT_TEST_TEMPLATE.ts` - Unit tests for hooks/utilities * `INTEGRATION_TEST_TEMPLATE.ts` - Workflow integration tests * `E2E_TEST_TEMPLATE.ts` - Playwright end-to-end tests **See Also:** `tests/README.md` for comprehensive testing documentation. *** ## 4. Data, Security & Privacy We operate as though under full HIPAA and payer audit from day one. ### 4.1 Security * Principle of least privilege for all users, services, and APIs. * All configuration secrets (keys, credentials, tokens) MUST be stored in secure environment management (not in code, migrations, or docs). * No backdoor “superuser” flows without explicit design, audit, and logging. ### 4.2 PHI / PII Handling * Use synthetic, de‑identified data in tests and examples. * Do NOT log free‑text PHI or full identifiers; prefer stable IDs and minimal necessary data. * Any export, report, or integration involving PHI MUST: * Be explicitly scoped in a spec. * Have a defined retention and access pattern. * **Regulatory compliance tracking:** Clinical and billing regulatory deadlines (e.g. 42 CFR Part 2, USCDI v3, CMS-0057-F, PDMP) MUST be tracked in `docs/compliance/REGULATORY_COMPLIANCE_TRACKER.md`. When a deadline is missed or at risk, interim procedures MUST be documented and followed until the responsible spec is implemented. **Rationale:** Security and privacy violations are existential risks for the organization and the communities we serve. *** ### 4.3 AI Integration Security The platform integrates AI capabilities via the **Vercel AI Gateway** (PF-111). All AI features MUST follow these security guidelines. #### 4.3.1 Architecture * AI features MUST use the Platform AI Integration Layer (`@/platform/ai`) * All AI calls MUST go through edge functions, NEVER direct client-side calls * Cores MUST NOT implement their own AI edge functions; use `ai-assistant` with module context * AI responses are stateless; conversation history is managed client-side #### 4.3.2 PHI Protection (CRITICAL) * **NEVER** send PHI/PII to external AI services * Sanitize all user input before including in AI prompts * Use anonymized identifiers (e.g., "Resident R-001" not "John Doe") * Module context provides audit trail of AI usage per organization * AI features SHOULD require user consent (settings toggle) #### 4.3.3 API Key Security * `AI_GATEWAY_API_KEY` is an Edge Function Secret (PM-15-P2); read it via `requireEnv('AI_GATEWAY_API_KEY')` in `_shared/ai/vercel-gateway.ts` * NEVER expose the API key to client code #### 4.3.4 Model Selection * Models are routed **per module**, not a single global default — see `STANDARD_MODELS` / `PHI_MODELS` in `supabase/functions/_shared/ai/models.ts` (each entry is a `[primary, fallback]` pair). E.g. `gr`/`hr`/`cl`/`pm` → `anthropic/claude-sonnet-4.6`; `fa` → `openai/gpt-4o`; `pf`/`rh`/`ce`/`fw` → `google/gemini-2.5-flash`; `lo`/`fm` → `google/gemini-2.5-flash-lite`. Update routing there, not inline. #### 4.3.5 Error Handling * 429 (Rate Limited): Show "Please wait and try again" * 402 (Payment Required): Show "AI credits depleted" with link to settings * 500 (Gateway Error): Show "AI temporarily unavailable" * Network errors: Graceful degradation, non-AI fallback when possible #### 4.3.6 Integration Pattern **Pattern:** Edge Function → Vercel AI Gateway → Response Stream ```typescript theme={null} // Client (via hook) import { useAIChat } from '@/platform/ai'; const { sendMessage } = useAIChat({ moduleContext: { module: 'hr', feature: 'onboarding' } }); // Edge Function (ai-assistant) const response = await fetch('https://ai-gateway.vercel.sh/v1/chat/completions', { headers: { Authorization: `Bearer ${requireEnv('AI_GATEWAY_API_KEY')}` }, body: JSON.stringify({ messages, stream: true }) }); ``` #### 4.3.7 Module Context All AI requests MUST include module context for audit and specialization: * `module`: Core code (`pf`, `rh`, `fa`, `hr`, `gr`, `fw`, `fm`, `lo`, `it`, `ce`, `cl`, `pm`) * `feature`: Specific feature within module * `contextData`: Additional metadata for prompt customization * `jurisdictionProfileId`: (optional) When the AI feature operates in a jurisdiction-sensitive context (CL, PM, GR), include the organization's jurisdiction profile ID so AI responses can be tailored to the correct state's regulations and compliance rules. AI prompts MUST NOT include PHI/PII regardless of jurisdiction context. **Rationale:** Centralized AI integration ensures consistent security, audit trails, and cost management across all modules. Jurisdiction context enables state-aware AI advice without duplicating compliance logic. *** ### 4.4 Permissions System Architecture (PF-30) The platform implements a **three-tier permission system** for granular access control: **Tier 1: Module Permissions (PF-30)** * Format: `{module}.{entity}.{action}` * Examples: `hr.employees.view`, `fa.bills.approve`, `rh.residents.create` * Categories: `view`, `create`, `edit`, `delete`, `approve`, `admin` * Defined in `pf_module_permissions` table (1,600+ permissions; baseline seed + \~19 `*_permissions_sync_*` migrations) * See `docs/pf/module-permissions-matrix.md` for complete catalog **Tier 2: Object Permissions (PF-26)** * Entity-level access with actions (view, create, edit, delete) per role * Defined per record or record type **Tier 3: Field-Level Permissions (PF-26)** * Field visibility rules per role * Controls which fields users can see/edit **Permission Check Hierarchy:** ``` Module Permission (PF-30) → Object Permission (PF-26) → Field Permission (PF-26) ``` If any tier fails, access is denied. **Custom Roles:** * Organizations can create custom roles with specific permission sets * Custom roles can optionally inherit from system roles (`staff`, `readonly`, `site_admin`) * Custom roles **CANNOT** inherit from `org_admin` or `platform_admin` (security constraint) * See `pf_custom_roles` and `pf_role_permissions` tables **Role Assignment:** * Users assigned via `pf_user_role_assignments` table * Supports site-scoped assignments (`site_ids` column) * Supports time-limited access (`expires_at` column) * Users can have multiple roles **System Status:** * V2 is the only active permission system * All organizations use granular permissions exclusively * Legacy `pf_user_roles` table is read-only (retained for audit/rollback purposes) **Rules:** 1. All UPDATE RLS policies for permission tables MUST include `WITH CHECK` clause 2. Permission checks MUST use `pf_has_permission()` SECURITY DEFINER function 3. Navigation filtering MUST use permission-based access control 4. Permission checks are cached for 5 minutes (React Query staleTime) 5. Custom roles scoped to organization (multi-tenant isolation) **Rationale:** Granular permissions enable organizations to customize access control beyond fixed roles while maintaining security through explicit allow-listing. *** ## 5. Database, Naming & Environment Guardrails The database is a core part of the platform, not an implementation detail. We treat it as product. ### 5.1 Multi‑Tenant Data Model * All business data tables MUST include tenant context (for example `organization_id`, and `site_id` where applicable). * **Application-layer filter:** Filtering by `organization_id` (and `site_id` where applicable) is **REQUIRED** on all mutations (INSERT, UPDATE, DELETE) as defense-in-depth. It is **RECOMMENDED** on SELECT queries as defense-in-depth alongside RLS; RLS remains the primary enforcement for reads. * **Row‑Level Security (RLS)** (or equivalent mechanism) MUST be enabled and enforced on all business tables. * RLS policies MUST guarantee: * No cross‑organization data leakage. * Restricted cross‑site visibility according to defined roles. * Any change to RLS MUST be accompanied by test coverage validating the tenant‑isolation behavior. * **Jurisdiction-aware configuration:** Organization-level and site-level business rules that vary by state Medicaid program (e.g., clinical assessment requirements, billing thresholds, filing deadlines, documentation timeliness) SHOULD be read from the jurisdiction profile system (PF-96) when available. Until PF-96 is implemented, state-specific configuration MAY use module-level settings with documented migration paths and TODO(PF-96) markers. New features in CL and PM MUST NOT introduce state-specific constants without a TODO(PF-96) marker; they SHOULD consume values from `pf_jurisdiction_profiles`, `pf_org_jurisdiction_config`, or `pf_site_jurisdiction_config` once available. See `specs/pf/specs/PF-96-medicaid-state-compliance-configuration.md`. ### 5.2 Database Naming Conventions **Schemas** * Prefer a single primary application schema (e.g., `public`) unless a compelling separation exists. * If multiple schemas are used, each schema MUST have a documented ownership and purpose. **Tables** * All table names use `snake_case` and should be plural (e.g., `rh_residents`, `fa_transactions`). * Tables owned by a core MUST be prefixed with that core: * `pf_` – Platform Foundation (e.g., `pf_users`, `pf_organizations`, `pf_sites`). * `rh_` – Recovery Housing (e.g., `rh_residents`, `rh_beds`, `rh_phases`). * `fa_` – Finance (e.g., `fa_transactions`, `fa_ledgers`). * `hr_` – Workforce & HR (e.g., `hr_employees`, `hr_credentials`). * `gr_` – Governance & Learning (e.g., `gr_policies`, `gr_training_events`). * `fw_` – Forms & Workflow (e.g., `fw_forms`, `fw_workflow_runs`). * `fm_` – Facilities & Maintenance (e.g., `fm_work_orders`). * `cl_` – Clinical & EHR (e.g., `cl_patient_charts`, `cl_progress_notes`, `cl_prescriptions`). * `pm_` – Practice Management (e.g., `pm_patients`, `pm_claims`, `pm_appointments`). * Junction tables use both entities with an underscore, ordered alphabetically (e.g., `rh_resident_phases`, `fa_transaction_tags`). **Columns** * All column names use `snake_case`. * Primary keys: * Prefer `id` as the primary key column, with type `uuid` or integer as documented in the DB architecture. * If a natural key is used, it MUST be documented in the spec. * Foreign keys: * Use `_id` corresponding to the referenced table (e.g., `resident_id`, `organization_id`, `site_id`). * Standard audit columns: * `created_at` (UTC timestamp). * `updated_at` (UTC timestamp). * `created_by` (user ID, where applicable). * `updated_by` (user ID, where applicable). * Soft‑delete pattern (where used): * `deleted_at` (nullable UTC timestamp). * Records with `deleted_at` not null are considered logically deleted. ### 5.2.1 Custom Fields & Extensibility **Purpose:** Enable organizations to extend business entities with domain-specific metadata without schema changes. **When to Use `custom_fields`:** All business entity tables MUST include `custom_fields JSONB DEFAULT '{}' NOT NULL` unless: * The table is purely a junction/mapping table (e.g., `hr_team_members`, `rh_resident_phases`). * The table is an audit/log table (e.g., `pf_audit_logs`, `fw_automation_logs`). * The table is a system/configuration table managed exclusively by the platform. **Examples of business entities requiring custom\_fields:** * Core entities: `pf_profiles`, `hr_employees`, `rh_residents`, `fa_transactions` * Workflow entities: `fw_form_submissions`, `fw_automation_rules`, `hr_onboarding_instances` * Document entities: `pf_documents`, `hr_employee_credentials` **Custom Fields vs. Settings vs. Preferences:** | Concept | Purpose | Scope | Example Use Case | | ------------------- | --------------------------------------- | ---------------------------- | ----------------------------------------------------------------------- | | **`custom_fields`** | Organization-specific business metadata | Per-record, per-organization | `{"badge_number": "12345", "external_case_id": "CASE-001"}` | | **`settings`** | Module/system-wide configuration | Per-module, per-organization | `hr_module_settings.default_alert_days = [90, 60, 30]` | | **`preferences`** | User-specific app behavior | Per-user, cross-organization | `pf_profiles.preferences = {"theme": "dark", "notifications": "email"}` | **Design rules (summary):** * Include `custom_fields` in migrations with `COMMENT ON COLUMN` and 3–5 realistic examples (not generic placeholders). * Query with `?`, `->>`, `@>` as needed; add a GIN index on `custom_fields` when queried heavily. * `custom_fields` inherits the table’s RLS; do not store secrets (SSN, passwords) in JSONB. **Playbook:** Migration snippets, table template, and patterns: [docs/development/DATABASE\_DEVELOPMENT\_GUIDE.md](/development/DATABASE_DEVELOPMENT_GUIDE) § Creating Tables with RLS and Custom Fields. **New Table Checklist:** When creating a new business entity table, developers/AI MUST: * ✅ Include `organization_id` (multi-tenant context) * ✅ Include `custom_fields JSONB DEFAULT '{}'` (extensibility) * ✅ Include `created_at`, `updated_at` (audit trail) * ✅ Add `COMMENT ON COLUMN` with 3-5 example use cases * ✅ Enable RLS policies * ✅ All UPDATE policies include `WITH CHECK` clause (see §5.2.9) * ✅ Document in spec and IMPLEMENTATION\_LOG.md ### 5.2.2 Organizational Data Structure **Purpose:** Standardize organizational data entities across all modules for consistent policy assignment, access control, and reporting. **Platform Foundation Organizational Entities:** * **Sites** (`pf_sites`): Physical work locations with tax jurisdiction and address * **Departments** (`pf_departments`): Unified organizational units (operational + cost centers) * **Levels** (`pf_levels`): Employee classification with numerical ranking * **Positions** (`pf_positions`): Job title library for consistency * **Teams** (`pf_teams`): Cross-functional groups **Design Rules:** 1. **Unified Departments:** Use `pf_departments` for both HR and FA (not separate tables) * `department_type` field: 'operational' | 'cost\_center' | 'both' * Single source of truth eliminates duplication 2. **Work Location:** Use `primary_site_id` (NOT `work_location` TEXT) for employee location * `pf_sites` includes `tax_jurisdiction`, `address` fields, `timezone` for structured operations 3. **Level Assignment:** All employees should have `level_id` for policy assignment * Levels enable level-based policies (spend policies, access control) * `level_rank` (1-10) for ordering and formula fields 4. **Site Usage:** Include `site_id` (nullable) when entity is location-specific * Required for: residences, work orders, assets, site-specific policies/forms * Optional for: organization-wide entities (strategic goals, vision) 5. **Programs:** `rh_programs` (operational) and `fa_programs` (financial) serve different purposes * `rh_programs`: Resident program structure, phase management * `fa_programs`: Medicaid cost reporting, grant tracking * Optional relationship: `fa_programs.rh_program_id` for financial tracking **Module-Specific Organizational Entities:** * **RH:** `rh_programs` (operational/resident programs) * **FA:** `fa_programs` (financial/cost reporting programs), `fa_funds` * **HR:** `hr_employees`, `hr_employee_sites` **Jurisdiction Profile Assignment:** * Organizations MUST have a `jurisdiction_profile_id` FK to `pf_jurisdiction_profiles` (PF-96) * Sites MAY override the organization's jurisdiction profile via `pf_site_jurisdiction_config` for multi-state operations (e.g., telehealth providers operating across state lines) * The jurisdiction profile provides state-specific clinical, billing, and compliance configuration consumed by CL, PM, and GR features * Profile resolution order: site override → organization profile → federal baseline defaults **Integration:** * All modules reference `pf_departments`, `pf_sites`, `pf_levels`, `pf_teams` * CL and PM modules reference `pf_jurisdiction_profiles` for state-specific rules * No cross-core dependencies (all via Platform Foundation) * Organizational data managed through Platform Foundation, consumed by domain cores **Rationale:** Unified organizational data structure enables consistent policy assignment, access control, and reporting across all modules while maintaining clear architectural boundaries. Jurisdiction profiles extend this to state-specific compliance configuration. ### 5.2.3 Module Settings Pattern **Purpose:** Enable organization-level configuration of module behavior without code changes or environment-specific configuration. **When to Use Module Settings:** Every domain core (HR, FW, RH, FA, etc.) SHOULD have a module settings table and admin page unless the module has no configuration requirements. **Required Components:** 1. **Settings Table:** `{core}_module_settings` * One row per organization (1:1 relationship) * Contains configuration columns specific to the module * Includes standard audit columns (`created_at`, `updated_at`, `created_by`, `updated_by`) * RLS policies: View (org users), Insert/Update (org\_admin only) 2. **Admin Page:** `src/cores/{core}/pages/{Core}Settings.tsx` * Route: `/{core}/settings` * Access: `org_admin` only (enforced in navigation and route) * Tabbed interface organizing related settings * Auto-creates settings record if not exists 3. **Hook:** `src/cores/{core}/hooks/use{Core}ModuleSettings.ts` * Query hook: Fetch organization's settings * Mutation hooks: Create/update settings * Handles loading states, errors, cache invalidation 4. **Form Component:** `src/cores/{core}/components/{Core}SettingsForm.tsx` * Tabbed form matching logical groupings * Form validation with Zod schemas * Save/reset actions with confirmation **DDL template:** [docs/development/DATABASE\_DEVELOPMENT\_GUIDE.md](/development/DATABASE_DEVELOPMENT_GUIDE) § Constitution playbook: PF DDL templates — Module settings table. **UI pattern:** [docs/development/settings-pattern-guide.md](/development/settings-pattern-guide) — shared settings layout, skeletons, and form structure. **When to use settings vs elsewhere (decision rule):** * ✅ **Settings** when organizations differ in requirements/preferences — time-based values, business-rule thresholds, UI/UX defaults, performance tuning, feature behavior. * ✅ **Jurisdiction profile (`pf_jurisdiction_profiles`, PF-96)** when the value varies by state Medicaid program (filing deadlines, timed-code thresholds, assessment / documentation-timeliness rules). Module settings override profile defaults only when an org explicitly customizes beyond its jurisdiction baseline. * ❌ **Hard-code** only system constants (enum values, system-wide limits). When writing a spec, identify hard-coded values and document them in the spec's "Settings Considerations" section. Admin-page requirements, the per-core status matrix, the new-core implementation checklist, and examples are the extended reference — see [settings-pattern-guide.md](/development/settings-pattern-guide); do not duplicate them here. ### 5.2.4 Centralized Picklist System **Purpose:** Enable organizations to define and manage custom picklist values without code changes or database migrations, providing flexibility for domain-specific workflows. **When to Use Picklists vs Enums:** | Scenario | Use Picklist | Use Enum | | ------------------------------ | ------------ | -------- | | Values vary by organization | ✅ Yes | ❌ No | | Values change frequently | ✅ Yes | ❌ No | | Users need to customize | ✅ Yes | ❌ No | | Values are system constants | ❌ No | ✅ Yes | | Values need strict type safety | ❌ No | ✅ Yes | **Playbook:** Table DDL, indexes, and example RLS: [docs/development/DATABASE\_DEVELOPMENT\_GUIDE.md](/development/DATABASE_DEVELOPMENT_GUIDE) § Constitution playbook — Picklists. Application hooks and UI: `specs/pf/PF-15-picklist-system.md`. Custom field definitions may reference `picklist_id` on `pf_custom_field_definitions` (same guide § Custom field definitions). **Spec-Authoring Checklist (Picklist Evaluation):** When a spec introduces new status fields, categories, types, reasons, or any dropdown/select option list: * [ ] Evaluate each value list against the Picklists vs Enums table above * [ ] Document the decision in the spec's **Enums and Source Types** section: `Picklist: Yes (org-customizable) | No (system constant, reason: ___)` * [ ] If picklist: add a task to seed default picklist values via migration (`INSERT INTO pf_picklists / pf_picklist_items`) * [ ] If picklist: reference in forms via `usePicklistItems(picklistId)` instead of hardcoded `