FitTrack_GarminSync/specs/005-ensure-the-current/spec.md

# Feature Specification: Code Alignment and Documentation Cleanup

**Feature Branch**: `005-ensure-the-current`  
**Created**: Saturday, October 18, 2025  
**Status**: Draft  
**Input**: User description: "ensure the current code aligns to this model and it's documented. When done delete the 3 informal reference docs."

## User Scenarios & Testing *(mandatory)*

### User Story 1 - Ensure Code Alignment with CentralDB Models (Priority: P1)

As a developer, I want the application's code to accurately reflect the defined CentralDB models so that data consistency and integrity are maintained.

**Why this priority**: Ensures the core data structures are correctly implemented, which is fundamental for the application's stability and correctness.

**Independent Test**: Can be tested by reviewing the application's data access layer and model definitions against the inferred CentralDB models.

**Acceptance Scenarios**:

1.  **Given** the inferred CentralDB models, **When** I review the application's code, **Then** all relevant data structures and their interactions align with these models.

---

### User Story 2 - Document Code Alignment (Priority: P1)

As a developer, I want the code's alignment with the CentralDB models to be clearly documented so that future development and maintenance are straightforward.

**Why this priority**: Good documentation is crucial for maintainability and onboarding new developers.

**Independent Test**: Can be tested by reviewing the project's documentation (e.g., `GEMINI.md`, `README.md`, or new dedicated documentation) to confirm the code alignment is explained.

**Acceptance Scenarios**:

1.  **Given** the code is aligned with the CentralDB models, **When** I review the project documentation, **Then** the alignment is clearly described and easy to understand.

---

### User Story 3 - Remove Informal Reference Documents (Priority: P2)

As a maintainer, I want to remove outdated or informal reference documents so that the project's source of truth is clear and unambiguous.

**Why this priority**: Reduces confusion and ensures that developers refer to the correct, formal specifications.

**Independent Test**: Can be tested by verifying that the specified informal reference documents are no longer present in the repository.

**Acceptance Scenarios**:

1.  **Given** the formal specifications are established, **When** the cleanup task is performed, **Then** `data-model.md`, `DB_API_SPEC.json`, and `GARMINSYNC_SPEC.md` are deleted from the repository.

---

### Edge Cases

-   What if the current code *does not* align with the inferred CentralDB models? (Requires refactoring and updates).
-   What if there are other informal reference documents that should also be deleted? (Scope limitation).

## Requirements *(mandatory)*

### Functional Requirements

-   **FR-001**: The system MUST ensure that its internal data models and data access logic align with the CentralDB models inferred from the formal specifications.
-   **FR-002**: The system MUST have documentation that clearly describes the mapping and alignment between the application's code and the CentralDB models.
-   **FR-003**: The project MUST remove the informal reference documents: `data-model.md`, `DB_API_SPEC.json`, and `GARMINSYNC_SPEC.md`.

### Key Entities *(include if feature involves data)*

-   **CentralDB Models**: The inferred models (User, Garmin Connect Account, GarminCredentials, Activity, Health Metric, Workout) that the application's code should align with.
-   **Application Code**: The existing codebase that needs to be reviewed and potentially updated.
-   **Project Documentation**: Files (e.g., `GEMINI.md`, `README.md`) that need to be updated.

## Success Criteria *(mandatory)*

## Appendix: Inferred CentralDB Models and API Endpoints

While a dedicated CentralDB data model specification isn't explicitly in `specs/**`, the functional requirements and key entities described in `specs/001-create-from-initialspec/spec.md`, `specs/002-intialspecv2/spec.md`, and `specs/003-loginimprovements-use-the/spec.md` imply the following CentralDB models:

1.  **User**: Represents the application's user.
    *   **Mapping**: Stores basic user information and is linked to Garmin Connect Account and GarminCredentials.
2.  **Garmin Connect Account**: Stores authentication tokens and connection status for a user's Garmin account.
    *   **Mapping**: This model would hold the OAuth2 tokens and other Garmin-specific identifiers.
3.  **GarminCredentials**: Explicitly defined in `specs/003-loginimprovements-use-the/spec.md`.
    *   **Mapping**: Stores the Garmin username, plaintext password (for re-authentication), access token, access token secret, and token expiration date.
4.  **Activity**: Represents a fitness activity.
    *   **Mapping**: Stores metadata and file paths for downloaded FIT, GPX, or TCX files from Garmin Connect.
5.  **Health Metric**: Represents a health measurement.
    *   **Mapping**: Stores synchronized health data points from Garmin Connect.
6.  **Workout**: Represents a structured training plan.
    *   **Mapping**: Stores workout definitions that can be uploaded to Garmin Connect.

**Note**: The SyncJob entity, as per `specs/004-home-sstent-projects/plan.md` and `GEMINI.md`, is managed in-memory by CurrentSyncJobManager and is not a CentralDB model.

### CentralDB API Endpoints (Consumed by GarminSync Service)

Although `DB_API_SPEC.json` is a reference, the `GARMINSYNC_SPEC.md` (also a reference, but detailing consumed interfaces) provides a clear list of CentralDB HTTP interfaces that the GarminSync service interacts with. These are the endpoints you would call to store data in CentralDB:

1.  **User Management**:
    *   `POST /users`: To create a new user.
    *   `GET /users/{user_id}`: To retrieve a user by ID.
    *   `GET /users`: To retrieve a user by email (e.g., `get_user_by_email`).

2.  **Garmin Credentials Management**:
    *   `POST /garmin_credentials/{user_id}`: To create new Garmin credentials for a user.
    *   `PUT /garmin_credentials/{user_id}`: To update existing Garmin credentials (e.g., after token refresh).
    *   `GET /garmin_credentials/{user_id}`: To retrieve Garmin credentials for a user.

3.  **Token Management (likely for application-level tokens, not Garmin-specific OAuth tokens)**:
    *   `POST /tokens/`: To create a new token.
    *   `PUT /tokens/{user_id}`: To update a token for a user.
    *   `GET /tokens/{user_id}`: To retrieve a token for a user.

4.  **Activity Storage**:
    *   `POST /activities/{user_id}`: To upload activity files (likely multipart file upload).

5.  **Health Metric Storage**:
    *   `POST /health_metrics`: To save health metric data.

6.  **Workout Plan Retrieval (for uploading workouts)**:
    *   `GET /workout_plans/{workout_id}`: To retrieve a workout plan by ID from CentralDB before uploading it to Garmin.

### Mapping Summary

*   **Garmin Login Credentials**: Map to GarminCredentials model, stored via `POST /garmin_credentials/{user_id}` or updated via `PUT /garmin_credentials/{user_id}`.
*   **Garmin Activities**: Map to Activity model, stored via `POST /activities/{user_id}`.
*   **Garmin Health Metrics**: Map to Health Metric model, stored via `POST /health_metrics`.
*   **Workouts (from application to Garmin)**: Map to Workout model (retrieved via `GET /workout_plans/{workout_id}` from CentralDB, then uploaded to Garmin).



### Measurable Outcomes

-   **SC-001**: 100% of the application's data models and data access logic are verified to align with the CentralDB models.
-   **SC-002**: The project's documentation clearly and accurately describes the code-to-CentralDB model alignment, with no ambiguities.
-   **SC-003**: The informal reference documents (`data-model.md`, `DB_API_SPEC.json`, `GARMINSYNC_SPEC.md`) are successfully deleted from the repository.