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