MoodSprint

Adaptive task management app that adjusts task breakdown based on your mood and energy level.

Features

• Mood-aware task decomposition: AI breaks down tasks into smaller steps based on your current state
• Focus sessions: Pomodoro-style timer with task tracking
• Gamification: XP, levels, streaks, and achievements
• Telegram Mini App: Optimized for use inside Telegram
• PWA support: Installable as mobile app

Tech Stack

• Frontend: Next.js 14, TypeScript, Tailwind CSS, React Query, Zustand
• Backend: Flask, SQLAlchemy, PostgreSQL
• Infrastructure: Docker, Nginx

Quick Start

Prerequisites

• Docker & Docker Compose
• (Optional) Telegram Bot Token from @BotFather
• (Optional) OpenAI API Key for AI task decomposition

Development

1. Clone the repository:

git clone <repo-url>
cd moodsprint

2. Copy environment file:

cp .env.example .env

3. Edit .env with your settings (Telegram token, OpenAI key, etc.)

4. Start the development environment:

docker-compose -f docker-compose.yml -f docker-compose.dev.yml up --build

5. Access the app:
   • Frontend: http://localhost:3000
   • Backend API: http://localhost:5000/api/v1
   • Full app via nginx: http://localhost:8080

Production

1. Configure production environment:

cp .env.example .env
# Edit .env with production values

2. Build and start:

docker-compose up -d --build

3. Access the app on port 80 (or configured PORT)

Project Structure

moodsprint/
├── backend/                 # Flask API
│   ├── app/
│   │   ├── api/            # API endpoints
│   │   ├── models/         # Database models
│   │   ├── services/       # Business logic
│   │   └── utils/          # Utilities
│   ├── Dockerfile
│   └── requirements.txt
│
├── frontend/               # Next.js App
│   ├── src/
│   │   ├── app/           # Pages (App Router)
│   │   ├── components/    # React components
│   │   ├── domain/        # Types & constants
│   │   ├── services/      # API clients
│   │   ├── hooks/         # Custom hooks
│   │   └── lib/           # Utilities
│   ├── Dockerfile
│   └── package.json
│
├── nginx/                  # Reverse proxy
│   ├── nginx.conf
│   └── Dockerfile
│
├── docker-compose.yml      # Production compose
├── docker-compose.dev.yml  # Development override
└── .env.example

API Documentation

See API.md for full API specification.

Key Endpoints

• POST /api/v1/auth/telegram - Authenticate via Telegram
• GET/POST /api/v1/tasks - Task management
• POST /api/v1/tasks/:id/decompose - AI task decomposition
• POST /api/v1/mood - Log mood check
• POST /api/v1/focus/start - Start focus session
• GET /api/v1/user/stats - User statistics

Telegram Mini App Setup

1. Create a bot with @BotFather
2. Enable Mini App for the bot
3. Set the Mini App URL to your deployed frontend
4. Add the bot token to .env

Development Setup

Pre-commit Hooks

This project uses pre-commit for code quality checks. This is required for all developers.

# Install pre-commit
pip install pre-commit

# Install hooks (run once after cloning)
pre-commit install

# (Optional) Run on all files
pre-commit run --all-files

The hooks will automatically:

• Format Python code with black
• Sort imports with isort
• Check for lint errors with flake8

Manual Linting

# Backend
cd backend
python -m black app
python -m flake8 app --max-line-length=100

# Bot
cd bot
python -m black .
python -m flake8 . --max-line-length=100

Contributing

1. Fork the repository
2. Set up pre-commit hooks (see above)
3. Create a feature branch
4. Make your changes
5. Submit a pull request

License

MIT