sstent/FitTrack_GarminSync
1
0
Fork 0
mirror of https://github.com/sstent/FitTrack_GarminSync.git synced 2026-02-07 06:52:22 +00:00
Code Issues Packages Projects Releases Wiki Activity

Complete spec: Code alignment and documentation cleanup

Browse Source 
- 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:
sstent
2025-12-18 13:21:54 -08:00
parent b0aa585372
commit ca9d7d9e90
58 changed files with 2726 additions and 377 deletions
Download Patch File Download Diff File Expand all files Collapse all files

58
README.md
View File

@@ -59,3 +59,61 @@ Upon successful login, your Garmin credentials and authentication tokens will be
### 2. Subsequent Synchronization
Once linked, other Garmin synchronization endpoints (e.g., for activities, health metrics) will automatically use the stored and refreshed credentials to access your Garmin data. **These subsequent synchronization calls do not require any additional authentication headers from the client.**
## CentralDB Models and API Endpoints
This section outlines the inferred CentralDB models and the API endpoints consumed by the GarminSync service, providing a clear mapping between the application's internal data structures and the CentralDB.
### Inferred CentralDB Models
Based on the functional requirements and key entities described in the formal specifications (`specs/001-create-from-initialspec/spec.md`, `specs/002-intialspecv2/spec.md`, and `specs/003-loginimprovements-use-the/spec.md`), the following CentralDB models are implied:
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)
These are the CentralDB HTTP interfaces that the GarminSync service interacts with:
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).