FitFlow Workout Builder

A full-stack fitness application for building custom workouts and generating AI-powered 60-minute workout plans.

Features

• Manual Workout Builder: Create custom workouts by selecting exercises and specifying sets/reps or duration
• FitFlow 60-Minute Generator: AI-powered workout generation with:
  • Equipment selection (No Equipment, Dumbbells, Kettlebell, Full Gym, Resistance Band, Pull-up Bar)
  • Focus area selection (Full Body, Upper Body, Lower Body, Core & Balance, Cardio)
  • Structured 5/50/5 split (5-min warmup, 50-min main set, 5-min cooldown)
  • Exercise swapping with intelligent alternatives
  • Workout tracking and completion logging
• Exercise Library: Filter and search exercises by name, muscle group, and type

Tech Stack

• Backend: FastAPI (Python) with in-memory storage
• Frontend: React 18 + TypeScript + Vite
• Styling: Tailwind CSS
• State Management: React Query + React hooks
• AI: OpenAI-compatible API (supports OpenRouter, Groq, etc.)

Project Structure

├── backend/
│   ├── main.py                    # FastAPI app, routes, data models
│   ├── schemas.py                 # Pydantic models
│   ├── services/
│   │   ├── exercises.py           # Exercise loading service
│   │   └── fitflow_generator.py   # AI workout generation logic
│   ├── tests/                     # pytest tests
│   ├── requirements.txt           # Python dependencies
│   └── .env.example               # Environment template
├── frontend/
│   ├── src/
│   │   ├── App.tsx                # Main React component
│   │   ├── api.ts                 # API client
│   │   ├── types.ts               # TypeScript types
│   │   └── styles.css             # Tailwind + custom styles
│   └── package.json               # Node dependencies
├── Makefile                       # Development shortcuts
└── README.md

Prerequisites

• Python 3.9+ (3.11+ recommended)
• Node.js 18+ and npm

Quick Start

# 1. Install dependencies
make install

# 2. Configure environment
cp backend/.env.example backend/.env
# Edit backend/.env with your API key (see Configuration below)

# 3. Run both servers
make dev

# 4. Open the app
open http://localhost:5173

Configuration

AI Provider Setup

The backend supports any OpenAI-compatible API. Copy the example and configure:

cp backend/.env.example backend/.env

Option A: OpenRouter (Recommended)

OPENAI_API_KEY=your-openrouter-api-key
OPENAI_BASE_URL=https://openrouter.ai/api/v1
OPENAI_MODEL=openai/gpt-4o-mini

Option B: OpenAI Direct

OPENAI_API_KEY=your-openai-api-key
OPENAI_MODEL=gpt-4o-mini

Option C: Other Providers (Groq, etc.)

OPENAI_API_KEY=your-api-key
OPENAI_BASE_URL=https://api.groq.com/openai/v1
OPENAI_MODEL=llama3-8b-8192

Environment Variables

Variable	Required	Description
OPENAI_API_KEY	Yes	API key for AI provider
OPENAI_BASE_URL	No	Custom API endpoint (default: OpenAI)
OPENAI_MODEL	No	Model to use (default: gpt-4o-mini)
LOG_LEVEL	No	Logging level: DEBUG, INFO, WARNING, ERROR

Development

Makefile Commands

make install    # Install all dependencies (backend + frontend)
make dev        # Start both servers concurrently
make backend    # Start backend only (port 8000)
make frontend   # Start frontend only (port 5173)
make test-be    # Run backend tests
make test-fe    # Run frontend tests
make stop       # Stop background processes

Manual Setup

Backend:

python3 -m venv .venv
source .venv/bin/activate
pip install -r backend/requirements.txt
uvicorn backend.main:app --reload --port 8000

Frontend:

cd frontend
npm install
npm run dev

API Reference

Core Endpoints

Method	Endpoint	Description
GET	/api/health	Health check
GET	/api/exercises	List exercises (query: q, muscle_group, type)
GET	/api/workouts	List saved workouts
POST	/api/workouts	Create a workout
DELETE	/api/workouts/{id}	Delete a workout

FitFlow Generator Endpoints

Method	Endpoint	Description
POST	/api/fitflow/generate	Generate a 60-minute AI workout
GET	/api/fitflow/swap/{exercise_id}	Get 3 alternative exercises

FitFlow Generate Request

POST /api/fitflow/generate
{
  "equipment_list": ["Dumbbells", "Pull-up Bar"],
  "focus_area": "Upper Body"
}

Response:

{
  "session_id": "uuid",
  "name": "Upper Body Power Session",
  "total_duration_minutes": 60,
  "equipment_used": ["Dumbbells", "Pull-up Bar"],
  "focus_area": "Upper Body",
  "warmup": {
    "name": "Warm-Up",
    "duration_minutes": 5,
    "exercises": [...]
  },
  "main_set": {
    "name": "Main Workout",
    "duration_minutes": 50,
    "exercises": [...]
  },
  "cooldown": {
    "name": "Cool-Down",
    "duration_minutes": 5,
    "exercises": [...]
  }
}

AI Chat Endpoint

curl http://localhost:8000/api/ai/chat \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Suggest a push day workout", "model": "gpt-4o-mini"}'

Testing

# Backend tests
make test-be
# or: python -m pytest backend/tests/ -v

# Frontend tests
make test-fe
# or: cd frontend && npm test

Notes

• Workouts are stored in-memory and reset on server restart
• CORS is configured for localhost development
• The FitFlow generator falls back to algorithmic generation if AI is unavailable