# MetaFlow ACCESS Core Database

Canonical normalized database for MetaFlow's participation in CMS's ACCESS (Advancing Chronic Care with Effective, Scalable Solutions) Model.

## Architecture

- **Database:** PostgreSQL (Django ORM, 91 models across 7 apps)
- **Framework:** Django 4.2–5.0
- **Cloud:** AWS (Fargate, RDS, S3, SQS, KMS, Secrets Manager, CloudWatch)
- **Patient Platform:** Healthie (GraphQL API, webhooks, forms, daily check-ins)
- **Migration Source:** Cognito Forms (one-time REST API export, not live)

## Django Apps

| App | Purpose | Models |
|---|---|---|
| `identity` | Users, roles, beneficiaries, consents, external IDs | 9 |
| `intake` | Intake records, assessments, screening, raw ingestion | 12 |
| `clinical` | Observations, labs, PROMs, imaging, OAP measures, standards | 19 |
| `cms_integration` | CMS API requests/responses, claims, payments, recoupment | 5 |
| `governance` | Audit events, safety signals, physician review, offshore pseudonymous review | 8 |
| `monitoring` | Care periods, eligibility requests/checks, alignment, monitoring plans, daily check-ins, adherence | 26 |
| `curation` | Curation tasks, observation drafts, documents, reporting views | 12 |

## Key Design Decisions

- **Two-stage identity:** `intake_records` (pre-enrollment) → `beneficiaries` (after CMS eligibility + consent + alignment)
- **Healthie-first model:** Healthie handles all patient-facing workflows. Cognito is migration source only.
- **PHI encryption:** App-level AES-256-GCM (`enc:v1` envelopes) — DOB encrypted at rest today (KMS in staging/prod, local key in dev/test); name/email/phone rollout follows. SSNs not stored. See `docs/security/PHI_Pseudonymization_Design.md` for the offshore case_id design.
- **Audit logging:** Append-only `audit_events` table (model implemented; write path pending) — changed field names + SHA-256 value hashes, never raw PHI.
- **Canonical data model:** `oap_measure_observations` reference `clinical_observations` (reporting projection, not duplicate).

## Documentation

| Document | Path |
|---|---|
| Technical Assessment (v0.3) | `docs/architecture/Technical_Assessment.md` |
| Database Schema (v0.3) | `docs/architecture/Database_Schema_Draft.md` |
| Data Flow (v0.3) | `docs/architecture/Data_Flow_Diagram.md` |
| AWS Components (v0.3) | `docs/architecture/AWS_Component_Diagram.md` |
| Integration Roadmap (v0.3) | `docs/architecture/Future_Integration_Roadmap.md` |
| Cost Estimate (v0.3) | `docs/architecture/AWS_Cost_Estimate.md` |
| Traceability Matrix (v0.3) | `docs/architecture/ACCESS_Traceability_Matrix.md` |
| Healthie Integration (validated) | `docs/healthie/Healthie_Integration_Mapping.md` |
| Healthie Post-Enrollment | `docs/healthie/Healthie_Post_Enrollment_Workflow_Notes.md` |
| Security Plan (v0.3) | `docs/security/Security_Access_Control_Plan.md` |
| PHI Pseudonymization Design | `docs/security/PHI_Pseudonymization_Design.md` |
| AWS Infrastructure (Terraform) | `infra/README.md` |
| Cognito Migration Spec | `docs/architecture/Healthie_Forms_Vs_Cognito.md` |
| Cognito Field Mapping | `docs/intake/Cognito_Field_Mapping.md` |

## Local Development

```bash
# Start the stack (migrations and fixture loading run automatically on first startup)
docker compose up -d django

# Run tests
docker compose run --rm tests

# Re-run migrations manually (if schema changed after initial start)
docker compose exec django python manage.py migrate

# Load synthetic seed data (or use the full-featured command below)
docker compose exec django python manage.py seed_synthetic_data

# Alternative: load fixtures directly
docker compose exec django python manage.py loaddata sample_data/fixtures/synthetic_seed_data
```

## Diagrams

SVG diagrams in `docs/diagrams/`: data flow, system boundaries, webhook ingestion, AWS components, integration roadmap, data curation, identity lifecycle, role permissions, PHI encryption, CI/CD, safety signals, reporting pipeline, and more.