mirror of
https://github.com/sstent/FitTrack_GarminSync.git
synced 2026-01-25 16:41:41 +00:00
65 lines
3.2 KiB
Markdown
65 lines
3.2 KiB
Markdown
# 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 |