# 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.