# swetha-arul/ai-mental-health-monitoring-system architecture

> Architecture diagram of the GitHub repository swetha-arul/ai-mental-health-monitoring-system, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/swetha-arul/ai-mental-health-monitoring-system
- Repository: https://github.com/swetha-arul/ai-mental-health-monitoring-system

## Overview

1. This repository is a single Python-based, multi-agent inference system for mental health risk estimation. It does not expose separate services or microservices; instead, `simulate.py` acts as the top-level orchestrator and user-facing entry point.

2. The presentation layer is a Gradio interface in `simulate.py`. It collects two distinct input streams: free-form text from the user and wearable/physiological metrics. The UI is meant for real-time simulation rather than batch processing.

3. The first analysis boundary is the `text_agent/` package. `text_agent/main.py` runs a local fine-tuned DistilBERT sentiment/emotion classifier using the bundled Hugging Face model assets under `text_agent/sentiment-analysis-model/`. Its output is a text label plus confidence, representing emotional state from journal-like or social text.

4. The second analysis boundary is the `wearable_agent/` package. `wearable_agent/main.py` loads serialized preprocessing and classification artifacts: `stress_model_xgb.pkl`, `scaler.pkl`, and `label_encoder.pkl`. This agent predicts stress level from numeric health/activity features such as heart rate, sleep, steps, and calories.

5. The wearable pipeline is explicitly model-driven but has a safety boundary: the README notes rule-based fallback behavior if model files are unavailable. That means the agent can degrade gracefully instead of failing hard when the serialized artifacts cannot be loaded.

6. The `fusion_agent/` package is the decision layer. It combines the text agent and wearable agent outputs with a weighted fusion strategy, defaulting to 60% text and 40% wearable. This layer is responsible for transforming two modality-specific predictions into a single mental health risk score.

7. The fusion layer also owns the user-facing interpretation logic. It maps the combined score into one of four risk bands: Low, Mild, Moderate, or High, and generates contextual warnings, advice, and supportive messages. In architecture terms, this is the boundary between raw ML predictions and human-readable guidance.

8. Data flow is strictly downstream: user input enters the Gradio UI, then splits into two independent inference paths, and finally converges in the fusion agent. There is no evidence of a shared feature store, external database, or online training loop in the repo.

9. The system includes longitudinal logging via JSONL in the fusion layer. The README references `results_log.jsonl`, which indicates append-only record keeping for previous assessments and supports simple audit/history tracking without a database.

10. The repository is fully self-contained for inference because the model artifacts are stored locally in the repo tree. The only runtime dependency outside the codebase is the Python environment defined by `requirements.txt`, with Gradio for UI and ML libraries for transformer and XGBoost-based inference.

11. Operationally, the key architectural distinction is modality separation: unstructured text and structured wearable metrics are processed by different models, then merged late. That separation is what makes the diagram useful: two specialized analyzers feeding one fusion-and-explanation layer, all behind a single interactive front end.

12. The project’s output is advisory, not diagnostic. The disclaimer matters architecturally because it frames the system as decision support and messaging, not a clinical workflow or medical-record system.

Main entry points: [`wearable_agent/main.py`](https://github.com/swetha-arul/ai-mental-health-monitoring-system/blob/main/wearable_agent/main.py) (Wearable agent), [`fusion_agent/main.py`](https://github.com/swetha-arul/ai-mental-health-monitoring-system/blob/main/fusion_agent/main.py) (Fusion engine), [`text_agent/main.py`](https://github.com/swetha-arul/ai-mental-health-monitoring-system/blob/main/text_agent/main.py) (Text agent), [`simulate.py`](https://github.com/swetha-arul/ai-mental-health-monitoring-system/blob/main/simulate.py) (Simulation UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Interactive front end"]
  node_simulate_ui["Simulation UI<br/>Gradio orchestrator<br/>[simulate.py]"]
  node_text_input["Text stream<br/>free-form input"]
  node_wearable_input[("Wearable stream<br/>numeric input")]
end

subgraph group_text["Text analysis"]
  node_text_agent_main["Text agent<br/>DistilBERT inference<br/>[main.py]"]
  node_hf_model[("Model assets<br/>HF bundle")]
  node_text_output["Text label<br/>emotion score"]
end

subgraph group_wearable["Wearable analysis"]
  node_wearable_agent_main["Wearable agent<br/>XGBoost inference<br/>[main.py]"]
  node_wearable_artifacts[("Model artifacts<br/>serialized bundle")]
  node_fallback_rules{{"Fallback rules<br/>graceful degrade"}}
end

subgraph group_fusion["Fusion and output"]
  node_fusion_logic["Fusion engine<br/>weighted merge<br/>[main.py]"]
  node_risk_band["Risk band<br/>4-level rating"]
  node_guidance_log["Guidance log<br/>advice and audit"]
end

node_simulate_ui -->|"collects"| node_text_input
node_simulate_ui -->|"collects"| node_wearable_input
node_text_input -->|"sent to"| node_text_agent_main
node_wearable_input -->|"sent to"| node_wearable_agent_main
node_text_agent_main -->|"loads"| node_hf_model
node_text_agent_main -->|"emits"| node_text_output
node_wearable_agent_main -->|"loads"| node_wearable_artifacts
node_wearable_agent_main -.->|"degrades to"| node_fallback_rules
node_wearable_agent_main -->|"emits"| node_fusion_logic
node_text_output -->|"contributes"| node_fusion_logic
node_wearable_agent_main -->|"contributes"| node_fusion_logic
node_fusion_logic -->|"maps to"| node_risk_band
node_risk_band -->|"drives"| node_guidance_log
node_fusion_logic -->|"records"| node_guidance_log

click node_simulate_ui "https://github.com/swetha-arul/ai-mental-health-monitoring-system/blob/main/simulate.py"
click node_text_agent_main "https://github.com/swetha-arul/ai-mental-health-monitoring-system/blob/main/text_agent/main.py"
click node_hf_model "https://github.com/swetha-arul/ai-mental-health-monitoring-system/tree/main/text_agent/sentiment-analysis-model"
click node_wearable_agent_main "https://github.com/swetha-arul/ai-mental-health-monitoring-system/blob/main/wearable_agent/main.py"
click node_fusion_logic "https://github.com/swetha-arul/ai-mental-health-monitoring-system/blob/main/fusion_agent/main.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_simulate_ui,node_text_input,node_wearable_input toneBlue
class node_text_agent_main,node_hf_model,node_text_output toneAmber
class node_wearable_agent_main,node_wearable_artifacts,node_fallback_rules toneMint
class node_fusion_logic,node_risk_band,node_guidance_log toneRose
```

## Components

### Interactive front end

Single Gradio entry point for real-time simulation and input collection.

- [Simulation UI](https://github.com/swetha-arul/ai-mental-health-monitoring-system/blob/main/simulate.py): Gradio orchestrator · Top-level entry point that collects text and wearable inputs for live simulation. · `simulate.py`
- **Text stream**: free-form input · User journal-like or social text provided to the simulation.
- **Wearable stream**: numeric input · Heart rate, sleep, steps, calories, and related physiological/activity metrics.

### Text analysis

Unstructured text is classified separately from wearable data.

- [Text agent](https://github.com/swetha-arul/ai-mental-health-monitoring-system/blob/main/text_agent/main.py): DistilBERT inference · Runs the local sentiment/emotion classifier on incoming text. · `text_agent/main.py`
- [Model assets](https://github.com/swetha-arul/ai-mental-health-monitoring-system/tree/main/text_agent/sentiment-analysis-model): HF bundle · Bundled tokenizer and fine-tuned DistilBERT assets used by the text agent. · `text_agent/sentiment-analysis-model`
- **Text label**: emotion score · Predicted emotional state label with confidence from the text path.

### Wearable analysis

Structured physiological features are scored by a model-driven pipeline with fallback behavior.

- [Wearable agent](https://github.com/swetha-arul/ai-mental-health-monitoring-system/blob/main/wearable_agent/main.py): XGBoost inference · Loads preprocessing and classification artifacts to estimate stress from structured metrics. · `wearable_agent/main.py`
- **Model artifacts**: serialized bundle · Stored scaler, label encoder, and stress classifier used for wearable inference.
- **Fallback rules**: graceful degrade · Rule-based behavior used when serialized wearable artifacts cannot be loaded.

### Fusion and output

Late fusion combines modality outputs and turns them into user-facing guidance.

- [Fusion engine](https://github.com/swetha-arul/ai-mental-health-monitoring-system/blob/main/fusion_agent/main.py): weighted merge · Combines text and wearable predictions using the repository’s weighted fusion strategy. · `fusion_agent/main.py`
- **Risk band**: 4-level rating · Maps the fused score into Low, Mild, Moderate, or High risk.
- **Guidance log**: advice and audit · Produces supportive warnings and appends assessment history in JSONL-style longitudinal records.

## Connections

- Simulation UI → Text stream: collects · The interface gathers free-form text from the user.
- Simulation UI → Wearable stream: collects · The interface gathers wearable and physiological metrics.
- Text stream → Text agent: sent to · Text input flows into the text analysis boundary.
- Wearable stream → Wearable agent: sent to · Structured health metrics flow into the wearable analysis boundary.
- Text agent → Model assets: loads · The text agent uses the bundled Hugging Face model assets.
- Text agent → Text label: emits · Outputs a text emotion label and confidence.
- Wearable agent → Model artifacts: loads · The wearable agent uses serialized scaler, encoder, and classifier artifacts.
- Wearable agent → Fallback rules: degrades to · If model files are unavailable, rule-based fallback behavior is used.
- Wearable agent → Fusion engine: emits · Outputs a wearable stress prediction for fusion.
- Text label → Fusion engine: contributes · Text modality prediction is weighted into the final score.
- Wearable agent → Fusion engine: contributes · Wearable modality prediction is weighted into the final score.
- Fusion engine → Risk band: maps to · The fused score is translated into one of four risk levels.
- Risk band → Guidance log: drives · Risk level determines warnings, advice, and assessment logging.
- Fusion engine → Guidance log: records · Assessment outputs can be appended as longitudinal JSONL history.
