FitTrack2/FitnessSync/docs/specs/fitbit-integration.md

Fitbit Integration Specification

Status: Implemented Version: 1.0.0 Last Updated: 2026-01-12

1. Overview

This specification documents the current implementation of the Fitbit integration within the FitTrack2 ecosystem. The primary goal is to authenticate with the Fitbit API using OAuth 2.0 and synchronize health metrics—specifically body weight and BMI—into the local database for analysis and visualization.

2. Authentication (OAuth 2.0)

2.1 Credentials Management

• Storage: Client ID and Client Secret are stored in the configuration table.
• Tokens: Access and Refresh tokens are stored in the api_tokens table with token_type='fitbit'.

2.2 Authorization Flow

1. Initiation:
   • Endpoint: POST /setup/fitbit
   • Input: client_id, client_secret, redirect_uri
   • Process: Generates an Authorization URL using the fitbit Python library.
   • Scopes Requested: ['weight', 'nutrition', 'activity', 'sleep', 'heartrate', 'profile']
2. Callback:
   • Endpoint: POST /setup/fitbit/callback
   • Input: code (Authorization Code)
   • Process: Exchanges code for Access and Refresh tokens.
   • Output: Saves tokens to api_tokens table.

2.3 Token Refresh

• Mechanism: The FitbitClient handles token expiration.
• Note: Current implementation of refresh_access_token in FitbitClient contains mock logic and requires finalization for production use.

3. Data Synchronization

3.1 Supported Metrics

Currently, only Weight and BMI are synchronized.

3.2 Sync Strategy

• On-Demand: Triggered via API or UI.
• Scopes:
  • 30d: Syncs the last 30 days.
  • all: Syncs all history starting from 2015-01-01.
• Chunking: Requests are chunked into 30-day intervals to respect API limits.
• Rate Limiting: Custom handling for HTTP 429 Too Many Requests. The system parses Retry-After headers and sleeps automatically before retrying a chunk.

3.3 Data Storage

Data is stored in the weight_records table.

Column	Type	Description
id	Integer	Primary Key
fitbit_id	String	Unique Log ID from Fitbit
weight	Float	Weight in Kg
bmi	Float	Calculated BMI
unit	String	Unit (default 'kg')
date	DateTime	Timestamp of measurement
sync_status	String	Status for downstream sync (e.g. 'unsynced')

3.4 Logic (Deduplication)

• Incoming records are matched against existing records by fitbit_id.
• Updates: If weight differs by > 0.01 or bmi was missing, the record is updated.
• Inserts: New records are created if no match is found.

4. API Endpoints

4.1 Configuration & Auth

• POST /setup/fitbit: Save credentials and get Auth URL.
• POST /setup/fitbit/callback: Exchange code for token.
• POST /setup/fitbit/test-token: Verify current token validity and fetch user profile.

4.2 Synchronization

• POST /api/sync/fitbit/weight: Trigger sync.
  • Body: { "scope": "30d" | "all" }
• GET /api/jobs/{job_id}: Check sync status (if run as background job).

4.3 Data Access

• GET /api/metrics/query:
  • Params: source=fitbit, metric_type=weight, start_date, end_date.
  • Returns: serialized WeightRecord objects.
• POST /api/sync/compare-weight: Compares Fitbit weight dates vs Garmin weight dates to find gaps.

5. Frontend UI

The UI is split between configuration (setup) and visualization (health dashboard).

5.1 Authentication UI (backend/templates/setup.html)

The setup page handles the OAuth 2.0 flow:

1. Credentials Form: Inputs for Client ID, Client Secret, and Redirect URI (defaulting to http://localhost:8000/fitbit_callback).
2. Actions:
   • Test Fitbit Credentials: Validates inputs and generates the Authorization URL.
   • Save Fitbit Credentials: Persists credentials to the database.
   • Test Current Fitbit Token: Checks if the stored token is valid.
3. OAuth Flow:
   • After validation, a link "Authorize with Fitbit" is displayed.
   • User clicks link, authorizes on Fitbit, and is redirected to the fitbit_callback URL (localhost).
   • Manual Step: User copys the full URL (including code) and pastes it into the "Paste full callback URL" input.
   • Complete OAuth Flow button sends the code to the backend.

5.2 Health Dashboard (backend/templates/fitbit_health.html)

Located at backend/templates/fitbit_health.html.

Features

• Sync Controls: Buttons to trigger "Sync Recent (30d)" and "Sync All".
• Comparison: "Compare vs Garmin" modal showing counts and missing dates.
• Data Table: Displays Date, Weight, BMI, and Source.
• Filtering: Date range pickers (Start/End) and quick toggles (30d, 1y, All).

6. Dependencies

• Libraries:
  • fitbit (Python client for interaction)
  • sqlalchemy (ORM)
  • pydantic (Data validation)

7. Future Considerations

• Token Refresh: Implement real token refresh logic in FitbitClient.
• Additional Metrics: Expand sync to cover Heart Rate, Sleep, and Activities using the already authorized scopes.