README.md

---
title: BREATHE
emoji: 🫁
colorFrom: blue
colorTo: indigo
sdk: docker
app_file: app.py
pinned: false
---

# 🫁 BREATHE

> **Stress Intelligence Platform** — understand your stress before it controls you.

BREATHE is a full-stack web app that fuses psychometric lifestyle data and free-text journaling through an ML pipeline to give you a personalised stress score, trend charts, and actionable advice — all in a clean, dark-themed React dashboard.

---

## ✨ Features

### Core
- **Secure auth** — sign up / log in with hashed passwords and server-side sessions
- **Psychometric assessment** — 12 lifestyle sliders (sleep, work hours, screen time, caffeine …) + 4 categorical cues
- **Text journaling** — write freely; RoBERTa NLP analyses the sentiment
- **ML fusion** — tabular ensemble (LightGBM / CatBoost / XGBoost / Stacking) + RoBERTa → weighted probability fusion → 5-class stress output
- **Demo mode** — app runs fully with rule-based heuristics when ML model files are absent

### Dashboard
- Area timeline chart of stress scores
- Pie distribution of stress levels
- Stat cards (total assessments, latest level, average score, trend)
- Recent assessments with per-assessment detail modal
- Stress relief activity panel (accordion)

### Profile
- Upload a profile photo (JPG/PNG/GIF/WebP, max 2 MB)
- Set gender, working status, and date of birth
- Write a short bio
- **Anonymous mode** — toggle to hide your name in shared/exported views

### Gratitude Journal
- Write 3 prompted daily gratitude items + optional mood tag + free-text reflection
- All entries saved to your account with timestamps
- Paginated history view with expand/collapse and per-entry delete

### Daily To-Do
- Add tasks with High / Medium / Low priority
- Filter by All / Active / Done; bulk-clear completed tasks
- **Stored in browser localStorage only** — never sent to the server

### Breathe Hub
- Full-screen activity centre (no sidebar) — opens on login
- 6 activity cards: Gratitude Journal, Box Breathing, Daily To-Do, Body Scan, Sound Bath, Progressive Relaxation
- Guided exercise modal with step-through progress dots for breathing and relaxation exercises
- Quick nav buttons to Dashboard and Profile

---

## 🖥️ Tech Stack

| Layer | Technology |
|-------|------------|
| Frontend | React 18, Vite 5, React Router v6, Recharts 2 |
| Backend | Python 3.10+, Flask 3, Flask-SQLAlchemy |
| Database | SQLite (dev) / PostgreSQL (prod) |
| Auth | Server-side sessions, Werkzeug password hashing |
| ML — Tabular | LightGBM / CatBoost / XGBoost / Stacking ensemble |
| ML — Text | RoBERTa-base fine-tuned on mental-health dataset |
| ML — Fusion | Weighted probability fusion → Minimal / Mild / Moderate / Severe / Critical |

---

## 🚀 Quick Start

> Full instructions are in [SETUP.md](SETUP.md). This is the short version.

### Prerequisites
- Python ≥ 3.10
- Node.js ≥ 18 + npm ≥ 9

### 1 — Install Python deps
```bash
cd breathe-app
python -m venv venv
source venv/bin/activate          # Windows: venv\Scripts\Activate.ps1
pip install -r requirements.txt
```

### 2 — Configure environment
```bash
cp .env.example .env
# edit .env — set SECRET_KEY at minimum
```

### 3 — Install frontend deps
```bash
cd frontend && npm install && cd ..
```

### 3.1 — Docker deployment support
This repo includes a root-level `Dockerfile` so you can build the app as a single container for Hugging Face Spaces or any Docker host.

### 4 — Run (two terminals)

**Terminal 1 — Flask API (port 5000)**
```bash
source venv/bin/activate
python app.py
```

**Terminal 2 — React dev server (port 5173)**
```bash
cd frontend
npm run dev
```

Open **http://localhost:5173** — after login you land on the Breathe hub 🎉

---

## 📁 Project Structure

```
breathe-app/
├── app.py                    # WSGI entry-point
├── requirements.txt
├── .env.example
├── backend/
│   ├── __init__.py           # Flask app factory
│   ├── models/
│   │   ├── user.py           # User ORM (incl. profile fields)
│   │   ├── assessment.py     # Assessment ORM
│   │   └── gratitude.py      # GratitudeEntry ORM
│   ├── routes/
│   │   ├── auth.py           # /api/auth/*
│   │   ├── assessments.py    # /api/assessments/*
│   │   ├── profile.py        # /api/profile/*
│   │   └── gratitude.py      # /api/gratitude/*
│   └── ml/ml_engine.py       # Inference wrapper + demo fallback
├── frontend/
│   ├── vite.config.js        # Proxies /api → Flask :5000
│   └── src/
│       ├── pages/
│       │   ├── LandingPage.jsx
│       │   ├── AuthPage.jsx
│       │   ├── BreathePage.jsx    # Activity hub (post-login home)
│       │   ├── DashboardPage.jsx
│       │   ├── AssessPage.jsx
│       │   ├── HistoryPage.jsx
│       │   ├── ProfilePage.jsx
│       │   ├── GratitudePage.jsx
│       │   └── TodoPage.jsx
│       ├── components/Layout.jsx  # Sidebar shell
│       ├── context/AuthContext.jsx
│       └── api/client.js          # Fetch wrapper (get/post/put/del)
├── models/
│   ├── psychometric/         # .pkl files from notebook
│   └── text/                 # roberta-model.pt
└── instance/
    └── breathe.db            # SQLite DB (auto-created)
```

---

## 🧠 ML Pipeline

```
Lifestyle cues (12 numeric + 4 categorical)
        │
        ▼
  Feature engineering (PolynomialFeatures, scaling, label encoding)
        │
        ▼
  Stacking ensemble  ──────────────────────────────┐
  (LightGBM + CatBoost + XGBoost + RF + MLP)       │
        │                                           │
        ▼                                           ▼
  psycho_score (0–1)              text_score (0–1) ← RoBERTa fine-tuned
        │                                           │
        └──────────── fusion (50/50) ───────────────┘
                             │
                             ▼
              fused_score → stress label
          [Minimal | Mild | Moderate | Severe | Critical]
```

The engine falls back to **Demo mode** (rule-based heuristics) if model files are missing.

---

## 🔌 API Reference

### Auth
| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | `/api/auth/signup` | Register (`username`, `email`, `password`) |
| POST | `/api/auth/login` | Login (`email` or `username`, `password`) |
| POST | `/api/auth/logout` | Logout |
| GET | `/api/auth/me` | Current user |

### Assessments
| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | `/api/assessments` | Submit assessment |
| GET | `/api/assessments` | List (paginated `?page=1&per_page=20`) |
| GET | `/api/assessments/<id>` | Single assessment |
| GET | `/api/assessments/summary` | Dashboard data + timeline |

### Profile
| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/api/profile` | Get current profile |
| PUT | `/api/profile` | Update bio, gender, working status, DOB, anonymous flag |
| POST | `/api/profile/avatar` | Upload / remove avatar (base64 data-url) |

### Gratitude Journal
| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | `/api/gratitude` | Save entry (`items[]`, `content`, `mood`) |
| GET | `/api/gratitude` | List entries (paginated `?page=1`) |
| DELETE | `/api/gratitude/<id>` | Delete entry |

---

## 🗺️ Page Routes

| URL | Page | Auth |
|-----|------|------|
| `/` | Landing page | Public |
| `/auth` | Login / Signup | Public |
| `/app/breathe` | Breathe hub (post-login home) | Protected |
| `/app/dashboard` | Stress dashboard | Protected |
| `/app/assess` | New assessment | Protected |
| `/app/history` | Assessment history | Protected |
| `/app/profile` | User profile | Protected |
| `/app/gratitude` | Gratitude journal | Protected |
| `/app/todo` | Daily to-do list | Protected |

---

## 📦 Production Build

```bash
# Build React bundle (output → frontend/dist/)
cd frontend && npm run build && cd ..

# Flask auto-serves frontend/dist/ — no Node process needed
gunicorn "app:app" --workers 2 --bind 0.0.0.0:5000 --timeout 120
```

---

## 📄 License

MIT — see `LICENSE` for details.


---

## 🖥️ Tech Stack

| Layer | Technology |
|-------|-----------|
| Frontend | React 18, Vite 5, React Router v6, Recharts 2 |
| Backend | Python 3.10+, Flask 3, Flask-SQLAlchemy |
| Database | SQLite (dev) / PostgreSQL (prod) |
| Auth | Server-side sessions, Werkzeug password hashing |
| ML — Tabular | LightGBM / CatBoost / XGBoost / Stacking ensemble |
| ML — Text | RoBERTa-base fine-tuned on mental-health dataset |
| ML — Fusion | Weighted probability fusion → Minimal / Mild / Moderate / Severe / Critical |

---

## 🚀 Quick Start

> Full instructions are in [SETUP.md](SETUP.md). This is the short version.

### Prerequisites
- Python ≥ 3.10
- Node.js ≥ 18 + npm ≥ 9

### 1 — Install Python deps
```bash
python -m venv venv
source venv/bin/activate          # Windows: venv\Scripts\Activate.ps1
pip install -r requirements.txt
```

### 2 — Configure environment
```bash
cp .env.example .env
# edit .env — set SECRET_KEY at minimum
```

### 3 — Install frontend deps
```bash
cd frontend && npm install && cd ..
```

### 3.1 — Docker deployment support
This repo includes a root-level `Dockerfile` so you can build the app as a single container for Hugging Face Spaces or any Docker host.

### 4 — Run (two terminals)

**Terminal 1 — Flask API**
```bash
source venv/bin/activate
python app.py
```

**Terminal 2 — React dev server**
```bash
cd frontend
npm run dev
```

Open **http://localhost:5173** 🎉

---

## 📁 Project Structure

```
breathe-app/
├── app.py                  # WSGI entry-point
├── requirements.txt
├── .env.example
├── backend/
│   ├── __init__.py         # Flask app factory
│   ├── models/             # SQLAlchemy ORM models
│   ├── routes/             # Auth + Assessment API blueprints
│   └── ml/ml_engine.py     # Inference wrapper + demo fallback
├── frontend/
│   ├── vite.config.js      # Proxies /api → Flask :5000
│   └── src/
│       ├── pages/          # AuthPage, DashboardPage, AssessPage, HistoryPage
│       ├── components/     # Layout (sidebar shell)
│       ├── context/        # AuthContext
│       └── api/client.js   # Fetch wrapper
├── models/
│   ├── psychometric/       # .pkl files from notebook
│   └── text/               # roberta-model.pt
└── notebooks/              # Original Jupyter notebooks
```

---

## 🧠 ML Pipeline

```
Lifestyle cues (12 numeric + 4 categorical)
        │
        ▼
  Feature engineering (PolynomialFeatures, scaling, label encoding)
        │
        ▼
  Stacking ensemble  ──────────────────────────────┐
  (LightGBM + CatBoost + XGBoost + RF + MLP)       │
        │                                           │
        ▼                                           ▼
  psycho_score (0–1)              text_score (0–1) ← RoBERTa fine-tuned
        │                                           │
        └──────────── fusion (50/50) ───────────────┘
                             │
                             ▼
              fused_score → stress label
          [Minimal | Mild | Moderate | Severe | Critical]
```

The engine falls back to **Demo mode** (rule-based heuristics) if model files are missing — the full UI still works.

---

## 🔌 API Reference

| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | `/api/auth/signup` | Register (`username`, `email`, `password`) |
| POST | `/api/auth/login` | Login (`email` or `username`, `password`) |
| POST | `/api/auth/logout` | Logout |
| GET | `/api/auth/me` | Current user |
| POST | `/api/assessments` | Submit assessment |
| GET | `/api/assessments` | List (paginated) |
| GET | `/api/assessments/<id>` | Single assessment |
| GET | `/api/assessments/summary` | Dashboard data |

---

## 📦 Production Build

```bash
# Build React bundle (output → frontend/dist/)
cd frontend && npm run build && cd ..

# Flask auto-serves frontend/dist/ — no Node process needed
gunicorn "app:app" --workers 2 --bind 0.0.0.0:5000 --timeout 120
```

---

## 🤝 Contributing

1. Fork the repo
2. Create a feature branch: `git checkout -b feat/my-feature`
3. Commit your changes: `git commit -m "feat: add my feature"`
4. Push and open a Pull Request

---

## 📄 License

MIT — see `LICENSE` for details.