Data Model: Fitbit-Garmin Local Sync

Overview

This document defines the data models for the Fitbit-Garmin Local Sync application based on the key entities identified in the feature specification.

Entity: Configuration

Description: Application settings including API credentials, sync settings, and database connection parameters Fields:

id (Integer): Unique identifier for the configuration record
fitbit_client_id (String): Fitbit API client ID
fitbit_client_secret (String): Fitbit API client secret (encrypted)
garmin_username (String): Garmin Connect username
garmin_password (String): Garmin Connect password (encrypted)
sync_settings (JSON): Sync preferences and settings
created_at (DateTime): Timestamp of creation
updated_at (DateTime): Timestamp of last update

Entity: Weight Record

Description: Individual weight entries with timestamps, values, and sync status with unique identifiers to prevent duplicate processing Fields:

id (Integer): Unique identifier for the weight record
fitbit_id (String): Original Fitbit ID for the weight entry
weight (Float): Weight value in user's preferred units
unit (String): Weight unit (e.g., 'kg', 'lbs')
date (Date): Date of the weight measurement
timestamp (DateTime): Exact timestamp of the measurement
sync_status (String): Sync status ('unsynced', 'synced', 'failed')
garmin_id (String, nullable): ID of the record if synced to Garmin
created_at (DateTime): Timestamp of record creation
updated_at (DateTime): Timestamp of last update

Entity: Activity Metadata

Description: Information about Garmin activities including download status, file content stored in database, and activity details Fields:

id (Integer): Unique identifier for the activity record
garmin_activity_id (String): Original Garmin ID for the activity
activity_name (String): Name of the activity
activity_type (String): Type of activity (e.g., 'running', 'cycling')
start_time (DateTime): Start time of the activity
duration (Integer): Duration in seconds
file_content (LargeBinary, nullable): Activity file content stored in database (base64 encoded)
file_type (String): File type (.fit, .gpx, .tcx, etc.)
download_status (String): Download status ('pending', 'downloaded', 'failed')
downloaded_at (DateTime, nullable): Timestamp when downloaded
created_at (DateTime): Timestamp of record creation
updated_at (DateTime): Timestamp of last update

Entity: Health Metric

Description: Comprehensive health data including type, timestamp, values across categories (steps, calories, heart rate, sleep, etc.) Fields:

id (Integer): Unique identifier for the health metric record
metric_type (String): Type of metric (e.g., 'steps', 'heart_rate', 'sleep', 'calories')
metric_value (Float): Value of the metric
unit (String): Unit of measurement
timestamp (DateTime): When the metric was recorded
date (Date): Date of the metric
source (String): Source of the metric ('garmin')
detailed_data (JSON, nullable): Additional details specific to the metric type
created_at (DateTime): Timestamp of record creation
updated_at (DateTime): Timestamp of last update

Entity: Sync Log

Description: Operation logs with timestamps, status, and results for monitoring and troubleshooting Fields:

id (Integer): Unique identifier for the sync log entry
operation (String): Type of sync operation ('weight_sync', 'activity_archive', 'metrics_download')
status (String): Status of the operation ('started', 'in_progress', 'completed', 'failed')
message (String): Status message or error details
start_time (DateTime): When the operation started
end_time (DateTime, nullable): When the operation completed
records_processed (Integer): Number of records processed
records_failed (Integer): Number of records that failed
user_id (Integer, nullable): Reference to user (if applicable)

Entity: API Token

Description: OAuth tokens for Fitbit and Garmin with expiration tracking and refresh mechanisms Fields:

id (Integer): Unique identifier for the token record
token_type (String): Type of token ('fitbit', 'garmin')
access_token (String): Access token (encrypted)
refresh_token (String): Refresh token (encrypted)
expires_at (DateTime): When the token expires
scopes (String): OAuth scopes granted
last_used (DateTime): When the token was last used
created_at (DateTime): Timestamp of record creation
updated_at (DateTime): Timestamp of last update

Entity: Auth Status

Description: Current authentication state for both Fitbit and Garmin, including token expiration times and last login information Fields:

id (Integer): Unique identifier for the auth status record
service_type (String): Type of service ('fitbit', 'garmin')
username (String): Username for the service (masked for security display)
authenticated (Boolean): Whether currently authenticated
token_expires_at (DateTime): When the current token expires
last_login (DateTime): When the last successful login occurred
is_china (Boolean): Whether using garmin.cn domain (Garmin only)
last_check (DateTime): When status was last checked
created_at (DateTime): Timestamp of record creation
updated_at (DateTime): Timestamp of last update

Relationships

Configuration has many API Tokens
Authentication Status references API Tokens
Sync Logs reference Configuration
Weight Records may reference API Tokens for sync operations
Activity Metadata may reference API Tokens for download operations
Health Metrics may reference API Tokens for retrieval operations

Validation Rules

Configuration records must have valid API credentials before sync operations
Weight Records must have unique fitbit_id to prevent duplicates
Activity Metadata records must have unique garmin_activity_id
Health Metric records must have valid metric_type from allowed list
Sync Log records must have valid operation and status values
API Token records must be refreshed before expiration
Authentication status must be updated when tokens are refreshed

6.1 KiB Raw Blame History