FitTrack_ReportGenerator/specs/001-create-a-new/tasks.md

Tasks: Initial Spec

Feature Branch: 001-create-a-new Date: 2025-10-09 Spec: /home/sstent/Projects/FitTrack_ReportGenerator/specs/001-create-a-new/spec.md

Summary

This document outlines the tasks required to implement the "Initial Spec" feature, which involves analyzing workout files, generating reports and charts, and exposing this functionality via a REST API.

Phase 1: Setup and Project Initialization

Goal: Establish the basic project structure, environment, and initial configurations.

• T001: Initialize Python project with pyproject.toml and create a virtual environment. (src/)
• T002: Create src/core, src/db, src/utils, api/, api/routers, tests/unit, tests/integration, tests/contract directories. (src/, api/, tests/)
• T003: Configure pytest for testing. (pyproject.toml)
• T004: Add initial requirements.txt with FastAPI, pandas, numpy, scipy, matplotlib, fitparse, tcxparser, gpxpy, psycopg2-binary (for PostgreSQL). (requirements.txt)
• T005: Implement basic FastAPI application in api/main.py with a root endpoint. (api/main.py)
• T006: Set up Dockerfile for the application. (Dockerfile)

Phase 2: Foundational Components

Goal: Implement core, reusable components that are prerequisites for all user stories.

• T007: Implement src/db/models.py for User and WorkoutAnalysis entities based on data-model.md. (src/db/models.py)
• T008: Implement database connection and session management in src/db/session.py. (src/db/session.py)
• T009: Implement src/utils/zone_calculator.py for calculating power and heart rate zones. (src/utils/zone_calculator.py)
• T010: Implement base classes/interfaces for file parsing in src/core/file_parser.py (e.g., FitParser, TcxParser, GpxParser). (src/core/file_parser.py)
• T011: Implement src/core/workout_data.py for WorkoutData, WorkoutMetadata, PowerData, HeartRateData objects. (src/core/workout_data.py)

Phase 3: User Story 1 - Analyze a single workout file (P1)

Goal: Enable users to upload a single workout file and receive a comprehensive analysis report.

Independent Test Criteria: Provide a single workout file and verify that a complete report is generated with all expected metrics and charts.

• T012 [US1]: Write unit tests for FitParser to ensure correct parsing of FIT files. (tests/unit/test_fit_parser.py)
• T013 [US1]: Implement FitParser in src/core/file_parser.py to parse FIT files (FR-001). (src/core/file_parser.py)
• T014 [US1]: Write unit tests for TcxParser to ensure correct parsing of TCX files. (tests/unit/test_tcx_parser.py)
• T015 [US1]: Implement TcxParser in src/core/file_parser.py to parse TCX files (FR-001). (src/core/file_parser.py)
• T016 [US1]: Write unit tests for GpxParser to ensure correct parsing of GPX files. (tests/unit/test_gpx_parser.py)
• T017 [US1]: Implement GpxParser in src/core/file_parser.py to parse GPX files (FR-001). (src/core/file_parser.py)
• T018 [US1]: Write unit tests for WorkoutData and related data objects (PowerData, HeartRateData). (tests/unit/test_workout_data.py)
• T019 [US1]: Implement src/core/workout_analyzer.py to calculate summary metrics (FR-002). (src/core/workout_analyzer.py)
• T020 [US1]: Implement detailed power analysis (NP, IF, TSS, zones) in src/core/workout_analyzer.py (FR-003). (src/core/workout_analyzer.py)
• T021 [US1]: Implement detailed heart rate analysis (zones) in src/core/workout_analyzer.py (FR-004). (src/core/workout_analyzer.py)
• T022 [US1]: Implement detailed speed analysis (zones) in src/core/workout_analyzer.py (FR-005). (src/core/workout_analyzer.py)
• T023 [US1]: Implement elevation analysis in src/core/workout_analyzer.py (FR-006). (src/core/workout_analyzer.py)
• T024 [US1]: Implement high-intensity interval detection in src/core/workout_analyzer.py (FR-007). (src/core/workout_analyzer.py)
• T025 [US1]: Implement efficiency metrics calculation in src/core/workout_analyzer.py (FR-008). (src/core/workout_analyzer.py)
• T026 [US1]: Implement power estimation when not present in source file in src/core/workout_analyzer.py (FR-009). (src/core/workout_analyzer.py)
• T027 [US1]: Implement gear usage analysis for single-speed bicycles in src/core/workout_analyzer.py (FR-010). (src/core/workout_analyzer.py)
• T028 [US1]: Implement report generation (HTML, PDF, Markdown) in src/core/report_generator.py (FR-011). (src/core/report_generator.py)
• T029 [US1]: Write contract tests for POST /api/analyze/workout endpoint. (tests/contract/test_analyze_workout_api.py)
• T030 [US1]: Implement POST /api/analyze/workout endpoint in api/routers/analysis.py (FR-013). (api/routers/analysis.py)
• T031 [US1]: Implement error handling for corrupted/malformed files (Edge Case). (api/routers/analysis.py, src/core/file_parser.py)
• T032 [US1]: Implement handling for missing data streams (Edge Case). (src/core/workout_analyzer.py)
• T033 [US1]: Implement detection and flagging of data spikes (Edge Case). (src/core/workout_analyzer.py)
• T034 [US1]: Implement GET /api/analysis/{id}/summary endpoint in api/routers/analysis.py (FR-016). (api/routers/analysis.py)
• T035 [US1]: Ensure FTP configuration is used for calculations (FR-018, FR-019). (src/core/workout_analyzer.py, api/routers/analysis.py)

Checkpoint: Single workout analysis and summary retrieval are functional and tested.

Phase 4: User Story 2 - Generate specific charts for a workout (P2)

Goal: Allow developers to request specific visualizations for an analyzed workout via an API.

Independent Test Criteria: Call an API endpoint with a workout ID and chart type, and verify that the correct chart image is returned.

• T036 [US2]: Write unit tests for chart generation logic. (tests/unit/test_chart_generator.py)
• T037 [US2]: Implement chart generation (power curves, elevation profiles, zone distribution) in src/core/chart_generator.py (FR-012). (src/core/chart_generator.py)
• T038 [US2]: Write contract tests for GET /api/analysis/{id}/charts endpoint. (tests/contract/test_charts_api.py)
• T039 [US2]: Implement GET /api/analysis/{id}/charts endpoint in api/routers/analysis.py (FR-015). (api/routers/analysis.py)

Checkpoint: Chart generation and retrieval are functional and tested.

Phase 5: User Story 3 - Batch analyze multiple workout files (P3)

Goal: Enable coaches to upload a directory of workout files for batch analysis and receive a summary report.

Independent Test Criteria: Provide a directory of workout files and verify that a batch analysis is performed and a summary CSV file is generated.

• T040 [US3]: Write unit tests for batch processing logic. (tests/unit/test_batch_processor.py)
• T041 [US3]: Implement batch processing logic in src/core/batch_processor.py to handle zip files and process multiple workouts. (src/core/batch_processor.py)
• T042 [US3]: Implement summary report generation for batch analysis (e.g., CSV) in src/core/report_generator.py. (src/core/report_generator.py)
• T043 [US3]: Write contract tests for POST /api/analyze/batch endpoint. (tests/contract/test_batch_analysis_api.py)
• T044 [US3]: Implement POST /api/analyze/batch endpoint in api/routers/analysis.py (FR-014). (api/routers/analysis.py)

Checkpoint: Batch analysis is functional and tested.

Phase 6: Polish & Cross-Cutting Concerns

Goal: Address remaining cross-cutting concerns and ensure overall quality.

• T045: Implement structured logging across the application. (src/, api/)
• T046: Review and refine error handling mechanisms for all API endpoints. (api/routers/analysis.py)
• T047: Ensure all API endpoints are publicly accessible (FR-017). (api/main.py, deployment config)
• T048: Conduct performance testing to meet SC-002 and SC-004. (tests/performance/)
• T049: Review and optimize database interactions. (src/db/)
• T050: Update plan.md with the final project structure. (specs/001-create-a-new/plan.md)

Dependencies

• Phase 1 must be completed before Phase 2.
• Phase 2 must be completed before Phase 3, Phase 4, and Phase 5.
• Phase 3, Phase 4, and Phase 5 can be developed in parallel after Phase 2, but are ordered by priority.
• Phase 6 can begin once all other phases are functionally complete.

Parallel Execution Examples

User Story 1 (P1)

• T012 [P]: Write unit tests for FitParser
• T014 [P]: Write unit tests for TcxParser
• T016 [P]: Write unit tests for GpxParser
• T018 [P]: Write unit tests for WorkoutData
• T029 [P]: Write contract tests for POST /api/analyze/workout

User Story 2 (P2)

• T036 [P]: Write unit tests for chart generation logic
• T038 [P]: Write contract tests for GET /api/analysis/{id}/charts

User Story 3 (P3)

• T040 [P]: Write unit tests for batch processing logic
• T043 [P]: Write contract tests for POST /api/analyze/batch

Implementation Strategy

We will adopt an incremental delivery approach, prioritizing User Story 1 (single workout analysis) as the Minimum Viable Product (MVP). Subsequent user stories will be developed and integrated in priority order. Each user story will be developed using a test-driven development (TDD) approach, ensuring that tests are written before implementation. Foundational components will be established first to provide a stable base for feature development.