AI_Cycling_Coach

Architecture

System Overview

┌─────────────────────────────────┐
│         React Frontend          │
│   (Vite + TypeScript + FC)      │
│  Port 3000 → proxies to :5000  │
└──────────────┬──────────────────┘
               │ HTTP/JSON (REST)
┌──────────────▼──────────────────┐
│         Flask Backend           │
│   (Python 3.11+ / Flask)        │
│  Port 5000                      │
│                                 │
│  ┌───────────────────────────┐  │
│  │     Route Blueprints      │  │
│  │  /api/health              │  │
│  │  /api/chat/*              │  │
│  │  /api/calendar/*          │  │
│  │  /api/workouts/*          │  │
│  └───────────┬───────────────┘  │
│              │                  │
│  ┌───────────▼───────────────┐  │
│  │    Services Layer         │  │
│  │  CoachAgent (AI logic)    │  │
│  └───────────┬───────────────┘  │
│              │                  │
│  ┌───────────▼───────────────┐  │
│  │   SQLAlchemy Models       │  │
│  │  User, CalendarEvent,     │  │
│  │  Workout, ChatMessage     │  │
│  └───────────┬───────────────┘  │
│              │                  │
│  ┌───────────▼───────────────┐  │
│  │  SQLite (dev) / Postgres  │  │
│  └───────────────────────────┘  │
└──────────────┬──────────────────┘
               │ OpenAI-compatible API
┌──────────────▼──────────────────┐
│   AI Provider                   │
│   (OpenAI / Ollama / etc.)      │
└─────────────────────────────────┘

Directory Structure

AI_Cycling_Coach/
├── Plan.md                 # Living project plan (updated as work progresses)
├── ARCHITECTURE.md         # This file
├── REQUIREMENTS.md         # API requirements & external dependencies
├── AGENT.md               # Instructions for AI agents working on this codebase
├── backend/
│   ├── run.py             # Entry point
│   ├── config.py          # Flask configuration (dev/prod/test)
│   ├── requirements.txt   # Python dependencies
│   ├── .env.example       # Environment variable template
│   └── app/
│       ├── __init__.py    # Flask app factory (create_app)
│       ├── models/        # SQLAlchemy models
│       │   ├── user.py
│       │   ├── calendar_event.py
│       │   ├── workout.py
│       │   └── chat_message.py
│       ├── routes/        # Flask blueprints (REST endpoints)
│       │   ├── health.py
│       │   ├── calendar.py
│       │   ├── chat.py
│       │   └── workouts.py
│       ├── services/      # Business logic
│       │   └── coach_agent.py  # AI coaching agent
│       └── utils/
│           └── auth.py    # User helper (MVP: single-user)
└── frontend/
    ├── package.json
    ├── vite.config.ts     # Dev server + API proxy
    ├── tsconfig.json
    └── src/
        ├── main.tsx       # Entry point
        ├── App.tsx        # Router setup
        ├── index.css      # Global styles (dark theme)
        ├── types/         # TypeScript interfaces
        ├── services/      # API client layer
        ├── hooks/         # Custom React hooks
        └── components/
            ├── Layout/    # Sidebar + shell
            ├── Calendar/  # FullCalendar integration
            ├── Chat/      # AI coach chat interface
            └── Workout/   # Workout list + detail/logging modal

Data Flow

Chat → Workout Creation

1. User sends message via Chat UI → POST /api/chat/send
2. Backend saves user message to DB
3. CoachAgent builds context (user profile, schedule, recent workouts)
4. CoachAgent calls OpenAI-compatible API with system prompt + context + history
5. AI response may contain a ```workouts JSON block
6. CoachAgent parses JSON, creates CalendarEvent + Workout records
7. Response returned to frontend; calendar auto-refreshes

Workout Logging

1. User clicks workout on Calendar or Workouts page
2. WorkoutDetailModal shows planned details + logging form
3. User enters actual ride data (duration, distance, power, HR, RPE, notes)
4. PUT /api/workouts/:id updates the record
5. Next AI conversation includes this data as context

Key Design Decisions

1. Single-user MVP: No auth — auto-creates user ID 1. Production would add JWT/OAuth.
2. OpenAI-compatible API: Works with OpenAI, Ollama, LM Studio, etc. by changing base URL.
3. Workout extraction: AI coach outputs structured JSON in a fenced block; backend parses it to create DB records.
4. Vite proxy: Frontend proxies /api/* to Flask, avoiding CORS in dev while keeping clean separation.
5. Dark theme: Cyclist-friendly dark UI with CSS custom properties for easy theming.