FitTrack_GarminSync/specs/004-single-sync-job.md

004-single-sync-job: Simplify Sync Job Management with Progress Tracking

Goal

To simplify the synchronization job management by allowing only one sync job to run at a time, and to provide progress tracking for this single active sync job via a polling API. This aligns with the system's single-user nature while offering better user feedback.

Motivation

The current system is designed for a single user. While the previous iteration aimed to remove all job management complexity, the need for user feedback on ongoing sync operations necessitates a simplified progress tracking mechanism. This approach avoids a full-fledged job queue and ID system but still provides visibility into the single active sync.

Proposed Changes

1. Reintroduction of a Simplified Sync Job Model

• Define SyncJob Model: Reintroduce a Pydantic model for SyncJob (e.g., in a new backend/src/sync_status.py file or similar). This model will represent the state of the single active sync job and will include fields such as:
  • status: str (e.g., "idle", "in_progress", "completed", "failed")
  • progress: float (0.0 to 1.0)
  • start_time: datetime
  • end_time: Optional[datetime]
  • error_message: Optional[str]
  • job_type: Optional[str] (e.g., "activities", "health", "workouts")

2. Introduce CurrentSyncJobManager

• Create CurrentSyncJobManager: Implement a singleton class or a global object (e.g., in backend/src/sync_manager.py) to manage the state of the SyncJob. This manager will hold the single SyncJob instance and provide methods for its lifecycle.
  • start_sync(job_type: str) -> SyncJob: Initializes a new SyncJob with "in_progress" status and the given type. Sets the start_time. Returns the SyncJob instance.
  • update_progress(progress: float, details: Optional[str] = None): Updates the progress and optionally details of the current SyncJob.
  • complete_sync(): Sets the status to "completed" and end_time for the current SyncJob.
  • fail_sync(error_message: str): Sets the status to "failed", error_message, and end_time for the current SyncJob.
  • get_current_sync_status() -> SyncJob: Returns the current SyncJob instance.
  • is_sync_active() -> bool: Returns True if a sync is currently "in_progress", False otherwise.

3. Modification of Sync Service Functions

• The _in_background functions in backend/src/services/garmin_health_service.py, backend/src/services/garmin_activity_service.py, and backend/src/services/garmin_workout_service.py will be modified:
  • They will no longer accept a job_id parameter.
  • Instead, they will receive the SyncJob instance (or a reference to the CurrentSyncJobManager) for the current operation.
  • They will use the CurrentSyncJobManager's update_progress, complete_sync, and fail_sync methods to report their status.

4. Modification of API Endpoints (backend/src/api/garmin_sync.py)

• Remove job_store and SyncJob imports from the old system.
• Import CurrentSyncJobManager and SyncJob from the new system.
• Remove /status/{job_id} endpoint: This endpoint is no longer needed as there are no individual job IDs to query.
• Modify sync initiation endpoints (/garmin/activities, /garmin/workouts, /garmin/health):
  • Before initiating a sync, check CurrentSyncJobManager.is_sync_active(). If True, return an error response (e.g., 409 Conflict) indicating that a sync is already in progress.
  • Call CurrentSyncJobManager.start_sync(job_type="...") to initialize the sync job.
  • Pass the SyncJob instance (or a reference to the CurrentSyncJobManager) to the background task.
  • Change the response_model to return the initial SyncJob status or a simple success message.
• Add New API Endpoint for Status Polling:
  • GET /garmin/sync/status:
    • Response Model: SyncJob
    • Description: Returns the current status of the single active sync job. If no sync is active, it returns an "idle" status SyncJob.

5. Update Dependencies and Main Application

• backend/src/dependencies.py: Remove any references to the old job_store and SyncStatusService.
• backend/src/main.py: Ensure the CurrentSyncJobManager is properly initialized and accessible (e.g., as a global or via dependency injection if preferred).

Impact

• Progress Tracking: Users can now poll a dedicated API endpoint to get real-time progress updates for the single active sync job.
• Clearer State: The system's state regarding sync operations is more transparent.
• Controlled Concurrency: Only one sync operation can run at a time, preventing resource contention in a single-user environment.
• Simplified API: No need to manage multiple job IDs. The status endpoint always refers to the current operation.
• Minimal Overhead: Avoids the complexity of a full-blown job queue and distributed job management system, suitable for a single-user application.