FitTrack_GarminSync/specs/010-specification-overview-the/data-model.md

Data Model: Garmin Authentication State

Date: 2025-12-22

This document defines the data model for storing a user's persisted Garmin Connect authentication state, as required by the Persist Garmin Authentication for Stateless Sync feature.

Entity: GarminAuthenticationState

This entity represents a user's authenticated session with Garmin Connect. It is designed to be stored in the CentralDB and is associated with a single application user.

Fields

Field Name	Data Type	Nullable	Description
user_id	Foreign Key	False	The unique identifier for the application user this authentication state belongs to.
session_data	Text / Blob	True	The serialized, possibly encrypted, session data from the garth library. Null if no session is stored.
mfa_pending	Boolean	False	A flag indicating if the authentication process is currently paused, awaiting an MFA code from the user.
last_validated	Timestamp	True	The timestamp when the session was last successfully used to communicate with the Garmin API.
created_at	Timestamp	False	The timestamp when this record was created.
updated_at	Timestamp	False	The timestamp when this record was last updated.

Relationships

• Belongs to: User. A one-to-one relationship exists between a User and their GarminAuthenticationState.

State Transitions

The GarminAuthenticationState entity can transition through several states:

1. Non-existent: No record exists for the user. This is the initial state.
2. MFA Pending: A record exists with mfa_pending = true and session_data is likely null. This occurs after an initial login attempt triggers an MFA challenge.
3. Active / Persisted: A record exists with mfa_pending = false and session_data is populated. This is the state for a successfully authenticated user, allowing for stateless background syncs.
4. Invalid / Stale: The session_data is present but no longer valid for authentication with Garmin's servers, and it could not be refreshed. This state is not explicitly stored but is determined at runtime, leading to the clearing of the session_data.

Validation Rules

• user_id must correspond to an existing user in the users table.
• session_data should be stored in an encrypted format to protect sensitive session information. [NEEDS CLARIFICATION: The encryption method and key management strategy needs to be defined during implementation.]
• last_validated should be updated after every successful background sync or API call to Garmin Connect.