# Feature Specification: Use CentralDB for Activities **Feature Branch**: `002-feature-use-centraldb` **Created**: 2025-10-11 **Status**: Draft **Input**: User description: "Feature: Use CentralDB for Activites. I have a CentralDB that I use to store activities. I want to update the `GET /api/analysis/{analysis_id}/charts` and `GET /api/analysis/{analysis_id}/summary` to automatically have service reach out to CentralDB download the fit file and perform the analysis. Also, we should make sure that the {analysis_id} variable we use always matches the activity ID." ## Clarifications ### Session 2025-10-11 - Q: Are the `analysis_id` and `activityID` variables interchangeable? i.e. if I know the `activity_id` can I use that in the API calls? → A: Yes, `analysis_id` and `activityID` should be treated as the same identifier. - Q: Does the CentralDB API provide an endpoint to retrieve analysis artifacts? The current spec only shows an endpoint for *creating* them. → A: No, this endpoint does not exist and needs to be created by the CentralDB team. - Q: What is the structure of the analysis artifact that will be stored? → A: A JSON object for the summary, and separate files for each chart. ## User Scenarios & Testing *(mandatory)* ### User Story 1 - Retrieve analysis from CentralDB (Priority: P1) As a user, I want to be able to retrieve analysis charts and summaries for my activities stored in CentralDB by using the activity ID, so that I don't have to manually upload the files every time. **Why this priority**: This is the core functionality of the feature and provides the main user value. **Independent Test**: A user can request a chart or a summary for an activity ID that exists in CentralDB and receive the correct analysis without having to upload the file. **Acceptance Scenarios**: 1. **Given** an activity ID that exists in CentralDB and has not been analyzed before, **When** a user requests a summary for that activity ID, **Then** the system should download the corresponding FIT file from CentralDB, perform the analysis, and return the summary. 2. **Given** an activity ID that exists in CentralDB and has been analyzed before, **When** a user requests a summary for that activity ID, **Then** the system should return the cached analysis summary without re-analyzing the file. 3. **Given** an activity ID that exists in CentralDB and has not been analyzed before, **When** a user requests a chart for that activity ID, **Then** the system should download the corresponding FIT file from CentralDB, perform the analysis, and return the chart. 4. **Given** an activity ID that exists in CentralDB and has been analyzed before, **When** a user requests a chart for that activity ID, **Then** the system should return the cached chart without re-analyzing the file. 5. **Given** an activity ID that does not exist in CentralDB, **When** a user requests a summary or a chart for that activity ID, **Then** the system should return a "not found" error. ### Edge Cases - What happens when the FIT file in CentralDB is corrupted or malformed? - How does the system handle network errors when trying to reach CentralDB? - What happens if the analysis process fails for a valid FIT file? ## Requirements *(mandatory)* ### Functional Requirements - **FR-001**: The system MUST be able to connect to the CentralDB. - **FR-002**: The `GET /api/analysis/{analysis_id}/summary` endpoint MUST be updated to accept an `analysis_id` which is the same as the `activity_id` in CentralDB. - **FR-003**: The `GET /api/analysis/{analysis_id}/charts` endpoint MUST be updated to accept an `analysis_id` which is the same as the `activity_id` in CentralDB. - **FR-004**: If an analysis for the given activity ID does not exist, the system MUST download the FIT file from CentralDB. - **FR-005**: After downloading the FIT file, the system MUST perform a workout analysis. - **FR-006**: The system MUST store the analysis results. The last 5 analysis results should be cached in local ephemeral storage. - **FR-007**: If an analysis for the given activity ID already exists, the system MUST return the stored results without re-downloading or re-analyzing the file. - **FR-008**: The system MUST handle errors gracefully, such as when an activity ID is not found in CentralDB, the FIT file is unavailable, or the analysis fails. - **FR-009**: The system MUST provide a mechanism to store the analysis results in the CentralDB. - **FR-010**: A new endpoint `GET /activities/{activity_id}/analysis` MUST be defined for the CentralDB API to retrieve analysis artifacts. - **FR-011**: The analysis artifact stored in CentralDB MUST consist of a JSON object for the summary and separate files for each chart. ### Key Entities *(include if feature involves data)* - **Activity**: Represents a workout activity stored in CentralDB. It has an ID and a corresponding FIT file. - **WorkoutAnalysis**: Represents the analysis result of an activity. It is associated with an activity ID. ### Assumptions - The API for CentralDB is defined and available for the development team. ## Success Criteria *(mandatory)* ### Measurable Outcomes - **SC-001**: 95% of requests for existing analyses should be returned in under 500ms. - **SC-002**: For new analyses, the complete process of downloading, analyzing, and returning the result should take less than 45 seconds for a typical 2-hour workout file. - **SC-003**: The system should be able to handle at least 50 concurrent analysis requests. - **SC-004**: The error rate for analysis requests should be less than 1%.