# nisheelmodi/healthsense-ai architecture

> Architecture diagram of the GitHub repository nisheelmodi/healthsense-ai, 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/nisheelmodi/healthsense-ai
- Repository: https://github.com/nisheelmodi/healthsense-ai

## Overview

HealthSense AI is a web-based cardiovascular risk assessment tool. A user enters personal, lifestyle, and symptom information in the guided wizard; the frontend submits it to FastAPI, which returns a prediction for the results page to display with risk factors and wellness recommendations. The README documents the backend’s ML inference flow and the CDC BRFSS training pipeline. Backend source was listed as read but not excerpted, so internal API-to-model details are shown only where documented, not inferred from unsampled implementation.

Main entry points: [`src/components/AssessmentWizard.tsx`](https://github.com/nisheelmodi/healthsense-ai/blob/main/src/components/AssessmentWizard.tsx) (Assessment wizard), [`src/app/result/page.tsx`](https://github.com/nisheelmodi/healthsense-ai/blob/main/src/app/result/page.tsx) (Results page), [`backend/main.py`](https://github.com/nisheelmodi/healthsense-ai/blob/main/backend/main.py) (FastAPI prediction API), [`ml/src/train.py`](https://github.com/nisheelmodi/healthsense-ai/blob/main/ml/src/train.py) (Model training)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Web experience"]
  node_home["Home page<br/>[page.tsx]"]
  node_navbar["Navigation<br/>[Navbar.tsx]"]
  node_result_page["Results page<br/>[page.tsx]"]
  node_result_card["Risk score display<br/>[ResultCard.tsx]"]
  node_summary_card["Risk summary<br/>[SummaryCard.tsx]"]
  node_recommendations["Recommendations"]
  node_disclaimer["Medical disclaimer<br/>[DisclaimerCard.tsx]"]
end

subgraph group_assessment["Assessment flow"]
  node_assessment_page["Assessment page<br/>[page.tsx]"]
  node_wizard["Assessment wizard"]
  node_personal["Personal details"]
  node_lifestyle["Lifestyle details<br/>[LifestyleStep.tsx]"]
  node_symptoms["Symptoms<br/>[SymptomsStep.tsx]"]
  node_progress["Step progress"]
  node_navigation_controls["Step controls"]
  node_loading["Loading state<br/>[LoadingScreen.tsx]"]
end

subgraph group_prediction["Prediction service"]
  node_backend["FastAPI prediction API<br/>[main.py]"]
  node_risk_calculator["Fallback risk scoring<br/>[riskCalculator.ts]"]
end

subgraph group_ml["Machine learning"]
  node_training["Model training<br/>[train.py]"]
  node_preprocessing["Dataset preprocessing<br/>[preprocess.py]"]
  node_model_artifacts["Trained model artifacts"]
end

node_user(("User"))

node_user -->|"opens"| node_home
node_navbar -->|"links to"| node_assessment_page
node_assessment_page -->|"renders"| node_wizard
node_wizard -->|"renders"| node_personal
node_wizard -->|"renders"| node_lifestyle
node_wizard -->|"renders"| node_symptoms
node_wizard -->|"renders"| node_progress
node_wizard -->|"renders"| node_navigation_controls
node_wizard -->|"shows"| node_loading
node_wizard -->|"POSTs assessment"| node_backend
node_backend -->|"predicts with"| node_model_artifacts
node_backend -->|"returns results"| node_wizard
node_wizard -->|"routes to"| node_result_page
node_result_page -->|"calculates fallback"| node_risk_calculator
node_result_page -->|"renders score"| node_result_card
node_result_page -->|"renders summary"| node_summary_card
node_result_page -->|"renders advice"| node_recommendations
node_result_page -->|"renders disclaimer"| node_disclaimer
node_training -->|"loads processed data"| node_preprocessing
node_preprocessing -->|"returns datasets"| node_training
node_training -->|"produces artifacts"| node_model_artifacts

click node_home "https://github.com/nisheelmodi/healthsense-ai/blob/main/src/app/page.tsx"
click node_navbar "https://github.com/nisheelmodi/healthsense-ai/blob/main/src/components/Navbar.tsx"
click node_assessment_page "https://github.com/nisheelmodi/healthsense-ai/blob/main/src/app/assessment/page.tsx"
click node_wizard "https://github.com/nisheelmodi/healthsense-ai/blob/main/src/components/AssessmentWizard.tsx"
click node_personal "https://github.com/nisheelmodi/healthsense-ai/blob/main/src/components/PersonalInfoStep.tsx"
click node_lifestyle "https://github.com/nisheelmodi/healthsense-ai/blob/main/src/components/LifestyleStep.tsx"
click node_symptoms "https://github.com/nisheelmodi/healthsense-ai/blob/main/src/components/SymptomsStep.tsx"
click node_progress "https://github.com/nisheelmodi/healthsense-ai/blob/main/src/components/AssessmentProgress.tsx"
click node_navigation_controls "https://github.com/nisheelmodi/healthsense-ai/blob/main/src/components/AssessmentNavigation.tsx"
click node_loading "https://github.com/nisheelmodi/healthsense-ai/blob/main/src/components/LoadingScreen.tsx"
click node_backend "https://github.com/nisheelmodi/healthsense-ai/blob/main/backend/main.py"
click node_result_page "https://github.com/nisheelmodi/healthsense-ai/blob/main/src/app/result/page.tsx"
click node_risk_calculator "https://github.com/nisheelmodi/healthsense-ai/blob/main/src/lib/riskCalculator.ts"
click node_result_card "https://github.com/nisheelmodi/healthsense-ai/blob/main/src/components/ResultCard.tsx"
click node_summary_card "https://github.com/nisheelmodi/healthsense-ai/blob/main/src/components/SummaryCard.tsx"
click node_recommendations "https://github.com/nisheelmodi/healthsense-ai/blob/main/src/components/RecommendationCard.tsx"
click node_disclaimer "https://github.com/nisheelmodi/healthsense-ai/blob/main/src/components/DisclaimerCard.tsx"
click node_training "https://github.com/nisheelmodi/healthsense-ai/blob/main/ml/src/train.py"
click node_preprocessing "https://github.com/nisheelmodi/healthsense-ai/blob/main/ml/src/preprocess.py"
click node_model_artifacts "https://github.com/nisheelmodi/healthsense-ai/tree/main/ml/models"

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_home,node_navbar,node_result_page,node_result_card,node_summary_card,node_recommendations,node_disclaimer,node_user toneBlue
class node_assessment_page,node_wizard,node_personal,node_lifestyle,node_symptoms,node_progress,node_navigation_controls,node_loading toneAmber
class node_backend,node_risk_calculator toneMint
class node_training,node_preprocessing,node_model_artifacts toneRose
```

## Components

### Web experience

- [Home page](https://github.com/nisheelmodi/healthsense-ai/blob/main/src/app/page.tsx): `src/app/page.tsx`
- [Navigation](https://github.com/nisheelmodi/healthsense-ai/blob/main/src/components/Navbar.tsx): `src/components/Navbar.tsx`
- [Results page](https://github.com/nisheelmodi/healthsense-ai/blob/main/src/app/result/page.tsx): `src/app/result/page.tsx`
- [Risk score display](https://github.com/nisheelmodi/healthsense-ai/blob/main/src/components/ResultCard.tsx): `src/components/ResultCard.tsx`
- [Risk summary](https://github.com/nisheelmodi/healthsense-ai/blob/main/src/components/SummaryCard.tsx): `src/components/SummaryCard.tsx`
- [Recommendations](https://github.com/nisheelmodi/healthsense-ai/blob/main/src/components/RecommendationCard.tsx): `src/components/RecommendationCard.tsx`
- [Medical disclaimer](https://github.com/nisheelmodi/healthsense-ai/blob/main/src/components/DisclaimerCard.tsx): `src/components/DisclaimerCard.tsx`

### Assessment flow

- [Assessment page](https://github.com/nisheelmodi/healthsense-ai/blob/main/src/app/assessment/page.tsx): `src/app/assessment/page.tsx`
- [Assessment wizard](https://github.com/nisheelmodi/healthsense-ai/blob/main/src/components/AssessmentWizard.tsx): `src/components/AssessmentWizard.tsx`
- [Personal details](https://github.com/nisheelmodi/healthsense-ai/blob/main/src/components/PersonalInfoStep.tsx): `src/components/PersonalInfoStep.tsx`
- [Lifestyle details](https://github.com/nisheelmodi/healthsense-ai/blob/main/src/components/LifestyleStep.tsx): `src/components/LifestyleStep.tsx`
- [Symptoms](https://github.com/nisheelmodi/healthsense-ai/blob/main/src/components/SymptomsStep.tsx): `src/components/SymptomsStep.tsx`
- [Step progress](https://github.com/nisheelmodi/healthsense-ai/blob/main/src/components/AssessmentProgress.tsx): `src/components/AssessmentProgress.tsx`
- [Step controls](https://github.com/nisheelmodi/healthsense-ai/blob/main/src/components/AssessmentNavigation.tsx): `src/components/AssessmentNavigation.tsx`
- [Loading state](https://github.com/nisheelmodi/healthsense-ai/blob/main/src/components/LoadingScreen.tsx): `src/components/LoadingScreen.tsx`

### Prediction service

- [FastAPI prediction API](https://github.com/nisheelmodi/healthsense-ai/blob/main/backend/main.py): `backend/main.py`
- [Fallback risk scoring](https://github.com/nisheelmodi/healthsense-ai/blob/main/src/lib/riskCalculator.ts): `src/lib/riskCalculator.ts`

### Machine learning

- [Model training](https://github.com/nisheelmodi/healthsense-ai/blob/main/ml/src/train.py): `ml/src/train.py`
- [Dataset preprocessing](https://github.com/nisheelmodi/healthsense-ai/blob/main/ml/src/preprocess.py): `ml/src/preprocess.py`
- [Trained model artifacts](https://github.com/nisheelmodi/healthsense-ai/tree/main/ml/models): `ml/models`

### Other components

- **User**

## Connections

- User → Home page: opens (evidence: `README.md`)
- Navigation → Assessment page: links to (evidence: `src/components/Navbar.tsx`)
- Assessment page → Assessment wizard: renders (evidence: `src/app/assessment/page.tsx`)
- Assessment wizard → Personal details: renders (evidence: `src/components/AssessmentWizard.tsx`)
- Assessment wizard → Lifestyle details: renders (evidence: `src/components/AssessmentWizard.tsx`)
- Assessment wizard → Symptoms: renders (evidence: `src/components/AssessmentWizard.tsx`)
- Assessment wizard → Step progress: renders (evidence: `src/components/AssessmentWizard.tsx`)
- Assessment wizard → Step controls: renders (evidence: `src/components/AssessmentWizard.tsx`)
- Assessment wizard → Loading state: shows (evidence: `src/components/AssessmentWizard.tsx`)
- Assessment wizard → FastAPI prediction API: POSTs assessment (evidence: `src/components/AssessmentWizard.tsx`)
- FastAPI prediction API → Trained model artifacts: predicts with (evidence: `README.md`)
- FastAPI prediction API → Assessment wizard: returns results (evidence: `README.md`)
- Assessment wizard → Results page: routes to (evidence: `README.md`)
- Results page → Fallback risk scoring: calculates fallback (evidence: `src/app/result/page.tsx`)
- Results page → Risk score display: renders score (evidence: `src/app/result/page.tsx`)
- Results page → Risk summary: renders summary (evidence: `src/app/result/page.tsx`)
- Results page → Recommendations: renders advice (evidence: `src/app/result/page.tsx`)
- Results page → Medical disclaimer: renders disclaimer (evidence: `src/app/result/page.tsx`)
- Model training → Dataset preprocessing: loads processed data (evidence: `ml/src/train.py`)
- Dataset preprocessing → Model training: returns datasets (evidence: `ml/src/train.py`)
- Model training → Trained model artifacts: produces artifacts (evidence: `README.md`)
