# Technical Assessment v0.3 — Healthie-First Architecture

## Project Summary / Current Understanding

We are building the ACCESS Core Database — the central, normalized ledger for MetaFlow's participation in CMS's ACCESS (Advancing Chronic Care with Effective, Scalable Solutions) Model. **Healthie is the unified patient-facing and clinical workflow platform** (intake forms, daily check-ins, care plans, charting). **ACCESS Core DB** serves as MetaFlow's canonical normalized database for ACCESS status, care periods, OAP Measures, monitoring plans, structured outcomes, enhanced evidence, CMS submissions, and audit history.

It operates on a two-layer data model:
- **ACCESS OAP Layer** — CMS-required clinical track reporting, payment reconciliation, and compliance/audit readiness.
- **MetaFlow Enhanced Evidence Layer** — Internal clinical governance, daily patient execution logs, structural evidence (imaging, labs), and adherence tracking.

Every clinical value carries full provenance — source, collection date, validity window, entry/review users, and submission status — with corrections creating new audit events rather than overwriting prior values. Data flows through a human-reviewed curation pipeline (raw ingestion → draft → QC → physician approval → approved → locked → submitted) before entering the official ledger. Role-based access controls plus DOB field encryption (name/email/phone rollout pending) define what each user role can see, and the designed pseudonymized view layer will isolate offshore clinical reviewers from all identifiable data (runtime service deferred — see `docs/security/PHI_Pseudonymization_Design.md`).

The key technical requirements for Phase 1 are to design the database schema, map how data flows from intake through curation into the reporting and evidence layers, establish security and access-control boundaries, and produce the architecture documentation that will guide future implementation.

---

## Key Risks & Missing Pieces

### Blocked Items (awaiting client action)

1. ~~**Cognito sandbox / test form access**~~ — **RESOLVED.** Cognito form definition JS extracted (`sample_data/cognito_form_data.js`) provides complete field labels, types, choices, conditional visibility, helptext, and page structure. Migration mapping YAML generated (`Cognito_to_Healthie_Form_Mapping.yaml`) with 80+ fields across 19 sections. Cognito is the migration source only; Healthie is the target platform.

    **Cognito webhook payload — not yet observed.** The form definition JS gives us all field data, but we have not observed the actual Cognito webhook payload. The sample JSON (`sample_data/MetaFlowEnrollmentAssessment.json`) is from an XLSX export, which may differ from the webhook format. **This risk is mitigated** because Cognito is the form field migration source only — the Cognito form was rebuilt in Healthie using the extracted field definitions. Healthie handles all patient intake with documented GraphQL API.

    **Cognito's OpenAPI spec** (`CognitoFormsOpenAPI-*.json`) was reviewed. Key findings:

    - **Form Schema endpoint exists** (`GET /forms/{formId}/schema`) — response documented only as `"type": "object"` with zero property definitions. **No longer a concern** — the form definition JS provides complete field data.
    - **EntryOutput is documented** for the REST API — `Entry` metadata object (`DateCreated`, `DateSubmitted`, `Status`, etc.) is defined.
    - **Prefill format is documented** — input format for programmatically filling forms.

    **Note:** explicit field-to-column mapping is required regardless of platform since DB columns are hardcoded. Healthie's `custom_module.id` values and `FormAnswerGroup` response are fully documented and queryable at runtime.

2. **Healthie sandbox testing** — ~~Blocked~~ → **In Progress.** Sandbox validated (July 2026): GraphQL API, lightweight webhook pointers, patient creation flow. Next: rebuild Cognito intake form in Healthie using `Cognito_to_Healthie_Form_Mapping.yaml`. Validate: multi-step questionnaire, sex-based branching, file uploads, signatures/consent, recurring daily check-ins, charting templates. Waiting on Enterprise sales proposal for full sandbox access. See `docs/healthie/Healthie_Integration_Mapping.md`.

3. **Prior technical tester materials** — The brief references "notes from the initial ACCESS technical/database connection test" (§20.2, item 3), and the client has requested review of sanitized ACCESS API test code, synthetic request/response payloads, and CMS submission logs. These materials are not present in the repository, and no contact information for the prior tester has been provided. The ACCESS Requirements Traceability Matrix can be partially built from the ACCESS Participation Agreement and API documentation, but the "test evidence" column will remain incomplete until these materials are shared.

### Design Risks

4. **Data retention policy undefined** — Raw ingestion records are preserved for provenance (§12), but no policy exists for how long raw records, daily logs, rejected intake records, or withdrawn patient records are retained. This affects schema partitioning, storage cost, and HIPAA compliance.

5. **PHI handling** — The core DB stores identity/contact PHI in place rather than stripping it; today only DOB is field-encrypted (`enc:v1` envelopes, KMS-backed in staging/prod), with name/email/phone rollout to follow. The offshore de-identified review boundary (§13) requires a pseudonymization/redaction mechanism — technically designed in `docs/security/PHI_Pseudonymization_Design.md` (HMAC case_id + Safe Harbor mapping), runtime service deferred.

6. **Source-of-truth boundaries between Healthie and the Core DB** — Simplified to two systems (Healthie = patient-facing clinical platform, Core DB = canonical normalized ledger). Integration boundaries defined in `Healthie_Integration_Mapping.md` and `Healthie_Forms_Vs_Cognito.md` (form field migration spec).

7. **No environment policy** — Dev/staging/prod separation, secrets management, migration strategy, and backup policy are listed as "still needed" (§23, item 8).

---

## Recommended Architecture

### Database

PostgreSQL will be used as our database. It supports the JSONB, array, UUID, and encrypted-field patterns required by the schema. See `Database_Schema_Draft.md` for the current schema draft.

### Application Framework

I recommend Django. It is a Python-based framework that provides:
- An ORM with migration tooling (Alembic-equivalent) for schema version control.
- A built-in admin interface usable for data curation, physician review, and internal operations.
- Built-in authentication and group-based permissions as a foundation for the 9+ user roles defined in the brief.

Django does not include built-in PHI field encryption. Encryption and key management require a separate design (see PHI Encryption section below).

### PHI Encryption & Key Management

Django provides the ORM, authentication, permissions, and admin interface. The proposed approach below is **partially implemented**: DOB field encryption (`enc:v1` envelopes) is live; name/email/phone/address/MBI remain plaintext pending a follow-up rollout. See `access_core/services/phi_crypto.py` for the shipped implementation.

- **Application-level field encryption** — Target: PHI fields (name, DOB, email, phone, address, MBI) encrypted at the application layer before being written to the database; decryption only under appropriate RBAC. Current: DOB only (`EncryptedDateField`).
- **Encryption algorithm** — AES-256-GCM (authenticated encryption) per field, using per-field data encryption keys (DEKs).
- **Key management** — AWS KMS (Key Management Service) for master key storage and DEK encryption/decryption. KMS handles key rotation and access logging.
- **Key rotation** — KMS supports automatic key rotation (annual by default). DEKs can be re-encrypted under new KMS keys during a scheduled maintenance window.
- **Access boundaries** — Identity data (name, DOB, contact) is stored in a separate table (`intake_records` / `beneficiaries`) from clinical data. Clinical data tables reference identity by UUID FK only. Offshore pseudonymous review tables contain no identity data.
- **Scope** — This is a Phase 1 design decision. The specific implementation library (e.g., `django-encrypted-model-fields`, custom KMS-backed encryption) and production key management policy should be validated before implementation.

### Cloud Provider

I recommend AWS (Amazon Web Services). It is the provider I have the most experience with and is widely adopted for healthcare workloads.

**Primary services:**
- **Amazon S3** — Object storage for clinical documents (lab PDFs, imaging reports, PROM screenshots). Server-Side Encryption with KMS (SSE-KMS), versioning, S3 Block Public Access, restricted bucket policies, object access logging, and lifecycle/retention rules.
- **Amazon RDS** — Managed PostgreSQL hosting. Automated backups with point-in-time recovery.
- **AWS Fargate** — Serverless container hosting for the Django application. Supports rolling deployments and auto-scaling.
- **AWS Secrets Manager** — Storage of API tokens, database passwords, encryption keys, and other sensitive configuration values. Access controlled via IAM.
- **AWS KMS** — Key management for PHI field encryption and S3 server-side encryption.
- **Amazon SQS** — Managed message queue for asynchronous webhook ingestion. Decouples webhook receipt from processing; provides dead-letter queue support.
- **Amazon CloudWatch** — Application and infrastructure logging, metrics, and alerting.
- **AWS CloudTrail** — API call auditing for security and compliance logging.
- **AWS CodePipeline** — CI/CD pipeline for automated testing, container build, and deployment.
- **Amazon VPC** — Private network isolation. All services communicate over private endpoints; no public Internet access to the application or database.
- **AWS Healthcare Compliance** — AWS provides HIPAA-eligible services and compliance documentation (https://aws.amazon.com/health/healthcare-compliance/).

**Other cloud providers** we can evaluate if AWS is not an option:
- DigitalOcean
- Microsoft Azure
- Google Cloud Platform

### Data Intake & Webhook Design

**Primary approach: Webhooks with polling reconciliation.**

Healthie is the primary webhook source. Webhooks are more efficient than polling and deliver data in near-real-time. The proposed design:

**Note:** Healthie has a built-in form builder (Form Templates + Onboarding Flows) that provides a fully documented GraphQL schema for form data. Healthie's `custom_module.id` keys are stable and queryable. See `Healthie_Forms_Vs_Cognito.md` for migration analysis.

**Important:** Healthie webhooks are lightweight pointers only:
- **Healthie:** Sends a lightweight pointer only (`resource_id`, `resource_id_type`, `event_type`, `changed_fields`) — two-step ingestion (worker must make a follow-up GraphQL query to fetch full resource data)

1. **SQS as ingestion buffer** — Webhook POST events from Healthie arrive at the ALB and are placed directly into SQS. SQS is the ingestion point; it buffers all webhook payloads so nothing is lost if the application is temporarily down.

2. **Fargate worker consumption** — Django workers consume messages from SQS, perform HMAC-SHA256 signature verification, fetch full resource data via GraphQL query, store the raw payload in `raw_ingestion_records`, normalize into canonical tables, and delete the SQS message on success.

3. **Dead-letter queue** — Messages that fail processing after N retries are routed to a dead-letter queue for manual inspection.

4. **Polling reconciliation** — A scheduled job (e.g., every 15 minutes) queries Healthie via GraphQL (e.g., `documents(private_user_id)`, `formAnswerGroups(user_id, date)`) for submissions in the last N minutes that do not exist in `raw_ingestion_records`. Polling uses GraphQL queries to fetch full resource data directly — no follow-up step needed. This catches any webhook deliveries that were missed.

5. **Idempotency** — `raw_ingestion_records.source_record_id` is unique. Both webhook and polling paths deduplicate against this field.

6. **No direct writes to the approved ledger** — Webhooks write only to `raw_ingestion_records` (raw, unprocessed). Normalization and curation proceed through the established pipeline.

**Cognito form field migration (completed):** Cognito form definition JS extracted → `Cognito_to_Healthie_Form_Mapping.yaml` → Healthie form rebuilt. No submission data to migrate — all intake originates from Healthie.

### CI/CD Pipeline & Deployment

We should use a single primary code branch (`main`) and promote the same tested container artifact through staging and then production, rather than relying on long-lived environment branches that may diverge.

**Pipeline stages:**
1. Run automated tests — halt deployment on failure.
2. Run security checks (dependency scanning, secret detection).
3. Build the application container.
4. Validate database migrations (dry-run, backward-compatibility check).
5. Deploy container to staging.
6. Approval gate (manual sign-off).
7. Promote the same container artifact to production.

**Database migration strategy:**
- Migrations are applied as a controlled step within the deployment pipeline, not solely on container startup.
- An expand-and-contract (backward-compatible) migration approach is used: new columns/tables are added before old ones are removed, ensuring the previous version of the application can survive the migration.
- A pre-deployment database backup is taken before production migrations.
- Rollback procedures are documented for each migration (e.g., revert migration, restore backup).

**Containerization:**
- Docker packages the core database application. It enables local development in an environment matching staging/production.
- At minimum, a development, staging, and production environment should exist.

**Secrets:**
All secret keys (API tokens, private credentials) are stored in AWS Secrets Manager. The application retrieves secrets at runtime via IAM-authorized API calls. Secrets are never stored in code, environment variables committed to the repository, or Docker images. Key rotation occurs quarterly or when a provider mandates it.

Secrets managed:
- Healthie API key
- ACCESS CMS API key
- Database password
- KMS encryption keys (managed by KMS, not Secrets Manager)

### AWS Security Architecture (Proposed)

For protected documents and data, the following controls are proposed:
- **S3:** Block Public Access, SSE-KMS, versioning, object access logging, restricted bucket policies, lifecycle/retention rules.
- **RDS:** Encrypted at rest (KMS), TLS in transit, private subnet only, automated backups.
- **VPC:** No public subnets for application or database. Private endpoints for S3, Secrets Manager, and KMS via VPC endpoints.
- **IAM:** Least-privilege policies. Each service (Fargate task, CI/CD pipeline, application) has its own IAM role with only the permissions it needs.
- **CloudTrail:** All API calls logged for compliance and security monitoring.
- **CloudWatch:** Application logs, error metrics, and alerting for failed webhook deliveries, queue depth, and deployment failures.

---

## Additional Information Needed

### Required to proceed with meaningful schema design:

1. **Cognito test/preview link** — **RESOLVED.** Cognito form definition JS extracted and parsed into `Cognito_to_Healthie_Form_Mapping.yaml` (80+ fields, 19 sections). Cognito is the migration source only; Healthie is the target platform.
2. **Cognito field export or screenshots** — **RESOLVED.** Form definition JS provides complete field labels, types, choices, conditional visibility, helptext, and page structure.
3. **Cognito Forms → Healthie Forms migration assessment** — **RESOLVED.** See `docs/architecture/Healthie_Forms_Vs_Cognito.md`. Migration mapping YAML generated with complete field-level detail.
4. **Technical handoff notes** from the initial ACCESS technical/database connection test — prior decisions, early code, lessons learned.
5. **Any organizational preference on backend framework or cloud provider** — or confirmation that my recommendations (Django + AWS) are acceptable.

### Required before Month 1 completion:

5. **Healthie workflow decision** — ~~Blocked~~ → **RESOLVED.** Data flow matrix and source-of-truth matrix defined in `docs/healthie/Healthie_Integration_Mapping.md`.
6. **Daily check-in template** — exact questions for CKM/eCKM and MSK with red/yellow/green safety rules.
7. **Source-of-truth matrix** — ~~Blocked~~ → **RESOLVED.** Defined in `docs/healthie/Healthie_Integration_Mapping.md` (Source of Truth Matrix table).
8. **Data retention policy draft** — how long raw records, daily logs, withdrawn patient records are kept.
9. **Environment policy** — ~~Blocked~~ → **Partially resolved.** Defined in `docs/security/Security_Access_Control_Plan.md` (Environment Separation section). Docker dev environment scaffolded.
10. **Prior technical tester materials** — ACCESS API test code, sanitized synthetic payloads, CMS submission logs.

### Open decisions requiring business, clinical, legal, or compliance input:

- Whether SSNs should be stored (no confirmed requirement exists; proposed: do not store unless required).
- Final patient consent, authorization, and data-sharing requirements per ACCESS Participation Agreement §7 and §8.
- Data retention periods for raw ingestion, daily logs, withdrawn patients, and CMS-related records.
- Offshore clinical review scope and data boundaries (pseudonymization requirements, prohibited data elements).
- Open compliance questions that require attorney review rather than contractor judgment (per brief §23, item 11).