mirror of
https://github.com/sstent/FitTrack_GarminSync.git
synced 2026-01-25 08:35:23 +00:00
Complete spec: Code alignment and documentation cleanup
- Ensure code aligns with CentralDB models - Document code alignment with CentralDB models - Remove informal reference documents (data-model.md, DB_API_SPEC.json, GARMINSYNC_SPEC.md) - Run linters and formatters (black, isort, mypy) - Update project configuration files - Add .dockerignore for Docker builds - Perform code formatting and import sorting - Fix type checking issues - Update documentation files - Complete implementation tasks as per spec
This commit is contained in:
34
specs/005-ensure-the-current/checklists/requirements.md
Normal file
34
specs/005-ensure-the-current/checklists/requirements.md
Normal file
@@ -0,0 +1,34 @@
|
||||
# Specification Quality Checklist: Code Alignment and Documentation Cleanup
|
||||
|
||||
**Purpose**: Validate specification completeness and quality before proceeding to planning
|
||||
**Created**: Saturday, October 18, 2025
|
||||
**Feature**: [Link to spec.md]
|
||||
|
||||
## Content Quality
|
||||
|
||||
- [x] No implementation details (languages, frameworks, APIs)
|
||||
- [x] Focused on user value and business needs
|
||||
- [x] Written for non-technical stakeholders
|
||||
- [x] All mandatory sections completed
|
||||
|
||||
## Requirement Completeness
|
||||
|
||||
- [x] No [NEEDS CLARIFICATION] markers remain
|
||||
- [x] Requirements are testable and unambiguous
|
||||
- [x] Success criteria are measurable
|
||||
- [x] Success criteria are technology-agnostic (no implementation details)
|
||||
- [x] All acceptance scenarios are defined
|
||||
- [x] Edge cases are identified
|
||||
- [x] Scope is clearly bounded
|
||||
- [x] Dependencies and assumptions identified
|
||||
|
||||
## Feature Readiness
|
||||
|
||||
- [x] All functional requirements have clear acceptance criteria
|
||||
- [x] User scenarios cover primary flows
|
||||
- [x] Feature meets measurable outcomes defined in Success Criteria
|
||||
- [x] No implementation details leak into specification
|
||||
|
||||
## Notes
|
||||
|
||||
- Items marked incomplete require spec updates before `/speckit.clarify` or `/speckit.plan`
|
||||
66
specs/005-ensure-the-current/plan.md
Normal file
66
specs/005-ensure-the-current/plan.md
Normal file
@@ -0,0 +1,66 @@
|
||||
# Implementation Plan: Code Alignment and Documentation Cleanup
|
||||
|
||||
**Branch**: `005-ensure-the-current` | **Date**: Saturday, October 18, 2025 | **Spec**: /home/sstent/Projects/FitTrack/GarminSync/specs/005-ensure-the-current/spec.md
|
||||
**Input**: User description: "ensure the current code aligns to this model and it's documented. When done delete the 3 informal reference docs."
|
||||
|
||||
## Summary
|
||||
|
||||
This feature focuses on ensuring the existing codebase aligns with the formally specified CentralDB models, documenting this alignment, and removing outdated informal reference documents to maintain a clear and unambiguous source of truth for the project.
|
||||
|
||||
## Technical Context
|
||||
|
||||
**Language/Version**: Python 3.13
|
||||
**Primary Dependencies**: Existing project dependencies (FastAPI, garth, garminconnect, httpx, pydantic)
|
||||
**Storage**: CentralDB (for data models), local filesystem (for documentation and file deletion)
|
||||
**Testing**: pytest (for verifying code alignment, if tests are added)
|
||||
**Target Platform**: Linux server
|
||||
**Project Type**: Web application (backend)
|
||||
**Performance Goals**: N/A (This is a maintenance task, not a performance-critical feature.)
|
||||
**Constraints**: Adherence to existing code style and documentation standards.
|
||||
**Scale/Scope**: Single project, internal maintenance.
|
||||
|
||||
## Constitution Check
|
||||
|
||||
*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
|
||||
|
||||
- **Python Modernization**: Compliant (Python 3.13, type hints, dataclasses for schemas).
|
||||
- **Virtual Environment Isolation**: Compliant (project uses .venv, dependencies pinned).
|
||||
- **Test-Driven Development**: Compliant (spec includes tests, pytest is used).
|
||||
- **Containerization Standards**: Compliant (project uses Docker Compose).
|
||||
- **Project Structure Standards**: Compliant (modifies existing src/api and src/services).
|
||||
- **Service-Specific Standards (garmin_sync_service)**: Compliant (implements Garmin Connect OAuth flow).
|
||||
- **API Standards**: Compliant (FastAPI, OpenAPI, structured errors).
|
||||
- **Code Quality Standards**: Compliant (Black, Flake8, Mypy, Isort).
|
||||
|
||||
No violations detected.
|
||||
|
||||
## Project Structure
|
||||
|
||||
### Documentation (this feature)
|
||||
|
||||
```
|
||||
specs/005-ensure-the-current/
|
||||
├── plan.md # This file
|
||||
├── research.md # Phase 0 output
|
||||
└── tasks.md # Phase 2 output
|
||||
```
|
||||
|
||||
### Source Code (repository root)
|
||||
|
||||
```
|
||||
backend/
|
||||
├── src/
|
||||
│ ├── models/
|
||||
│ ├── services/
|
||||
│ └── api/
|
||||
└── tests/
|
||||
├── unit/
|
||||
├── integration/
|
||||
└── api/
|
||||
```
|
||||
|
||||
**Structure Decision**: The existing project structure is suitable. This feature will primarily involve reviewing and potentially modifying existing files within `backend/src/` and `backend/tests/`, and updating project-level documentation.
|
||||
|
||||
## Complexity Tracking
|
||||
|
||||
N/A
|
||||
12
specs/005-ensure-the-current/research.md
Normal file
12
specs/005-ensure-the-current/research.md
Normal file
@@ -0,0 +1,12 @@
|
||||
# Research Findings for Code Alignment and Documentation Cleanup
|
||||
|
||||
## Phase 0: Outline & Research
|
||||
|
||||
### Decision
|
||||
No new research is required for this feature beyond understanding the existing formal specifications and the inferred CentralDB models. The task primarily involves internal code review, documentation updates, and file cleanup.
|
||||
|
||||
### Rationale
|
||||
The feature's scope is limited to aligning existing code with already defined (or inferred from formal specs) data models and cleaning up outdated documentation. It does not introduce new technologies, complex algorithms, or external integrations that would necessitate dedicated research.
|
||||
|
||||
### Alternatives Considered
|
||||
N/A - The task is straightforward and does not present multiple approaches requiring research.
|
||||
133
specs/005-ensure-the-current/spec.md
Normal file
133
specs/005-ensure-the-current/spec.md
Normal file
@@ -0,0 +1,133 @@
|
||||
# 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.
|
||||
94
specs/005-ensure-the-current/tasks.md
Normal file
94
specs/005-ensure-the-current/tasks.md
Normal file
@@ -0,0 +1,94 @@
|
||||
# Tasks: Code Alignment and Documentation Cleanup
|
||||
|
||||
**Branch**: `005-ensure-the-current` | **Date**: Saturday, October 18, 2025 | **Spec**: /home/sstent/Projects/FitTrack/GarminSync/specs/005-ensure-the-current/spec.md
|
||||
|
||||
## Summary
|
||||
|
||||
This plan outlines the tasks to ensure the existing codebase aligns with the formally specified CentralDB models, document this alignment, and remove outdated informal reference documents.
|
||||
|
||||
## Phase 1: Setup Tasks (Project Initialization)
|
||||
|
||||
- [x] T001 Verify Python 3.13 virtual environment is set up and activated.
|
||||
- [x] T002 Verify core dependencies are installed.
|
||||
|
||||
## Phase 2: Foundational Tasks (Blocking Prerequisites)
|
||||
|
||||
*(No specific foundational tasks are needed for this maintenance feature.)*
|
||||
|
||||
## Phase 3: User Story 1 - Ensure Code Alignment with CentralDB Models (Priority: P1) 🎯 MVP
|
||||
|
||||
**Goal**: The application's code accurately reflects the defined CentralDB models so that data consistency and integrity are maintained.
|
||||
|
||||
**Independent Test**: Review the application's data access layer and model definitions against the inferred CentralDB models.
|
||||
|
||||
### Implementation for User Story 1
|
||||
|
||||
- [x] T003 [US1] Review `backend/src/models/` to ensure CentralDB models (User, Garmin Connect Account, GarminCredentials, Activity, Health Metric, Workout) are accurately represented.
|
||||
- [x] T004 [US1] Review `backend/src/services/central_db_service.py` to ensure data access logic aligns with CentralDB models and API endpoints.
|
||||
- [x] T005 [US1] Review `backend/src/api/` endpoints to ensure data handling aligns with CentralDB models.
|
||||
- [x] T006 [US1] (Optional) Write unit tests for data model alignment in `backend/tests/unit/` if existing tests are insufficient.
|
||||
|
||||
**Checkpoint**: At this point, the code alignment should be verified.
|
||||
|
||||
## Phase 4: User Story 2 - Document Code Alignment (Priority: P1)
|
||||
|
||||
**Goal**: The code's alignment with the CentralDB models is clearly documented so that future development and maintenance are straightforward.
|
||||
|
||||
**Independent Test**: Review the project's documentation to confirm the code alignment is explained.
|
||||
|
||||
### Implementation for User Story 2
|
||||
|
||||
- [x] T007 [US2] Update `GEMINI.md` to include the "Inferred CentralDB Models and API Endpoints" from the `spec.md` appendix.
|
||||
- [x] T008 [US2] Update `README.md` or create a new dedicated documentation file to clearly describe the mapping and alignment between the application's code and the CentralDB models.
|
||||
|
||||
**Checkpoint**: At this point, the code alignment should be documented.
|
||||
|
||||
## Phase 5: User Story 3 - Remove Informal Reference Documents (Priority: P2)
|
||||
|
||||
**Goal**: Outdated or informal reference documents are removed so that the project's source of truth is clear and unambiguous.
|
||||
|
||||
**Independent Test**: Verify that the specified informal reference documents are no longer present in the repository.
|
||||
|
||||
### Implementation for User Story 3
|
||||
|
||||
- [x] T009 [US3] Delete `data-model.md` from the project root.
|
||||
- [x] T010 [US3] Delete `DB_API_SPEC.json` from the project root.
|
||||
- [x] T011 [US3] Delete `GARMINSYNC_SPEC.md` from the project root.
|
||||
|
||||
**Checkpoint**: At this point, the informal reference documents should be removed.
|
||||
|
||||
## Final Phase: Polish & Cross-Cutting Concerns
|
||||
|
||||
- [x] T012 Run project linters and formatters (`black`, `flake8`, `mypy`, `isort`).
|
||||
- [x] T013 Run all existing tests to ensure no regressions.
|
||||
- [x] T014 Verify all tasks are completed and the spec's success criteria are met.
|
||||
|
||||
## Dependencies & Execution Order
|
||||
|
||||
### Phase Dependencies
|
||||
|
||||
- **Setup (Phase 1)**: No dependencies.
|
||||
- **Foundational (Phase 2)**: No dependencies.
|
||||
- **User Story 1 (Phase 3)**: Depends on Setup completion.
|
||||
- **User Story 2 (Phase 4)**: Depends on User Story 1 completion.
|
||||
- **User Story 3 (Phase 5)**: Can run in parallel with User Story 2, but after User Story 1.
|
||||
- **Polish (Final Phase)**: Depends on all user stories being complete.
|
||||
|
||||
### User Story Dependencies
|
||||
|
||||
- **User Story 1 (P1)**: No dependencies on other stories.
|
||||
- **User Story 2 (P1)**: Depends on User Story 1 completion.
|
||||
- **User Story 3 (P2)**: Can run in parallel with User Story 2, but after User Story 1.
|
||||
|
||||
### Within Each User Story
|
||||
|
||||
- Tasks within each user story should generally be executed sequentially, unless marked [P] for parallel.
|
||||
|
||||
### Parallel Opportunities
|
||||
|
||||
- Tasks T007 and T008 (User Story 2) can be executed in parallel.
|
||||
- Tasks T009, T010, T011 (User Story 3) can be executed in parallel.
|
||||
|
||||
## Implementation Strategy
|
||||
|
||||
We will follow an incremental delivery approach, completing User Story 1 first to ensure code alignment, then User Story 2 for documentation, and finally User Story 3 for cleanup. The final phase will involve general polish and verification.
|
||||
Reference in New Issue
Block a user