# abhiram0102/rapid-twin architecture

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

- Interactive diagram: https://gitdiagram.com/abhiram0102/rapid-twin
- Repository: https://github.com/abhiram0102/rapid-twin

## Overview

RAPiD-Twin is an experimental research prototype for combining retinal imagery, physiological time series, and longitudinal health-state modelling—not a verified clinical system. Its intended workflow runs retinal images through segmentation and graph/image encoders, combines those representations with encoded physiology, then models temporal state and experimental disease outputs; biomarker and reliability concepts feed a proposed API. The README documents this architecture but cautions that end-to-end patient alignment is unestablished. The only sampled source is the wearable collector, so other stage relationships reflect documented intent, not inspected runtime calls.

Main entry points: [`src/wearables.py`](https://github.com/abhiram0102/rapid-twin/blob/main/src/wearables.py) (Wearable collectors), [`notebooks/06_phase5_fusion_transformer.ipynb`](https://github.com/abhiram0102/rapid-twin/blob/main/notebooks/06_phase5_fusion_transformer.ipynb) (Multimodal fusion), [`notebooks/02_phase1_segmentation_finetune.ipynb`](https://github.com/abhiram0102/rapid-twin/blob/main/notebooks/02_phase1_segmentation_finetune.ipynb) (Vessel segmentation), [`notebooks/10_phase9_reliability.ipynb`](https://github.com/abhiram0102/rapid-twin/blob/main/notebooks/10_phase9_reliability.ipynb) (Reliability concepts)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_retina["Retinal processing"]
  node_segmentation["Vessel segmentation"]
  node_graph_extraction["Vessel graph extraction"]
  node_graph_encoder["Graph encoder"]
  node_retinal_encoder["Retinal encoder"]
end

subgraph group_physiology["Physiology inputs"]
  node_wearables["Wearable collectors<br/>[wearables.py]"]
  node_physio_series["Physiological series"]
  node_physio_encoder["Physiology encoder"]
end

subgraph group_modelling["Twin modelling"]
  node_fusion["Multimodal fusion"]
  node_temporal["Temporal state model"]
end

subgraph group_outputs["Outputs and API"]
  node_disease_heads["Disease heads"]
  node_biomarkers["Biomarker extraction"]
  node_reliability["Reliability concepts"]
  node_api["Proposed API"]
end

node_fundus(("Fundus image"))
node_apple_health["Apple HealthKit"]
node_google_fit["Google Fit"]
node_fitbit["Fitbit API"]

node_fundus -->|"segments"| node_segmentation
node_segmentation -->|"extracts graph"| node_graph_extraction
node_graph_extraction -->|"encodes graph"| node_graph_encoder
node_fundus -->|"encodes image"| node_retinal_encoder
node_apple_health -->|"collects data"| node_wearables
node_google_fit -->|"collects data"| node_wearables
node_fitbit -->|"collects data"| node_wearables
node_wearables -->|"returns series"| node_physio_series
node_physio_series -->|"encodes series"| node_physio_encoder
node_graph_encoder -->|"fuses representation"| node_fusion
node_retinal_encoder -->|"fuses representation"| node_fusion
node_physio_encoder -->|"fuses representation"| node_fusion
node_fusion -->|"models state"| node_temporal
node_temporal -->|"feeds heads"| node_disease_heads
node_segmentation -->|"extracts biomarkers"| node_biomarkers
node_disease_heads -->|"informs concepts"| node_reliability
node_biomarkers -->|"informs concepts"| node_reliability
node_reliability -->|"feeds proposal"| node_api

click node_segmentation "https://github.com/abhiram0102/rapid-twin/blob/main/notebooks/02_phase1_segmentation_finetune.ipynb"
click node_graph_extraction "https://github.com/abhiram0102/rapid-twin/blob/main/notebooks/03_phase2_graph_gnn.ipynb"
click node_graph_encoder "https://github.com/abhiram0102/rapid-twin/blob/main/notebooks/03_phase2_graph_gnn.ipynb"
click node_retinal_encoder "https://github.com/abhiram0102/rapid-twin/blob/main/notebooks/04_phase3_retinal_encoder.ipynb"
click node_wearables "https://github.com/abhiram0102/rapid-twin/blob/main/src/wearables.py"
click node_physio_encoder "https://github.com/abhiram0102/rapid-twin/blob/main/notebooks/05_phase4_physiology_encoder.ipynb"
click node_fusion "https://github.com/abhiram0102/rapid-twin/blob/main/notebooks/06_phase5_fusion_transformer.ipynb"
click node_temporal "https://github.com/abhiram0102/rapid-twin/blob/main/notebooks/07_phase6_temporal_twin.ipynb"
click node_disease_heads "https://github.com/abhiram0102/rapid-twin/blob/main/notebooks/08_phase7_disease_heads.ipynb"
click node_biomarkers "https://github.com/abhiram0102/rapid-twin/blob/main/notebooks/09_phase8_biomarkers.ipynb"
click node_reliability "https://github.com/abhiram0102/rapid-twin/blob/main/notebooks/10_phase9_reliability.ipynb"
click node_api "https://github.com/abhiram0102/rapid-twin/blob/main/notebooks/11_phase10_api.ipynb"

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_segmentation,node_graph_extraction,node_graph_encoder,node_retinal_encoder toneBlue
class node_wearables,node_physio_series,node_physio_encoder toneAmber
class node_fusion,node_temporal,node_fitbit toneMint
class node_disease_heads,node_biomarkers,node_reliability,node_api toneRose
class node_fundus,node_apple_health,node_google_fit toneIndigo
```

## Components

### Retinal processing

- [Vessel segmentation](https://github.com/abhiram0102/rapid-twin/blob/main/notebooks/02_phase1_segmentation_finetune.ipynb): `notebooks/02_phase1_segmentation_finetune.ipynb`
- [Vessel graph extraction](https://github.com/abhiram0102/rapid-twin/blob/main/notebooks/03_phase2_graph_gnn.ipynb): `notebooks/03_phase2_graph_gnn.ipynb`
- [Graph encoder](https://github.com/abhiram0102/rapid-twin/blob/main/notebooks/03_phase2_graph_gnn.ipynb): `notebooks/03_phase2_graph_gnn.ipynb`
- [Retinal encoder](https://github.com/abhiram0102/rapid-twin/blob/main/notebooks/04_phase3_retinal_encoder.ipynb): `notebooks/04_phase3_retinal_encoder.ipynb`

### Physiology inputs

- [Wearable collectors](https://github.com/abhiram0102/rapid-twin/blob/main/src/wearables.py): `src/wearables.py`
- **Physiological series**
- [Physiology encoder](https://github.com/abhiram0102/rapid-twin/blob/main/notebooks/05_phase4_physiology_encoder.ipynb): `notebooks/05_phase4_physiology_encoder.ipynb`

### Twin modelling

- [Multimodal fusion](https://github.com/abhiram0102/rapid-twin/blob/main/notebooks/06_phase5_fusion_transformer.ipynb): `notebooks/06_phase5_fusion_transformer.ipynb`
- [Temporal state model](https://github.com/abhiram0102/rapid-twin/blob/main/notebooks/07_phase6_temporal_twin.ipynb): `notebooks/07_phase6_temporal_twin.ipynb`

### Outputs and API

- [Disease heads](https://github.com/abhiram0102/rapid-twin/blob/main/notebooks/08_phase7_disease_heads.ipynb): `notebooks/08_phase7_disease_heads.ipynb`
- [Biomarker extraction](https://github.com/abhiram0102/rapid-twin/blob/main/notebooks/09_phase8_biomarkers.ipynb): `notebooks/09_phase8_biomarkers.ipynb`
- [Reliability concepts](https://github.com/abhiram0102/rapid-twin/blob/main/notebooks/10_phase9_reliability.ipynb): `notebooks/10_phase9_reliability.ipynb`
- [Proposed API](https://github.com/abhiram0102/rapid-twin/blob/main/notebooks/11_phase10_api.ipynb): `notebooks/11_phase10_api.ipynb`

### Other components

- **Fundus image**
- **Apple HealthKit**
- **Google Fit**
- **Fitbit API**

## Connections

- Fundus image → Vessel segmentation: segments (evidence: `README.md`)
- Vessel segmentation → Vessel graph extraction: extracts graph (evidence: `README.md`)
- Vessel graph extraction → Graph encoder: encodes graph (evidence: `README.md`)
- Fundus image → Retinal encoder: encodes image (evidence: `README.md`)
- Apple HealthKit → Wearable collectors: collects data (evidence: `src/wearables.py`)
- Google Fit → Wearable collectors: collects data (evidence: `src/wearables.py`)
- Fitbit API → Wearable collectors: collects data (evidence: `src/wearables.py`)
- Wearable collectors → Physiological series: returns series (evidence: `src/wearables.py`)
- Physiological series → Physiology encoder: encodes series (evidence: `README.md`)
- Graph encoder → Multimodal fusion: fuses representation (evidence: `README.md`)
- Retinal encoder → Multimodal fusion: fuses representation (evidence: `README.md`)
- Physiology encoder → Multimodal fusion: fuses representation (evidence: `README.md`)
- Multimodal fusion → Temporal state model: models state (evidence: `README.md`)
- Temporal state model → Disease heads: feeds heads (evidence: `README.md`)
- Vessel segmentation → Biomarker extraction: extracts biomarkers (evidence: `README.md`)
- Disease heads → Reliability concepts: informs concepts (evidence: `README.md`)
- Biomarker extraction → Reliability concepts: informs concepts (evidence: `README.md`)
- Reliability concepts → Proposed API: feeds proposal (evidence: `README.md`)