Implementation Plan: Simplify Sync Job Management with Progress Tracking

Branch: 004-home-sstent-projects | Date: Saturday, October 11, 2025 | Spec: /home/sstent/Projects/FitTrack_GarminSync/specs/004-home-sstent-projects/spec.md Input: Feature specification from /specs/004-home-sstent-projects/spec.md

Note: This template is filled in by the /speckit.plan command. See .specify/templates/commands/plan.md for the execution workflow.

Summary

The feature aims to simplify sync job management for a single-user system by allowing only one sync job at a time and providing progress tracking via a polling API. This involves reintroducing a simplified SyncJob model and a CurrentSyncJobManager to manage its state, modifying existing sync services to update this state, and creating a new API endpoint (GET /garmin/sync/status) for users to monitor progress.

Technical Context

Language/Version: Python 3.13 Primary Dependencies: FastAPI, Pydantic, garth, garminconnect, httpx Storage: In-memory for CurrentSyncJobManager Testing: Pytest Target Platform: Linux server Project Type: Web application (backend) Performance Goals:

Users can successfully initiate any sync operation and receive an initial confirmation within 2 seconds.
The GET /garmin/sync/status API endpoint responds with the current sync status within 500ms, even under moderate load (e.g., 10 requests per second).
Sync progress updates are reflected in the GET /garmin/sync/status API with a granularity that provides meaningful feedback to the user (e.g., progress updates at least every 10% completion or every 30 seconds for long syncs). Constraints: Single-user system, only one sync job active at a time. Scale/Scope: Single user, managing personal Garmin data synchronization.

Constitution Check

GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.

All gates pass. No violations.

Project Structure

Documentation (this feature)

specs/004-home-sstent-projects/
├── 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/
├── src/
│   ├── models/             # For SyncJob model
│   ├── services/           # For CurrentSyncJobManager and sync logic
│   └── api/                # For garmin_sync API endpoints
└── tests/
    ├── unit/
    ├── integration/
    └── api/

Structure Decision: The existing "Option 2: Web application" structure is appropriate and will be used. New files will be added to backend/src/models/ (for SyncJob), backend/src/services/ (for CurrentSyncJobManager), and backend/src/api/ (for the new status endpoint and modifications to existing sync endpoints).

Complexity Tracking

N/A

3.2 KiB Raw Blame History