FitLine

Design, evaluate, and manage training programs from one focused workspace.

FitLine is a full-stack workout planning platform built around a configurable training-block editor, AI-assisted program feedback, and a data-driven home dashboard. It brings program design, saved-program management, upcoming workout scheduling, and weekly volume tracking into one application.

React 19 · Express 5 · PostgreSQL · Gemini AI

What Makes FitLine Different

Most fitness applications either log workouts or provide static templates. FitLine focuses on the decisions behind a program: training ideology, weekly structure, exercise selection, volume, frequency, and recovery.

The central configurator lets users build multi-week programs and receive contextual feedback before committing to them. Gemini analyzes the program against the selected methodology, while a local rule-based expert system keeps analysis available when the external AI service is not configured.

Product Highlights

Intelligent Program Configurator

Build complete training blocks from weeks, scheduled training days, exercises, sets, and rep targets. Programs can be named, saved, edited, activated, and exported as formatted PDFs.

AI Feedback With Graceful Fallback

FitLine sends the current program structure and selected training ideology to Gemini for an assessment of volume, frequency, exercise selection, and recovery. The response is presented as an actionable status with a follow-up coaching conversation.

If Gemini is unavailable, a client-side rule engine evaluates the same plan against methodology-specific constraints, so the core analysis flow still works.

Dashboard Driven by the Active Program

The home dashboard reads from active workout-plan data and combines profile information, a calendar, the upcoming scheduled training day, exercise progress, and monthly training-volume trends.

Templates, Saved Programs, and Exercise Library

Users can start with curated HIT, Push/Pull/Legs, or full-body templates, manage their own saved programs, and search a seeded exercise library by name, muscle group, or tag.

Account and Appearance Controls

The account flow includes registration, server-side sessions, email confirmation, password reset, editable profile metrics, persistent dark mode, and an optional animated Vanta fog background.

Feature Overview

Area	Functionality
Program design	Multi-week blocks, day scheduling, exercise search, custom sets and reps, and methodology presets
Program intelligence	Gemini-powered analysis, status-based feedback, contextual AI chat, and local rules fallback
Program management	Save, edit, activate, browse, and export programs to PDF
Dashboard	Upcoming workout, exercise progress, calendar context, and weekly volume trend visualization
Personalization	Profile metrics, light/dark theme, system-theme detection, and optional animated background
Account lifecycle	Registration, login, logout, email confirmation, password reset, and session management
Security	bcrypt password hashing, PostgreSQL-backed sessions, CSRF protection, route guards, and rate limiting

Tech Stack

Layer	Technology
Frontend	React 19, Vite, React Router
Styling and interface	Tailwind CSS, Lucide React
Visualization	Recharts
Interactive background	Three.js, Vanta.js
PDF generation	jsPDF, jsPDF-AutoTable
Backend	Node.js, Express 5
Database	PostgreSQL 17, pg, SQL migrations
Authentication	Express Session, connect-pg-simple, bcrypt, CSRF tokens
AI	Google Gemini 2.5 Flash with a local rule-based fallback
Email	Nodemailer with SMTP support and Ethereal development fallback
Testing	Node.js test runner, Supertest

Architecture

React client
    |
    |  credentialed requests + CSRF token
    v
Express API
    |
    |-- routes        HTTP validation and response handling
    |-- services      application and domain logic
    |-- repositories  parameterized PostgreSQL queries
    |
    +--> PostgreSQL   users, sessions, programs, schedules, and volume data
    |
    +--> Gemini API   program analysis and fitness-focused follow-up chat

The frontend is organized by pages, reusable components, API clients, and focused utilities. The backend follows a route-service-repository structure that keeps transport logic, business rules, and persistence concerns separate.

fitline/
├── frontend/
│   └── src/
│       ├── api/          # Credentialed API client and endpoint modules
│       ├── components/   # Dashboard, AI, navigation, and visual components
│       ├── context/      # Persistent theme and animation preferences
│       ├── pages/        # Auth, dashboard, configurator, explore, and settings
│       └── utils/        # PDF export and local program analysis
├── backend/
│   ├── db/
│   │   ├── migrations/   # Ordered SQL schema changes and seed data
│   │   └── init.sql      # Initial PostgreSQL schema
│   └── src/
│       ├── middleware/   # Authentication, CSRF, and rate limiting
│       ├── repositories/ # Database access
│       ├── routes/       # API endpoints
│       ├── services/     # Domain logic, AI, auth, and email flows
│       └── tests/        # Authentication lifecycle integration tests
└── docs/screenshots/     # README product imagery

Key Workflow

1. Select a training ideology or start from a curated template.
2. Build a multi-week block and schedule each training day.
3. Add exercises from the searchable library and define sets and rep targets.
4. Analyze the plan for volume, frequency, exercise balance, and recovery concerns.
5. Save, edit, activate, and manage the finished program from the Explore workspace.
6. Export the finished program as a portable PDF.

Running Locally

Prerequisites

• Node.js 20+
• Docker with Docker Compose
• A Gemini API key for live AI analysis and coaching; the local analyzer works without one

1. Configure the backend

cp backend/.env.example backend/.env

For Gemini-powered analysis, add this to backend/.env:

GEMINI_API_KEY=your_gemini_api_key
APP_BASE_URL=http://localhost:5173

SMTP variables are optional. Without them, Nodemailer creates an Ethereal test inbox and prints preview links during development.

2. Start PostgreSQL and apply migrations

cd backend
docker compose --env-file .env up -d
npm install
npm run migrate

Optional: populate a demo account, active plan, and dashboard trend data.

npm run seed:home

The default demo credentials are demo@fitline.local / DemoPass123! and can be overridden with DEMO_EMAIL, DEMO_PASSWORD, and DEMO_FULL_NAME.

3. Start the API

cd backend
npm start

The API runs at http://localhost:4567.

4. Start the frontend

cd frontend
npm install
npm run dev

Open http://localhost:5173. Vite proxies API requests to the Express server during development.

Testing

The backend integration tests cover login, authenticated profile access, logout, email confirmation, and password-reset flows.

cd backend
npm test

Frontend quality checks:

cd frontend
npm run lint
npm run build

Engineering Notes

• Passwords are hashed with configurable bcrypt cost factors and are never returned from the API.
• Sessions are stored server-side in PostgreSQL and regenerated after authentication.
• Mutating authenticated requests use session-bound CSRF tokens.
• Authentication and recovery endpoints use dedicated rate limits.
• Password-reset requests deliberately return the same response whether an email exists or not.
• Database changes are applied through ordered, transaction-wrapped SQL migrations.
• AI prompts are kept on the server, and the assistant is scoped to fitness, nutrition, workouts, and recovery.

---

FitLine was built as an end-to-end product project, with emphasis on thoughtful UX, maintainable application boundaries, secure account flows, and practical AI integration.