Task Breakdown: Persist Garmin Authentication for Stateless Sync

This document breaks down the implementation of the "Persist Garmin Authentication for Stateless Sync" feature into actionable, dependency-ordered tasks.

Implementation Strategy: The feature will be delivered in increments based on user story dependencies. The foundational database work will be done first. Then, we will implement the login/MFA flow (US2) to enable session creation. With sessions available, we'll implement the core background sync logic (US1). Finally, we'll add session invalidation and status checks (US3). This ensures a logical build-up of functionality.

Phase 1: Foundational Setup

Goal: Prepare the database schema and core data structures. This phase must be completed before any user story implementation can begin.

T001: [DB Model] Define the GarminAuthenticationState SQLAlchemy model in a new file src/models/garmin_auth_state.py.
T002: [DB Migration] Create a new Alembic migration script to add the garmin_authentication_state table to the database.
T003: [Test] Write a unit test in tests/unit/models/test_garmin_auth_state.py to verify the model's structure and relationships. [P]
T004: [Pydantic Model] Define Pydantic schemas for API requests and responses related to authentication (Login, MFA, Status) in src/models/schemas/garmin_auth.py. [P]

User Story: A user can perform a one-time login, handle an MFA challenge, and have their session persisted. Independent Test: A user can log in via the API, enter an MFA code when prompted, and a valid session will be stored in the database, verifiable by checking the garmin_authentication_state table.

T005: [Test] Create an API test file tests/api/test_auth_api.py with tests for the POST /login and POST /mfa endpoints, covering success, MFA required, and failure cases.
T006: [Service] Create a new service src/services/garmin_auth_service.py containing the business logic for logging in, handling MFA, and saving the session to the database using garth.
T007: [API Endpoint] Create a new API router in src/api/v1/auth.py. Implement the POST /api/v1/garmin/session/login endpoint, calling the auth service.
T008: [API Endpoint] Implement the POST /api/v1/garmin/session/mfa endpoint in src/api/v1/auth.py, calling the auth service.
T009: [Test] Write unit tests in tests/unit/services/test_garmin_auth_service.py to mock garth and the database, verifying the service logic for login and MFA handling. [P]

Checkpoint: User Story 2 is complete. The system can now authenticate users and persist their sessions.

Phase 3: [US1] Seamless Background Sync

User Story: Background sync jobs can run automatically using the persisted session. Independent Test: Trigger a background sync for a user with a valid persisted session. Verify that the job completes successfully without any manual intervention and that new data is fetched. Test the auto-refresh mechanism by using a slightly expired (but refreshable) mock session.

T010: [Test] Update tests for background sync services (e.g., tests/unit/services/test_activity_sync.py) to include scenarios where the service loads a session from the database.
T011: [Service] Modify the existing background sync services (e.g., GarminActivityService) to implement the "Load-Use-Update" pattern:
- Load the GarminAuthenticationState from the DB.
- Initialize garth with the session data.
- Perform the sync.
- If the session was refreshed by garth, update the session_data and last_validated fields in the database.

Checkpoint: User Story 1 is complete. The system can now perform its core function of stateless, automated synchronization.

Phase 4: [US3] Session Invalidation and Status

User Story: The system can detect an invalid session, report it, and allow a client to check the session's status. Independent Test: For a user with a persisted session, manually invalidate it. Trigger a sync and verify the job status becomes AUTH_EXPIRED and the session data is cleared from the DB. Also, call the GET /status endpoint before and after to see the status change.

T012: [Test] Add API tests to tests/api/test_auth_api.py for the GET /status endpoint.
T013: [API Endpoint] Implement the GET /api/v1/garmin/session/status endpoint in src/api/v1/auth.py. The endpoint should use the auth service to validate the token. [P]
T014: [Test] Add unit tests to tests/unit/services/test_garmin_auth_service.py for the session validation logic.
T015: [Service] Add a get_session_status method to src/services/garmin_auth_service.py that performs a lightweight check on the session.
T016: [Service] Enhance the error handling in background sync services. If a sync fails with an unrecoverable auth error, the service must call a method in the auth service to clear the session_data from the database.

Checkpoint: User Story 3 is complete. The system is now resilient to session invalidation.

Phase 5: Polish & Integration

T017: [Documentation] Update the main README.md and any relevant developer docs to explain the new authentication flow.
T018: [CI/CD] Ensure all new tests are integrated into the CI pipeline and that all pre-commit hooks pass.

Dependencies

graph TD
    subgraph Phase 1 [Foundational]
        T001(DB Model) --> T002(DB Migration);
        T003(Test Model);
        T004(Pydantic Model);
    end

    subgraph Phase 2 [US2 - Login/MFA]
        T005(API Tests) --> T007(Login Endpoint);
        T007 --> T008(MFA Endpoint);
        T009(Unit Tests) --> T006(Auth Service);
        T007 & T008 --> T006;
    end

    subgraph Phase 3 [US1 - Background Sync]
        T010(Sync Tests) --> T011(Update Sync Service);
    end

    subgraph Phase 4 [US3 - Invalidation]
        T012(Status API Test) --> T013(Status Endpoint);
        T014(Status Unit Test) --> T015(Status Service Logic);
        T013 --> T015;
        T011 --> T016(Enhance Error Handling);
    end

    Phase 1 --> Phase 2;
    Phase 2 --> Phase 3;
    Phase 3 --> Phase 4;
    Phase 4 --> T017(Docs) & T018(CI/CD);

Parallel Execution Examples

Within Phase 1: T003 and T004 can be done in parallel while T001 and T002 are being worked on sequentially.
Within Phase 2: The API tests (T005) and unit tests (T009) can be developed in parallel before the service (T006) and endpoints (T007, T008) are implemented.
Within Phase 4: The status endpoint (T012-T015) can be developed in parallel with the error handling enhancements for the sync service (T016).

6.8 KiB Raw Blame History