sync

specs/002-feature-use-centraldb/plan.md

@@ -0,0 +1,105 @@
+# Implementation Plan: [FEATURE]
+
+**Branch**: `[###-feature-name]` | **Date**: [DATE] | **Spec**: [link]
+**Input**: Feature specification from `/specs/[###-feature-name]/spec.md`
+
+**Note**: This template is filled in by the `/speckit.plan` command. See `.specify/templates/commands/plan.md` for the execution workflow.
+
+## Summary
+
+This feature updates the GET /api/analysis/{analysis_id}/charts and GET /api/analysis/{analysis_id}/summary endpoints to automatically fetch and analyze workout files from a CentralDB.
+
+## Technical Context
+
+<!--
+  ACTION REQUIRED: Replace the content in this section with the technical details
+  for the project. The structure here is presented in advisory capacity to guide
+  the iteration process.
+-->
+
+**Language/Version**: Python 3.11  
+**Primary Dependencies**: FastAPI, pandas, numpy, scipy, matplotlib, fitparse, tcxparser, gpxpy, requests  
+**Storage**: Ephemeral in-memory cache (last 5), CentralDB (long-term)  
+**Testing**: pytest  
+**Target Platform**: Linux server
+**Project Type**: web  
+**Performance Goals**: 95% of cached requests < 500ms; new analyses < 45s for a 2-hour workout.  
+**Constraints**: `analysis_id` must match CentralDB activity ID.  
+**Scale/Scope**: 50 concurrent analysis requests.
+
+## Constitution Check
+
+*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
+
+| Principle | Status | Justification (if violation) |
+|---|---|---|
+| I. Library-First | Aligned | The new functionality will be part of the existing library structure. |
+| II. CLI Interface | VIOLATION | The feature is API-only, which is the primary interface for this web service. |
+| III. Test-First (NON-NEGOTIABLE) | Aligned | The spec has acceptance scenarios that can be tested first. |
+| IV. Integration Testing | Aligned | The feature requires integration with CentralDB. |
+| V. Observability | Aligned | No new observability requirements for this feature. |
+| VI. Versioning & Breaking Changes | Aligned | No breaking changes are expected. |
+| VII. Simplicity | Aligned | The feature simplifies the user workflow by removing the need for manual file uploads. |
+
+## Project Structure
+
+### Documentation (this feature)
+
+```
+specs/[###-feature]/
+├── plan.md              # This file (/speckit.plan command output)
+├── research.md          # Phase 0 output (/speckit.plan command)
+├── data-model.md        # Phase 1 output (/speckit.plan command)
+├── quickstart.md        # Phase 1 output (/speckit.plan command)
+├── contracts/           # Phase 1 output (/speckit.plan command)
+└── tasks.md             # Phase 2 output (/speckit.tasks command - NOT created by /speckit.plan)
+```
+
+### Source Code (repository root)
+<!--
+  ACTION REQUIRED: Replace the placeholder tree below with the concrete layout
+  for this feature. Delete unused options and expand the chosen structure with
+  real paths (e.g., apps/admin, packages/something). The delivered plan must
+  not include Option labels.
+-->
+
+```
+src/
+├── core/
+│   ├── batch_processor.py
+│   ├── chart_generator.py
+│   ├── file_parser.py
+│   ├── logger.py
+│   ├── report_generator.py
+│   ├── workout_analyzer.py
+│   └── workout_data.py
+├── db/
+│   ├── models.py
+│   └── session.py
+└── utils/
+    └── zone_calculator.py
+
+api/
+├── routers/
+│   └── analysis.py
+├── main.py
+└── schemas.py
+
+tests/
+├── unit/
+├── integration/
+├── contract/
+└── performance/
+```
+
+**Structure Decision**: The project will continue to use the existing structure, which separates the core logic, API, and tests into `src`, `api`, and `tests` directories respectively.
+
+## Complexity Tracking
+
+*Fill ONLY if Constitution Check has violations that must be justified*
+
+| Violation | Why Needed | Simpler Alternative Rejected Because |
+|-----------|------------|-------------------------------------|
+| Violation | Why Needed | Simpler Alternative Rejected Because |
+|---|---|---|
+| II. CLI Interface | The primary interface for this feature is a REST API, as it is extending an existing web service. | A CLI is not the primary interface for this service and would add unnecessary complexity at this stage. |