FitTrack2/FitnessSync/specs/002-fitbit-garmin-sync/data-model.md

Data Model: Fitbit/Garmin Data Sync

Date: 2025-12-24

This document describes the data models for the entities involved in the Fitbit/Garmin data sync feature. The models are based on the existing SQLAlchemy models in the project.

Activity

Represents a single fitness activity (e.g., running, cycling).

SQLAlchemy Model: src/models/activity.py

Field	Type	Description
id	Integer	Primary key.
garmin_activity_id	String	The original unique identifier from Garmin Connect.
activity_name	String	The name of the activity (e.g., "Afternoon Run").
activity_type	String	The type of activity (e.g., 'running', 'cycling').
start_time	DateTime	The time the activity started.
duration	Integer	The duration of the activity in seconds.
file_content	LargeBinary	The original activity file content (e.g., .fit, .gpx, .tcx).
file_type	String	The file type of the original activity file.
download_status	String	The status of the file download ('pending', 'downloaded', 'failed').
downloaded_at	DateTime	The timestamp when the file was downloaded.
created_at	DateTime	The timestamp when the record was created.
updated_at	DateTime	The timestamp when the record was last updated.

HealthMetric

Represents a single health data point (e.g., steps, heart rate variability).

SQLAlchemy Model: src/models/health_metric.py

Field	Type	Description
id	Integer	Primary key.
metric_type	String	The type of metric (e.g., 'steps', 'heart_rate').
metric_value	Float	The value of the metric.
unit	String	The unit of measurement (e.g., 'steps', 'ms').
timestamp	DateTime	The timestamp when the metric was recorded.
date	DateTime	The date of the metric.
source	String	The source of the metric (e.g., 'garmin').
detailed_data	Text	Additional details, stored as a JSON string.
created_at	DateTime	The timestamp when the record was created.
updated_at	DateTime	The timestamp when the record was last updated.

SyncLog

Records the status and results of each synchronization operation.

SQLAlchemy Model: src/models/sync_log.py

Field	Type	Description
id	Integer	Primary key.
operation	String	The type of operation (e.g., 'metrics_download', 'activity_sync').
status	String	The status of the operation ('started', 'completed', 'failed').
message	Text	A status message or error details.
start_time	DateTime	The timestamp when the operation started.
end_time	DateTime	The timestamp when the operation completed.
records_processed	Integer	The number of records successfully processed.

• records_failed | Integer | The number of records that failed to process. | | user_id | Integer | A reference to the user for whom the sync was run (if applicable). | | created_at | DateTime | The timestamp when the record was created. | | updated_at | DateTime | The timestamp when the record was last updated. |