# 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