# devil-thirupu/healthmate-ai architecture

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

- Interactive diagram: https://gitdiagram.com/devil-thirupu/healthmate-ai
- Repository: https://github.com/devil-thirupu/healthmate-ai

## Overview

HealthMate AI is a personal health-record vault and clinical document assistant. Patients authenticate, upload and review records, then use structured health insights and evidence-grounded assistance to prepare for care or share selected records. The graph also preserves nutrition, reminders, audit, and doctor-connection capabilities. Source excerpts establish app routing, authentication, startup, and storage behavior; several feature modules were not sampled, so their internal call paths are not inferred.

Main entry points: [`frontend/src/App.jsx`](https://github.com/devil-thirupu/healthmate-ai/blob/main/frontend/src/App.jsx) (Web application), [`frontend/src/context/AuthContext.jsx`](https://github.com/devil-thirupu/healthmate-ai/blob/main/frontend/src/context/AuthContext.jsx) (Authentication UI), [`backend/app/api/documents.py`](https://github.com/devil-thirupu/healthmate-ai/blob/main/backend/app/api/documents.py) (Document ingestion), [`backend/app/services/hybrid_rag_service.py`](https://github.com/devil-thirupu/healthmate-ai/blob/main/backend/app/services/hybrid_rag_service.py) (Hybrid RAG)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Patient experience"]
  node_webapp["Web application<br/>[App.jsx]"]
  node_authui["Authentication UI<br/>[AuthContext.jsx]"]
  node_api_client["API client<br/>[api.js]"]
  node_vault_ui["Records and reports"]
  node_assistant_ui["AI assistant"]
end

subgraph group_records["Records and intelligence"]
  node_upload["Document ingestion<br/>[documents.py]"]
  node_storage["Secure file storage<br/>[storage_service.py]"]
  node_cloud_storage["Private cloud storage"]
  node_ocr["Multi-tier OCR<br/>[ocr_service.py]"]
  node_clinical["Clinical extraction"]
  node_intelligence["Health intelligence"]
  node_rag["Hybrid RAG"]
  node_evidence["Evidence guard"]
end

subgraph group_care["Care planning"]
  node_nutrition["Nutrition intelligence"]
  node_appointments["Appointment preparation"]
  node_explanations["Trilingual explanations"]
  node_reminders["Medication reminders"]
  node_doctors["Doctor connections<br/>[MyDoctorsPage.jsx]"]
end

subgraph group_trust["Privacy and access"]
  node_sharing["Patient-controlled sharing<br/>[sharing.py]"]
  node_audit["Audit logging<br/>[audit_service.py]"]
  node_auth_api["Authentication API<br/>[auth.py]"]
end

subgraph group_platform["Application platform"]
  node_api["FastAPI application<br/>[main.py]"]
  node_router["API routes<br/>[api_router.py]"]
  node_database[("Health record database<br/>[database.py]")]
end

node_patient(("Patient"))

node_patient -->|"uses"| node_webapp
node_webapp -->|"provides auth"| node_authui
node_webapp -->|"routes to"| node_vault_ui
node_webapp -->|"routes to"| node_assistant_ui
node_authui -->|"calls"| node_api_client
node_authui -.->|"authenticates via"| node_auth_api
node_vault_ui -.->|"uploads records"| node_upload
node_upload -.->|"stores files"| node_storage
node_storage -->|"mirrors files"| node_cloud_storage
node_upload -.->|"processes documents"| node_ocr
node_ocr -.->|"extracts clinical data"| node_clinical
node_clinical -.->|"informs insights"| node_intelligence
node_assistant_ui -.->|"queries"| node_api_client
node_api_client -.->|"requests answers"| node_rag
node_rag -->|"guards responses"| node_evidence
node_rag -->|"formats explanations"| node_explanations
node_patient -.->|"explores nutrition"| node_nutrition
node_patient -.->|"prepares visit"| node_appointments
node_patient -.->|"controls sharing"| node_sharing
node_patient -.->|"reviews activity"| node_audit
node_patient -.->|"uses reminders"| node_reminders
node_patient -->|"connects doctors"| node_doctors
node_api -->|"mounts routes"| node_router
node_api -->|"initializes schema"| node_database
node_auth_api -->|"queries users"| node_database
node_auth_api -->|"records activity"| node_audit

click node_webapp "https://github.com/devil-thirupu/healthmate-ai/blob/main/frontend/src/App.jsx"
click node_authui "https://github.com/devil-thirupu/healthmate-ai/blob/main/frontend/src/context/AuthContext.jsx"
click node_api_client "https://github.com/devil-thirupu/healthmate-ai/blob/main/frontend/src/services/api.js"
click node_vault_ui "https://github.com/devil-thirupu/healthmate-ai/blob/main/frontend/src/pages/MedicalRecordsPage.jsx"
click node_assistant_ui "https://github.com/devil-thirupu/healthmate-ai/blob/main/frontend/src/pages/AIAssistantPage.jsx"
click node_upload "https://github.com/devil-thirupu/healthmate-ai/blob/main/backend/app/api/documents.py"
click node_storage "https://github.com/devil-thirupu/healthmate-ai/blob/main/backend/app/services/storage_service.py"
click node_cloud_storage "https://github.com/devil-thirupu/healthmate-ai/blob/main/backend/app/services/supabase_storage_service.py"
click node_ocr "https://github.com/devil-thirupu/healthmate-ai/blob/main/backend/app/services/ocr_service.py"
click node_clinical "https://github.com/devil-thirupu/healthmate-ai/blob/main/backend/app/services/clinical_extractor.py"
click node_intelligence "https://github.com/devil-thirupu/healthmate-ai/blob/main/backend/app/services/health_intelligence_service.py"
click node_rag "https://github.com/devil-thirupu/healthmate-ai/blob/main/backend/app/services/hybrid_rag_service.py"
click node_evidence "https://github.com/devil-thirupu/healthmate-ai/blob/main/backend/app/services/evidence_guard_service.py"
click node_nutrition "https://github.com/devil-thirupu/healthmate-ai/blob/main/backend/app/services/nutrition_service.py"
click node_appointments "https://github.com/devil-thirupu/healthmate-ai/blob/main/backend/app/services/appointment_summary_service.py"
click node_explanations "https://github.com/devil-thirupu/healthmate-ai/blob/main/backend/app/services/multilingual_explanation_service.py"
click node_sharing "https://github.com/devil-thirupu/healthmate-ai/blob/main/backend/app/api/sharing.py"
click node_audit "https://github.com/devil-thirupu/healthmate-ai/blob/main/backend/app/services/audit_service.py"
click node_auth_api "https://github.com/devil-thirupu/healthmate-ai/blob/main/backend/app/api/auth.py"
click node_reminders "https://github.com/devil-thirupu/healthmate-ai/blob/main/backend/app/services/reminder_service.py"
click node_doctors "https://github.com/devil-thirupu/healthmate-ai/blob/main/frontend/src/pages/MyDoctorsPage.jsx"
click node_api "https://github.com/devil-thirupu/healthmate-ai/blob/main/backend/app/main.py"
click node_router "https://github.com/devil-thirupu/healthmate-ai/blob/main/backend/app/api/api_router.py"
click node_database "https://github.com/devil-thirupu/healthmate-ai/blob/main/backend/app/core/database.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_webapp,node_authui,node_api_client,node_vault_ui,node_assistant_ui toneBlue
class node_upload,node_storage,node_cloud_storage,node_ocr,node_clinical,node_intelligence,node_rag,node_evidence toneAmber
class node_nutrition,node_appointments,node_explanations,node_reminders,node_doctors toneMint
class node_sharing,node_audit,node_auth_api toneRose
class node_api,node_router,node_database,node_patient toneIndigo
```

## Components

### Patient experience

- [Web application](https://github.com/devil-thirupu/healthmate-ai/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Authentication UI](https://github.com/devil-thirupu/healthmate-ai/blob/main/frontend/src/context/AuthContext.jsx): `frontend/src/context/AuthContext.jsx`
- [API client](https://github.com/devil-thirupu/healthmate-ai/blob/main/frontend/src/services/api.js): `frontend/src/services/api.js`
- [Records and reports](https://github.com/devil-thirupu/healthmate-ai/blob/main/frontend/src/pages/MedicalRecordsPage.jsx): `frontend/src/pages/MedicalRecordsPage.jsx`
- [AI assistant](https://github.com/devil-thirupu/healthmate-ai/blob/main/frontend/src/pages/AIAssistantPage.jsx): `frontend/src/pages/AIAssistantPage.jsx`

### Records and intelligence

- [Document ingestion](https://github.com/devil-thirupu/healthmate-ai/blob/main/backend/app/api/documents.py): `backend/app/api/documents.py`
- [Secure file storage](https://github.com/devil-thirupu/healthmate-ai/blob/main/backend/app/services/storage_service.py): `backend/app/services/storage_service.py`
- [Private cloud storage](https://github.com/devil-thirupu/healthmate-ai/blob/main/backend/app/services/supabase_storage_service.py): `backend/app/services/supabase_storage_service.py`
- [Multi-tier OCR](https://github.com/devil-thirupu/healthmate-ai/blob/main/backend/app/services/ocr_service.py): `backend/app/services/ocr_service.py`
- [Clinical extraction](https://github.com/devil-thirupu/healthmate-ai/blob/main/backend/app/services/clinical_extractor.py): `backend/app/services/clinical_extractor.py`
- [Health intelligence](https://github.com/devil-thirupu/healthmate-ai/blob/main/backend/app/services/health_intelligence_service.py): `backend/app/services/health_intelligence_service.py`
- [Hybrid RAG](https://github.com/devil-thirupu/healthmate-ai/blob/main/backend/app/services/hybrid_rag_service.py): `backend/app/services/hybrid_rag_service.py`
- [Evidence guard](https://github.com/devil-thirupu/healthmate-ai/blob/main/backend/app/services/evidence_guard_service.py): `backend/app/services/evidence_guard_service.py`

### Care planning

- [Nutrition intelligence](https://github.com/devil-thirupu/healthmate-ai/blob/main/backend/app/services/nutrition_service.py): `backend/app/services/nutrition_service.py`
- [Appointment preparation](https://github.com/devil-thirupu/healthmate-ai/blob/main/backend/app/services/appointment_summary_service.py): `backend/app/services/appointment_summary_service.py`
- [Trilingual explanations](https://github.com/devil-thirupu/healthmate-ai/blob/main/backend/app/services/multilingual_explanation_service.py): `backend/app/services/multilingual_explanation_service.py`
- [Medication reminders](https://github.com/devil-thirupu/healthmate-ai/blob/main/backend/app/services/reminder_service.py): `backend/app/services/reminder_service.py`
- [Doctor connections](https://github.com/devil-thirupu/healthmate-ai/blob/main/frontend/src/pages/MyDoctorsPage.jsx): `frontend/src/pages/MyDoctorsPage.jsx`

### Privacy and access

- [Patient-controlled sharing](https://github.com/devil-thirupu/healthmate-ai/blob/main/backend/app/api/sharing.py): `backend/app/api/sharing.py`
- [Audit logging](https://github.com/devil-thirupu/healthmate-ai/blob/main/backend/app/services/audit_service.py): `backend/app/services/audit_service.py`
- [Authentication API](https://github.com/devil-thirupu/healthmate-ai/blob/main/backend/app/api/auth.py): `backend/app/api/auth.py`

### Application platform

- [FastAPI application](https://github.com/devil-thirupu/healthmate-ai/blob/main/backend/app/main.py): `backend/app/main.py`
- [API routes](https://github.com/devil-thirupu/healthmate-ai/blob/main/backend/app/api/api_router.py): `backend/app/api/api_router.py`
- [Health record database](https://github.com/devil-thirupu/healthmate-ai/blob/main/backend/app/core/database.py): `backend/app/core/database.py`

### Other components

- **Patient**

## Connections

- Patient → Web application: uses (evidence: `frontend/src/App.jsx`)
- Web application → Authentication UI: provides auth (evidence: `frontend/src/App.jsx`)
- Web application → Records and reports: routes to (evidence: `frontend/src/App.jsx`)
- Web application → AI assistant: routes to (evidence: `frontend/src/App.jsx`)
- Authentication UI → API client: calls (evidence: `frontend/src/context/AuthContext.jsx`)
- Authentication UI → Authentication API: authenticates via
- Records and reports → Document ingestion: uploads records
- Document ingestion → Secure file storage: stores files
- Secure file storage → Private cloud storage: mirrors files (evidence: `backend/app/services/storage_service.py`)
- Document ingestion → Multi-tier OCR: processes documents
- Multi-tier OCR → Clinical extraction: extracts clinical data
- Clinical extraction → Health intelligence: informs insights
- AI assistant → API client: queries
- API client → Hybrid RAG: requests answers
- Hybrid RAG → Evidence guard: guards responses (evidence: `backend/app/services/hybrid_rag_service.py`)
- Hybrid RAG → Trilingual explanations: formats explanations (evidence: `backend/app/services/hybrid_rag_service.py`)
- Patient → Nutrition intelligence: explores nutrition
- Patient → Appointment preparation: prepares visit
- Patient → Patient-controlled sharing: controls sharing
- Patient → Audit logging: reviews activity
- Patient → Medication reminders: uses reminders
- Patient → Doctor connections: connects doctors
- FastAPI application → API routes: mounts routes (evidence: `backend/app/main.py`)
- FastAPI application → Health record database: initializes schema (evidence: `backend/app/main.py`)
- Authentication API → Health record database: queries users (evidence: `backend/app/api/auth.py`)
- Authentication API → Audit logging: records activity (evidence: `backend/app/api/auth.py`)
