136 lines
5.1 KiB
Markdown
136 lines
5.1 KiB
Markdown
# 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.
|