# subhadip543/heartguard-ai architecture

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

- Interactive diagram: https://gitdiagram.com/subhadip543/heartguard-ai
- Repository: https://github.com/subhadip543/heartguard-ai

## Overview

HeartGuard AI is an educational heart-risk assessment application combining a React interface, a FastAPI backend, and a Python ML pipeline. The intended user journey is to access the app, register or sign in, complete an assessment, and view risk results and history; the README cautions that frontend-backend integration and inference remain under development. The UI also exposes doctor, emergency, monitoring, education, and AI-assistant features. Edges reflect shown imports/calls or README-documented intent; unsampled modules and planned integrations are not treated as verified runtime connections.

Main entry points: [`frontend/src/App.jsx`](https://github.com/subhadip543/heartguard-ai/blob/main/frontend/src/App.jsx) (React app routes), [`backend/app/api/v1/router.py`](https://github.com/subhadip543/heartguard-ai/blob/main/backend/app/api/v1/router.py) (API v1 routes), [`backend/app/api/v1/endpoints/auth.py`](https://github.com/subhadip543/heartguard-ai/blob/main/backend/app/api/v1/endpoints/auth.py) (Authentication endpoints), [`backend/app/api/v1/endpoints/assessments.py`](https://github.com/subhadip543/heartguard-ai/blob/main/backend/app/api/v1/endpoints/assessments.py) (Assessment endpoints)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["User interface"]
  node_app["React app routes<br/>[App.jsx]"]
  node_home["Home and dashboards<br/>[Home.jsx]"]
  node_assessment_ui["Risk assessment UI"]
  node_results_ui["Results and history"]
  node_auth_ui["Sign-in and registration<br/>[Login.jsx]"]
  node_doctor_ui["Doctor dashboard"]
  node_emergency_ui["Emergency support<br/>[Emergency.jsx]"]
  node_monitoring_ui["Health monitoring"]
  node_education_ui["Heart education"]
  node_resources_ui["Heart resources<br/>[HeartResources.jsx]"]
  node_assistant_ui["Heart assistant<br/>[HeartAssistant.jsx]"]
  node_theme["Theme context<br/>[ThemeProvider.jsx]"]
end

subgraph group_backend["API and services"]
  node_api["API application<br/>[main.py]"]
  node_router["API v1 routes<br/>[router.py]"]
  node_auth_api["Authentication endpoints<br/>[auth.py]"]
  node_patient_api["Patient endpoints<br/>[patients.py]"]
  node_assessment_api["Assessment endpoints<br/>[assessments.py]"]
  node_predict_api["Prediction endpoint<br/>[predict.py]"]
  node_ai_api["AI chat endpoint<br/>[ai.py]"]
  node_ai_service["AI chat service<br/>[ai_service.py]"]
  node_email["Reset email service<br/>[email_service.py]"]
  node_auth_security["Auth dependencies<br/>[dependencies.py]"]
  node_security["Token security<br/>[security.py]"]
  node_prediction_service["Prediction service"]
end

subgraph group_data["Patient data"]
  node_db_session["Database sessions<br/>[session.py]"]
  node_patient_model[("Patient records<br/>[patient.py]")]
  node_assessment_model[("Assessment records<br/>[assessment.py]")]
end

subgraph group_ml["ML pipeline"]
  node_ml_inference["Model inference<br/>[prediction.py]"]
  node_ml_preprocess["Preprocessing<br/>[preprocessing.py]"]
  node_ml_train["Training and evaluation<br/>[train.py]"]
  node_ml_experiments["Missing-value experiments"]
end

node_patient(("Patient"))
node_doctor(("Doctor"))
node_gemini["Google Gemini API"]

node_patient -->|"uses"| node_app
node_doctor -->|"uses"| node_app
node_app -->|"routes to"| node_home
node_app -->|"routes to"| node_assessment_ui
node_app -->|"routes to"| node_results_ui
node_app -->|"routes to"| node_auth_ui
node_app -->|"routes to"| node_doctor_ui
node_app -->|"routes to"| node_emergency_ui
node_app -->|"routes to"| node_monitoring_ui
node_app -->|"routes to"| node_education_ui
node_app -->|"routes to"| node_resources_ui
node_app -->|"routes to"| node_assistant_ui
node_app -->|"provides"| node_theme
node_app -.->|"HTTP API"| node_api
node_api -->|"mounts"| node_router
node_router -->|"registers"| node_auth_api
node_router -->|"registers"| node_patient_api
node_router -->|"registers"| node_assessment_api
node_router -->|"registers"| node_predict_api
node_router -->|"registers"| node_ai_api
node_auth_api -->|"authenticates via"| node_auth_security
node_auth_security -->|"decodes token"| node_security
node_auth_api -->|"queries"| node_db_session
node_auth_api -->|"reads and writes"| node_patient_model
node_auth_api -->|"sends reset email"| node_email
node_patient_api -->|"queries"| node_db_session
node_patient_api -->|"reads and writes"| node_patient_model
node_assessment_api -->|"uses"| node_db_session
node_assessment_api -->|"uses"| node_patient_model
node_assessment_api -->|"uses"| node_assessment_model
node_assessment_api -->|"requests prediction"| node_prediction_service
node_predict_api -->|"requests prediction"| node_prediction_service
node_ai_api -->|"generates reply"| node_ai_service
node_ai_service -->|"sends prompt"| node_gemini
node_prediction_service -->|"calls inference"| node_ml_inference
node_ml_train -->|"uses"| node_ml_preprocess
node_ml_train -->|"builds classifiers"| node_ml_experiments

click node_app "https://github.com/subhadip543/heartguard-ai/blob/main/frontend/src/App.jsx"
click node_home "https://github.com/subhadip543/heartguard-ai/blob/main/frontend/src/Pages/Home.jsx"
click node_assessment_ui "https://github.com/subhadip543/heartguard-ai/blob/main/frontend/src/Pages/HeartAssessment.jsx"
click node_results_ui "https://github.com/subhadip543/heartguard-ai/blob/main/frontend/src/Pages/AssessmentResult.jsx"
click node_auth_ui "https://github.com/subhadip543/heartguard-ai/blob/main/frontend/src/Pages/Login.jsx"
click node_doctor_ui "https://github.com/subhadip543/heartguard-ai/blob/main/frontend/src/DoctorDashboard.jsx"
click node_emergency_ui "https://github.com/subhadip543/heartguard-ai/blob/main/frontend/src/Emergency.jsx"
click node_monitoring_ui "https://github.com/subhadip543/heartguard-ai/blob/main/frontend/src/Pages/LiveHealthMonitoring.jsx"
click node_education_ui "https://github.com/subhadip543/heartguard-ai/blob/main/frontend/src/Pages/HealthAwareness.jsx"
click node_resources_ui "https://github.com/subhadip543/heartguard-ai/blob/main/frontend/src/HeartResources.jsx"
click node_assistant_ui "https://github.com/subhadip543/heartguard-ai/blob/main/frontend/src/HeartAssistant.jsx"
click node_theme "https://github.com/subhadip543/heartguard-ai/blob/main/frontend/src/context/ThemeProvider.jsx"
click node_api "https://github.com/subhadip543/heartguard-ai/blob/main/backend/app/main.py"
click node_router "https://github.com/subhadip543/heartguard-ai/blob/main/backend/app/api/v1/router.py"
click node_auth_api "https://github.com/subhadip543/heartguard-ai/blob/main/backend/app/api/v1/endpoints/auth.py"
click node_patient_api "https://github.com/subhadip543/heartguard-ai/blob/main/backend/app/api/v1/endpoints/patients.py"
click node_assessment_api "https://github.com/subhadip543/heartguard-ai/blob/main/backend/app/api/v1/endpoints/assessments.py"
click node_predict_api "https://github.com/subhadip543/heartguard-ai/blob/main/backend/app/api/v1/endpoints/predict.py"
click node_ai_api "https://github.com/subhadip543/heartguard-ai/blob/main/backend/app/api/v1/endpoints/ai.py"
click node_ai_service "https://github.com/subhadip543/heartguard-ai/blob/main/backend/app/services/ai_service.py"
click node_email "https://github.com/subhadip543/heartguard-ai/blob/main/backend/app/services/email_service.py"
click node_auth_security "https://github.com/subhadip543/heartguard-ai/blob/main/backend/app/core/dependencies.py"
click node_security "https://github.com/subhadip543/heartguard-ai/blob/main/backend/app/core/security.py"
click node_db_session "https://github.com/subhadip543/heartguard-ai/blob/main/backend/app/db/session.py"
click node_patient_model "https://github.com/subhadip543/heartguard-ai/blob/main/backend/app/models/patient.py"
click node_assessment_model "https://github.com/subhadip543/heartguard-ai/blob/main/backend/app/models/assessment.py"
click node_prediction_service "https://github.com/subhadip543/heartguard-ai/blob/main/backend/app/services/prediction_service.py"
click node_ml_inference "https://github.com/subhadip543/heartguard-ai/blob/main/ml/src/prediction.py"
click node_ml_preprocess "https://github.com/subhadip543/heartguard-ai/blob/main/ml/src/preprocessing.py"
click node_ml_train "https://github.com/subhadip543/heartguard-ai/blob/main/ml/src/train.py"
click node_ml_experiments "https://github.com/subhadip543/heartguard-ai/blob/main/ml/src/missing_value_experiment.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_app,node_home,node_assessment_ui,node_results_ui,node_auth_ui,node_doctor_ui,node_emergency_ui,node_monitoring_ui,node_education_ui,node_resources_ui,node_assistant_ui,node_theme toneBlue
class node_api,node_router,node_auth_api,node_patient_api,node_assessment_api,node_predict_api,node_ai_api,node_ai_service,node_email,node_auth_security,node_security,node_prediction_service toneAmber
class node_db_session,node_patient_model,node_assessment_model,node_gemini toneMint
class node_ml_inference,node_ml_preprocess,node_ml_train,node_ml_experiments toneRose
class node_patient,node_doctor toneIndigo
```

## Components

### User interface

- [React app routes](https://github.com/subhadip543/heartguard-ai/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Home and dashboards](https://github.com/subhadip543/heartguard-ai/blob/main/frontend/src/Pages/Home.jsx): `frontend/src/Pages/Home.jsx`
- [Risk assessment UI](https://github.com/subhadip543/heartguard-ai/blob/main/frontend/src/Pages/HeartAssessment.jsx): `frontend/src/Pages/HeartAssessment.jsx`
- [Results and history](https://github.com/subhadip543/heartguard-ai/blob/main/frontend/src/Pages/AssessmentResult.jsx): `frontend/src/Pages/AssessmentResult.jsx`
- [Sign-in and registration](https://github.com/subhadip543/heartguard-ai/blob/main/frontend/src/Pages/Login.jsx): `frontend/src/Pages/Login.jsx`
- [Doctor dashboard](https://github.com/subhadip543/heartguard-ai/blob/main/frontend/src/DoctorDashboard.jsx): `frontend/src/DoctorDashboard.jsx`
- [Emergency support](https://github.com/subhadip543/heartguard-ai/blob/main/frontend/src/Emergency.jsx): `frontend/src/Emergency.jsx`
- [Health monitoring](https://github.com/subhadip543/heartguard-ai/blob/main/frontend/src/Pages/LiveHealthMonitoring.jsx): `frontend/src/Pages/LiveHealthMonitoring.jsx`
- [Heart education](https://github.com/subhadip543/heartguard-ai/blob/main/frontend/src/Pages/HealthAwareness.jsx): `frontend/src/Pages/HealthAwareness.jsx`
- [Heart resources](https://github.com/subhadip543/heartguard-ai/blob/main/frontend/src/HeartResources.jsx): `frontend/src/HeartResources.jsx`
- [Heart assistant](https://github.com/subhadip543/heartguard-ai/blob/main/frontend/src/HeartAssistant.jsx): `frontend/src/HeartAssistant.jsx`
- [Theme context](https://github.com/subhadip543/heartguard-ai/blob/main/frontend/src/context/ThemeProvider.jsx): `frontend/src/context/ThemeProvider.jsx`

### API and services

- [API application](https://github.com/subhadip543/heartguard-ai/blob/main/backend/app/main.py): `backend/app/main.py`
- [API v1 routes](https://github.com/subhadip543/heartguard-ai/blob/main/backend/app/api/v1/router.py): `backend/app/api/v1/router.py`
- [Authentication endpoints](https://github.com/subhadip543/heartguard-ai/blob/main/backend/app/api/v1/endpoints/auth.py): `backend/app/api/v1/endpoints/auth.py`
- [Patient endpoints](https://github.com/subhadip543/heartguard-ai/blob/main/backend/app/api/v1/endpoints/patients.py): `backend/app/api/v1/endpoints/patients.py`
- [Assessment endpoints](https://github.com/subhadip543/heartguard-ai/blob/main/backend/app/api/v1/endpoints/assessments.py): `backend/app/api/v1/endpoints/assessments.py`
- [Prediction endpoint](https://github.com/subhadip543/heartguard-ai/blob/main/backend/app/api/v1/endpoints/predict.py): `backend/app/api/v1/endpoints/predict.py`
- [AI chat endpoint](https://github.com/subhadip543/heartguard-ai/blob/main/backend/app/api/v1/endpoints/ai.py): `backend/app/api/v1/endpoints/ai.py`
- [AI chat service](https://github.com/subhadip543/heartguard-ai/blob/main/backend/app/services/ai_service.py): `backend/app/services/ai_service.py`
- [Reset email service](https://github.com/subhadip543/heartguard-ai/blob/main/backend/app/services/email_service.py): `backend/app/services/email_service.py`
- [Auth dependencies](https://github.com/subhadip543/heartguard-ai/blob/main/backend/app/core/dependencies.py): `backend/app/core/dependencies.py`
- [Token security](https://github.com/subhadip543/heartguard-ai/blob/main/backend/app/core/security.py): `backend/app/core/security.py`
- [Prediction service](https://github.com/subhadip543/heartguard-ai/blob/main/backend/app/services/prediction_service.py): `backend/app/services/prediction_service.py`

### Patient data

- [Database sessions](https://github.com/subhadip543/heartguard-ai/blob/main/backend/app/db/session.py): `backend/app/db/session.py`
- [Patient records](https://github.com/subhadip543/heartguard-ai/blob/main/backend/app/models/patient.py): `backend/app/models/patient.py`
- [Assessment records](https://github.com/subhadip543/heartguard-ai/blob/main/backend/app/models/assessment.py): `backend/app/models/assessment.py`

### ML pipeline

- [Model inference](https://github.com/subhadip543/heartguard-ai/blob/main/ml/src/prediction.py): `ml/src/prediction.py`
- [Preprocessing](https://github.com/subhadip543/heartguard-ai/blob/main/ml/src/preprocessing.py): `ml/src/preprocessing.py`
- [Training and evaluation](https://github.com/subhadip543/heartguard-ai/blob/main/ml/src/train.py): `ml/src/train.py`
- [Missing-value experiments](https://github.com/subhadip543/heartguard-ai/blob/main/ml/src/missing_value_experiment.py): `ml/src/missing_value_experiment.py`

### Other components

- **Patient**
- **Doctor**
- **Google Gemini API**

## Connections

- Patient → React app routes: uses (evidence: `README.md`)
- Doctor → React app routes: uses (evidence: `README.md`)
- React app routes → Home and dashboards: routes to (evidence: `frontend/src/App.jsx`)
- React app routes → Risk assessment UI: routes to (evidence: `frontend/src/App.jsx`)
- React app routes → Results and history: routes to (evidence: `frontend/src/App.jsx`)
- React app routes → Sign-in and registration: routes to (evidence: `frontend/src/App.jsx`)
- React app routes → Doctor dashboard: routes to (evidence: `frontend/src/App.jsx`)
- React app routes → Emergency support: routes to (evidence: `frontend/src/App.jsx`)
- React app routes → Health monitoring: routes to (evidence: `frontend/src/App.jsx`)
- React app routes → Heart education: routes to (evidence: `frontend/src/App.jsx`)
- React app routes → Heart resources: routes to (evidence: `frontend/src/App.jsx`)
- React app routes → Heart assistant: routes to (evidence: `frontend/src/App.jsx`)
- React app routes → Theme context: provides (evidence: `frontend/src/App.jsx`)
- React app routes → API application: HTTP API (evidence: `README.md`)
- API application → API v1 routes: mounts (evidence: `backend/app/main.py`)
- API v1 routes → Authentication endpoints: registers (evidence: `backend/app/api/v1/router.py`)
- API v1 routes → Patient endpoints: registers (evidence: `backend/app/api/v1/router.py`)
- API v1 routes → Assessment endpoints: registers (evidence: `backend/app/api/v1/router.py`)
- API v1 routes → Prediction endpoint: registers (evidence: `backend/app/api/v1/router.py`)
- API v1 routes → AI chat endpoint: registers (evidence: `backend/app/api/v1/router.py`)
- Authentication endpoints → Auth dependencies: authenticates via (evidence: `backend/app/api/v1/endpoints/auth.py`)
- Auth dependencies → Token security: decodes token (evidence: `backend/app/core/dependencies.py`)
- Authentication endpoints → Database sessions: queries (evidence: `backend/app/api/v1/endpoints/auth.py`)
- Authentication endpoints → Patient records: reads and writes (evidence: `backend/app/api/v1/endpoints/auth.py`)
- Authentication endpoints → Reset email service: sends reset email (evidence: `backend/app/api/v1/endpoints/auth.py`)
- Patient endpoints → Database sessions: queries (evidence: `backend/app/api/v1/endpoints/patients.py`)
- Patient endpoints → Patient records: reads and writes (evidence: `backend/app/api/v1/endpoints/patients.py`)
- Assessment endpoints → Database sessions: uses (evidence: `backend/app/api/v1/endpoints/assessments.py`)
- Assessment endpoints → Patient records: uses (evidence: `backend/app/api/v1/endpoints/assessments.py`)
- Assessment endpoints → Assessment records: uses (evidence: `backend/app/api/v1/endpoints/assessments.py`)
- Assessment endpoints → Prediction service: requests prediction (evidence: `backend/app/api/v1/endpoints/assessments.py`)
- Prediction endpoint → Prediction service: requests prediction (evidence: `backend/app/api/v1/endpoints/predict.py`)
- AI chat endpoint → AI chat service: generates reply (evidence: `backend/app/api/v1/endpoints/ai.py`)
- AI chat service → Google Gemini API: sends prompt (evidence: `backend/app/services/ai_service.py`)
- Prediction service → Model inference: calls inference (evidence: `backend/app/services/prediction_service.py`)
- Training and evaluation → Preprocessing: uses (evidence: `ml/src/train.py`)
- Training and evaluation → Missing-value experiments: builds classifiers (evidence: `ml/src/missing_value_experiment.py`)
