FitTrack_GarminSync/quickstart.md

# Quickstart Guide: GarminSync Service

This guide provides essential steps for setting up and running the GarminSync service.

## 1. Prerequisites

Before you begin, ensure you have the following installed:

*   **Docker and Docker Compose**: The service is containerized using Docker. Ensure Docker Engine and Docker Compose V3 are installed on your system.
    *   [Install Docker](https://docs.docker.com/get-docker/)
    *   [Install Docker Compose](https://docs.docker.com/compose/install/)
*   **Python 3.13+**: While the service runs in Docker, you might need Python for local development tools or scripting.
    *   [Install Python](https://www.python.org/downloads/)
*   **Git**: For cloning the repository.

## 2. Environment Setup

### 2.1. Clone the Repository

First, clone the GarminSync service repository:

```bash
git clone <repository-url>
cd <repository-name>
```

### 2.2. Create and Activate a Python Virtual Environment (Optional, for local development)

It's recommended to use a virtual environment for dependency management:

```bash
python3.13 -m venv .venv
source .venv/bin/activate
```

### 2.3. Install Dependencies (Optional, for local development)

If you are developing locally outside of Docker, install the Python dependencies:

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

## 3. Configuration

The GarminSync service can be configured via YAML files or environment variables.

### 3.1. Default Configuration

The service defaults to listening on port `8001`.

### 3.2. CentralDB Integration

The service requires a running CentralDB instance. By default, it expects CentralDB to be accessible via its API. The `DB_API_SPEC.json` defines the CentralDB API, and the service will attempt to refresh this spec from `http://localhost:8000/openapi.json`.

You will likely need to configure the CentralDB connection details, either in a YAML configuration file or via environment variables. Refer to the project's main `README.md` or `config` directory for specific configuration options.

## 4. Running the Service

The recommended way to run the GarminSync service is using Docker Compose.

### 4.1. Development Environment

To run the service in a development environment:

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

This command will build the necessary Docker images and start the GarminSync service along with any other services defined in `docker-compose.dev.yml` (e.g., CentralDB, Redis).

### 4.2. Production Environment

To run the service in a production environment (typically in detached mode):

```bash
docker compose -f docker-compose.prod.yml up -d
```

### 4.3. Accessing the Service

Once the service is running, it will be accessible at `http://localhost:8001` (or the configured port). You can then interact with its API endpoints.

## 5. Basic Usage

### 5.1. Link Garmin Connect Account

Before syncing data, you need to link your Garmin Connect account:

```bash
curl -X POST http://localhost:8001/api/garmin/auth/link \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer <your-app-auth-token>" \
     -d '{
           "email": "your_garmin_email@example.com",
           "password": "your_garmin_password"
         }'
```
Replace `<your-app-auth-token>`, `your_garmin_email@example.com`, and `your_garmin_password` with your actual authentication token and Garmin Connect credentials.

**Note on Authentication**: Currently, `<your-app-auth-token>` is a placeholder. Any non-empty string will be accepted as a valid token by the backend's authentication mechanism, which will then return a mock user. Full token management will be implemented in a future update.

### 5.2. Trigger Activity Synchronization

To trigger an activity sync:

```bash
curl -X POST http://localhost:8001/api/sync/garmin/activities \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer <your-app-auth-token>" \
     -d '{
           "start_date": "2024-01-01",
           "end_date": "2024-01-31"
         }'
```

### 5.3. Check Sync Status

To check the status of synchronization processes:

```bash
curl -X GET http://localhost:8001/api/sync/status \
     -H "Authorization: Bearer <your-app-auth-token>"
```

### 5.4. Upload a Workout

To upload a workout (assuming you have a workout defined in CentralDB with ID `[workout_id]`):

```bash
curl -X POST http://localhost:8001/api/sync/garmin/workouts \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer <your-app-auth-token>" \
     -d '{
           "workout_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef"
         }'
```

## 6. Next Steps

*   Refer to the full API documentation (available via OpenAPI/Swagger at `/docs` or `/redoc` when the service is running) for all available endpoints and detailed usage.
*   Explore the `tests/` directory for examples of how to interact with the service.
*   Consult the `constitution.yaml` for development and code quality standards.