before claude fix #1

2025-12-23 06:09:34 -08:00
parent c505fb69a6
commit a23fa1b30d
83 changed files with 5682 additions and 0 deletions
--- a/FitnessSync/backend/docs/setup.md
+++ b/FitnessSync/backend/docs/setup.md
@@ -0,0 +1,162 @@
+# 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
+```