FitTrack_GarminSync/specs/003-loginimprovements-use-the/tasks.md

Tasks: Garmin Login Improvements

Branch: 003-loginimprovements-use-the | Date: 2025-10-10 | Spec: /home/sstent/Projects/FitTrack_GarminSync/specs/003-loginimprovements-use-the/spec.md

Summary

This plan outlines the implementation of Garmin login improvements, enabling users to link their Garmin accounts via a /login endpoint. The system will store credentials, automatically refresh tokens, and operate statelessly for API callers, implicitly using stored Garmin credentials for sync operations.

Phase 1: Setup Tasks (Project Initialization)

• T001: Ensure Python 3.13 virtual environment is set up and activated.
• T002: Install core dependencies: FastAPI, garth, garminconnect, httpx, pydantic.
• T003: Verify centralDB connection and schema for GarminCredentials entity.

Phase 2: Foundational Tasks (Blocking Prerequisites)

• T004: Implement GarminCredentials Pydantic model in backend/src/schemas.py based on data-model.md.
• T005: Implement GarminLoginRequest and GarminLoginResponse Pydantic models in backend/src/schemas.py based on garmin_auth_login.json.
• T006: Implement ActivitySyncRequest Pydantic model in backend/src/schemas.py based on sync_garmin_activities.json.
• T007: Update CentralDBService in backend/src/services/central_db_service.py to include methods for create_garmin_credentials, get_garmin_credentials, and update_garmin_credentials.
• T008: Implement GarminAuthService in backend/src/services/garmin_auth_service.py with initial_login method to authenticate with Garmin and return GarminCredentials.

Phase 3: User Story 1 - Initial Garmin Account Setup (P1)

Goal: User can link their Garmin account via /api/garmin/login. Independent Test Criteria: Call /api/garmin/login with valid/invalid credentials and verify centralDB state and response.

• T009 [US1]: Implement /api/garmin/login endpoint in backend/src/api/garmin_auth.py to accept GarminLoginRequest.
• T010 [US1]: Integrate GarminAuthService.initial_login and CentralDBService methods into /api/garmin/login endpoint.
• T011 [US1]: Ensure /api/garmin/login returns GarminLoginResponse on success and appropriate error on failure.
• T012 [US1]: Write unit tests for /api/garmin/login endpoint in backend/tests/api/test_garmin_auth_api.py covering success and failure scenarios.

Phase 4: User Story 3 - Stateless Garmin Sync Operations (P1)

Goal: Garmin Sync operations retrieve tokens from centralDB without client-side authentication. Independent Test Criteria: Call /api/sync/garmin/activities after successful login and verify sync initiation.

• T013 [US3]: Modify get_current_user dependency in backend/src/dependencies.py to retrieve user_id implicitly (e.g., from a fixed value for single-user system) and then fetch GarminCredentials from CentralDBService.
• T014 [US3]: Implement GarminActivityService in backend/src/services/garmin_activity_service.py to use GarminCredentials from CentralDBService for Garmin API calls.
• T015 [US3]: Implement /api/sync/garmin/activities endpoint in backend/src/api/garmin_sync.py to accept ActivitySyncRequest.
• T016 [US3]: Integrate GarminActivityService into /api/sync/garmin/activities endpoint.
• T017 [US3]: Write unit tests for /api/sync/garmin/activities endpoint in backend/tests/api/test_garmin_sync_api.py covering successful sync initiation.

Phase 5: User Story 2 - Automatic Garmin Token Refresh (P1)

Goal: System automatically refreshes Garmin authentication tokens. Independent Test Criteria: Simulate expired token and verify refresh during a sync operation.

• T018 [US2]: Enhance GarminAuthService to include a method for checking token expiration and refreshing tokens.
• T019 [US2]: Integrate token refresh logic into GarminActivityService (and other Garmin services) before making Garmin API calls.
• T020 [US2]: Ensure CentralDBService is updated with new tokens after refresh.
• T021 [US2]: Write integration tests for automatic token refresh in backend/tests/integration/test_garmin_token_refresh.py.

Final Phase: Polish & Cross-Cutting Concerns

• T022: Review and update README.md with instructions for setting up and running the service.
• T023: Ensure all new code adheres to project's code quality standards (Black, Flake8, Mypy, Isort).
• T024: Update GEMINI.md with any new technologies or commands.

Dependencies

• Phase 1 -> Phase 2
• Phase 2 -> Phase 3
• Phase 3 -> Phase 4
• Phase 4 -> Phase 5
• Phase 5 -> Final Phase

Parallel Execution Examples

• Phase 2: T004, T005, T006 can be executed in parallel.
• Phase 3 (US1): T009, T010, T011 can be executed in parallel after T008.
• Phase 4 (US3): T014, T015, T016 can be executed in parallel after T013.

Implementation Strategy

We will follow an MVP-first approach, delivering User Story 1, then User Story 3, and finally User Story 2. This ensures core login and stateless sync functionality is established before implementing automatic token refresh.