4.6 KiB
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