# sattyajeetmaharana/mind_tone architecture

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

- Interactive diagram: https://gitdiagram.com/sattyajeetmaharana/mind_tone
- Repository: https://github.com/sattyajeetmaharana/mind_tone

## Overview

MindTone screens for mental-health risks by combining questionnaire predictions with conversational-audio classification, then produces a fused result and PDF report. The web app provides survey, account, dashboard, history, report, and administrative experiences; README documents the web-to-FastAPI assessment and PDF-download flow. The Python API and prediction path are sampled; some web wiring and unsampled model/report details are represented only where documented, so uncertain internal links are omitted.

Main entry points: [`src/api/server.py`](https://github.com/sattyajeetmaharana/mind_tone/blob/main/src/api/server.py) (FastAPI assessment API), [`src/tabular/predict.py`](https://github.com/sattyajeetmaharana/mind_tone/blob/main/src/tabular/predict.py) (Questionnaire prediction), [`web/src/app/api/assessment/submit/route.ts`](https://github.com/sattyajeetmaharana/mind_tone/blob/main/web/src/app/api/assessment/submit/route.ts) (Assessment endpoint), [`src/audio/predict.py`](https://github.com/sattyajeetmaharana/mind_tone/blob/main/src/audio/predict.py) (Audio prediction)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experience"]
  node_web_survey["Survey and audio UI<br/>[page.tsx]"]
  node_web_submit["Assessment endpoint<br/>[route.ts]"]
  node_web_dashboard["Dashboard and history<br/>[page.tsx]"]
  node_web_report["Report viewer and download<br/>[route.ts]"]
  node_web_auth["Account and admin<br/>[route.ts]"]
end

subgraph group_assessment["Assessment engine"]
  node_api["FastAPI assessment API<br/>[server.py]"]
  node_tabular["Questionnaire prediction<br/>[predict.py]"]
  node_risk["Risk flag rules<br/>[risk_engine.py]"]
  node_tabular_prep["Tabular preprocessing<br/>[preprocess.py]"]
  node_tabular_models["Tabular model scoring<br/>[model_manager.py]"]
  node_audio["Audio prediction<br/>[predict.py]"]
  node_audio_features["Acoustic feature extraction"]
  node_audio_models["Audio model scoring<br/>[model_manager.py]"]
  node_fusion["Multimodal fusion<br/>[fusion.py]"]
end

subgraph group_insight["Explainability and reports"]
  node_shap["SHAP explainability<br/>[shap_analysis.py]"]
  node_graphs["Assessment graphs<br/>[graphs.py]"]
  node_pdf["PDF report generation<br/>[generate_report.py]"]
end

subgraph group_state["Persistence"]
  node_history["CLI history and cleanup<br/>[save_history.py]"]
  node_db[("Web relational database")]
end

node_user(("Assessment user"))

node_user -->|"submits assessment"| node_web_survey
node_web_survey -->|"sends answers"| node_web_submit
node_web_submit -->|"forwards payload"| node_api
node_api -->|"runs questionnaire"| node_tabular
node_api -->|"runs audio analysis"| node_audio
node_tabular -->|"generates flags"| node_risk
node_tabular -->|"preprocesses inputs"| node_tabular_prep
node_tabular -->|"scores features"| node_tabular_models
node_audio -->|"extracts features"| node_audio_features
node_audio -->|"scores features"| node_audio_models
node_api -->|"fuses predictions"| node_fusion
node_api -->|"generates plots"| node_graphs
node_api -->|"compiles report"| node_pdf
node_user -->|"signs in"| node_web_auth
node_web_auth -->|"stores account data"| node_db
node_web_dashboard -.->|"uses check-in records"| node_db
node_web_submit -.->|"stores assessment records"| node_db
node_api -->|"returns report name"| node_web_report
node_web_report -->|"streams generated PDF"| node_pdf
node_api -.->|"explainability capability"| node_shap

click node_web_survey "https://github.com/sattyajeetmaharana/mind_tone/blob/main/web/src/app/(dashboard)/survey/page.tsx"
click node_web_submit "https://github.com/sattyajeetmaharana/mind_tone/blob/main/web/src/app/api/assessment/submit/route.ts"
click node_web_dashboard "https://github.com/sattyajeetmaharana/mind_tone/blob/main/web/src/app/(dashboard)/dashboard/page.tsx"
click node_web_report "https://github.com/sattyajeetmaharana/mind_tone/blob/main/web/src/app/api/assessment/pdf/%5BpdfName%5D/route.ts"
click node_web_auth "https://github.com/sattyajeetmaharana/mind_tone/blob/main/web/src/app/api/auth/login/route.ts"
click node_api "https://github.com/sattyajeetmaharana/mind_tone/blob/main/src/api/server.py"
click node_tabular "https://github.com/sattyajeetmaharana/mind_tone/blob/main/src/tabular/predict.py"
click node_risk "https://github.com/sattyajeetmaharana/mind_tone/blob/main/src/tabular/risk_engine.py"
click node_tabular_prep "https://github.com/sattyajeetmaharana/mind_tone/blob/main/src/tabular/preprocess.py"
click node_tabular_models "https://github.com/sattyajeetmaharana/mind_tone/blob/main/src/tabular/model_manager.py"
click node_audio "https://github.com/sattyajeetmaharana/mind_tone/blob/main/src/audio/predict.py"
click node_audio_features "https://github.com/sattyajeetmaharana/mind_tone/blob/main/src/audio/extract_features.py"
click node_audio_models "https://github.com/sattyajeetmaharana/mind_tone/blob/main/src/audio/model_manager.py"
click node_fusion "https://github.com/sattyajeetmaharana/mind_tone/blob/main/src/fusion/fusion.py"
click node_shap "https://github.com/sattyajeetmaharana/mind_tone/blob/main/src/tabular/shap_analysis.py"
click node_graphs "https://github.com/sattyajeetmaharana/mind_tone/blob/main/src/report/graphs.py"
click node_pdf "https://github.com/sattyajeetmaharana/mind_tone/blob/main/src/report/generate_report.py"
click node_history "https://github.com/sattyajeetmaharana/mind_tone/blob/main/src/history/save_history.py"
click node_db "https://github.com/sattyajeetmaharana/mind_tone/tree/main/web/prisma"

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_web_survey,node_web_submit,node_web_dashboard,node_web_report,node_web_auth,node_user toneBlue
class node_api,node_tabular,node_risk,node_tabular_prep,node_tabular_models,node_audio,node_audio_features,node_audio_models,node_fusion toneAmber
class node_shap,node_graphs,node_pdf toneMint
class node_history,node_db toneRose
```

## Components

### Web experience

- [Survey and audio UI](https://github.com/sattyajeetmaharana/mind_tone/blob/main/web/src/app/(dashboard)/survey/page.tsx): `web/src/app/(dashboard)/survey/page.tsx`
- [Assessment endpoint](https://github.com/sattyajeetmaharana/mind_tone/blob/main/web/src/app/api/assessment/submit/route.ts): `web/src/app/api/assessment/submit/route.ts`
- [Dashboard and history](https://github.com/sattyajeetmaharana/mind_tone/blob/main/web/src/app/(dashboard)/dashboard/page.tsx): `web/src/app/(dashboard)/dashboard/page.tsx`
- [Report viewer and download](https://github.com/sattyajeetmaharana/mind_tone/blob/main/web/src/app/api/assessment/pdf/%5BpdfName%5D/route.ts): `web/src/app/api/assessment/pdf/[pdfName]/route.ts`
- [Account and admin](https://github.com/sattyajeetmaharana/mind_tone/blob/main/web/src/app/api/auth/login/route.ts): `web/src/app/api/auth/login/route.ts`

### Assessment engine

- [FastAPI assessment API](https://github.com/sattyajeetmaharana/mind_tone/blob/main/src/api/server.py): `src/api/server.py`
- [Questionnaire prediction](https://github.com/sattyajeetmaharana/mind_tone/blob/main/src/tabular/predict.py): `src/tabular/predict.py`
- [Risk flag rules](https://github.com/sattyajeetmaharana/mind_tone/blob/main/src/tabular/risk_engine.py): `src/tabular/risk_engine.py`
- [Tabular preprocessing](https://github.com/sattyajeetmaharana/mind_tone/blob/main/src/tabular/preprocess.py): `src/tabular/preprocess.py`
- [Tabular model scoring](https://github.com/sattyajeetmaharana/mind_tone/blob/main/src/tabular/model_manager.py): `src/tabular/model_manager.py`
- [Audio prediction](https://github.com/sattyajeetmaharana/mind_tone/blob/main/src/audio/predict.py): `src/audio/predict.py`
- [Acoustic feature extraction](https://github.com/sattyajeetmaharana/mind_tone/blob/main/src/audio/extract_features.py): `src/audio/extract_features.py`
- [Audio model scoring](https://github.com/sattyajeetmaharana/mind_tone/blob/main/src/audio/model_manager.py): `src/audio/model_manager.py`
- [Multimodal fusion](https://github.com/sattyajeetmaharana/mind_tone/blob/main/src/fusion/fusion.py): `src/fusion/fusion.py`

### Explainability and reports

- [SHAP explainability](https://github.com/sattyajeetmaharana/mind_tone/blob/main/src/tabular/shap_analysis.py): `src/tabular/shap_analysis.py`
- [Assessment graphs](https://github.com/sattyajeetmaharana/mind_tone/blob/main/src/report/graphs.py): `src/report/graphs.py`
- [PDF report generation](https://github.com/sattyajeetmaharana/mind_tone/blob/main/src/report/generate_report.py): `src/report/generate_report.py`

### Persistence

- [CLI history and cleanup](https://github.com/sattyajeetmaharana/mind_tone/blob/main/src/history/save_history.py): `src/history/save_history.py`
- [Web relational database](https://github.com/sattyajeetmaharana/mind_tone/tree/main/web/prisma): `web/prisma`

### Other components

- **Assessment user**

## Connections

- Assessment user → Survey and audio UI: submits assessment (evidence: `README.md`)
- Survey and audio UI → Assessment endpoint: sends answers (evidence: `README.md`)
- Assessment endpoint → FastAPI assessment API: forwards payload (evidence: `README.md`)
- FastAPI assessment API → Questionnaire prediction: runs questionnaire (evidence: `src/api/server.py`)
- FastAPI assessment API → Audio prediction: runs audio analysis (evidence: `src/api/server.py`)
- Questionnaire prediction → Risk flag rules: generates flags (evidence: `src/tabular/predict.py`)
- Questionnaire prediction → Tabular preprocessing: preprocesses inputs (evidence: `src/tabular/predict.py`)
- Questionnaire prediction → Tabular model scoring: scores features (evidence: `src/tabular/predict.py`)
- Audio prediction → Acoustic feature extraction: extracts features (evidence: `src/audio/predict.py`)
- Audio prediction → Audio model scoring: scores features (evidence: `src/audio/predict.py`)
- FastAPI assessment API → Multimodal fusion: fuses predictions (evidence: `src/api/server.py`)
- FastAPI assessment API → Assessment graphs: generates plots (evidence: `src/api/server.py`)
- FastAPI assessment API → PDF report generation: compiles report (evidence: `src/api/server.py`)
- Assessment user → Account and admin: signs in (evidence: `README.md`)
- Account and admin → Web relational database: stores account data (evidence: `README.md`)
- Dashboard and history → Web relational database: uses check-in records
- Assessment endpoint → Web relational database: stores assessment records
- FastAPI assessment API → Report viewer and download: returns report name (evidence: `README.md`)
- Report viewer and download → PDF report generation: streams generated PDF (evidence: `README.md`)
- FastAPI assessment API → SHAP explainability: explainability capability
