FitTrack2/FitnessSync/specs/001-fitbit-garmin-sync/quickstart.md

Quickstart Guide: Fitbit-Garmin Local Sync

Prerequisites

• Python 3.11+
• PostgreSQL database
• Docker and Docker Compose (for containerized deployment)
• Fitbit Developer Account (to create an app and get API credentials)
• Garmin Connect Account

Setup

1. Clone and Install Dependencies

# Clone the repository
git clone <repository-url>
cd fitbit-garmin-sync

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

2. Database Setup

# Create PostgreSQL database
createdb fitbit_garmin_sync

# Update database configuration in application
# The application will handle schema creation automatically

3. Environment Configuration

Create a .env file with the following:

DATABASE_URL=postgresql://username:password@localhost:5432/fitbit_garmin_sync
FITBIT_CLIENT_ID=your_fitbit_client_id
FITBIT_CLIENT_SECRET=your_fitbit_client_secret
FITBIT_REDIRECT_URI=http://localhost:8000/api/setup/fitbit/callback

4. Run the Application

# Using uvicorn directly
uvicorn main:app --host 0.0.0.0 --port 8000

# Or using Docker
docker-compose up --build

Initial Configuration

1. Open the application in your browser at http://localhost:8000
2. Navigate to the Setup page (/setup)
3. Enter your Garmin Connect username and password
4. Enter your Fitbit Client ID and Client Secret
5. Click the authorization link provided to authenticate with Fitbit
6. Copy the full callback URL from your browser after authorizing and paste it into the input field on the setup page

Using the Application

Sync Weight Data

1. Go to the home page (/)
2. Click the "Sync Weight" button
3. Monitor the sync status in the logs table

Archive Activities

1. Go to the home page (/)
2. Click the "Sync Activities" button
3. Enter the number of days back to look for activities
4. Monitor the sync status in the logs table

View Health Metrics

1. Use the API endpoints to query health metrics:
   • /api/metrics/list - List available metric types
   • /api/metrics/query - Query specific metrics
   • /api/health-data/summary - Get aggregated health statistics

Docker Deployment

# Build and run with Docker Compose
docker-compose up --build

# The application will be available at http://localhost:8000
# PostgreSQL database will be automatically set up

API Endpoints

See the full API documentation in the contracts/api-contract.yaml file or access the automatic documentation at /docs when running the application.