<div align="center">

🧠 MindScope-2025

AI-Powered Mental Wellbeing Assessment

An end-to-end machine learning application that turns clinically validated depression and anxiety screening into a calm, guided, and explainable risk assessment.

</div>

MindScope-2025 combines the PHQ-9 (depression) and GAD-7 (anxiety) screening instruments with a trained Random Forest classifier to deliver a confidential, evidence-based reflection on mental wellbeing — wrapped in a polished, guided, step-by-step web experience.

---

📑 Table of Contents

1. Overview
2. Flow at a Glance
3. Key Features
4. System Architecture
5. Core Flows
6. Clinical Scales & Risk Logic
7. Dataset
8. Machine Learning
9. Technology Stack
10. Project Structure
11. Getting Started
12. Usage & Test Cases
13. Personalized Guidance
14. Roadmap
15. Privacy & Security
16. Disclaimers & Crisis Resources
17. Resources
18. License

---

🌍 Overview

MindScope-2025 is a complete demonstration of the machine learning lifecycle — from raw data to a deployed, user-facing product:

Data acquisition → cleaning → exploratory analysis → modeling → serialization → application → containerization → cloud deployment.

Rather than stopping at a notebook, the project ships a production web app. A user answers a short, guided questionnaire; the app scores their responses against standardized clinical thresholds, feeds an engineered feature vector to a trained model, and returns a risk band (Low / Moderate / High) with a confidence score and personalized, actionable guidance.

The interface is intentionally calm — a Warm Wellness design system with a guided wizard — because the subject matter is sensitive and the goal is reflection, not alarm.

---

🗺️ Flow at a Glance

A single end-to-end view of the project — from the public dataset (offline modeling) all the way to a live prediction in the user's browser. This text diagram renders everywhere, including plain Markdown viewers.

        ╔══════════════════════════════════════════╗
        ║M I N D S C O P E   data > model > decision║
        ╚══════════════════════════════════════════╝

   PHASE 1  —  DATA SCIENCE & MODELING   (offline, run once)

   ┌──────────────────────────────────────┐
   │        Kaggle Dataset  (CSV)         │   Global Mental Health 2025
   └──────────────────────────────────────┘
                       │
                       ▼
   ┌──────────────────────────────────────┐
   │          Clean + Preprocess          │   pandas · numpy
   └──────────────────────────────────────┘
                       │
                       ▼
   ┌──────────────────────────────────────┐
   │            EDA + Insights            │   Jupyter notebook
   └──────────────────────────────────────┘
                       │
                       ▼
   ┌──────────────────────────────────────┐
   │         Feature Engineering          │   encode + clinical thresholds
   └──────────────────────────────────────┘
                       │
                       ▼
   ┌──────────────────────────────────────┐
   │       Train + Compare 3 Models       │   LogReg · Decision Tree · Forest
   └──────────────────────────────────────┘
                       │
                       ▼
   ┌──────────────────────────────────────┐
   │       Select + Save Best Model       │   joblib .pkl  ->  Random Forest
   └──────────────────────────────────────┘
                       │
                       ▼
   PHASE 2  —  APPLICATION & INFERENCE   (every user session)

   ┌──────────────────────────────────────┐
   │          User Opens Web App          │   Streamlit · Docker · Render
   └──────────────────────────────────────┘
                       │
                       ▼
   ┌──────────────────────────────────────┐
   │         Guided 4-Step Wizard         │   Basics > PHQ-9 > GAD-7 > Lifestyle
   └──────────────────────────────────────┘
                       │
                       ▼
   ┌──────────────────────────────────────┐
   │     Encode -> 12-Feature Vector      │
   └──────────────────────────────────────┘
                       │
                       ▼
   ┌──────────────────────────────────────┐
   │      Predict Risk + Confidence       │   Random Forest model
   └──────────────────────────────────────┘
                       │
                       ▼
   ┌──────────────────────────────────────┐
   │     Risk:  Low / Moderate / High     │
   └──────────────────────────────────────┘
                       │
                       ▼
   ┌──────────────────────────────────────┐
   │   Results + Personalized Guidance    │
   └──────────────────────────────────────┘

---

✨ Key Features

| Capability | Description | |---|---| | 🩺 Clinically grounded | Built on validated PHQ-9 and GAD-7 instruments with standard severity thresholds | | 🤖 Explainable ML | Random Forest risk classifier with a transparent, reproducible training pipeline | | 🧭 Guided wizard | A four-step assessment (Basics → Depression → Anxiety → Lifestyle) with live scoring | | 📊 Visual results | Risk banner, metric cards, and interactive PHQ-9 / GAD-7 gauges | | 💬 Personalized guidance | 65+ tailored recommendations mapped to the assessed risk level | | 🔒 Privacy-first | Session-only processing — nothing is stored, tracked, or transmitted to third parties | | 🐳 Portable & deployed | Containerized with Docker and deployed on Render |

---

🏗️ System Architecture

Thick arrows are the primary user path; dotted arrows load the trained model artifacts. Each tier is colour-coded.

flowchart TB
    subgraph userT["USER TIER"]
        U["Person<br/>taking the assessment"]
    end

    subgraph appT["PRESENTATION TIER — Streamlit on Render"]
        UI["app.py · guided wizard<br/>Warm Wellness UI"]
        Home["Home"]
        Wiz["Assessment Wizard<br/>4 steps"]
        Res["Results dashboard"]
        Abt["About"]
    end

    subgraph logicT["INFERENCE TIER — Python"]
        Score["Score PHQ-9 / GAD-7"]
        Enc["Encode features"]
        Pred["Predict risk"]
        Guide["Map guidance"]
    end

    subgraph artT["MODEL ARTIFACTS — joblib"]
        M1[("best_risk_model.pkl")]
        M2[("encoders.pkl")]
        M3[("feature_cols.pkl")]
    end

    subgraph offT["OFFLINE TRAINING — run once"]
        CSV[["Kaggle CSV dataset"]]
        Train["02_model_training.py"]
    end

    U ==>|HTTPS| UI
    UI --> Home & Wiz & Res & Abt
    Wiz ==>|responses| Score
    Score ==> Enc ==> Pred ==> Guide
    Guide ==>|risk + tips| Res
    Enc -.->|load| M2
    Pred -.->|load| M1 & M3
    CSV ==> Train
    Train -.->|export| M1 & M2 & M3

    classDef tUser fill:#EEF3E9,stroke:#5F7A57,color:#2E3A24
    classDef tApp fill:#FBF0E6,stroke:#C2703D,color:#7E3F1A
    classDef tLogic fill:#F3F7EF,stroke:#7C9473,color:#2E3A24
    classDef tData fill:#FCF6E9,stroke:#B8924A,color:#5C4710
    classDef tOff fill:#F1ECE3,stroke:#8A7A66,color:#3D3326

    class U tUser
    class UI,Home,Wiz,Res,Abt tApp
    class Score,Enc,Pred,Guide tLogic
    class M1,M2,M3 tData
    class CSV,Train tOff

---

🔄 Core Flows

1. Machine Learning Lifecycle — training path

flowchart LR
    A(["Kaggle Dataset<br/>Global Mental Health 2025"]) ==> B["Clean + Preprocess<br/>pandas · numpy"]
    B ==> C["EDA + Insights<br/>Jupyter"]
    C ==> D["Feature Engineering<br/>encode + clinical thresholds"]
    D ==> E{{"Train + Compare<br/>LogReg · Tree · Forest"}}
    E ==> F["Select Best<br/>Random Forest"]
    F ==> G[("Serialize .pkl<br/>joblib")]
    G ==> H(["Deployed app<br/>Docker · Render"])

    classDef start fill:#EEF3E9,stroke:#5F7A57,color:#2E3A24
    classDef proc fill:#F3F7EF,stroke:#7C9473,color:#2E3A24
    classDef task fill:#FBF0E6,stroke:#C2703D,color:#7E3F1A
    classDef store fill:#FCF6E9,stroke:#B8924A,color:#5C4710
    classDef ok fill:#E7F0DF,stroke:#5F7A57,color:#2E3A24

    class A start
    class B,C,D,F proc
    class E task
    class G store
    class H ok

Stage-by-stage explanation

| # | Stage | What happens | Tools | |---|---|---|---| | 1 | Data Acquisition | Source the Global Mental Health Dataset 2025 (synthetic, patient-level records) from Kaggle. | Kaggle | | 2 | Cleaning & Preprocessing | Handle missing values (median/mode imputation), normalize types, and validate ranges. | pandas, numpy | | 3 | Exploratory Data Analysis | Examine distributions, correlations (PHQ-9 vs GAD-7), and lifestyle relationships to surface insight. | Jupyter, matplotlib, seaborn | | 4 | Feature Engineering | Derive Depression_Level, Anxiety_Level, and Risk_Level from clinical thresholds; encode categoricals with LabelEncoder. | scikit-learn | | 5 | Model Training | Train and compare three classifiers under a fixed train/test split. | scikit-learn | | 6