before claude fix #1

FitnessSync/specs/001-fitbit-garmin-sync/research.md

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