# vtg2208/medicare-secure architecture

> Architecture diagram of the GitHub repository vtg2208/medicare-secure, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vtg2208/medicare-secure
- Repository: https://github.com/vtg2208/medicare-secure

## Overview

Medicare is a permission-aware healthcare and patient-management platform. Patients and care teams use role-specific workspaces to manage visits, records, diagnostic and medication workflows, and patient-controlled sharing; the API enforces access at the data boundary and persists application state in PostgreSQL. The graph also preserves the documented identity, oversight, privacy-rights, retention, research, and optional AI capabilities. Relationships between unsampled subsystems are shown only where the README documents them; the source excerpts provide additional evidence for clinical-access checks, workflow orchestration, and database-backed audit.

Main entry points: [`backend/src/app.js`](https://github.com/vtg2208/medicare-secure/blob/main/backend/src/app.js) (Express API), [`backend/src/modules/emr/emr.controller.js`](https://github.com/vtg2208/medicare-secure/blob/main/backend/src/modules/emr/emr.controller.js) (Medical records), [`backend/src/modules/visit/visit.controller.js`](https://github.com/vtg2208/medicare-secure/blob/main/backend/src/modules/visit/visit.controller.js) (Visits and appointments), [`backend/src/modules/workflow/workflow.controller.js`](https://github.com/vtg2208/medicare-secure/blob/main/backend/src/modules/workflow/workflow.controller.js) (Care coordination)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Web experience"]
  node_web["Role workspaces<br/>[AppRoutes.jsx]"]
  node_web_api["API client<br/>[client.js]"]
end

subgraph group_clinical["Clinical care"]
  node_records["Medical records<br/>[emr.controller.js]"]
  node_visits["Visits and appointments"]
  node_lifecycle["Visit lifecycle"]
  node_workflow["Care coordination"]
  node_diagnostics["Lab and imaging<br/>[lab.controller.js]"]
  node_pharmacy["Medication workflows"]
  node_messages["Care correspondence<br/>[messages.routes.js]"]
  node_insurance["Insurance workflows"]
end

subgraph group_trust["Identity and safeguards"]
  node_auth["Identity and sessions<br/>[auth.controller.js]"]
  node_access["Clinical access checks"]
  node_consent["Consent grants"]
end

subgraph group_governance["Privacy and oversight"]
  node_audit["Audit evidence<br/>[audit.service.js]"]
  node_compliance["Incidents and breaches"]
  node_rights["Patient rights requests"]
  node_retention["Retention governance"]
  node_research["Research cohorts<br/>[research-cohort.js]"]
end

subgraph group_platform["Runtime and integrations"]
  node_api["Express API<br/>[app.js]"]
  node_database[("PostgreSQL<br/>[db.js]")]
  node_ai["Optional AI intake<br/>[app.py]"]
  node_ai_engine["Triage engine<br/>[triage_engine.py]"]
end

node_people(("Patients and staff"))
node_mail["SMTP service"]

node_people -->|"use"| node_web
node_web -.->|"request"| node_web_api
node_web_api -->|"call API"| node_api
node_api -->|"query"| node_database
node_api -.->|"route requests"| node_auth
node_api -.->|"route requests"| node_visits
node_api -.->|"route requests"| node_records
node_api -.->|"route requests"| node_workflow
node_api -.->|"route requests"| node_consent
node_records -->|"check access"| node_access
node_access -->|"check grants"| node_consent
node_visits -->|"manage states"| node_lifecycle
node_workflow -->|"read history"| node_lifecycle
node_people -->|"manage sharing"| node_consent
node_people -->|"review and document"| node_records
node_people -->|"manage visits"| node_visits
node_people -->|"coordinate care"| node_workflow
node_people -->|"process orders"| node_diagnostics
node_people -->|"process medication"| node_pharmacy
node_people -->|"exchange messages"| node_messages
node_people -->|"use scoped access"| node_insurance
node_people -->|"review evidence"| node_audit
node_people -->|"review casework"| node_compliance
node_people -->|"submit requests"| node_rights
node_people -->|"govern disposal"| node_retention
node_people -->|"analyze cohorts"| node_research
node_records -->|"record access"| node_audit
node_rights -->|"log fulfillment"| node_audit
node_people -.->|"request intake"| node_ai
node_ai -.->|"triage"| node_ai_engine
node_auth -.->|"send verification"| node_mail

click node_web "https://github.com/vtg2208/medicare-secure/blob/main/frontend/src/routes/AppRoutes.jsx"
click node_web_api "https://github.com/vtg2208/medicare-secure/blob/main/frontend/src/api/client.js"
click node_api "https://github.com/vtg2208/medicare-secure/blob/main/backend/src/app.js"
click node_auth "https://github.com/vtg2208/medicare-secure/blob/main/backend/src/modules/auth/auth.controller.js"
click node_access "https://github.com/vtg2208/medicare-secure/blob/main/backend/src/middleware/clinical-access.middleware.js"
click node_consent "https://github.com/vtg2208/medicare-secure/blob/main/backend/src/modules/consent/consent.controller.js"
click node_records "https://github.com/vtg2208/medicare-secure/blob/main/backend/src/modules/emr/emr.controller.js"
click node_visits "https://github.com/vtg2208/medicare-secure/blob/main/backend/src/modules/visit/visit.controller.js"
click node_lifecycle "https://github.com/vtg2208/medicare-secure/blob/main/backend/src/services/visit.lifecycle.service.js"
click node_workflow "https://github.com/vtg2208/medicare-secure/blob/main/backend/src/modules/workflow/workflow.controller.js"
click node_diagnostics "https://github.com/vtg2208/medicare-secure/blob/main/backend/src/modules/lab/lab.controller.js"
click node_pharmacy "https://github.com/vtg2208/medicare-secure/blob/main/backend/src/modules/pharmacist/pharmacist.controller.js"
click node_messages "https://github.com/vtg2208/medicare-secure/blob/main/backend/src/modules/messages/messages.routes.js"
click node_insurance "https://github.com/vtg2208/medicare-secure/blob/main/backend/src/modules/insurance/insurance.controller.js"
click node_audit "https://github.com/vtg2208/medicare-secure/blob/main/backend/src/services/audit.service.js"
click node_compliance "https://github.com/vtg2208/medicare-secure/blob/main/backend/src/modules/compliance/compliance.routes.js"
click node_rights "https://github.com/vtg2208/medicare-secure/blob/main/backend/src/modules/privacy/privacy-fulfillment.service.js"
click node_retention "https://github.com/vtg2208/medicare-secure/blob/main/backend/src/modules/privacy/retention-policy.js"
click node_research "https://github.com/vtg2208/medicare-secure/blob/main/backend/src/modules/research/research-cohort.js"
click node_database "https://github.com/vtg2208/medicare-secure/blob/main/backend/src/config/db.js"
click node_ai "https://github.com/vtg2208/medicare-secure/blob/main/ai-service/app.py"
click node_ai_engine "https://github.com/vtg2208/medicare-secure/blob/main/ai-service/triage_engine.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_web,node_web_api toneBlue
class node_records,node_visits,node_lifecycle,node_workflow,node_diagnostics,node_pharmacy,node_messages,node_insurance toneAmber
class node_auth,node_access,node_consent toneMint
class node_audit,node_compliance,node_rights,node_retention,node_research toneRose
class node_api,node_database,node_ai,node_ai_engine,node_people,node_mail toneIndigo
```

## Components

### Web experience

- [Role workspaces](https://github.com/vtg2208/medicare-secure/blob/main/frontend/src/routes/AppRoutes.jsx): `frontend/src/routes/AppRoutes.jsx`
- [API client](https://github.com/vtg2208/medicare-secure/blob/main/frontend/src/api/client.js): `frontend/src/api/client.js`

### Clinical care

- [Medical records](https://github.com/vtg2208/medicare-secure/blob/main/backend/src/modules/emr/emr.controller.js): `backend/src/modules/emr/emr.controller.js`
- [Visits and appointments](https://github.com/vtg2208/medicare-secure/blob/main/backend/src/modules/visit/visit.controller.js): `backend/src/modules/visit/visit.controller.js`
- [Visit lifecycle](https://github.com/vtg2208/medicare-secure/blob/main/backend/src/services/visit.lifecycle.service.js): `backend/src/services/visit.lifecycle.service.js`
- [Care coordination](https://github.com/vtg2208/medicare-secure/blob/main/backend/src/modules/workflow/workflow.controller.js): `backend/src/modules/workflow/workflow.controller.js`
- [Lab and imaging](https://github.com/vtg2208/medicare-secure/blob/main/backend/src/modules/lab/lab.controller.js): `backend/src/modules/lab/lab.controller.js`
- [Medication workflows](https://github.com/vtg2208/medicare-secure/blob/main/backend/src/modules/pharmacist/pharmacist.controller.js): `backend/src/modules/pharmacist/pharmacist.controller.js`
- [Care correspondence](https://github.com/vtg2208/medicare-secure/blob/main/backend/src/modules/messages/messages.routes.js): `backend/src/modules/messages/messages.routes.js`
- [Insurance workflows](https://github.com/vtg2208/medicare-secure/blob/main/backend/src/modules/insurance/insurance.controller.js): `backend/src/modules/insurance/insurance.controller.js`

### Identity and safeguards

- [Identity and sessions](https://github.com/vtg2208/medicare-secure/blob/main/backend/src/modules/auth/auth.controller.js): `backend/src/modules/auth/auth.controller.js`
- [Clinical access checks](https://github.com/vtg2208/medicare-secure/blob/main/backend/src/middleware/clinical-access.middleware.js): `backend/src/middleware/clinical-access.middleware.js`
- [Consent grants](https://github.com/vtg2208/medicare-secure/blob/main/backend/src/modules/consent/consent.controller.js): `backend/src/modules/consent/consent.controller.js`

### Privacy and oversight

- [Audit evidence](https://github.com/vtg2208/medicare-secure/blob/main/backend/src/services/audit.service.js): `backend/src/services/audit.service.js`
- [Incidents and breaches](https://github.com/vtg2208/medicare-secure/blob/main/backend/src/modules/compliance/compliance.routes.js): `backend/src/modules/compliance/compliance.routes.js`
- [Patient rights requests](https://github.com/vtg2208/medicare-secure/blob/main/backend/src/modules/privacy/privacy-fulfillment.service.js): `backend/src/modules/privacy/privacy-fulfillment.service.js`
- [Retention governance](https://github.com/vtg2208/medicare-secure/blob/main/backend/src/modules/privacy/retention-policy.js): `backend/src/modules/privacy/retention-policy.js`
- [Research cohorts](https://github.com/vtg2208/medicare-secure/blob/main/backend/src/modules/research/research-cohort.js): `backend/src/modules/research/research-cohort.js`

### Runtime and integrations

- [Express API](https://github.com/vtg2208/medicare-secure/blob/main/backend/src/app.js): `backend/src/app.js`
- [PostgreSQL](https://github.com/vtg2208/medicare-secure/blob/main/backend/src/config/db.js): `backend/src/config/db.js`
- [Optional AI intake](https://github.com/vtg2208/medicare-secure/blob/main/ai-service/app.py): `ai-service/app.py`
- [Triage engine](https://github.com/vtg2208/medicare-secure/blob/main/ai-service/triage_engine.py): `ai-service/triage_engine.py`

### Other components

- **Patients and staff**
- **SMTP service**

## Connections

- Patients and staff → Role workspaces: use (evidence: `README.md`)
- Role workspaces → API client: request
- API client → Express API: call API (evidence: `README.md`)
- Express API → PostgreSQL: query (evidence: `backend/src/config/db.js`)
- Express API → Identity and sessions: route requests
- Express API → Visits and appointments: route requests
- Express API → Medical records: route requests
- Express API → Care coordination: route requests
- Express API → Consent grants: route requests
- Medical records → Clinical access checks: check access (evidence: `backend/src/modules/emr/emr.controller.js`)
- Clinical access checks → Consent grants: check grants (evidence: `backend/src/middleware/clinical-access.middleware.js`)
- Visits and appointments → Visit lifecycle: manage states (evidence: `backend/src/modules/visit/visit.controller.js`)
- Care coordination → Visit lifecycle: read history (evidence: `backend/src/modules/workflow/workflow.controller.js`)
- Patients and staff → Consent grants: manage sharing (evidence: `README.md`)
- Patients and staff → Medical records: review and document (evidence: `README.md`)
- Patients and staff → Visits and appointments: manage visits (evidence: `README.md`)
- Patients and staff → Care coordination: coordinate care (evidence: `README.md`)
- Patients and staff → Lab and imaging: process orders (evidence: `README.md`)
- Patients and staff → Medication workflows: process medication (evidence: `README.md`)
- Patients and staff → Care correspondence: exchange messages (evidence: `README.md`)
- Patients and staff → Insurance workflows: use scoped access (evidence: `README.md`)
- Patients and staff → Audit evidence: review evidence (evidence: `README.md`)
- Patients and staff → Incidents and breaches: review casework (evidence: `README.md`)
- Patients and staff → Patient rights requests: submit requests (evidence: `README.md`)
- Patients and staff → Retention governance: govern disposal (evidence: `README.md`)
- Patients and staff → Research cohorts: analyze cohorts (evidence: `README.md`)
- Medical records → Audit evidence: record access (evidence: `backend/src/modules/emr/emr.controller.js`)
- Patient rights requests → Audit evidence: log fulfillment
- Patients and staff → Optional AI intake: request intake (evidence: `README.md`)
- Optional AI intake → Triage engine: triage
- Identity and sessions → SMTP service: send verification
