# Tasks: Fitbit/Garmin Data Sync **Input**: Design documents from `specs/002-fitbit-garmin-sync/` **Prerequisites**: plan.md (required), spec.md (required for user stories), research.md, data-model.md, contracts/ **Tests**: Tests are included based on the TDD principle mentioned in the constitution. **Organization**: Tasks are grouped by user story to enable independent implementation and testing of each story. ## Format: `[ID] [P?] [Story] Description` - **[P]**: Can run in parallel (different files, no dependencies) - **[Story]**: Which user story this task belongs to (e.g., US1, US2, US3) - Include exact file paths in descriptions ## Path Conventions - Paths shown below assume single project - adjust based on plan.md structure ## Phase 1: Setup (Shared Infrastructure) **Purpose**: Project initialization and basic structure - [X] T001 Review `sync_app.py` in `backend/src/services/sync_app.py` - [X] T002 Review `garmin/client.py` in `backend/src/services/garmin/client.py` --- ## Phase 2: Foundational (Blocking Prerequisites) **Purpose**: Core infrastructure that MUST be complete before ANY user story can be implemented **⚠️ CRITICAL**: No user story work can begin until this phase is complete - [X] T003 Add error handling to all endpoints in `backend/src/api/` - [X] T004 Add logging at key points in `backend/src/api/` and `backend/src/services/` - [X] T005 Add missing imports for API Token, SyncApp, GarminClient, setup_logger to `backend/src/api/sync.py` - [X] T006 Add missing imports for Response, Activity to `backend/src/api/activities.py` - [X] T007 Add missing imports for func, HealthMetric to `backend/src/api/metrics.py` **Checkpoint**: Foundation ready - user story implementation can now begin in parallel --- ## Phase 3: User Story 1 - Sync Activities from Garmin (Priority: P1) 🎯 MVP **Goal**: Users can trigger a synchronization of their recent activities from their Garmin account so that their fitness data is stored and available within the application. **Independent Test**: Trigger a sync and verify recent activities appear in the activity list. Also, verify error message when Garmin account is not connected. ### Tests for User Story 1 - [ ] T008 [US1] Write unit tests for `POST /api/sync/activities` endpoint in `backend/tests/unit/test_api/test_sync.py` - [ ] T009 [US1] Write integration tests for activity sync flow in `backend/tests/integration/test_sync_flow.py` ### Implementation for User Story 1 - [X] T010 [US1] Implement activity sync logic in `backend/src/api/sync.py` (replace mock response with actual sync logic) - [X] T011 [US1] Implement `sync_activities` method in `backend/src/services/sync_app.py` to use `GarminClient` **Checkpoint**: At this point, User Story 1 should be fully functional and testable independently --- ## Phase 4: User Story 3 - Sync Health Metrics from Garmin (Priority: P1) **Goal**: Users can trigger a synchronization of their daily health metrics (like steps and HRV) from their Garmin account to track their wellness over time. **Independent Test**: Trigger a metric sync and see updated data in their health dashboard or metric query views. ### Tests for User Story 3 - [ ] T012 [US3] Write unit tests for `POST /api/sync/metrics` endpoint in `backend/tests/unit/test_api/test_sync.py` - [ ] T013 [US3] Write integration tests for health metrics sync flow in `backend/tests/integration/test_sync_flow.py` ### Implementation for User Story 3 - [X] T014 [US3] Create `POST /api/sync/metrics` endpoint in `backend/src/api/sync.py` - [X] T015 [US3] Implement `sync_health_metrics` method in `backend/src/services/sync_app.py` to use `garth` library **Checkpoint**: At this point, User Stories 1 AND 3 should both work independently --- ## Phase 5: User Story 2 - View and Query Activities (Priority: P2) **Goal**: Users can list their synced activities, filter them by criteria like activity type and date, and download the original activity file for their records. **Independent Test**: Navigate to the activity list, apply filters, and attempt to download a file. ### Tests for User Story 2 - [ ] T016 [US2] Write unit tests for `GET /api/activities/list` endpoint in `backend/tests/unit/test_api/test_activities.py` - [ ] T017 [US2] Write unit tests for `GET /api/activities/query` endpoint in `backend/tests/unit/test_api/test_activities.py` - [ ] T018 [US2] Write unit tests for `GET /api/activities/download/{activity_id}` endpoint in `backend/tests/unit/test_api/test_activities.py` ### Implementation for User Story 2 - [X] T019 [US2] Implement `list_activities` endpoint logic in `backend/src/api/activities.py` - [X] T020 [US2] Implement `query_activities` endpoint logic in `backend/src/api/activities.py` - [X] T021 [US2] Implement `download_activity` endpoint logic in `backend/src/api/activities.py` **Checkpoint**: At this point, User Stories 1, 3 and 2 should all work independently --- ## Phase 6: User Story 4 - View and Query Health Metrics (Priority: P2) **Goal**: Users can see a list of all the metric types they've synced, query their data for specific time ranges, and view a high-level summary. **Independent Test**: Navigate to the metrics section, select a metric type and date range, and view the resulting data and summary. ### Tests for User Story 4 - [ ] T022 [US4] Write unit tests for `GET /api/metrics/list` endpoint in `backend/tests/unit/test_api/test_metrics.py` - [ ] T023 [US4] Write unit tests for `GET /api/metrics/query` endpoint in `backend/tests/unit/test_api/test_metrics.py` - [ ] T024 [US4] Write unit tests for `GET /api/health-data/summary` endpoint in `backend/tests/unit/test_api/test_metrics.py` ### Implementation for User Story 4 - [X] T025 [US4] Implement `list_available_metrics` endpoint logic in `backend/src/api/metrics.py` - [X] T026 [US4] Implement `query_metrics` endpoint logic in `backend/src/api/metrics.py` - [X] T027 [US4] Implement `get_health_summary` endpoint logic in `backend/src/api/metrics.py` **Checkpoint**: All user stories should now be independently functional --- ## Phase 7: Polish & Cross-Cutting Concerns **Purpose**: Improvements that affect multiple user stories - [X] T028 Review error handling across all new endpoints in `backend/src/api/` - [X] T029 Review logging implementation across `backend/src/api/` and `backend/src/services/` - [X] T030 Add/update documentation for new API endpoints (e.g., OpenAPI spec, inline comments) in `specs/002-fitbit-garmin-sync/contracts/api-contract.yaml` and relevant Python files. - [X] T031 Run quickstart.md validation as described in `specs/002-fitbit-garmin-sync/quickstart.md` --- ## Dependencies & Execution Order ### Phase Dependencies - **Setup (Phase 1)**: No dependencies - can start immediately - **Foundational (Phase 2)**: Depends on Setup completion - BLOCKS all user stories - **User Stories (Phase 3+)**: All depend on Foundational phase completion - User stories can then proceed in parallel (if staffed) - Or sequentially in priority order (P1 → P1 → P2 → P2) - **Polish (Final Phase)**: Depends on all desired user stories being complete ### User Story Dependencies - **User Story 1 (P1)**: Can start after Foundational (Phase 2) - No dependencies on other stories - **User Story 3 (P1)**: Can start after Foundational (Phase 2) - No dependencies on other stories - **User Story 2 (P2)**: Can start after Foundational (Phase 2) - May integrate with US1 but should be independently testable - **User Story 4 (P2)**: Can start after Foundational (Phase 2) - May integrate with US1/US3/US2 but should be independently testable ### Within Each User Story - Tests MUST be written and FAIL before implementation - Models before services (where applicable) - Services before endpoints (where applicable) - Core implementation before integration - Story complete before moving to next priority ### Parallel Opportunities - All Setup tasks can run in parallel. - All Foundational tasks can run in parallel (within Phase 2). - Once Foundational phase completes, user stories can start in parallel by different team members. - Tests for a user story can run in parallel. - Implementation tasks within a user story can be identified for parallel execution where there are no dependencies. ## Implementation Strategy ### MVP First (User Stories 1 & 3) 1. Complete Phase 1: Setup 2. Complete Phase 2: Foundational (CRITICAL - blocks all stories) 3. Complete Phase 3: User Story 1 4. Complete Phase 4: User Story 3 5. **STOP and VALIDATE**: Test User Stories 1 and 3 independently. 6. Deploy/demo if ready ### Incremental Delivery 1. Complete Setup + Foundational → Foundation ready 2. Add User Story 1 → Test independently → Deploy/Demo (MVP!) 3. Add User Story 3 → Test independently → Deploy/Demo 4. Add User Story 2 → Test independently → Deploy/Demo 5. Add User Story 4 → Test independently → Deploy/Demo 6. Each story adds value without breaking previous stories ### Parallel Team Strategy With multiple developers: 1. Team completes Setup + Foundational together 2. Once Foundational is done: - Developer A: User Story 1 - Developer B: User Story 3 - Developer C: User Story 2 - Developer D: User Story 4 3. Stories complete and integrate independently --- ## Notes - Tasks with file paths indicate specific files to be created or modified. - Each user story should be independently completable and testable. - Verify tests fail before implementing. - Commit after each task or logical group. - Stop at any checkpoint to validate story independently. - Avoid: vague tasks, same file conflicts, cross-story dependencies that break independence