# Fitbit-Garmin Sync Setup Guide

## Prerequisites

Before setting up the Fitbit-Garmin Sync application, ensure you have the following:

- Python 3.11+ installed
- PostgreSQL database server
- Docker and Docker Compose (for containerized deployment)
- Fitbit Developer Account to create an API application
- Garmin Connect Account

## Quick Setup with Docker

The easiest way to get started is using Docker Compose:

```bash
# Navigate to the backend directory
cd backend

# Start the application and database
docker-compose up --build
```

The application will be available at `http://localhost:8000`.

## Manual Setup

### 1. Clone the Repository

```bash
git clone <repository-url>
cd fitbit-garmin-sync
```

### 2. Create Virtual Environment

```bash
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
```

### 3. Install Dependencies

```bash
pip install -r requirements.txt
```

### 4. Database Setup

Create a PostgreSQL database for the application:

```bash
createdb fitbit_garmin_sync
```

### 5. Environment Configuration

Create a `.env` file in the backend directory with the following content:

```env
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
DEBUG=True
```

### 6. Run the Application

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

## Configuration Steps

Once the application is running, you'll need to configure both Fitbit and Garmin access:

### 1. Garmin Connect Setup

1. Navigate to the Setup page at `http://localhost:8000/setup`
2. Enter your Garmin Connect username and password
3. Click "Save Garmin Credentials"

### 2. Fitbit API Setup

1. Go to the [Fitbit Developer Portal](https://dev.fitbit.com/)
2. Create a new application
3. Set the OAuth 2.0 Application Type to "Personal"
4. Set the Callback URL to `http://localhost:8000/api/setup/fitbit/callback`
5. Note down the "Client ID" and "Client Secret"
6. On the setup page, enter these values in the Fitbit API Credentials section
7. Click "Save Fitbit Credentials"
8. Click the authorization link that appears to connect your Fitbit account
9. After authorizing, copy the complete URL from your browser and paste it in the "Complete Fitbit OAuth Flow" section
10. Click "Complete OAuth Flow"

## Running the Synchronization

### 1. Weight Sync

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

### 2. Activity Archiving

1. Go to the home page (`/`)
2. Click the "Sync Activities" button
3. Enter the number of days back to look for activities
4. The original activity files (.fit, .gpx, .tcx) will be downloaded from Garmin and stored in the PostgreSQL database
5. Monitor the sync status in the logs table
6. Use the "List Stored Activities" and "Download Activity File" options to access stored activity files

### 3. Health Metrics Sync

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

## Security Considerations

- Store API credentials securely (not in version control)
- Use environment variables for configuration
- Encrypt sensitive data stored in the database
- Regularly rotate API tokens
- Implement proper error handling to avoid information disclosure

## Troubleshooting

### Common Issues

- **Database Connection**: Ensure PostgreSQL is running and accessible
- **API Credentials**: Verify Fitbit and Garmin credentials are correct
- **Rate Limits**: Be mindful of API rate limits from both providers
- **Network Issues**: Ensure the application has internet access

### Logs

Check the application logs for errors:

```bash
# In Docker
docker-compose logs app

# For direct Python execution, add logging to track operations
```

## Updating

To update to the latest version:

```bash
# Pull latest changes
git pull origin main

# Update dependencies
pip install -r requirements.txt

# Restart the application
```