mirror of
https://github.com/sstent/FitTrack_GarminSync.git
synced 2026-01-26 09:01:53 +00:00
sstent
846725a81e
Adds the technical plan, data model, API contracts, and research for the persisted Garmin authentication feature.
37 lines
2.9 KiB
Markdown
37 lines
2.9 KiB
Markdown
# Research: Persist Garmin Authentication for Stateless Sync
|
|
|
|
**Date**: 2025-12-22
|
|
|
|
This document outlines the decisions made regarding the technical implementation for persisting Garmin authentication sessions.
|
|
|
|
## 1. Authentication Library
|
|
|
|
- **Decision**: Use the `garth` library for handling Garmin Connect authentication.
|
|
- **Rationale**: The initial feature description explicitly mentions `garth`. This library is purpose-built for interacting with the Garmin Connect API, handles MFA, and most importantly, supports session export (`dumps`) and import (`loads`). This is the cornerstone of the "stateless sync" requirement, allowing us to persist the session state. It aligns with the existing project dependencies mentioned in `GEMINI.md`.
|
|
- **Alternatives considered**:
|
|
- `garminconnect`: Another popular library. While it's great for fetching data, its session management is not as explicitly designed for serialization and deserialization as `garth`'s, which is critical for this feature. We will continue to use it for data fetching, but `garth` will manage the authentication lifecycle.
|
|
|
|
## 2. Session Data Storage
|
|
|
|
- **Decision**: Store the serialized `garth` session in the CentralDB.
|
|
- **Rationale**: The feature spec requires a persistent store. The CentralDB (as defined in the constitution and project context) is the designated single source of truth for user-related data. Storing the session here ensures that any service or background worker can access it. The session data will be stored as a text or blob type.
|
|
- **Alternatives considered**:
|
|
- **Redis Cache**: Could be used for faster access, but it's not guaranteed to be persistent. The constitution mentions Redis for rate limiting, not for primary data storage.
|
|
- **Local File System**: Not suitable for a distributed or stateless service architecture, as different workers would not have access to the same session file.
|
|
|
|
## 3. API Framework
|
|
|
|
- **Decision**: Use FastAPI for the new API endpoints.
|
|
- **Rationale**: The project constitution mandates FastAPI for all API services. It's already in use in the project, ensuring consistency. Pydantic, which comes with FastAPI, will be used for request/response modeling.
|
|
- **Alternatives considered**: None, as this is a strict requirement from the project constitution.
|
|
|
|
## 4. Database Interaction
|
|
|
|
- **Decision**: Use SQLAlchemy to interact with the CentralDB.
|
|
- **Rationale**: The constitution specifies SQLAlchemy as the ORM. This ensures that the data model for the `GarminAuthenticationState` is managed consistently with other project models.
|
|
- **Alternatives considered**: None. This is a constitutional requirement.
|
|
|
|
## Conclusion
|
|
|
|
The technical approach is a straightforward integration of `garth`'s session management with the existing FastAPI and SQLAlchemy stack. All technical choices are dictated by the feature's core requirements and the project's established constitution.
|