FitTrack_GarminSync/GEMINI.md

FitTrack_GarminSync Development Guidelines

Auto-generated from all feature plans. Last updated: 2025-10-10

Active Technologies

• Python 3.13 + FastAPI, garth, garminconnect, httpx, pydantic (003-loginimprovements-use-the)
• Python 3.13 + FastAPI, garth, garminconnect, httpx, pydantic (003-loginimprovements-use-the)
• centralDB (PostgreSQL/SQLite with SQLAlchemy) (003-loginimprovements-use-the)
• Python 3.13 + FastAPI, Pydantic, garth, garminconnect, httpx (004-home-sstent-projects)
• In-memory for CurrentSyncJobManager (004-home-sstent-projects)
• Python 3.13 + Existing project dependencies (FastAPI, garth, garminconnect, httpx, pydantic) (005-ensure-the-current)
• CentralDB (for data models), local filesystem (for documentation and file deletion) (005-ensure-the-current)

Project Structure

src/
tests/

Commands

cd src [ONLY COMMANDS FOR ACTIVE TECHNOLOGIES][ONLY COMMANDS FOR ACTIVE TECHNOLOGIES] pytest [ONLY COMMANDS FOR ACTIVE TECHNOLOGIES][ONLY COMMANDS FOR ACTIVE TECHNOLOGIES] ruff check .

Code Style

Python 3.13: Follow standard conventions

Recent Changes

• 005-ensure-the-current: Added Python 3.13 + Existing project dependencies (FastAPI, garth, garminconnect, httpx, pydantic)
• 004-home-sstent-projects: Added Python 3.13 + FastAPI, Pydantic, garth, garminconnect, httpx
• 003-loginimprovements-use-the: Added Python 3.13 + FastAPI, garth, garminconnect, httpx, pydantic

Inferred CentralDB Models and API Endpoints

While a dedicated CentralDB data model specification isn't explicitly in specs/**, the functional requirements and key entities described in specs/001-create-from-initialspec/spec.md, specs/002-intialspecv2/spec.md, and specs/003-loginimprovements-use-the/spec.md imply the following CentralDB models:

1. User: Represents the application's user.
   • Mapping: Stores basic user information and is linked to Garmin Connect Account and GarminCredentials.
2. Garmin Connect Account: Stores authentication tokens and connection status for a user's Garmin account.
   • Mapping: This model would hold the OAuth2 tokens and other Garmin-specific identifiers.
3. GarminCredentials: Explicitly defined in specs/003-loginimprovements-use-the/spec.md.
   • Mapping: Stores the Garmin username, plaintext password (for re-authentication), access token, access token secret, and token expiration date.
4. Activity: Represents a fitness activity.
   • Mapping: Stores metadata and file paths for downloaded FIT, GPX, or TCX files from Garmin Connect.
5. Health Metric: Represents a health measurement.
   • Mapping: Stores synchronized health data points from Garmin Connect.
6. Workout: Represents a structured training plan.
   • Mapping: Stores workout definitions that can be uploaded to Garmin Connect.

Note: The SyncJob entity, as per specs/004-home-sstent-projects/plan.md and GEMINI.md, is managed in-memory by CurrentSyncJobManager and is not a CentralDB model.

CentralDB API Endpoints (Consumed by GarminSync Service)

Although DB_API_SPEC.json is a reference, the GARMINSYNC_SPEC.md (also a reference, but detailing consumed interfaces) provides a clear list of CentralDB HTTP interfaces that the GarminSync service interacts with. These are the endpoints you would call to store data in CentralDB:

1. User Management:

   • POST /users: To create a new user.
   • GET /users/{user_id}: To retrieve a user by ID.
   • GET /users: To retrieve a user by email (e.g., get_user_by_email).

2. Garmin Credentials Management:

   • POST /garmin_credentials/{user_id}: To create new Garmin credentials for a user.
   • PUT /garmin_credentials/{user_id}: To update existing Garmin credentials (e.g., after token refresh).
   • GET /garmin_credentials/{user_id}: To retrieve Garmin credentials for a user.

3. Token Management (likely for application-level tokens, not Garmin-specific OAuth tokens):

   • POST /tokens/: To create a new token.
   • PUT /tokens/{user_id}: To update a token for a user.
   • GET /tokens/{user_id}: To retrieve a token for a user.

4. Activity Storage:

   • POST /activities/{user_id}: To upload activity files (likely multipart file upload).

5. Health Metric Storage:

   • POST /health_metrics: To save health metric data.

6. Workout Plan Retrieval (for uploading workouts):

   • GET /workout_plans/{workout_id}: To retrieve a workout plan by ID from CentralDB before uploading it to Garmin.

Mapping Summary

• Garmin Login Credentials: Map to GarminCredentials model, stored via POST /garmin_credentials/{user_id} or updated via PUT /garmin_credentials/{user_id}.
• Garmin Activities: Map to Activity model, stored via POST /activities/{user_id}.
• Garmin Health Metrics: Map to Health Metric model, stored via POST /health_metrics.
• Workouts (from application to Garmin): Map to Workout model (retrieved via GET /workout_plans/{workout_id} from CentralDB, then uploaded to Garmin).