5.1 KiB

Raw Blame History

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 (do NOT use pip directly).

AI SDK: google-genai (Standard Python SDK for Gemini).

Frontend Tooling: Vite + npm.

System Overview

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)

Defines all REST endpoints.
Implements global exception handling and structured logging.
Manages CORS and service initialization.

2. Garmin Service (backend/src/garmin/)

client.py: Low-level wrapper for Garmin Connect, handling authentication and MFA.
sync.py: Higher-level logic for fetching activities and synchronizing them with local storage.
workout.py: Logic for translating internal workout models to Garmin JSON format.

3. Recommendation Engine (backend/src/recommendations/)

engine.py: Interfaces with the Google Gemini API using the google-genai SDK. Implements AGENTIC behavior with function calling.
tools.py: Set of tools provided to the AI Agent (e.g., get_weekly_stats, get_user_profile).

4. Storage (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)

Acts as the central hub and dashboard.
Orchestrates global states like authentication and time horizons.

2. Analyze View (AnalyzeView.vue)

Visualizes fitness trends using Chart.js.
Hosts the AI Analyst chat interface.

3. Plan View (PlanView.vue)

Integrated environment for creating Garmin workouts.
Combines AI-assisted creation with manual editing.
Uses WorkoutVisualEditor.vue for drag-and-drop step management.

Key Data Flows

Data Synchronization

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

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.

5.1 KiB Raw Blame History