# yashlad009/ai-powered-chronic-risk-detection-and-explanation-assistant- architecture

> Architecture diagram of the GitHub repository yashlad009/ai-powered-chronic-risk-detection-and-explanation-assistant-, 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/yashlad009/ai-powered-chronic-risk-detection-and-explanation-assistant-
- Repository: https://github.com/yashlad009/ai-powered-chronic-risk-detection-and-explanation-assistant-

## Overview

This WIP skeleton presents a chronic-disease risk assistant. Its demonstrated user workflow is a patient entering vitals in the frontend, which submits them to the prediction API; the API validates the request, runs the ANN pipeline, converts its score to a fuzzy risk band, and returns the result for display. Training, authentication, patient and explanation routes, guardrails, and RAG are present in the tree but their runtime wiring is not established by the excerpts. The frontend form’s fields also differ from the API schema. Unsampled subsystem links are therefore omitted.

Main entry points: [`backend/app/api/v1/predictions.py`](https://github.com/yashlad009/ai-powered-chronic-risk-detection-and-explanation-assistant-/blob/main/backend/app/api/v1/predictions.py) (Prediction route), [`frontend/src/api/predict.ts`](https://github.com/yashlad009/ai-powered-chronic-risk-detection-and-explanation-assistant-/blob/main/frontend/src/api/predict.ts) (Prediction client), [`backend/app/ml/pipeline.py`](https://github.com/yashlad009/ai-powered-chronic-risk-detection-and-explanation-assistant-/blob/main/backend/app/ml/pipeline.py) (Prediction pipeline), [`frontend/src/App.tsx`](https://github.com/yashlad009/ai-powered-chronic-risk-detection-and-explanation-assistant-/blob/main/frontend/src/App.tsx) (Risk form)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Patient interface"]
  node_app["Risk form<br/>[App.tsx]"]
  node_client_api["Prediction client<br/>[predict.ts]"]
end

subgraph group_api["Prediction API"]
  node_server["API application<br/>[main.py]"]
  node_prediction_route["Prediction route<br/>[predictions.py]"]
  node_schema["Vitals schema<br/>[predict.py]"]
  node_auth["Authentication routes<br/>[auth.py]"]
  node_patients["Patient routes<br/>[patients.py]"]
  node_explanations["Explanation routes<br/>[explanations.py]"]
end

subgraph group_ml["Risk modeling"]
  node_pipeline["Prediction pipeline<br/>[pipeline.py]"]
  node_ann["ANN classifier<br/>[model.py]"]
  node_fis["Fuzzy risk bands<br/>[risk_bands.py]"]
  node_shap["SHAP explainer<br/>[shap_explainer.py]"]
  node_ga["Hyperparameter tuning"]
end

subgraph group_support["Assistant capabilities"]
  node_guard_checks["Guardrail checks<br/>[checks.py]"]
  node_guard_rules["Guardrail rules<br/>[rules.py]"]
  node_rag_embed["Knowledge embedding<br/>[embed.py]"]
  node_rag_retriever["Knowledge retrieval<br/>[retriever.py]"]
  node_rag_generator["Response generation<br/>[generator.py]"]
  node_db_session["Database session<br/>[session.py]"]
end

subgraph group_training["Model training"]
  node_trainer["ANN training<br/>[train.py]"]
  node_model_artifacts["Saved model artifacts"]
end

node_patient(("Patient"))

node_patient -->|"enters vitals"| node_app
node_app -->|"submits vitals"| node_client_api
node_client_api -->|"POSTs request"| node_prediction_route
node_server -->|"registers route"| node_prediction_route
node_prediction_route -->|"validates request"| node_schema
node_prediction_route -->|"runs prediction"| node_pipeline
node_prediction_route -->|"classifies score"| node_fis
node_pipeline -->|"predicts probability"| node_ann
node_pipeline -->|"loads model and scaler"| node_model_artifacts
node_trainer -->|"trains classifier"| node_ann
node_trainer -->|"saves model and scaler"| node_model_artifacts
node_client_api -->|"returns response"| node_app

click node_app "https://github.com/yashlad009/ai-powered-chronic-risk-detection-and-explanation-assistant-/blob/main/frontend/src/App.tsx"
click node_client_api "https://github.com/yashlad009/ai-powered-chronic-risk-detection-and-explanation-assistant-/blob/main/frontend/src/api/predict.ts"
click node_server "https://github.com/yashlad009/ai-powered-chronic-risk-detection-and-explanation-assistant-/blob/main/backend/app/main.py"
click node_prediction_route "https://github.com/yashlad009/ai-powered-chronic-risk-detection-and-explanation-assistant-/blob/main/backend/app/api/v1/predictions.py"
click node_schema "https://github.com/yashlad009/ai-powered-chronic-risk-detection-and-explanation-assistant-/blob/main/backend/app/schemas/predict.py"
click node_auth "https://github.com/yashlad009/ai-powered-chronic-risk-detection-and-explanation-assistant-/blob/main/backend/app/api/v1/auth.py"
click node_patients "https://github.com/yashlad009/ai-powered-chronic-risk-detection-and-explanation-assistant-/blob/main/backend/app/api/v1/patients.py"
click node_explanations "https://github.com/yashlad009/ai-powered-chronic-risk-detection-and-explanation-assistant-/blob/main/backend/app/api/v1/explanations.py"
click node_pipeline "https://github.com/yashlad009/ai-powered-chronic-risk-detection-and-explanation-assistant-/blob/main/backend/app/ml/pipeline.py"
click node_ann "https://github.com/yashlad009/ai-powered-chronic-risk-detection-and-explanation-assistant-/blob/main/backend/app/ml/ann/model.py"
click node_fis "https://github.com/yashlad009/ai-powered-chronic-risk-detection-and-explanation-assistant-/blob/main/backend/app/ml/fis/risk_bands.py"
click node_shap "https://github.com/yashlad009/ai-powered-chronic-risk-detection-and-explanation-assistant-/blob/main/backend/app/ml/shap_explainer.py"
click node_ga "https://github.com/yashlad009/ai-powered-chronic-risk-detection-and-explanation-assistant-/blob/main/backend/app/ml/ga/tune_hyperparams.py"
click node_guard_checks "https://github.com/yashlad009/ai-powered-chronic-risk-detection-and-explanation-assistant-/blob/main/backend/app/guardrail/checks.py"
click node_guard_rules "https://github.com/yashlad009/ai-powered-chronic-risk-detection-and-explanation-assistant-/blob/main/backend/app/guardrail/rules.py"
click node_rag_embed "https://github.com/yashlad009/ai-powered-chronic-risk-detection-and-explanation-assistant-/blob/main/backend/app/rag/embed.py"
click node_rag_retriever "https://github.com/yashlad009/ai-powered-chronic-risk-detection-and-explanation-assistant-/blob/main/backend/app/rag/retriever.py"
click node_rag_generator "https://github.com/yashlad009/ai-powered-chronic-risk-detection-and-explanation-assistant-/blob/main/backend/app/rag/generator.py"
click node_db_session "https://github.com/yashlad009/ai-powered-chronic-risk-detection-and-explanation-assistant-/blob/main/backend/app/db/session.py"
click node_trainer "https://github.com/yashlad009/ai-powered-chronic-risk-detection-and-explanation-assistant-/blob/main/backend/app/ml/ann/train.py"
click node_model_artifacts "https://github.com/yashlad009/ai-powered-chronic-risk-detection-and-explanation-assistant-/tree/main/ml-training/saved_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_app,node_client_api toneBlue
class node_server,node_prediction_route,node_schema,node_auth,node_patients,node_explanations toneAmber
class node_pipeline,node_ann,node_fis,node_shap,node_ga toneMint
class node_guard_checks,node_guard_rules,node_rag_embed,node_rag_retriever,node_rag_generator,node_db_session toneRose
class node_trainer,node_model_artifacts,node_patient toneIndigo
```

## Components

### Patient interface

- [Risk form](https://github.com/yashlad009/ai-powered-chronic-risk-detection-and-explanation-assistant-/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Prediction client](https://github.com/yashlad009/ai-powered-chronic-risk-detection-and-explanation-assistant-/blob/main/frontend/src/api/predict.ts): `frontend/src/api/predict.ts`

### Prediction API

- [API application](https://github.com/yashlad009/ai-powered-chronic-risk-detection-and-explanation-assistant-/blob/main/backend/app/main.py): `backend/app/main.py`
- [Prediction route](https://github.com/yashlad009/ai-powered-chronic-risk-detection-and-explanation-assistant-/blob/main/backend/app/api/v1/predictions.py): `backend/app/api/v1/predictions.py`
- [Vitals schema](https://github.com/yashlad009/ai-powered-chronic-risk-detection-and-explanation-assistant-/blob/main/backend/app/schemas/predict.py): `backend/app/schemas/predict.py`
- [Authentication routes](https://github.com/yashlad009/ai-powered-chronic-risk-detection-and-explanation-assistant-/blob/main/backend/app/api/v1/auth.py): `backend/app/api/v1/auth.py`
- [Patient routes](https://github.com/yashlad009/ai-powered-chronic-risk-detection-and-explanation-assistant-/blob/main/backend/app/api/v1/patients.py): `backend/app/api/v1/patients.py`
- [Explanation routes](https://github.com/yashlad009/ai-powered-chronic-risk-detection-and-explanation-assistant-/blob/main/backend/app/api/v1/explanations.py): `backend/app/api/v1/explanations.py`

### Risk modeling

- [Prediction pipeline](https://github.com/yashlad009/ai-powered-chronic-risk-detection-and-explanation-assistant-/blob/main/backend/app/ml/pipeline.py): `backend/app/ml/pipeline.py`
- [ANN classifier](https://github.com/yashlad009/ai-powered-chronic-risk-detection-and-explanation-assistant-/blob/main/backend/app/ml/ann/model.py): `backend/app/ml/ann/model.py`
- [Fuzzy risk bands](https://github.com/yashlad009/ai-powered-chronic-risk-detection-and-explanation-assistant-/blob/main/backend/app/ml/fis/risk_bands.py): `backend/app/ml/fis/risk_bands.py`
- [SHAP explainer](https://github.com/yashlad009/ai-powered-chronic-risk-detection-and-explanation-assistant-/blob/main/backend/app/ml/shap_explainer.py): `backend/app/ml/shap_explainer.py`
- [Hyperparameter tuning](https://github.com/yashlad009/ai-powered-chronic-risk-detection-and-explanation-assistant-/blob/main/backend/app/ml/ga/tune_hyperparams.py): `backend/app/ml/ga/tune_hyperparams.py`

### Assistant capabilities

- [Guardrail checks](https://github.com/yashlad009/ai-powered-chronic-risk-detection-and-explanation-assistant-/blob/main/backend/app/guardrail/checks.py): `backend/app/guardrail/checks.py`
- [Guardrail rules](https://github.com/yashlad009/ai-powered-chronic-risk-detection-and-explanation-assistant-/blob/main/backend/app/guardrail/rules.py): `backend/app/guardrail/rules.py`
- [Knowledge embedding](https://github.com/yashlad009/ai-powered-chronic-risk-detection-and-explanation-assistant-/blob/main/backend/app/rag/embed.py): `backend/app/rag/embed.py`
- [Knowledge retrieval](https://github.com/yashlad009/ai-powered-chronic-risk-detection-and-explanation-assistant-/blob/main/backend/app/rag/retriever.py): `backend/app/rag/retriever.py`
- [Response generation](https://github.com/yashlad009/ai-powered-chronic-risk-detection-and-explanation-assistant-/blob/main/backend/app/rag/generator.py): `backend/app/rag/generator.py`
- [Database session](https://github.com/yashlad009/ai-powered-chronic-risk-detection-and-explanation-assistant-/blob/main/backend/app/db/session.py): `backend/app/db/session.py`

### Model training

- [ANN training](https://github.com/yashlad009/ai-powered-chronic-risk-detection-and-explanation-assistant-/blob/main/backend/app/ml/ann/train.py): `backend/app/ml/ann/train.py`
- [Saved model artifacts](https://github.com/yashlad009/ai-powered-chronic-risk-detection-and-explanation-assistant-/tree/main/ml-training/saved_models): `ml-training/saved_models`

### Other components

- **Patient**

## Connections

- Patient → Risk form: enters vitals (evidence: `frontend/src/App.tsx`)
- Risk form → Prediction client: submits vitals (evidence: `frontend/src/App.tsx`)
- Prediction client → Prediction route: POSTs request (evidence: `frontend/src/api/predict.ts`)
- API application → Prediction route: registers route (evidence: `backend/app/main.py`)
- Prediction route → Vitals schema: validates request (evidence: `backend/app/api/v1/predictions.py`)
- Prediction route → Prediction pipeline: runs prediction (evidence: `backend/app/api/v1/predictions.py`)
- Prediction route → Fuzzy risk bands: classifies score (evidence: `backend/app/api/v1/predictions.py`)
- Prediction pipeline → ANN classifier: predicts probability (evidence: `backend/app/ml/pipeline.py`)
- Prediction pipeline → Saved model artifacts: loads model and scaler (evidence: `backend/app/ml/pipeline.py`)
- ANN training → ANN classifier: trains classifier (evidence: `backend/app/ml/ann/train.py`)
- ANN training → Saved model artifacts: saves model and scaler (evidence: `backend/app/ml/ann/train.py`)
- Prediction client → Risk form: returns response (evidence: `frontend/src/App.tsx`)
