mirror of
https://github.com/sstent/FitTrack_GarminSync.git
synced 2026-01-25 16:41:41 +00:00
sstent
ca9d7d9e90
- 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
89 lines
5.1 KiB
Markdown
89 lines
5.1 KiB
Markdown
# FitTrack_GarminSync Development Guidelines
|
|
|
|
Auto-generated from all feature plans. Last updated: 2025-10-10
|
|
|
|
## Active Technologies
|
|
- Python 3.13 + FastAPI, `garth`, `garminconnect`, `httpx`, `pydantic` (003-loginimprovements-use-the)
|
|
- Python 3.13 + FastAPI, garth, garminconnect, httpx, pydantic (003-loginimprovements-use-the)
|
|
- centralDB (PostgreSQL/SQLite with SQLAlchemy) (003-loginimprovements-use-the)
|
|
- Python 3.13 + FastAPI, Pydantic, `garth`, `garminconnect`, `httpx` (004-home-sstent-projects)
|
|
- In-memory for `CurrentSyncJobManager` (004-home-sstent-projects)
|
|
- Python 3.13 + Existing project dependencies (FastAPI, garth, garminconnect, httpx, pydantic) (005-ensure-the-current)
|
|
- CentralDB (for data models), local filesystem (for documentation and file deletion) (005-ensure-the-current)
|
|
|
|
## Project Structure
|
|
```
|
|
src/
|
|
tests/
|
|
```
|
|
|
|
## Commands
|
|
cd src [ONLY COMMANDS FOR ACTIVE TECHNOLOGIES][ONLY COMMANDS FOR ACTIVE TECHNOLOGIES] pytest [ONLY COMMANDS FOR ACTIVE TECHNOLOGIES][ONLY COMMANDS FOR ACTIVE TECHNOLOGIES] ruff check .
|
|
|
|
## Code Style
|
|
Python 3.13: Follow standard conventions
|
|
|
|
## Recent Changes
|
|
- 005-ensure-the-current: Added Python 3.13 + Existing project dependencies (FastAPI, garth, garminconnect, httpx, pydantic)
|
|
- 004-home-sstent-projects: Added Python 3.13 + FastAPI, Pydantic, `garth`, `garminconnect`, `httpx`
|
|
- 003-loginimprovements-use-the: Added Python 3.13 + FastAPI, garth, garminconnect, httpx, pydantic
|
|
|
|
<!-- MANUAL ADDITIONS START -->
|
|
<!-- MANUAL ADDITIONS START -->
|
|
|
|
### 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).
|
|
|
|
<!-- MANUAL ADDITIONS END -->
|