# adithya-257/mental-health-analysis architecture

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

- Interactive diagram: https://gitdiagram.com/adithya-257/mental-health-analysis
- Repository: https://github.com/adithya-257/mental-health-analysis

## Overview

#### Purpose and Entry Points
This is an offline NLP/ML pipeline plus Streamlit dashboard for classifying Reddit posts into depression, anxiety, bipolar, PTSD, or normal. The operational entry point is `src/app.py`; pipeline stages are individually executable scripts, with the intended sequence documented in `README.md`.

#### Dataset Preparation and Text Boundaries
Raw train/validation/test CSVs are expected under an untracked `data/` directory. `src/build_clean_dataset.py` creates reusable cleaned splits, using `src/preprocess.py`. Preprocessing intentionally branches:
- Transformer-safe cleaning preserves sentence structure for RoBERTa.
- Traditional normalization supports lexical analytics, VADER, and vectorizers.
This separation prevents destructive token cleanup from affecting transformer inputs.

#### Data Access and Shared Configuration
`src/config.py` centralizes model/training and path-level assumptions; `src/data_loader.py` loads dataset splits for downstream consumers. These are the main coordination boundary between file-based datasets and model/analysis stages. Paths referenced in the repository include `src/config.py`, `src/data_loader.py`, and `src/build_clean_dataset.py`.

#### Modeling: Baseline and Transformer
The primary classifier is a fine-tuned `roberta-base` five-class model implemented by `src/train.py`, with a published checkpoint hosted on Hugging Face (`Adithya-257/mental-health-roberta`). Training produces run and evaluation metadata in `logs/runs.json` and `logs/eval_results.json`. A separate TF-IDF plus logistic-regression comparison path is implemented in `src/baseline.py`; vector construction and serialized feature artifacts are handled by `src/feature_extraction.py`.

#### Evaluation and Explainability
`src/evaluate.py` evaluates the trained classifier on held-out data and emits reports, confusion/ROC visualizations, and row-level error analysis. Persisted outputs include `logs/classification_report.txt`, `logs/eval_results.json`, and `assets/error_analysis.csv`. `src/lime_explainer.py` wraps model inference for LIME, exporting human-readable HTML and visual explanations to `assets/lime_html/` and `assets/lime_examples/`; existing explanation files demonstrate that output contract.

#### Parallel Sentiment and Corpus Analytics
VADER is an independent sentiment-analysis path, rather than an input feature required by RoBERTa, implemented in `src/vader_module.py`. Corpus-level lexical artifacts derive from traditional preprocessing: `src/wordcloud_gen.py` creates class word clouds in `assets/wordclouds/`, while `src/frequent_words.py` creates per-class term-frequency charts in `assets/frequent_words/`. Dashboard and evaluation charts are stored under `assets/charts/`.

#### Runtime, UI, and Dependencies
The system runs in Python with dependencies declared in `requirements.txt`; material libraries include Hugging Face transformer tooling, VADER, LIME, scikit-learn-style vectorization/baselines, and Streamlit. `src/app.py` is the serving boundary: it accepts a user-supplied post, invokes RoBERTa prediction and VADER sentiment in parallel presentation, and surfaces class probabilities and LIME explanation. It depends on local/generated artifacts and/or the Hugging Face model checkpoint; no backend service or database is represented in the tree.

Main entry points: [`src/data_loader.py`](https://github.com/adithya-257/mental-health-analysis/blob/main/src/data_loader.py) (Dataset loader), [`src/train.py`](https://github.com/adithya-257/mental-health-analysis/blob/main/src/train.py) (RoBERTa training), [`src/build_clean_dataset.py`](https://github.com/adithya-257/mental-health-analysis/blob/main/src/build_clean_dataset.py) (Build clean dataset), [`src/app.py`](https://github.com/adithya-257/mental-health-analysis/blob/main/src/app.py) (Streamlit dashboard)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Data preparation"]
  node_raw_data[("Raw CSV splits<br/>dataset")]
  node_build_clean["Build clean dataset<br/>pipeline script"]
  node_preprocess["Text preprocessing<br/>processing module<br/>[preprocess.py]"]
  node_clean_splits[("Cleaned splits<br/>dataset")]
  node_config["Shared configuration<br/>config module<br/>[config.py]"]
  node_loader["Dataset loader<br/>data access module<br/>[data_loader.py]"]
end

subgraph group_models["Modeling and evaluation"]
  node_roberta_train["RoBERTa training<br/>training script<br/>[train.py]"]
  node_hf_checkpoint{{"RoBERTa checkpoint<br/>model artifact"}}
  node_training_logs["Run metadata<br/>training output<br/>[runs.json]"]
  node_features["Feature extraction<br/>feature module"]
  node_baseline["TF-IDF baseline<br/>comparison model<br/>[baseline.py]"]
  node_evaluate["Model evaluation<br/>evaluation script<br/>[evaluate.py]"]
  node_eval_outputs["Evaluation outputs<br/>evaluation artifacts<br/>[eval_results.json]"]
  node_lime["LIME explainer<br/>explainability module<br/>[lime_explainer.py]"]
  node_lime_outputs["LIME outputs<br/>explanation artifacts"]
end

subgraph group_analytics["Analytics outputs"]
  node_vader["VADER sentiment<br/>sentiment module<br/>[vader_module.py]"]
  node_corpus_analytics["Corpus lexical analytics<br/>analysis scripts<br/>[wordcloud_gen.py]"]
  node_analytics_outputs["Lexical artifacts<br/>analysis artifacts"]
end

subgraph group_ui["Dashboard runtime"]
  node_app["Streamlit dashboard<br/>application entry point<br/>[app.py]"]
  node_requirements["Python dependencies<br/>dependency manifest<br/>[requirements.txt]"]
end

node_readme["Pipeline sequence<br/>documentation<br/>[README.md]"]

node_raw_data -->|"input"| node_build_clean
node_build_clean -->|"cleans with"| node_preprocess
node_preprocess -->|"produces"| node_clean_splits
node_config -.->|"paths"| node_build_clean
node_config -.->|"paths"| node_loader
node_clean_splits -->|"loaded by"| node_loader
node_loader -->|"training data"| node_roberta_train
node_config -.->|"training settings"| node_roberta_train
node_roberta_train -->|"produces/publishes"| node_hf_checkpoint
node_roberta_train -->|"writes"| node_training_logs
node_loader -->|"traditional text"| node_features
node_features -->|"TF-IDF features"| node_baseline
node_loader -->|"held-out data"| node_evaluate
node_hf_checkpoint -->|"evaluated model"| node_evaluate
node_evaluate -->|"writes"| node_eval_outputs
node_hf_checkpoint -->|"inference wrapper"| node_lime
node_lime -->|"exports"| node_lime_outputs
node_loader -->|"traditional text"| node_vader
node_loader -->|"traditional text"| node_corpus_analytics
node_corpus_analytics -->|"exports"| node_analytics_outputs
node_hf_checkpoint -->|"class prediction"| node_app
node_vader -->|"sentiment result"| node_app
node_lime -->|"explanation"| node_app
node_requirements -.->|"runtime dependencies"| node_app
node_readme -.->|"documents sequence"| node_build_clean

click node_build_clean "https://github.com/adithya-257/mental-health-analysis/blob/main/src/build_clean_dataset.py"
click node_preprocess "https://github.com/adithya-257/mental-health-analysis/blob/main/src/preprocess.py"
click node_config "https://github.com/adithya-257/mental-health-analysis/blob/main/src/config.py"
click node_loader "https://github.com/adithya-257/mental-health-analysis/blob/main/src/data_loader.py"
click node_roberta_train "https://github.com/adithya-257/mental-health-analysis/blob/main/src/train.py"
click node_training_logs "https://github.com/adithya-257/mental-health-analysis/blob/main/logs/runs.json"
click node_features "https://github.com/adithya-257/mental-health-analysis/blob/main/src/feature_extraction.py"
click node_baseline "https://github.com/adithya-257/mental-health-analysis/blob/main/src/baseline.py"
click node_evaluate "https://github.com/adithya-257/mental-health-analysis/blob/main/src/evaluate.py"
click node_eval_outputs "https://github.com/adithya-257/mental-health-analysis/blob/main/logs/eval_results.json"
click node_lime "https://github.com/adithya-257/mental-health-analysis/blob/main/src/lime_explainer.py"
click node_vader "https://github.com/adithya-257/mental-health-analysis/blob/main/src/vader_module.py"
click node_corpus_analytics "https://github.com/adithya-257/mental-health-analysis/blob/main/src/wordcloud_gen.py"
click node_app "https://github.com/adithya-257/mental-health-analysis/blob/main/src/app.py"
click node_requirements "https://github.com/adithya-257/mental-health-analysis/blob/main/requirements.txt"
click node_readme "https://github.com/adithya-257/mental-health-analysis/blob/main/README.md"

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_raw_data,node_build_clean,node_preprocess,node_clean_splits,node_config,node_loader toneBlue
class node_roberta_train,node_hf_checkpoint,node_training_logs,node_features,node_baseline,node_evaluate,node_eval_outputs,node_lime,node_lime_outputs toneAmber
class node_vader,node_corpus_analytics,node_analytics_outputs toneMint
class node_app,node_requirements toneRose
class node_readme toneNeutral
```

## Components

### Data preparation

File-based dataset and two text-processing paths.

- **Raw CSV splits**: dataset · Untracked train, validation, and test inputs.
- [Build clean dataset](https://github.com/adithya-257/mental-health-analysis/blob/main/src/build_clean_dataset.py): pipeline script · Creates reusable cleaned splits. · `src/build_clean_dataset.py`
- [Text preprocessing](https://github.com/adithya-257/mental-health-analysis/blob/main/src/preprocess.py): processing module · Separates transformer-safe cleaning from traditional normalization. · `src/preprocess.py`
- **Cleaned splits**: dataset · Shared inputs for model and analysis stages.
- [Shared configuration](https://github.com/adithya-257/mental-health-analysis/blob/main/src/config.py): config module · Centralizes paths and model/training assumptions. · `src/config.py`
- [Dataset loader](https://github.com/adithya-257/mental-health-analysis/blob/main/src/data_loader.py): data access module · Loads splits for downstream consumers. · `src/data_loader.py`

### Modeling and evaluation

Classifier training, comparison, evaluation, and explanations.

- [RoBERTa training](https://github.com/adithya-257/mental-health-analysis/blob/main/src/train.py): training script · Fine-tunes the five-class roberta-base classifier. · `src/train.py`
- **RoBERTa checkpoint**: model artifact · Published five-class model used for inference.
- [Run metadata](https://github.com/adithya-257/mental-health-analysis/blob/main/logs/runs.json): training output · Training and evaluation run records. · `logs/runs.json`
- [Feature extraction](https://github.com/adithya-257/mental-health-analysis/blob/main/src/feature_extraction.py): feature module · Builds and serializes TF-IDF feature artifacts. · `src/feature_extraction.py`
- [TF-IDF baseline](https://github.com/adithya-257/mental-health-analysis/blob/main/src/baseline.py): comparison model · Logistic-regression comparison path. · `src/baseline.py`
- [Model evaluation](https://github.com/adithya-257/mental-health-analysis/blob/main/src/evaluate.py): evaluation script · Produces reports, metrics, plots, and row-level errors. · `src/evaluate.py`
- [Evaluation outputs](https://github.com/adithya-257/mental-health-analysis/blob/main/logs/eval_results.json): evaluation artifacts · Report, metrics, charts, and error analysis. · `logs/eval_results.json`
- [LIME explainer](https://github.com/adithya-257/mental-health-analysis/blob/main/src/lime_explainer.py): explainability module · Wraps classifier inference for human-readable explanations. · `src/lime_explainer.py`
- **LIME outputs**: explanation artifacts · HTML and visual explanation exports.

### Analytics outputs

Independent sentiment and corpus-analysis pipeline.

- [VADER sentiment](https://github.com/adithya-257/mental-health-analysis/blob/main/src/vader_module.py): sentiment module · Independent sentiment-analysis path. · `src/vader_module.py`
- [Corpus lexical analytics](https://github.com/adithya-257/mental-health-analysis/blob/main/src/wordcloud_gen.py): analysis scripts · Generates class word clouds and frequent-term charts. · `src/wordcloud_gen.py`
- **Lexical artifacts**: analysis artifacts · Per-class word clouds and term-frequency charts.

### Dashboard runtime

Interactive serving boundary.

- [Streamlit dashboard](https://github.com/adithya-257/mental-health-analysis/blob/main/src/app.py): application entry point · Accepts posts and presents predictions, sentiment, probabilities, and explanations. · `src/app.py`
- [Python dependencies](https://github.com/adithya-257/mental-health-analysis/blob/main/requirements.txt): dependency manifest · Declares Streamlit, Transformers, VADER, LIME, and ML libraries. · `requirements.txt`

### Other components

- [Pipeline sequence](https://github.com/adithya-257/mental-health-analysis/blob/main/README.md): documentation · Documents the intended executable-stage order. · `README.md`

## Connections

- Raw CSV splits → Build clean dataset: input
- Build clean dataset → Text preprocessing: cleans with
- Text preprocessing → Cleaned splits: produces
- Shared configuration → Build clean dataset: paths
- Shared configuration → Dataset loader: paths
- Cleaned splits → Dataset loader: loaded by
- Dataset loader → RoBERTa training: training data
- Shared configuration → RoBERTa training: training settings
- RoBERTa training → RoBERTa checkpoint: produces/publishes
- RoBERTa training → Run metadata: writes
- Dataset loader → Feature extraction: traditional text
- Feature extraction → TF-IDF baseline: TF-IDF features
- Dataset loader → Model evaluation: held-out data
- RoBERTa checkpoint → Model evaluation: evaluated model
- Model evaluation → Evaluation outputs: writes
- RoBERTa checkpoint → LIME explainer: inference wrapper
- LIME explainer → LIME outputs: exports
- Dataset loader → VADER sentiment: traditional text
- Dataset loader → Corpus lexical analytics: traditional text
- Corpus lexical analytics → Lexical artifacts: exports
- RoBERTa checkpoint → Streamlit dashboard: class prediction
- VADER sentiment → Streamlit dashboard: sentiment result
- LIME explainer → Streamlit dashboard: explanation
- Python dependencies → Streamlit dashboard: runtime dependencies
- Pipeline sequence → Build clean dataset: documents sequence