README.md

metadata

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. This is the short version.

Prerequisites

• Python ≥ 3.10
• Node.js ≥ 18 + npm ≥ 9

1 — Install Python deps

cd breathe-app
python -m venv venv
source venv/bin/activate          # Windows: venv\Scripts\Activate.ps1
pip install -r requirements.txt

2 — Configure environment

cp .env.example .env
# edit .env — set SECRET_KEY at minimum

3 — Install frontend deps

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)

source venv/bin/activate
python app.py

Terminal 2 — React dev server (port 5173)

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

# 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. This is the short version.

Prerequisites

• Python ≥ 3.10
• Node.js ≥ 18 + npm ≥ 9

1 — Install Python deps

python -m venv venv
source venv/bin/activate          # Windows: venv\Scripts\Activate.ps1
pip install -r requirements.txt

2 — Configure environment

cp .env.example .env
# edit .env — set SECRET_KEY at minimum

3 — Install frontend deps

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

source venv/bin/activate
python app.py

Terminal 2 — React dev server

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

# 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.