services/backup_service/USAGE.md

# Example usage in routes and app.py

"""
In app.py (startup):

    from services.drive_service import DriveService
    from services.backup_service import initialize_backup_service
    
    drive_service = DriveService()
    backup_service = initialize_backup_service(
        drive_service,
        min_interval_seconds=30  # 30 seconds between backups
    )

In routes (e.g., payments.py):

    from fastapi import BackgroundTasks
    from services.backup_service import get_backup_service
    
    @router.post("/verify")
    async def verify_payment(background_tasks: BackgroundTasks, ...):
        # ... payment logic ...
        
        # Trigger backup in background (non-blocking)
        backup_service = get_backup_service()
        background_tasks.add_task(backup_service.backup_async)
        
        return {"success": True}

In app.py (shutdown):

    from services.backup_service import get_backup_service
    
    @app.on_event("shutdown")
    async def shutdown():
        backup_service = get_backup_service()
        # Force backup on shutdown (ignore debouncing)
        await backup_service.backup_async(force=True)

How it works:

1. User A pays → backup starts in background
2. User B pays (1s later) → sees backup in progress, skips
3. User C pays (2s later) → sees backup in progress, skips
4. Backup completes (5s)
5. User D pays (10s after first) → only 10s elapsed, skips (debounce)
6. User E pays (35s after first) → 35s > 30s, new backup starts!

Benefits:
- ✅ No concurrent uploads
- ✅ Response returns immediately
- ✅ Minimal Drive API usage
- ✅ No wasted resources
"""