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:

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

5.5 KiB Raw Permalink Blame History