# Research: Fitbit-Garmin Local Sync

## Overview
This document captures research findings for the Fitbit-Garmin Local Sync feature, addressing technology choices, best practices, and integration patterns.

## Decision: Python 3.11 as primary language
**Rationale**: Python is well-suited for API integrations and web applications. Version 3.11 offers performance improvements and is widely supported by the required libraries (FastAPI, garminconnect, fitbit).
**Alternatives considered**: Node.js/JavaScript, Go, Rust - Python has the most mature ecosystem for health data API integrations.

## Decision: FastAPI for web framework
**Rationale**: FastAPI provides automatic API documentation (OpenAPI), type validation, asynchronous support, and excellent performance. It's ideal for both the API endpoints and web UI rendering.
**Alternatives considered**: Flask (less modern features), Django (too heavy for this use case), Starlette (requires more manual work).

## Decision: garminconnect and garth libraries for Garmin integration
**Rationale**: garminconnect is the most actively maintained Python library for Garmin Connect API. garth handles authentication, including the complex authentication flow for Garmin's API.
**Alternatives considered**: Custom HTTP requests implementation (more error-prone), selenium for web scraping (against ToS and less reliable).

## Decision: Fitbit official Python library
**Rationale**: The official fitbit library provides proper OAuth 2.0 handling and is maintained by Fitbit. It includes all necessary endpoints for weight data retrieval.
**Alternatives considered**: Direct API calls with requests library (would require more OAuth management code).

## Decision: PostgreSQL for data storage
**Rationale**: PostgreSQL provides ACID compliance, robustness, and complex query capabilities needed for health metrics. It supports the data types needed for timestamps and metric values.
**Alternatives considered**: SQLite (simpler but less scalable), MongoDB (document-based which may not suit structured health data), MySQL (similar capabilities but PostgreSQL has better JSON support).

## Decision: SQLAlchemy as ORM
**Rationale**: SQLAlchemy provides database abstraction, migration support, and protection against SQL injection. It works well with FastAPI and supports asynchronous operations.
**Alternatives considered**: Peewee (simpler but less feature-rich), Django ORM (requires Django framework), direct database connectors (more error-prone).

## Decision: Docker for deployment
**Rationale**: Docker provides consistent deployment across environments, easy dependency management, and isolation. It's the standard for modern application deployment.
**Alternatives considered**: Direct installation on host system (harder to manage dependencies), virtual environments (doesn't solve system-level dependency issues).

## Decision: Jinja2 for templating
**Rationale**: Jinja2 is the standard Python templating engine, supported by FastAPI. It provides the right balance of functionality and simplicity for the web interface.
**Alternatives considered**: Mako, Chameleon (less common), building HTML responses directly (not maintainable).

## Authentication Research
- **Fitbit OAuth 2.0**: Requires app registration with Fitbit, supports refresh tokens for long-term access
- **Garmin authentication**: Uses garth library to handle OAuth 1.0a/2.0 hybrid, stores session tokens for reuse
- **Multi-Factor Authentication (MFA)**: Garmin may require MFA for accounts with enhanced security. The garth library handles MFA flows by prompting for verification codes when required
- **Security**: Both systems support proper token refresh and secure storage

## API Rate Limiting Considerations
- **Fitbit**: Has rate limits (150 req/hour for user endpoints) - need to implement backoff/retry logic
- **Garmin**: No official rate limits published, but need to be respectful to avoid being blocked
- **Best practice**: Implement exponential backoff and caching to minimize API calls

## Data Synchronization Strategy
- **Deduplication**: Use unique identifiers and timestamps to prevent duplicate processing
- **State tracking**: Store sync status in database to enable resumption of interrupted operations
- **Conflict resolution**: For weight data, prefer Fitbit as source of truth since the feature is to sync FROM Fitbit TO Garmin

## Error Handling Approach
- **Network errors**: Retry with exponential backoff
- **Authentication errors**: Detect and re-authenticate automatically
- **API errors**: Log with context and allow user to retry operations
- **Storage errors**: Validate disk space before downloading activity files