AI_Cycling_Coach

AGENT.md — Instructions for AI Agents

This file provides context and instructions for AI coding agents (GitHub Copilot, Cursor, Cline, Aider, etc.) working on this codebase.

Project Overview

AI Cycling Coach — a web app where cyclists chat with an AI coaching agent to build training plans. The AI creates workouts on a calendar; users log ride results.

Quick Orientation

What	Where
Backend entry point	backend/run.py
Flask app factory	backend/app/__init__.py
Database models	backend/app/models/
API routes	backend/app/routes/
AI coach logic	backend/app/services/coach_agent.py
Frontend entry	frontend/src/main.tsx
React router	frontend/src/App.tsx
API client	frontend/src/services/api.ts
TypeScript types	frontend/src/types/index.ts
Living plan	Plan.md (update this as you make changes)

Dev Server Commands

# Backend
cd backend
python -m venv venv && source venv/bin/activate
pip install -r requirements.txt
cp .env.example .env  # then edit with your API key
python run.py          # http://localhost:5000

# Frontend
cd frontend
npm install
npm run dev            # http://localhost:3000 (proxies /api to :5000)

Coding Conventions

Backend (Python)

• Style: PEP 8, type hints on all function signatures
• Models: Each model in its own file under app/models/, with a to_dict() method
• Routes: Grouped by resource in Flask Blueprints under app/routes/
• Services: Business logic in app/services/, not in route handlers
• Error handling: Use first_or_404() for lookups; return JSON error responses
• Config: All secrets via environment variables (never hardcoded)

Frontend (TypeScript/React)

• Style: Functional components, hooks only (no class components)
• Types: All interfaces in src/types/index.ts
• API calls: All go through src/services/api.ts (single source of truth)
• CSS: Component-scoped CSS files next to their components; global vars in index.css
• State: Local state with useState; no Redux needed at current scale

Common Tasks

Adding a new API endpoint

1. If needed, add/modify model in backend/app/models/
2. Create or modify route in backend/app/routes/
3. Register blueprint in backend/app/__init__.py (if new file)
4. Add corresponding function in frontend/src/services/api.ts
5. Add TypeScript types in frontend/src/types/index.ts

Modifying the AI coaching behavior

• Edit SYSTEM_PROMPT in backend/app/services/coach_agent.py
• The _build_context() method controls what data the AI sees
• The _extract_and_save_workouts() method parses AI output for workout JSON

Adding a new page

1. Create component folder under frontend/src/components/
2. Add route in frontend/src/App.tsx
3. Add nav link in frontend/src/components/Layout/AppLayout.tsx

Skills That Help

• grep_search for finding where things are defined/used
• Read Plan.md first to understand current project state
• Read this file to understand conventions before making changes
• Update Plan.md after completing significant work
• When modifying the AI system prompt, test by sending a chat message and checking if workouts are correctly created

Known Limitations (Good First Issues)

• No authentication (single-user mode) — add JWT or OAuth
• No recurring event expansion — recurrence_rule stored but not expanded
• Chat history not paginated — add cursor-based pagination
• No workout deletion from calendar click — only from workouts page
• No data export (CSV, .fit file support)
• No Strava/Garmin integration
• No unit tests yet — add pytest for backend, vitest for frontend

Architecture Notes

• The AI coach uses a structured JSON output format (```workouts block) to create workouts
• The frontend uses Vite’s proxy to forward /api requests to Flask
• SQLite for dev, PostgreSQL-ready for prod (just change DATABASE_URL)
• The CoachAgent class is the core intelligence — it builds context from DB, manages conversation history, and extracts structured workout data from AI responses