mirror of
https://github.com/sstent/FitTrack_GarminSync.git
synced 2026-01-26 00:51:44 +00:00
sstent
846725a81e
Adds the technical plan, data model, API contracts, and research for the persisted Garmin authentication feature.
61 lines
3.7 KiB
Markdown
61 lines
3.7 KiB
Markdown
# Implementation Plan: Persist Garmin Authentication for Stateless Sync
|
|
|
|
**Feature Spec**: [/home/sstent/Projects/FitTrack/GarminSync/specs/010-specification-overview-the/spec.md](/home/sstent/Projects/FitTrack/GarminSync/specs/010-specification-overview-the/spec.md)
|
|
**Branch**: `010-specification-overview-the`
|
|
|
|
## Technical Context
|
|
|
|
This section outlines the technologies and architectural decisions for implementing the feature.
|
|
|
|
- **Authentication Library**: `garth` will be used for handling the Garmin Connect authentication lifecycle, including login, MFA, and session serialization.
|
|
- **API Framework**: FastAPI will be used to build the new REST API endpoints, with Pydantic for data modeling.
|
|
- **Database**: The CentralDB (PostgreSQL/SQLite) will store the persisted session data.
|
|
- **ORM**: SQLAlchemy will be used to define the `GarminAuthenticationState` model and interact with the database.
|
|
- **Session Storage**: The serialized `garth` session will be stored as a Text/Blob field in the `GarminAuthenticationState` table.
|
|
- **Background Jobs**: Existing background job services will be modified to load the session from the DB, use it, and update it if refreshed.
|
|
|
|
## Constitution Check
|
|
|
|
This feature plan is evaluated against the project's constitution.
|
|
|
|
- [x] **I. Python Modernization**: All new code will use Python 3.13+ with type hints.
|
|
- [x] **II. Virtual Environment Isolation**: Development will occur within the existing `.venv`.
|
|
- [x] **III. Test-Driven Development**: Tests will be created for the new services and endpoints.
|
|
- [x] **V. Project Structure Standards**: New code will be placed in the appropriate `src/api`, `src/models`, and `src/services` directories.
|
|
- [x] **VI. Service-Specific Standards**:
|
|
- `centraldb_service`: The plan uses the mandated SQLAlchemy 2.0+ and FastAPI.
|
|
- `garminsync_service`: The plan directly addresses OAuth flows for Garmin Connect.
|
|
- [x] **X. API Standards**: A new FastAPI router will be created, and the OpenAPI contract will be published.
|
|
|
|
**Result**: The plan is fully compliant with the project constitution.
|
|
|
|
---
|
|
|
|
## Phase 0: Outline & Research
|
|
|
|
The research phase focused on validating the use of `garth` and confirming its integration with the existing technology stack.
|
|
|
|
- **`research.md`**: [/home/sstent/Projects/FitTrack/GarminSync/specs/010-specification-overview-the/research.md](/home/sstent/Projects/FitTrack/GarminSync/specs/010-specification-overview-the/research.md)
|
|
|
|
All technical unknowns have been resolved. The chosen stack is `FastAPI` + `SQLAlchemy` + `garth`.
|
|
|
|
---
|
|
|
|
## Phase 1: Design & Contracts
|
|
|
|
This phase defines the data structures and API contracts for the feature.
|
|
|
|
- **`data-model.md`**: [/home/sstent/Projects/FitTrack/GarminSync/specs/010-specification-overview-the/data-model.md](/home/sstent/Projects/FitTrack/GarminSync/specs/010-specification-overview-the/data-model.md)
|
|
- **API Contracts**:
|
|
- [/home/sstent/Projects/FitTrack/GarminSync/contracts/garmin_auth_session.json](/home/sstent/Projects/FitTrack/GarminSync/contracts/garmin_auth_session.json)
|
|
- **`quickstart.md`**: [/home/sstent/Projects/FitTrack/GarminSync/specs/010-specification-overview-the/quickstart.md](/home/sstent/Projects/FitTrack/GarminSync/specs/010-specification-overview-the/quickstart.md)
|
|
|
|
### Agent Context Update
|
|
|
|
No new technologies are being introduced that are not already listed in the agent's context (`GEMINI.md`). The plan uses the existing stack (`FastAPI`, `garth`, `SQLAlchemy`, `httpx`, `pydantic`). Therefore, no update to the agent context is required at this time.
|
|
|
|
---
|
|
|
|
## Phase 2: Implementation Tasks
|
|
|
|
This phase will be detailed in the next step (`/speckit.tasks`) and will involve creating the actual Python code based on the design artifacts from Phase 1. |