Healthtech — patient portal

Entities (4)

These are the persistent business objects. Field-level annotations (`phi`, `pci_scope`, `eu_pii`) drive the compliance overlay decisions.

Process flows (2)

Capabilities + integrations

• auth.universalproduction
• rbac.tier-2production
• audit.append_onlyproduction
• audit.tamper_evidentproduction
• search.fulltextproduction
• payment.orchestrationproduction
• security.policiesproduction

Integrations: Twilio · SendGrid · Stripe

Architecture brief

# Healthtech reference architecture — patient portal

## Who this is for

Telehealth providers, multi-state primary-care chains, clinical
research platforms, healthtech SaaS for physician offices. Anyone
covered by HIPAA whose customers expect a real auditor-ready
artifact set on day one.

## What's in scope

- **Patient + ClinicalNote** — every PHI field flagged `phi: true`.
  ClinicalNote is `contains_phi: true` at the entity level (the
  whole row is PHI even when individual fields aren't tagged).
- **Appointment scheduling** — straightforward CRUD + Twilio SMS
  reminders.
- **Provider directory** — NPI numbers; not PHI-tagged because the
  HIPAA scope is around patient data, not provider identity.
- **PHI audit decorator** — emitted by the C01 HIPAA overlay; reads
  through this decorator emit an audit_event into the tamper-evident
  chain.
- **BAA tracking** — Twilio + SendGrid both `data_handled: phi`, so
  the C01 BAA tracker auto-populates with both vendors as
  BAA-required.
- **PHI search** — Patient + ClinicalNote both `searchable: true`,
  driving the G03 search infra generator. The PHI fields stay in the
  search index but read-time PII redaction (when not admin) is
  handled by the audit decorator's actor check.

## Compliance bundles produced

- **HIPAA**: control_matrix.md (30 Security Rule controls per 45 CFR
  §164.308–.316 mapped to ✅/📝/—), baa_tracking.md (Twilio +
  SendGrid pre-populated), risk_assessment.md, breach_notification_runbook.md
  (60-day OCR clock + portal template), phi_data_flow.mmd Mermaid
  diagram.

## Build-time savings

| Build path | Time |
|---|---|
| Manual senior-eng team + HIPAA consultant | 12-24 weeks (most time on the consultant) |
| Replit / Lovable | "TODO scope" — they don't ship HIPAA artifacts |
| Archiet from this reference architecture | 5-15 minutes for the codebase + auditor-ready bundle |

## How to use

1. Clone to your workspace.
2. Edit the genome to match your state-specific compliance overlays
   (Texas / California / NY have additional state laws on top of
   HIPAA).
3. Generate. The C01 HIPAA overlay produces the BAA tracker + PHI
   data-flow diagram + control matrix automatically.
4. Hand `compliance/hipaa/` to your Security Officer.

## What's NOT in this reference

- FHIR client implementation — the genome shapes Patient + ClinicalNote
  in Archiet's native model. Real EHR integration via Epic / Cerner
  / Athenahealth requires a custom FHIR adapter; the integration
  capability exists but the FHIR-specific mapping is not in this
  reference.
- 21 CFR Part 11 (electronic records for clinical research) — this
  reference is a clinical-care portal. Add 21 CFR Part 11 controls
  if your scope includes regulated trials.