# Tasks: IntialSpecV2 **Input**: Design documents from `/specs/002-intialspecv2/` **Prerequisites**: plan.md (required), spec.md (required for user stories), research.md, contracts/ **Tests**: The examples below include test tasks. Tests are OPTIONAL - only include them if explicitly requested in the feature specification. **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 - **Web app**: `backend/src/`, `frontend/src/` ## Phase 1: Setup (Shared Infrastructure) **Purpose**: Project initialization and basic structure - [X] T001 Create project structure (`backend/`, `frontend/`, `tests/`) - [X] T002 Initialize Python backend project with dependencies (FastAPI, `garth`, `garminconnect`) in `backend/` - [X] T003 [P] Configure linting and formatting tools for Python in `backend/` - [X] T004 [P] Setup Docker and Docker Compose for development environment --- ## 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] T005 Setup CentralDB integration (FR-016, FR-017) - [X] Define CentralDB client/SDK generation from `DB_API_SPEC.json` - [X] Implement CentralDB client in `backend/src/services/central_db_service.py` - [X] T007 Implement authentication/authorization framework (FR-001, FR-012) - [X] Create User authentication service in `backend/src/services/auth_service.py` to use CentralDB for authentication - [X] Implement Garmin Connect authentication flow using `garth` and `garminconnect` (FR-019) - [X] T008 Setup API routing and middleware structure (FR-013: default to port 8001) - [X] Create basic FastAPI application setup in `backend/src/main.py` - [X] Implement configuration management (YAML/Environment variables) (FR-014) - [X] T009 Configure error handling and logging infrastructure (FR-010) - [X] T010 Implement in-memory background job processing mechanism (FR-008) - [X] T011 Implement rate limiting for external API calls (FR-009) - [X] T012 Integrate `garth` and `garminconnect` libraries (FR-019) - [X] T013 Reuse code/logic from @GarminAnalyser.md (FR-015) **Checkpoint**: Foundation ready - user story implementation can now begin in parallel --- ## Phase 3: User Story 1 - Garmin Connect Activity Synchronization (Priority: P1) 🎯 MVP **Goal**: Synchronize Garmin Connect activities and store them as FIT/GPX/TCX files in CentralDB. **Independent Test**: Authenticate with Garmin Connect, trigger an activity sync via `POST /api/sync/garmin/activities`, and then verify that activity files are correctly stored in CentralDB, with only new or updated activities downloaded. ### Implementation for User Story 1 - [X] T015 [P] [US1] Define `SyncJob` Pydantic model for in-memory job tracking - [X] T016 [US1] Implement Garmin Activity Service for downloading activities (`backend/src/services/garmin_activity_service.py`) (FR-002) - [X] T017 [US1] Implement CentralDB storage for activity files (`backend/src/services/central_db_service.py`) (FR-003) - [X] T018 [US1] Implement activity synchronization logic (handling new/updated activities) (FR-002) - [X] T019 [US1] Create `POST /api/sync/garmin/activities` endpoint (`backend/src/api/garmin_sync.py`) (FR-006) - [X] T020 [US1] Implement background job for activity synchronization (FR-008) - [X] T021 [US1] Add error handling and retry logic for activity sync (FR-010) - [X] T022 [US1] Update in-memory `SyncJob` status and details (FR-011) **Checkpoint**: At this point, User Story 1 should be fully functional and testable independently --- ## Phase 4: User Story 2 - Garmin Connect Health Metrics Synchronization (Priority: P2) **Goal**: Synchronize Garmin Connect health metrics and store them in CentralDB. **Independent Test**: Authenticate with Garmin Connect, trigger a sync, and verify that health metrics (e.g., heart rate, sleep data) are correctly synchronized and stored in CentralDB. ### Implementation for User Story 2 - [X] T024 [US2] Implement Garmin Health Metrics Service for downloading metrics (`backend/src/services/garmin_health_service.py`) (FR-004) - [X] T025 [US2] Implement CentralDB storage for health metrics (`backend/src/services/central_db_service.py`) (FR-004) - [X] T026 [US2] Implement health metrics synchronization logic - [X] T027 [US2] Integrate health metrics sync into in-memory `SyncJob` mechanism - [X] T028 [US2] Add error handling and retry logic for health metrics sync (FR-010) **Checkpoint**: At this point, User Stories 1 AND 2 should both work independently --- ## Phase 5: User Story 3 - Garmin Workout Upload (Priority: P2) **Goal**: Allow users to upload workouts from the application to Garmin Connect. **Independent Test**: Create a workout in the application, initiate its upload to Garmin Connect, and then verify that the workout appears correctly on the user's Garmin Connect account. ### Implementation for User Story 3 - [X] T030 [US3] Implement Garmin Workout Service for uploading workouts (`backend/src/services/garmin_workout_service.py`) (FR-005) - [X] T031 [US3] Create `POST /api/sync/garmin/workouts` endpoint (`backend/src/api/garmin_sync.py`) (FR-005) - [X] T032 [US3] Implement background job for workout upload (FR-008) - [X] T033 [US3] Add error handling and retry logic for workout upload (FR-010) - [X] T034 [US3] Update in-memory `SyncJob` status and details for workout uploads **Checkpoint**: All user stories should now be independently functional --- ## Phase 6: User Story 4 - Check Sync Status (Priority: P3) **Goal**: Provide essential feedback to the user on ongoing and completed synchronization operations. **Independent Test**: Trigger a synchronization process, then query the `/api/sync/status` endpoint to verify that it accurately reflects the ongoing or completed status of the sync. ### Implementation for User Story 4 - [X] T035 [US4] Implement `SyncStatusService` to query in-memory `SyncJob` records (`backend/src/services/sync_status_service.py`) - [X] T036 [US4] Create `GET /api/sync/status` endpoint (`backend/src/api/garmin_sync.py`) (FR-007) - [X] T037 [US4] Format and return synchronization status, progress, and error details --- ## Phase N: Polish & Cross-Cutting Concerns **Purpose**: Improvements that affect multiple user stories - [X] T038 [P] Documentation updates in `specs/002-intialspecv2/` (e.g., `quickstart.md` for new features) - [X] T039 Code cleanup and refactoring across services and API endpoints - [X] T040 Performance optimization (e.g., for large data syncs) - [X] T041 [P] Additional unit tests for new services and utilities in `backend/tests/unit/` - [X] T042 Security hardening (e.g., validation rules) - [X] T043 Run `quickstart.md` validation and update as necessary - [X] T044 Implement `auth_token` and `refresh_token` management (refreshing tokens before expiry) --- ## 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 → P2 → P3) - **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 2 (P2)**: Can start after Foundational (Phase 2) - May integrate with US1 but should be independently testable - **User Story 3 (P3)**: Can start after Foundational (Phase 2) - May integrate with US1/US2 but should be independently testable - **User Story 4 (P3)**: Can start after Foundational (Phase 2) - Depends on SyncJob from US1/US2/US3 to provide status ### Within Each User Story - Tests (if included) MUST be written and FAIL before implementation - Services before endpoints - Core implementation before integration - Story complete before moving to next priority ### Parallel Opportunities - All Setup tasks marked [P] can run in parallel - All Foundational tasks marked [P] can run in parallel (within Phase 2) - Once Foundational phase completes, all user stories can start in parallel (if team capacity allows) - All tests for a user story marked [P] can run in parallel - Models within a story marked [P] can run in parallel - Different user stories can be worked on in parallel by different team members --- ## Implementation Strategy ### MVP First (User Story 1 Only) 1. Complete Phase 1: Setup 2. Complete Phase 2: Foundational (CRITICAL - blocks all stories) 3. Complete Phase 3: User Story 1 4. **STOP and VALIDATE**: Test User Story 1 independently 5. 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 2 → Test independently → Deploy/Demo 4. Add User Story 3 → 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 2 - Developer C: User Story 3 - Developer D: User Story 4 3. Stories complete and integrate independently --- ## Notes - [P] tasks = different files, no dependencies - [Story] label maps task to specific user story for traceability - 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