# FitMop Architecture

FitMop is a full-stack fitness analytics and workout planning platform. It follows a decoupled Client-Server architecture with a FastAPI backend and a Vue.js frontend, orchestrated by a single startup script.

## Core Technology Stack & Tooling

> [!IMPORTANT]
> **Adherence to these tools is mandatory.**
> - **Backend Package Manager**: [`uv`](https://github.com/astral-sh/uv) (do NOT use pip directly).
> - **AI SDK**: [`google-genai`](https://pypi.org/project/google-genai/) (Standard Python SDK for Gemini).
> - **Frontend Tooling**: `Vite` + `npm`.

## System Overview

```mermaid
graph TD
    User((User))
    subgraph Frontend [Vue.js Frontend]
        Dashboard[App.vue Dashboard]
        Analyze[AnalyzeView AI Analyst]
        Plan[PlanView Workout Builder]
    end
    subgraph Backend [FastAPI Backend]
        API[main.py API Layer]
        GarminSvc[Garmin Service]
        AISvc[Recommendation Engine]
        Storage[Local JSON Storage]
    end
    subgraph External [External APIs]
        GarminAPI[(Garmin Connect)]
        GeminiAPI[(Google Gemini AI)]
    end

    User <--> Dashboard
    User <--> Analyze
    User <--> Plan
    
    Dashboard <--> API
    Analyze <--> API
    Plan <--> API
    
    API <--> GarminSvc
    API <--> AISvc
    API <--> Storage
    
    GarminSvc <--> GarminAPI
    GarminSvc <--> Storage
    AISvc <--> GeminiAPI
    AISvc <--> Storage
```

## Backend Components

The backend is built with **FastAPI** and located in `backend/src`.

### 1. API Layer ([main.py](file:///Users/moritz/src/fitness_antigravity/backend/src/main.py))
- Defines all REST endpoints.
- Implements global exception handling and structured logging.
- Manages CORS and service initialization.

### 2. Garmin Service ([backend/src/garmin/](file:///Users/moritz/src/fitness_antigravity/backend/src/garmin/))
- **[client.py](file:///Users/moritz/src/fitness_antigravity/backend/src/garmin/client.py)**: Low-level wrapper for Garmin Connect, handling authentication and MFA.
- **[sync.py](file:///Users/moritz/src/fitness_antigravity/backend/src/garmin/sync.py)**: Higher-level logic for fetching activities and synchronizing them with local storage.
- **[workout.py](file:///Users/moritz/src/fitness_antigravity/backend/src/garmin/workout.py)**: Logic for translating internal workout models to Garmin JSON format.

### 3. Recommendation Engine ([backend/src/recommendations/](file:///Users/moritz/src/fitness_antigravity/backend/src/recommendations/))
- **[engine.py](file:///Users/moritz/src/fitness_antigravity/backend/src/recommendations/engine.py)**: Interfaces with the Google Gemini API using the `google-genai` SDK. Implements AGENTIC behavior with function calling.
- **[tools.py](file:///Users/moritz/src/fitness_antigravity/backend/src/recommendations/tools.py)**: Set of tools provided to the AI Agent (e.g., `get_weekly_stats`, `get_user_profile`).

### 4. Storage ([backend/data/local/](file:///Users/moritz/src/fitness_antigravity/backend/data/local/))
- Data is persisted as structured JSON files for simplicity and privacy.
- `activities_*.json`: Cached Garmin activity data.
- `user_profile.json`: Mock user goals and bio.

## Frontend Components

The frontend is a **Vue.js 3** Single Page Application located in `frontend/src`.

### 1. Main Application ([App.vue](file:///Users/moritz/src/fitness_antigravity/frontend/src/App.vue))
- Acts as the central hub and dashboard.
- Orchestrates global states like authentication and time horizons.

### 2. Analyze View ([AnalyzeView.vue](file:///Users/moritz/src/fitness_antigravity/frontend/src/views/AnalyzeView.vue))
- Visualizes fitness trends using Chart.js.
- Hosts the AI Analyst chat interface.

### 3. Plan View ([PlanView.vue](file:///Users/moritz/src/fitness_antigravity/frontend/src/views/PlanView.vue))
- Integrated environment for creating Garmin workouts.
- Combines AI-assisted creation with manual editing.
- Uses **[WorkoutVisualEditor.vue](file:///Users/moritz/src/fitness_antigravity/frontend/src/components/WorkoutVisualEditor.vue)** for drag-and-drop step management.

## Key Data Flows

### Data Synchronization
```mermaid
sequenceDiagram
    participant FE as Frontend
    participant BE as Backend
    participant GR as Garmin API
    participant LS as Local Storage
    
    FE->>BE: POST /sync
    BE->>BE: Check Session
    BE->>GR: Fetch Activities
    GR-->>BE: Activity Data
    BE->>LS: Save to JSON
    BE-->>FE: Sync Count
    FE->>BE: GET /analyze/dashboard
    BE->>LS: Read JSON
    LS-->>BE: Activities
    BE-->>FE: Aggregated Stats
```

### AI Recommendation Loop
```mermaid
sequenceDiagram
    participant User
    participant BE as Backend (AI Engine)
    participant GM as Gemini API
    participant LS as Local Storage
    
    User->>BE: Send Message
    BE->>GM: Send Prompt + Tools
    GM->>BE: Call Tool: get_weekly_stats
    BE->>LS: Read Data
    LS-->>BE: Stats
    BE-->>GM: Tool Result
    GM-->>BE: Final Motivation/Advice
    BE-->>User: Display Response
```

## Security & Reliability
- **CORS**: Restricted to localhost:5173.
- **Error Handling**: Global FastAPI handler ensures API never crashes silently.
- **Pre-flight**: `Makefile` checks for mandatory environment variables before launch.