# baranidharan16/digital-health-twin architecture

> Architecture diagram of the GitHub repository baranidharan16/digital-health-twin, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/baranidharan16/digital-health-twin
- Repository: https://github.com/baranidharan16/digital-health-twin

## Overview

Human Health Digital Twin synchronizes wearable or simulated readings into a person-specific physiology model, then presents state, explanations, history, and an interactive anatomical view. The main path is source data → normalization → twin update and persistence → live dashboard; users can also import wearable exports and run personalized what-if scenarios. The README documents the system-level lifecycle and capabilities; sampled source confirms key engine, ingestion, frontend, and phone-app behavior. Several API routes and unsampled subsystems are represented from README documentation rather than inspected implementation.

Main entry points: [`backend/app/services/twin_service.py`](https://github.com/baranidharan16/digital-health-twin/blob/main/backend/app/services/twin_service.py) (Twin synchronization), [`digital_twin/engine.py`](https://github.com/baranidharan16/digital-health-twin/blob/main/digital_twin/engine.py) (Twin engine), [`frontend/src/api/client.ts`](https://github.com/baranidharan16/digital-health-twin/blob/main/frontend/src/api/client.ts) (Web API client), [`backend/app/api`](https://github.com/baranidharan16/digital-health-twin/tree/main/backend/app/api) (Backend API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_inputs["Data sources"]
  node_simulator["Physiology simulator<br/>[generator.py]"]
  node_phone["Android companion<br/>[MainActivity.kt]"]
  node_healthconnect["Health Connect reader<br/>[HealthReader.kt]"]
  node_imports["Wearable imports<br/>[importers.py]"]
end

subgraph group_twin["Twin runtime"]
  node_normalizer["Reading normalization<br/>[ingestion.py]"]
  node_api["Backend API"]
  node_twinservice["Twin synchronization<br/>[twin_service.py]"]
  node_engine["Twin engine<br/>[engine.py]"]
  node_baseline["Personal baseline<br/>[baseline.py]"]
  node_anomaly["Anomaly detection<br/>[anomaly.py]"]
  node_states["State transitions<br/>[state_engine.py]"]
  node_database[("Twin data store<br/>[db.py]")]
end

subgraph group_insights["Analytics and simulation"]
  node_queries["History and analytics<br/>[queries.py]"]
  node_wellness["Wellness summaries<br/>[wellness.py]"]
  node_whatif["What-if scenarios<br/>[whatif.py]"]
end

subgraph group_experience["User experience"]
  node_client["Web API client<br/>[client.ts]"]
  node_livehook["Live twin hook<br/>[useLiveTwin.ts]"]
  node_dashboard["Web dashboard<br/>[App.tsx]"]
  node_analyticsui["Analytics and history<br/>[AnalyticsPage.tsx]"]
  node_simulationui["Scenario interface<br/>[SimulationPage.tsx]"]
  node_anatomy["3D anatomical twin<br/>[TwinScene.tsx]"]
end

node_person(("Person / demo user"))

node_person -->|"pairs phone"| node_phone
node_healthconnect -->|"reads measurements"| node_phone
node_phone -->|"syncs readings"| node_api
node_simulator -->|"supplies readings"| node_normalizer
node_person -->|"uploads export"| node_imports
node_imports -->|"normalizes records"| node_normalizer
node_normalizer -->|"passes observations"| node_twinservice
node_api -->|"routes twin requests"| node_twinservice
node_twinservice -->|"updates twin"| node_engine
node_twinservice -->|"persists state"| node_database
node_engine -->|"assesses against"| node_baseline
node_engine -->|"assesses vitals"| node_anomaly
node_engine -->|"updates state"| node_states
node_queries -->|"reads history"| node_database
node_queries -->|"uses summaries"| node_wellness
node_whatif -->|"classifies scenarios"| node_engine
node_client -->|"calls endpoints"| node_api
node_livehook -->|"loads twin data"| node_client
node_livehook -->|"opens live stream"| node_api
node_dashboard -->|"shows live state"| node_livehook
node_dashboard -->|"loads twin list"| node_client
node_analyticsui -.->|"requests analytics"| node_client
node_simulationui -->|"submits scenarios"| node_client
node_dashboard -.->|"renders twin view"| node_anatomy
node_twinservice -.->|"serves twin analytics"| node_queries

click node_simulator "https://github.com/baranidharan16/digital-health-twin/blob/main/simulator/generator.py"
click node_phone "https://github.com/baranidharan16/digital-health-twin/blob/main/mobile/android/app/src/main/java/com/healthtwin/app/MainActivity.kt"
click node_healthconnect "https://github.com/baranidharan16/digital-health-twin/blob/main/mobile/android/app/src/main/java/com/healthtwin/app/HealthReader.kt"
click node_imports "https://github.com/baranidharan16/digital-health-twin/blob/main/backend/app/importers.py"
click node_normalizer "https://github.com/baranidharan16/digital-health-twin/blob/main/backend/app/ingestion.py"
click node_api "https://github.com/baranidharan16/digital-health-twin/tree/main/backend/app/api"
click node_twinservice "https://github.com/baranidharan16/digital-health-twin/blob/main/backend/app/services/twin_service.py"
click node_engine "https://github.com/baranidharan16/digital-health-twin/blob/main/digital_twin/engine.py"
click node_baseline "https://github.com/baranidharan16/digital-health-twin/blob/main/digital_twin/baseline.py"
click node_anomaly "https://github.com/baranidharan16/digital-health-twin/blob/main/digital_twin/anomaly.py"
click node_states "https://github.com/baranidharan16/digital-health-twin/blob/main/digital_twin/state_engine.py"
click node_database "https://github.com/baranidharan16/digital-health-twin/blob/main/backend/app/db.py"
click node_queries "https://github.com/baranidharan16/digital-health-twin/blob/main/backend/app/services/queries.py"
click node_wellness "https://github.com/baranidharan16/digital-health-twin/blob/main/digital_twin/wellness.py"
click node_whatif "https://github.com/baranidharan16/digital-health-twin/blob/main/digital_twin/whatif.py"
click node_client "https://github.com/baranidharan16/digital-health-twin/blob/main/frontend/src/api/client.ts"
click node_livehook "https://github.com/baranidharan16/digital-health-twin/blob/main/frontend/src/hooks/useLiveTwin.ts"
click node_dashboard "https://github.com/baranidharan16/digital-health-twin/blob/main/frontend/src/App.tsx"
click node_analyticsui "https://github.com/baranidharan16/digital-health-twin/blob/main/frontend/src/pages/AnalyticsPage.tsx"
click node_simulationui "https://github.com/baranidharan16/digital-health-twin/blob/main/frontend/src/pages/SimulationPage.tsx"
click node_anatomy "https://github.com/baranidharan16/digital-health-twin/blob/main/frontend/src/twin3d/TwinScene.tsx"

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_simulator,node_phone,node_healthconnect,node_imports,node_person toneBlue
class node_normalizer,node_api,node_twinservice,node_engine,node_baseline,node_anomaly,node_states,node_database toneAmber
class node_queries,node_wellness,node_whatif toneMint
class node_client,node_livehook,node_dashboard,node_analyticsui,node_simulationui,node_anatomy toneRose
```

## Components

### Data sources

- [Physiology simulator](https://github.com/baranidharan16/digital-health-twin/blob/main/simulator/generator.py): `simulator/generator.py`
- [Android companion](https://github.com/baranidharan16/digital-health-twin/blob/main/mobile/android/app/src/main/java/com/healthtwin/app/MainActivity.kt): `mobile/android/app/src/main/java/com/healthtwin/app/MainActivity.kt`
- [Health Connect reader](https://github.com/baranidharan16/digital-health-twin/blob/main/mobile/android/app/src/main/java/com/healthtwin/app/HealthReader.kt): `mobile/android/app/src/main/java/com/healthtwin/app/HealthReader.kt`
- [Wearable imports](https://github.com/baranidharan16/digital-health-twin/blob/main/backend/app/importers.py): `backend/app/importers.py`

### Twin runtime

- [Reading normalization](https://github.com/baranidharan16/digital-health-twin/blob/main/backend/app/ingestion.py): `backend/app/ingestion.py`
- [Backend API](https://github.com/baranidharan16/digital-health-twin/tree/main/backend/app/api): `backend/app/api`
- [Twin synchronization](https://github.com/baranidharan16/digital-health-twin/blob/main/backend/app/services/twin_service.py): `backend/app/services/twin_service.py`
- [Twin engine](https://github.com/baranidharan16/digital-health-twin/blob/main/digital_twin/engine.py): `digital_twin/engine.py`
- [Personal baseline](https://github.com/baranidharan16/digital-health-twin/blob/main/digital_twin/baseline.py): `digital_twin/baseline.py`
- [Anomaly detection](https://github.com/baranidharan16/digital-health-twin/blob/main/digital_twin/anomaly.py): `digital_twin/anomaly.py`
- [State transitions](https://github.com/baranidharan16/digital-health-twin/blob/main/digital_twin/state_engine.py): `digital_twin/state_engine.py`
- [Twin data store](https://github.com/baranidharan16/digital-health-twin/blob/main/backend/app/db.py): `backend/app/db.py`

### Analytics and simulation

- [History and analytics](https://github.com/baranidharan16/digital-health-twin/blob/main/backend/app/services/queries.py): `backend/app/services/queries.py`
- [Wellness summaries](https://github.com/baranidharan16/digital-health-twin/blob/main/digital_twin/wellness.py): `digital_twin/wellness.py`
- [What-if scenarios](https://github.com/baranidharan16/digital-health-twin/blob/main/digital_twin/whatif.py): `digital_twin/whatif.py`

### User experience

- [Web API client](https://github.com/baranidharan16/digital-health-twin/blob/main/frontend/src/api/client.ts): `frontend/src/api/client.ts`
- [Live twin hook](https://github.com/baranidharan16/digital-health-twin/blob/main/frontend/src/hooks/useLiveTwin.ts): `frontend/src/hooks/useLiveTwin.ts`
- [Web dashboard](https://github.com/baranidharan16/digital-health-twin/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Analytics and history](https://github.com/baranidharan16/digital-health-twin/blob/main/frontend/src/pages/AnalyticsPage.tsx): `frontend/src/pages/AnalyticsPage.tsx`
- [Scenario interface](https://github.com/baranidharan16/digital-health-twin/blob/main/frontend/src/pages/SimulationPage.tsx): `frontend/src/pages/SimulationPage.tsx`
- [3D anatomical twin](https://github.com/baranidharan16/digital-health-twin/blob/main/frontend/src/twin3d/TwinScene.tsx): `frontend/src/twin3d/TwinScene.tsx`

### Other components

- **Person / demo user**

## Connections

- Person / demo user → Android companion: pairs phone (evidence: `README.md`)
- Health Connect reader → Android companion: reads measurements (evidence: `mobile/android/app/src/main/java/com/healthtwin/app/MainActivity.kt`)
- Android companion → Backend API: syncs readings (evidence: `README.md`)
- Physiology simulator → Reading normalization: supplies readings (evidence: `backend/app/ingestion.py`)
- Person / demo user → Wearable imports: uploads export (evidence: `README.md`)
- Wearable imports → Reading normalization: normalizes records (evidence: `backend/app/importers.py`)
- Reading normalization → Twin synchronization: passes observations (evidence: `backend/app/ingestion.py`)
- Backend API → Twin synchronization: routes twin requests (evidence: `backend/app/api/twins.py`)
- Twin synchronization → Twin engine: updates twin (evidence: `backend/app/services/twin_service.py`)
- Twin synchronization → Twin data store: persists state (evidence: `backend/app/services/twin_service.py`)
- Twin engine → Personal baseline: assesses against (evidence: `digital_twin/engine.py`)
- Twin engine → Anomaly detection: assesses vitals (evidence: `digital_twin/engine.py`)
- Twin engine → State transitions: updates state (evidence: `digital_twin/engine.py`)
- History and analytics → Twin data store: reads history (evidence: `backend/app/services/queries.py`)
- History and analytics → Wellness summaries: uses summaries (evidence: `backend/app/services/queries.py`)
- What-if scenarios → Twin engine: classifies scenarios (evidence: `digital_twin/whatif.py`)
- Web API client → Backend API: calls endpoints (evidence: `frontend/src/api/client.ts`)
- Live twin hook → Web API client: loads twin data (evidence: `frontend/src/hooks/useLiveTwin.ts`)
- Live twin hook → Backend API: opens live stream (evidence: `frontend/src/hooks/useLiveTwin.ts`)
- Web dashboard → Live twin hook: shows live state (evidence: `frontend/src/App.tsx`)
- Web dashboard → Web API client: loads twin list (evidence: `frontend/src/App.tsx`)
- Analytics and history → Web API client: requests analytics
- Scenario interface → Web API client: submits scenarios (evidence: `frontend/src/pages/SimulationPage.tsx`)
- Web dashboard → 3D anatomical twin: renders twin view (evidence: `README.md`)
- Twin synchronization → History and analytics: serves twin analytics (evidence: `README.md`)
