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.