Tburnout-sentinel

# Burnout Sentinel **An Early Warning System for Student Burnout Using Workload and Recovery Indicators** [](README.md) [](frontend/package.json) [](backend/app/main.py) [](README.md) [Overview](#overview) - [Features](#features) - [Quick Start](#quick-start) - [Project Structure](#project-structure) - [Roadmap](#roadmap)

---

Table of Contents

• Overview
• Project Status
• Features
• How It Works
• Quick Start
• Project Structure
• Tech Stack
• Research Question
• Roadmap
• Contributing Notes

---

Overview

Burnout Sentinel is a student wellness project focused on helping students detect overload early and rebalance their week before stress becomes burnout.

Instead of acting like a basic to-do list, the app combines planning inputs with explainable risk scoring, personalized recommendations, and trend tracking.

The current implementation is an MVP prototype with a polished UI, backend analysis API, and competition-ready demo flow.

Project Status

• Project title: Burnout Sentinel
• Research subtitle: An Early Warning System for Student Burnout Using Workload and Recovery Indicators
• Version: 0.4.0
• Last updated: April 19, 2026
• Scope: MVP prototype
• Current focus: frontend experience, research feed, and explainable burnout analysis

Features

Core Planner

• Weekly workload and recovery input form
• Preset weeks (Balanced, Heavy, Overloaded)
• Live workload summary while editing
• Collapse/expand controls for planner sections and analysis panels

Analysis and Guidance

• Burnout risk score (0-100) with Low/Moderate/High labels
• Explainable score breakdown and contributing factors
• What-if simulation for schedule adjustments
• Personalized recommendation generation

Visualization and Interaction

• Workload snapshot metrics
• Risk trend chart with saved snapshots
• Drag-and-drop panel reordering
• State-aware UI feedback for preset and risk interactions

Research and Product Experience

• Research Signal page with external links and infinite scrolling
• Help popup for formula and usage instructions
• Lightweight cookie-session login/signup flow

How It Works

1. Student enters weekly workload and recovery indicators.
2. Frontend validates payload and posts to POST /api/v1/analyze.
3. Backend computes explainable risk and recommendations.
4. Frontend renders risk summary, breakdown, what-if panel, and trend insights.
5. If backend is unavailable, frontend can fall back to local analyzer logic.

Quick Start

Backend

For full setup, tests, and troubleshooting, see backend/README.md.

cd /Users/dominhduy/Documents/Playground/burnout-sentinel/backend
source .venv/bin/activate
python3 -m uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

Backend endpoints:

• Health: http://localhost:8000/health
• Docs: http://localhost:8000/docs

Frontend

cd /Users/dominhduy/Documents/Playground/burnout-sentinel/frontend
cp .env.example .env.local
npm install
npm run dev

Frontend app:

• http://localhost:3000

Vercel Deployment

See docs/vercel-deployment.md for monorepo/Vercel setup.

Project Structure

• frontend/: Next.js application (UI, client logic, API route bridge)
• backend/: FastAPI burnout scoring and recommendation API
• backend/README.md: backend run/test/troubleshooting guide
• docs/: proposal, pitch notes, build plan, deployment notes
• ml/: future machine-learning workspace
• shared/: future shared schemas/constants/prompts

Tech Stack

• Frontend: Next.js, React, TypeScript, Tailwind CSS
• Forms/Validation: React Hook Form, Zod
• Charts: Recharts
• Backend: FastAPI, Pydantic
• Modeling approach: explainable rules-based risk scoring (ML-ready architecture)
• Deployment target: Vercel (frontend) + Render/Railway/Fly/Azure (backend)

Research Question

Can a machine learning-supported planning tool help students identify overload and reduce burnout risk by providing personalized weekly planning recommendations?

Roadmap

• Replace explainable rules with trained model once dataset is available
• Add persistence for long-term schedule and trend history
• Expand recommendation quality and personalization
• Add optional account system for multi-device continuity

Contributing Notes

• Frontend is the most active iteration area.
• Backend currently prioritizes explainability and stability for demos.
• Auth is session-cookie based (not OAuth/password auth).
• Research feed uses paged loading with link fallbacks.
• Feedback currently opens mail draft to [email protected].

Built With

• css
• javascript
• powershell
• python
• shell
• typescript