103 lines
4.6 KiB
Markdown
103 lines
4.6 KiB
Markdown
# Implementation Plan: Fitbit-Garmin Local Sync
|
|
|
|
**Branch**: `001-fitbit-garmin-sync` | **Date**: December 22, 2025 | **Spec**: [spec.md](./spec.md)
|
|
**Input**: Feature specification from `/specs/001-fitbit-garmin-sync/spec.md`
|
|
|
|
**Note**: This template is filled in by the `/speckit.plan` command. See `.specify/templates/commands/plan.md` for the execution workflow.
|
|
|
|
## Summary
|
|
|
|
This feature implements a standalone Python application that synchronizes health and fitness data between Fitbit and Garmin Connect platforms. The primary requirements include: 1) Weight data synchronization from Fitbit to Garmin, 2) Activity file archiving from Garmin to local storage, and 3) Comprehensive health metrics download from Garmin to local database. The system uses a web interface with API endpoints for user interaction and operates with local-only data storage for privacy.
|
|
|
|
## Technical Context
|
|
|
|
**Language/Version**: Python 3.11
|
|
**Primary Dependencies**: FastAPI, uvicorn, garminconnect, garth, fitbit, SQLAlchemy, Jinja2, psycopg2
|
|
**Storage**: PostgreSQL database for all data including configuration, health metrics, activity files, and authentication status information
|
|
**Testing**: pytest for unit and integration tests, contract tests for API endpoints
|
|
**Target Platform**: Linux server (containerized with Docker)
|
|
**Project Type**: Web application (backend API + web UI)
|
|
**Performance Goals**: Process 1000 activity files within 2 hours, sync weight data with 95% success rate, API responses under 3 seconds
|
|
**Constraints**: All sensitive data stored locally, offline-capable operation, secure storage of OAuth tokens
|
|
**Scale/Scope**: Single user system supporting personal health data synchronization
|
|
|
|
## Constitution Check
|
|
|
|
*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
|
|
|
|
Based on the project constitution, this implementation needs to follow library-first principles, exposing functionality via web API. All new features should have tests written before implementation, with integration tests for API contracts and inter-service communication. The system must include structured logging and observability for debugging.
|
|
|
|
## Project Structure
|
|
|
|
### Documentation (this feature)
|
|
|
|
```text
|
|
specs/001-fitbit-garmin-sync/
|
|
├── plan.md # This file (/speckit.plan command output)
|
|
├── research.md # Phase 0 output (/speckit.plan command)
|
|
├── data-model.md # Phase 1 output (/speckit.plan command)
|
|
├── quickstart.md # Phase 1 output (/speckit.plan command)
|
|
├── contracts/ # Phase 1 output (/speckit.plan command)
|
|
└── tasks.md # Phase 2 output (/speckit.tasks command - NOT created by /speckit.plan)
|
|
```
|
|
|
|
### Source Code (repository root)
|
|
|
|
```text
|
|
backend/
|
|
├── main.py
|
|
├── src/
|
|
│ ├── models/
|
|
│ │ ├── __init__.py
|
|
│ │ ├── config.py
|
|
│ │ ├── weight_record.py
|
|
│ │ ├── activity.py
|
|
│ │ ├── health_metric.py
|
|
│ │ ├── sync_log.py
|
|
│ │ ├── api_token.py
|
|
│ │ └── auth_status.py
|
|
│ ├── services/
|
|
│ │ ├── __init__.py
|
|
│ │ ├── fitbit_client.py
|
|
│ │ ├── garmin_client.py
|
|
│ │ ├── postgresql_manager.py
|
|
│ │ └── sync_app.py
|
|
│ ├── api/
|
|
│ │ ├── __init__.py
|
|
│ │ ├── auth.py
|
|
│ │ ├── sync.py
|
|
│ │ ├── setup.py
|
|
│ │ └── metrics.py
|
|
│ └── utils/
|
|
│ ├── __init__.py
|
|
│ └── helpers.py
|
|
├── templates/
|
|
│ ├── index.html
|
|
│ └── setup.html
|
|
├── static/
|
|
│ ├── css/
|
|
│ └── js/
|
|
├── requirements.txt
|
|
├── Dockerfile
|
|
└── docker-compose.yml
|
|
|
|
tests/
|
|
├── unit/
|
|
│ ├── test_models/
|
|
│ ├── test_services/
|
|
│ └── test_api/
|
|
├── integration/
|
|
│ └── test_sync_flow.py
|
|
└── contract/
|
|
└── test_api_contracts.py
|
|
```
|
|
|
|
**Structure Decision**: Web application structure selected to support the backend API and web UI requirements from the feature specification. The backend includes models for data representation, services for business logic, and API endpoints for user interaction.
|
|
|
|
## Complexity Tracking
|
|
|
|
> **Fill ONLY if Constitution Check has violations that must be justified**
|
|
|
|
| Violation | Why Needed | Simpler Alternative Rejected Because |
|
|
|-----------|------------|-------------------------------------|
|
|
| External API dependencies | Required for Fitbit and Garmin integration | Direct DB access insufficient for external services | |