# ayush-dev-001/cardio architecture

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

- Interactive diagram: https://gitdiagram.com/ayush-dev-001/cardio
- Repository: https://github.com/ayush-dev-001/cardio

## Overview

CardioScope is an interactive CAD decision-support and education application. A user enters routine clinical measurements, receives overall CAD and LAD/LCX/RCA stenosis estimates, sees risk mapped onto a 3D heart, and can inspect SHAP explanations and what-if changes. The repository also includes the data preparation and model-training workflow behind the serving models. The principal execution path is documented, while several frontend and ML internals are represented at their source-directory boundary because their implementation was not sampled.

Main entry points: [`frontend/src/App.tsx`](https://github.com/ayush-dev-001/cardio/blob/main/frontend/src/App.tsx) (Dashboard), [`backend/app/service.py`](https://github.com/ayush-dev-001/cardio/blob/main/backend/app/service.py) (Prediction service), [`ml/cardioscope_ml/train.py`](https://github.com/ayush-dev-001/cardio/blob/main/ml/cardioscope_ml/train.py) (Training and evaluation), [`backend/app/main.py`](https://github.com/ayush-dev-001/cardio/blob/main/backend/app/main.py) (HTTP API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_landing["Landing page<br/>[Landing.tsx]"]
  node_dashboard["Dashboard<br/>[App.tsx]"]
  node_patient["Patient inputs<br/>[PatientForm.tsx]"]
  node_api_client["API client<br/>[client.ts]"]
  node_heart_view["3D heart viewer<br/>[HeartViewer.tsx]"]
  node_results["Risk and SHAP results<br/>[Results.tsx]"]
  node_whatif["What-if analysis<br/>[WhatIfPanel.tsx]"]
end

subgraph group_serving["Prediction service"]
  node_backend_api["HTTP API<br/>[main.py]"]
  node_service["Prediction service<br/>[service.py]"]
  node_schemas["Request and response schemas<br/>[schemas.py]"]
end

subgraph group_ml["ML pipeline"]
  node_predictor["Model predictor<br/>[predictor.py]"]
  node_explain["SHAP explanations<br/>[explain.py]"]
  node_calibration["Probability calibration<br/>[calibration.py]"]
  node_training["Training and evaluation<br/>[train.py]"]
  node_nested_cv["Nested cross-validation<br/>[nested_cv.py]"]
  node_modeling["Model fitting<br/>[modeling.py]"]
  node_model_store[("Trained models")]
end

subgraph group_data["Data and configuration"]
  node_data_prep["Data preparation<br/>[data.py]"]
  node_feature_config["Feature and target definitions<br/>[config.py]"]
  node_derived["Derived clinical features<br/>[derived.py]"]
  node_dataset[("Clinical dataset")]
end

node_user(("Clinician or learner"))

node_user -->|"opens"| node_landing
node_landing -->|"opens app"| node_dashboard
node_user -->|"enters data"| node_patient
node_patient -.->|"updates inputs"| node_dashboard
node_dashboard -.->|"requests predictions"| node_api_client
node_api_client -->|"sends HTTP"| node_backend_api
node_backend_api -->|"validates and shapes"| node_schemas
node_backend_api -->|"dispatches"| node_service
node_service -->|"predicts"| node_predictor
node_service -->|"derives inputs"| node_derived
node_service -->|"builds explanations"| node_explain
node_service -->|"reads definitions"| node_feature_config
node_predictor -->|"calibrates probabilities"| node_calibration
node_predictor -.->|"loads models"| node_model_store
node_dashboard -->|"renders probabilities"| node_heart_view
node_dashboard -.->|"renders results"| node_results
node_dashboard -.->|"offers what-if"| node_whatif
node_results -.->|"maps risk to anatomy"| node_heart_view
node_training -->|"prepares data"| node_data_prep
node_data_prep -.->|"reads clinical records"| node_dataset
node_data_prep -->|"uses definitions"| node_feature_config
node_training -->|"evaluates models"| node_nested_cv
node_nested_cv -->|"fits fold models"| node_modeling
node_modeling -->|"fits calibrator"| node_calibration
node_training -->|"creates explainers"| node_explain
node_training -.->|"saves trained models"| node_model_store

click node_landing "https://github.com/ayush-dev-001/cardio/blob/main/frontend/src/landing/Landing.tsx"
click node_dashboard "https://github.com/ayush-dev-001/cardio/blob/main/frontend/src/App.tsx"
click node_patient "https://github.com/ayush-dev-001/cardio/blob/main/frontend/src/components/PatientForm.tsx"
click node_api_client "https://github.com/ayush-dev-001/cardio/blob/main/frontend/src/api/client.ts"
click node_heart_view "https://github.com/ayush-dev-001/cardio/blob/main/frontend/src/scene/HeartViewer.tsx"
click node_results "https://github.com/ayush-dev-001/cardio/blob/main/frontend/src/components/Results.tsx"
click node_whatif "https://github.com/ayush-dev-001/cardio/blob/main/frontend/src/components/WhatIfPanel.tsx"
click node_backend_api "https://github.com/ayush-dev-001/cardio/blob/main/backend/app/main.py"
click node_service "https://github.com/ayush-dev-001/cardio/blob/main/backend/app/service.py"
click node_schemas "https://github.com/ayush-dev-001/cardio/blob/main/backend/app/schemas.py"
click node_predictor "https://github.com/ayush-dev-001/cardio/blob/main/ml/cardioscope_ml/predictor.py"
click node_explain "https://github.com/ayush-dev-001/cardio/blob/main/ml/cardioscope_ml/explain.py"
click node_calibration "https://github.com/ayush-dev-001/cardio/blob/main/ml/cardioscope_ml/calibration.py"
click node_training "https://github.com/ayush-dev-001/cardio/blob/main/ml/cardioscope_ml/train.py"
click node_nested_cv "https://github.com/ayush-dev-001/cardio/blob/main/ml/cardioscope_ml/nested_cv.py"
click node_modeling "https://github.com/ayush-dev-001/cardio/blob/main/ml/cardioscope_ml/modeling.py"
click node_data_prep "https://github.com/ayush-dev-001/cardio/blob/main/ml/cardioscope_ml/data.py"
click node_feature_config "https://github.com/ayush-dev-001/cardio/blob/main/ml/cardioscope_ml/config.py"
click node_derived "https://github.com/ayush-dev-001/cardio/blob/main/ml/cardioscope_ml/derived.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_landing,node_dashboard,node_patient,node_api_client,node_heart_view,node_results,node_whatif toneBlue
class node_backend_api,node_service,node_schemas toneAmber
class node_predictor,node_explain,node_calibration,node_training,node_nested_cv,node_modeling,node_model_store toneMint
class node_data_prep,node_feature_config,node_derived,node_dataset toneRose
class node_user toneIndigo
```

## Components

### User experience

- [Landing page](https://github.com/ayush-dev-001/cardio/blob/main/frontend/src/landing/Landing.tsx): `frontend/src/landing/Landing.tsx`
- [Dashboard](https://github.com/ayush-dev-001/cardio/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Patient inputs](https://github.com/ayush-dev-001/cardio/blob/main/frontend/src/components/PatientForm.tsx): `frontend/src/components/PatientForm.tsx`
- [API client](https://github.com/ayush-dev-001/cardio/blob/main/frontend/src/api/client.ts): `frontend/src/api/client.ts`
- [3D heart viewer](https://github.com/ayush-dev-001/cardio/blob/main/frontend/src/scene/HeartViewer.tsx): `frontend/src/scene/HeartViewer.tsx`
- [Risk and SHAP results](https://github.com/ayush-dev-001/cardio/blob/main/frontend/src/components/Results.tsx): `frontend/src/components/Results.tsx`
- [What-if analysis](https://github.com/ayush-dev-001/cardio/blob/main/frontend/src/components/WhatIfPanel.tsx): `frontend/src/components/WhatIfPanel.tsx`

### Prediction service

- [HTTP API](https://github.com/ayush-dev-001/cardio/blob/main/backend/app/main.py): `backend/app/main.py`
- [Prediction service](https://github.com/ayush-dev-001/cardio/blob/main/backend/app/service.py): `backend/app/service.py`
- [Request and response schemas](https://github.com/ayush-dev-001/cardio/blob/main/backend/app/schemas.py): `backend/app/schemas.py`

### ML pipeline

- [Model predictor](https://github.com/ayush-dev-001/cardio/blob/main/ml/cardioscope_ml/predictor.py): `ml/cardioscope_ml/predictor.py`
- [SHAP explanations](https://github.com/ayush-dev-001/cardio/blob/main/ml/cardioscope_ml/explain.py): `ml/cardioscope_ml/explain.py`
- [Probability calibration](https://github.com/ayush-dev-001/cardio/blob/main/ml/cardioscope_ml/calibration.py): `ml/cardioscope_ml/calibration.py`
- [Training and evaluation](https://github.com/ayush-dev-001/cardio/blob/main/ml/cardioscope_ml/train.py): `ml/cardioscope_ml/train.py`
- [Nested cross-validation](https://github.com/ayush-dev-001/cardio/blob/main/ml/cardioscope_ml/nested_cv.py): `ml/cardioscope_ml/nested_cv.py`
- [Model fitting](https://github.com/ayush-dev-001/cardio/blob/main/ml/cardioscope_ml/modeling.py): `ml/cardioscope_ml/modeling.py`
- **Trained models**

### Data and configuration

- [Data preparation](https://github.com/ayush-dev-001/cardio/blob/main/ml/cardioscope_ml/data.py): `ml/cardioscope_ml/data.py`
- [Feature and target definitions](https://github.com/ayush-dev-001/cardio/blob/main/ml/cardioscope_ml/config.py): `ml/cardioscope_ml/config.py`
- [Derived clinical features](https://github.com/ayush-dev-001/cardio/blob/main/ml/cardioscope_ml/derived.py): `ml/cardioscope_ml/derived.py`
- **Clinical dataset**

### Other components

- **Clinician or learner**

## Connections

- Clinician or learner → Landing page: opens (evidence: `README.md`)
- Landing page → Dashboard: opens app (evidence: `frontend/src/landing/Landing.tsx`)
- Clinician or learner → Patient inputs: enters data (evidence: `README.md`)
- Patient inputs → Dashboard: updates inputs (evidence: `frontend/src/App.tsx`)
- Dashboard → API client: requests predictions (evidence: `frontend/src/App.tsx`)
- API client → HTTP API: sends HTTP (evidence: `README.md`)
- HTTP API → Request and response schemas: validates and shapes (evidence: `backend/app/main.py`)
- HTTP API → Prediction service: dispatches (evidence: `backend/app/main.py`)
- Prediction service → Model predictor: predicts (evidence: `backend/app/service.py`)
- Prediction service → Derived clinical features: derives inputs (evidence: `backend/app/service.py`)
- Prediction service → SHAP explanations: builds explanations (evidence: `backend/app/service.py`)
- Prediction service → Feature and target definitions: reads definitions (evidence: `backend/app/service.py`)
- Model predictor → Probability calibration: calibrates probabilities (evidence: `ml/cardioscope_ml/predictor.py`)
- Model predictor → Trained models: loads models
- Dashboard → 3D heart viewer: renders probabilities (evidence: `frontend/src/App.tsx`)
- Dashboard → Risk and SHAP results: renders results (evidence: `frontend/src/App.tsx`)
- Dashboard → What-if analysis: offers what-if (evidence: `frontend/src/App.tsx`)
- Risk and SHAP results → 3D heart viewer: maps risk to anatomy
- Training and evaluation → Data preparation: prepares data (evidence: `ml/cardioscope_ml/train.py`)
- Data preparation → Clinical dataset: reads clinical records
- Data preparation → Feature and target definitions: uses definitions (evidence: `ml/cardioscope_ml/data.py`)
- Training and evaluation → Nested cross-validation: evaluates models (evidence: `ml/cardioscope_ml/train.py`)
- Nested cross-validation → Model fitting: fits fold models (evidence: `ml/cardioscope_ml/nested_cv.py`)
- Model fitting → Probability calibration: fits calibrator (evidence: `ml/cardioscope_ml/modeling.py`)
- Training and evaluation → SHAP explanations: creates explainers (evidence: `ml/cardioscope_ml/train.py`)
- Training and evaluation → Trained models: saves trained models
