FitTrack_ReportGenerator/specs/002-feature-use-centraldb/spec.md

# 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%.