Implementation Plan: Fitbit-Garmin Local Sync

Branch: 001-fitbit-garmin-sync | Date: December 22, 2025 | Spec: 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)

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)

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

4.6 KiB Raw Blame History