feat: Initial commit of FitTrack_GarminSync project

quickstart.md

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