# Quickstart Guide for GarminSync Service

This guide provides instructions to quickly set up and run the GarminSync service.

## Prerequisites

*   Python 3.13 or newer
*   Docker and Docker Compose (version 3.x)
*   Git

## 1. Clone the Repository

First, clone the project repository to your local machine:

```bash
git clone https://github.com/your-repo/GarminSync.git
cd GarminSync
```

## 2. Set up Python Virtual Environment

It is highly recommended to use a Python virtual environment to manage dependencies.

```bash
python3.13 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```

## 3. Configure Environment Variables

The service can be configured via environment variables. Create a `.env` file in the project root based on `example.env` (if provided) or set them directly in your shell.

**Essential Environment Variables**:

*   `GARMIN_CONNECT_EMAIL`: Your Garmin Connect account email.
*   `GARMIN_CONNECT_PASSWORD`: Your Garmin Connect account password. *(Ensure secure handling of this variable)*
*   `API_PORT`: The port the service will listen on (defaults to `8001`).

Example `.env` content:
```
GARMIN_CONNECT_EMAIL="your_email@example.com"
GARMIN_CONNECT_PASSWORD="your_garmin_password"
API_PORT=8001
```

## 4. Run the Service (Development)

You can run the service directly using `uvicorn` or via Docker Compose.

### Option A: Using Uvicorn (for local development)

```bash
source .venv/bin/activate
uvicorn src.main:app --host 0.0.0.0 --port ${API_PORT:-8001} --reload
```

### Option B: Using Docker Compose

For a containerized development environment:

```bash
docker compose -f docker-compose.dev.yml up --build
```

## 5. Access the API Documentation

Once the service is running, you can access the interactive API documentation (Swagger UI) at:

`http://localhost:8001/docs` (or your configured `API_PORT`)

## 6. Basic Usage

### Link Garmin Account

To link your Garmin Connect account, send a POST request to `/api/garmin/auth/link`:

```bash
curl -X POST "http://localhost:8001/api/garmin/auth/link" \
     -H "Content-Type: application/json" \
     -d '{
           "email": "your_email@example.com",
           "password": "your_garmin_password"
         }'
```

### Trigger Activity Sync

To trigger activity synchronization:

```bash
curl -X POST "http://localhost:8001/api/sync/garmin/activities" \
     -H "Content-Type: application/json" \
     -d '{}'
```

### Trigger Health Metrics Sync

To trigger health metrics synchronization:

```bash
curl -X POST "http://localhost:8001/api/sync/garmin/health-metrics" \
     -H "Content-Type: application/json" \
     -d '{}'
```

### Upload Workout

To upload a workout (replace `<WORKOUT_ID>` with an actual workout ID from your CentralDB):

```bash
curl -X POST "http://localhost:8001/api/sync/garmin/workouts" \
     -H "Content-Type: application/json" \
     -d '{
           "workout_id": "<WORKOUT_ID>"
         }'
```

### Check Sync Status

To check the status of synchronization jobs:

```bash
curl "http://localhost:8001/api/sync/status"
```

---

**Note**: This quickstart assumes a basic setup. Refer to the full documentation for advanced configuration, deployment, and troubleshooting.