# that-tech-geek/digital-twin architecture

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

- Interactive diagram: https://gitdiagram.com/that-tech-geek/digital-twin
- Repository: https://github.com/that-tech-geek/digital-twin

## Overview

This research prototype turns longitudinal glucose and related signals into patient-specific glucose forecasts, hypoglycemia-risk estimates, and explicitly hypothetical counterfactuals. The principal workflow is source adaptation, canonicalization and timeline preparation, causal features and future-event labels, patient-level validation, model training, and three-layer twin simulation; evaluation and artifacts capture research results. The dashboard also exposes state, uncertainty, risk, and scenario simulation. Links follow the README’s materialized architecture and sampled calls; unsampled subsystem wiring is shown only where documented.

Main entry points: [`src/digital_twin/pipeline.py`](https://github.com/that-tech-geek/digital-twin/blob/main/src/digital_twin/pipeline.py) (Pipeline orchestrator), [`src/digital_twin/twin_layers/layer_c.py`](https://github.com/that-tech-geek/digital-twin/blob/main/src/digital_twin/twin_layers/layer_c.py) (Layer C simulator), [`src/digital_twin/ingestion/csv.py`](https://github.com/that-tech-geek/digital-twin/blob/main/src/digital_twin/ingestion/csv.py) (CSV adapter), [`src/digital_twin/twin_layers/layer_b.py`](https://github.com/that-tech-geek/digital-twin/blob/main/src/digital_twin/twin_layers/layer_b.py) (Layer B estimator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Data preparation"]
  node_csv_adapter["CSV adapter<br/>[csv.py]"]
  node_synthea_adapter["FHIR adapter<br/>[synthea.py]"]
  node_schema["Canonical schema<br/>[schema.py]"]
  node_preprocessing["Timeline and features<br/>[preprocessing.py]"]
  node_labels["Hypoglycemia labels<br/>[labels.py]"]
end

subgraph group_learning["Forecast learning"]
  node_splits["Patient splits<br/>[splits.py]"]
  node_baselines["Forecast baselines<br/>[baselines.py]"]
  node_training["GRU training<br/>[training.py]"]
  node_models["Forecast model<br/>[models.py]"]
end

subgraph group_twin["Digital twin"]
  node_prior["Layer A prior<br/>[layer_a.py]"]
  node_state["Layer B estimator<br/>[layer_b.py]"]
  node_simulator["Layer C simulator<br/>[layer_c.py]"]
  node_runtime_twin["Runtime patient twin<br/>[twin.py]"]
end

subgraph group_research["Research outputs"]
  node_pipeline["Pipeline orchestrator<br/>[pipeline.py]"]
  node_evaluation["Patient evaluation<br/>[evaluation.py]"]
  node_artifacts["Research artifacts<br/>[artifacts.py]"]
  node_cli["CLI and demo<br/>[cli.py]"]
  node_dashboard["Research dashboard<br/>[app.py]"]
end

node_ohio(("OhioT1DM"))
node_diatrend(("DiaTrend"))
node_hupa(("HUPA-UCM"))
node_synthea(("Synthea FHIR"))

node_ohio -->|"provides data"| node_csv_adapter
node_diatrend -->|"provides data"| node_csv_adapter
node_hupa -->|"provides data"| node_csv_adapter
node_synthea -->|"provides bundle"| node_synthea_adapter
node_csv_adapter -->|"canonicalizes"| node_schema
node_synthea_adapter -->|"outputs records"| node_schema
node_pipeline -->|"canonicalizes"| node_schema
node_pipeline -->|"resamples and featurizes"| node_preprocessing
node_pipeline -->|"adds labels"| node_labels
node_pipeline -->|"checks patient split"| node_splits
node_splits -->|"supports comparison"| node_baselines
node_pipeline -->|"trains model"| node_training
node_training -->|"optimizes"| node_models
node_pipeline -->|"builds estimator"| node_state
node_state -->|"runs forecasts"| node_models
node_pipeline -->|"creates patient prior"| node_prior
node_pipeline -->|"forecasts and simulates"| node_simulator
node_simulator -->|"requests distribution"| node_state
node_simulator -->|"conditions uncertainty"| node_prior
node_runtime_twin -->|"updates state"| node_state
node_runtime_twin -->|"forecasts or simulates"| node_simulator
node_pipeline -->|"computes metrics"| node_evaluation
node_pipeline -->|"writes results"| node_artifacts
node_cli -->|"runs workflow"| node_pipeline
node_dashboard -->|"prepares demo"| node_pipeline
node_dashboard -->|"shows forecast and scenarios"| node_simulator

click node_csv_adapter "https://github.com/that-tech-geek/digital-twin/blob/main/src/digital_twin/ingestion/csv.py"
click node_synthea_adapter "https://github.com/that-tech-geek/digital-twin/blob/main/src/digital_twin/ingestion/synthea.py"
click node_schema "https://github.com/that-tech-geek/digital-twin/blob/main/src/digital_twin/schema.py"
click node_preprocessing "https://github.com/that-tech-geek/digital-twin/blob/main/src/digital_twin/preprocessing.py"
click node_labels "https://github.com/that-tech-geek/digital-twin/blob/main/src/digital_twin/labels.py"
click node_pipeline "https://github.com/that-tech-geek/digital-twin/blob/main/src/digital_twin/pipeline.py"
click node_splits "https://github.com/that-tech-geek/digital-twin/blob/main/src/digital_twin/splits.py"
click node_baselines "https://github.com/that-tech-geek/digital-twin/blob/main/src/digital_twin/baselines.py"
click node_training "https://github.com/that-tech-geek/digital-twin/blob/main/src/digital_twin/training.py"
click node_models "https://github.com/that-tech-geek/digital-twin/blob/main/src/digital_twin/models.py"
click node_prior "https://github.com/that-tech-geek/digital-twin/blob/main/src/digital_twin/twin_layers/layer_a.py"
click node_state "https://github.com/that-tech-geek/digital-twin/blob/main/src/digital_twin/twin_layers/layer_b.py"
click node_simulator "https://github.com/that-tech-geek/digital-twin/blob/main/src/digital_twin/twin_layers/layer_c.py"
click node_runtime_twin "https://github.com/that-tech-geek/digital-twin/blob/main/src/digital_twin/twin.py"
click node_evaluation "https://github.com/that-tech-geek/digital-twin/blob/main/src/digital_twin/evaluation.py"
click node_artifacts "https://github.com/that-tech-geek/digital-twin/blob/main/src/digital_twin/artifacts.py"
click node_cli "https://github.com/that-tech-geek/digital-twin/blob/main/src/digital_twin/cli.py"
click node_dashboard "https://github.com/that-tech-geek/digital-twin/blob/main/src/digital_twin/dashboard/app.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_csv_adapter,node_synthea_adapter,node_schema,node_preprocessing,node_labels toneBlue
class node_splits,node_baselines,node_training,node_models toneAmber
class node_prior,node_state,node_simulator,node_runtime_twin toneMint
class node_pipeline,node_evaluation,node_artifacts,node_cli,node_dashboard toneRose
class node_ohio,node_diatrend,node_hupa,node_synthea toneIndigo
```

## Components

### Data preparation

- [CSV adapter](https://github.com/that-tech-geek/digital-twin/blob/main/src/digital_twin/ingestion/csv.py): `src/digital_twin/ingestion/csv.py`
- [FHIR adapter](https://github.com/that-tech-geek/digital-twin/blob/main/src/digital_twin/ingestion/synthea.py): `src/digital_twin/ingestion/synthea.py`
- [Canonical schema](https://github.com/that-tech-geek/digital-twin/blob/main/src/digital_twin/schema.py): `src/digital_twin/schema.py`
- [Timeline and features](https://github.com/that-tech-geek/digital-twin/blob/main/src/digital_twin/preprocessing.py): `src/digital_twin/preprocessing.py`
- [Hypoglycemia labels](https://github.com/that-tech-geek/digital-twin/blob/main/src/digital_twin/labels.py): `src/digital_twin/labels.py`

### Forecast learning

- [Patient splits](https://github.com/that-tech-geek/digital-twin/blob/main/src/digital_twin/splits.py): `src/digital_twin/splits.py`
- [Forecast baselines](https://github.com/that-tech-geek/digital-twin/blob/main/src/digital_twin/baselines.py): `src/digital_twin/baselines.py`
- [GRU training](https://github.com/that-tech-geek/digital-twin/blob/main/src/digital_twin/training.py): `src/digital_twin/training.py`
- [Forecast model](https://github.com/that-tech-geek/digital-twin/blob/main/src/digital_twin/models.py): `src/digital_twin/models.py`

### Digital twin

- [Layer A prior](https://github.com/that-tech-geek/digital-twin/blob/main/src/digital_twin/twin_layers/layer_a.py): `src/digital_twin/twin_layers/layer_a.py`
- [Layer B estimator](https://github.com/that-tech-geek/digital-twin/blob/main/src/digital_twin/twin_layers/layer_b.py): `src/digital_twin/twin_layers/layer_b.py`
- [Layer C simulator](https://github.com/that-tech-geek/digital-twin/blob/main/src/digital_twin/twin_layers/layer_c.py): `src/digital_twin/twin_layers/layer_c.py`
- [Runtime patient twin](https://github.com/that-tech-geek/digital-twin/blob/main/src/digital_twin/twin.py): `src/digital_twin/twin.py`

### Research outputs

- [Pipeline orchestrator](https://github.com/that-tech-geek/digital-twin/blob/main/src/digital_twin/pipeline.py): `src/digital_twin/pipeline.py`
- [Patient evaluation](https://github.com/that-tech-geek/digital-twin/blob/main/src/digital_twin/evaluation.py): `src/digital_twin/evaluation.py`
- [Research artifacts](https://github.com/that-tech-geek/digital-twin/blob/main/src/digital_twin/artifacts.py): `src/digital_twin/artifacts.py`
- [CLI and demo](https://github.com/that-tech-geek/digital-twin/blob/main/src/digital_twin/cli.py): `src/digital_twin/cli.py`
- [Research dashboard](https://github.com/that-tech-geek/digital-twin/blob/main/src/digital_twin/dashboard/app.py): `src/digital_twin/dashboard/app.py`

### Other components

- **OhioT1DM**
- **DiaTrend**
- **HUPA-UCM**
- **Synthea FHIR**

## Connections

- OhioT1DM → CSV adapter: provides data
- DiaTrend → CSV adapter: provides data
- HUPA-UCM → CSV adapter: provides data
- Synthea FHIR → FHIR adapter: provides bundle
- CSV adapter → Canonical schema: canonicalizes
- FHIR adapter → Canonical schema: outputs records
- Pipeline orchestrator → Canonical schema: canonicalizes
- Pipeline orchestrator → Timeline and features: resamples and featurizes
- Pipeline orchestrator → Hypoglycemia labels: adds labels
- Pipeline orchestrator → Patient splits: checks patient split
- Patient splits → Forecast baselines: supports comparison
- Pipeline orchestrator → GRU training: trains model
- GRU training → Forecast model: optimizes
- Pipeline orchestrator → Layer B estimator: builds estimator
- Layer B estimator → Forecast model: runs forecasts
- Pipeline orchestrator → Layer A prior: creates patient prior
- Pipeline orchestrator → Layer C simulator: forecasts and simulates
- Layer C simulator → Layer B estimator: requests distribution
- Layer C simulator → Layer A prior: conditions uncertainty
- Runtime patient twin → Layer B estimator: updates state
- Runtime patient twin → Layer C simulator: forecasts or simulates
- Pipeline orchestrator → Patient evaluation: computes metrics
- Pipeline orchestrator → Research artifacts: writes results
- CLI and demo → Pipeline orchestrator: runs workflow
- Research dashboard → Pipeline orchestrator: prepares demo
- Research dashboard → Layer C simulator: shows forecast and scenarios