FitTrack_GarminSync/specs/005-ensure-the-current/tasks.md

Tasks: Code Alignment and Documentation Cleanup

Branch: 005-ensure-the-current | Date: Saturday, October 18, 2025 | Spec: /home/sstent/Projects/FitTrack/GarminSync/specs/005-ensure-the-current/spec.md

Summary

This plan outlines the tasks to ensure the existing codebase aligns with the formally specified CentralDB models, document this alignment, and remove outdated informal reference documents.

Phase 1: Setup Tasks (Project Initialization)

• T001 Verify Python 3.13 virtual environment is set up and activated.
• T002 Verify core dependencies are installed.

Phase 2: Foundational Tasks (Blocking Prerequisites)

(No specific foundational tasks are needed for this maintenance feature.)

Phase 3: User Story 1 - Ensure Code Alignment with CentralDB Models (Priority: P1) 🎯 MVP

Goal: The application's code accurately reflects the defined CentralDB models so that data consistency and integrity are maintained.

Independent Test: Review the application's data access layer and model definitions against the inferred CentralDB models.

Implementation for User Story 1

• T003 [US1] Review backend/src/models/ to ensure CentralDB models (User, Garmin Connect Account, GarminCredentials, Activity, Health Metric, Workout) are accurately represented.
• T004 [US1] Review backend/src/services/central_db_service.py to ensure data access logic aligns with CentralDB models and API endpoints.
• T005 [US1] Review backend/src/api/ endpoints to ensure data handling aligns with CentralDB models.
• T006 [US1] (Optional) Write unit tests for data model alignment in backend/tests/unit/ if existing tests are insufficient.

Checkpoint: At this point, the code alignment should be verified.

Phase 4: User Story 2 - Document Code Alignment (Priority: P1)

Goal: The code's alignment with the CentralDB models is clearly documented so that future development and maintenance are straightforward.

Independent Test: Review the project's documentation to confirm the code alignment is explained.

Implementation for User Story 2

• T007 [US2] Update GEMINI.md to include the "Inferred CentralDB Models and API Endpoints" from the spec.md appendix.
• T008 [US2] Update README.md or create a new dedicated documentation file to clearly describe the mapping and alignment between the application's code and the CentralDB models.

Checkpoint: At this point, the code alignment should be documented.

Phase 5: User Story 3 - Remove Informal Reference Documents (Priority: P2)

Goal: Outdated or informal reference documents are removed so that the project's source of truth is clear and unambiguous.

Independent Test: Verify that the specified informal reference documents are no longer present in the repository.

Implementation for User Story 3

• T009 [US3] Delete data-model.md from the project root.
• T010 [US3] Delete DB_API_SPEC.json from the project root.
• T011 [US3] Delete GARMINSYNC_SPEC.md from the project root.

Checkpoint: At this point, the informal reference documents should be removed.

Final Phase: Polish & Cross-Cutting Concerns

• T012 Run project linters and formatters (black, flake8, mypy, isort).
• T013 Run all existing tests to ensure no regressions.
• T014 Verify all tasks are completed and the spec's success criteria are met.

Dependencies & Execution Order

Phase Dependencies

• Setup (Phase 1): No dependencies.
• Foundational (Phase 2): No dependencies.
• User Story 1 (Phase 3): Depends on Setup completion.
• User Story 2 (Phase 4): Depends on User Story 1 completion.
• User Story 3 (Phase 5): Can run in parallel with User Story 2, but after User Story 1.
• Polish (Final Phase): Depends on all user stories being complete.

User Story Dependencies

• User Story 1 (P1): No dependencies on other stories.
• User Story 2 (P1): Depends on User Story 1 completion.
• User Story 3 (P2): Can run in parallel with User Story 2, but after User Story 1.

Within Each User Story

• Tasks within each user story should generally be executed sequentially, unless marked [P] for parallel.

Parallel Opportunities

• Tasks T007 and T008 (User Story 2) can be executed in parallel.
• Tasks T009, T010, T011 (User Story 3) can be executed in parallel.

Implementation Strategy

We will follow an incremental delivery approach, completing User Story 1 first to ensure code alignment, then User Story 2 for documentation, and finally User Story 3 for cleanup. The final phase will involve general polish and verification.