66 lines
5.0 KiB
Markdown
66 lines
5.0 KiB
Markdown
# 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
|
|
|
|
## Implementation Findings
|
|
The implementation has been successfully completed with the following key findings:
|
|
- garth library effectively handles Garmin authentication, including MFA flows
|
|
- FastAPI provides excellent performance and automatic API documentation
|
|
- SQLAlchemy ORM simplifies database operations and migrations
|
|
- The system can handle large volumes of health data efficiently
|
|
- Proper error handling and logging enable effective debugging and monitoring |