feat: Initial commit of FitTrack_GarminSync project

specs/002-intialspecv2/quickstart.md

@@ -0,0 +1,129 @@
+# 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.