⚡ Phase 2 Sprint Report
Batch Download Manager — Structured Lifecycle, Pause/Resume, Cooldown
13/13 Complete
3 New Endpoints
6 Batch States
Feb 2026
Phase 2 Complete — 13/13 Tasks Delivered (100%)
3 new API endpoints · 6 batch states · 22 acceptance criteria · All passing
13
Tasks Done
3
New Endpoints
6
Batch States
5 min
Default Cooldown
📋 Sprint Summary
Phase 2 replaces the fire-and-forget download approach with a Batch Download Manager that organizes downloads into structured batches with a defined lifecycle, operator controls, and real-time visibility. This builds on Phase 1's error classification and circuit breaker to deliver a fully operator-controlled auto-download system.
FC-26 Stats Capture — Auto-Download System Improvements · Sprint Date: 2026-02-15 · Branch: feat/auto-download-phase2
🚀 Key Capabilities
Batch Lifecycle
Downloads organized into batches: collect ready videos, download with concurrency control, enforce cooldown, then repeat. Clear start/end boundaries for every batch.
Pause/Resume
Operators can pause batch processing at any time. In-flight downloads complete gracefully. Resume starts the next batch immediately.
Cooldown Pacing
Configurable batch_cooldown_minutes (default: 5) enforces breathing room between batches, reducing YouTube bot detection risk.
Batch Progress UI
Real-time batch progress bar in YouTube Monitor: batch number, per-item status, cooldown countdown, pause/resume controls.
🔧 What We Built
2.1 BatchDownloadManager (Story 2.1)
New class that manages the batch lifecycle. Replaces the fire-and-forget autoDownloadNewVideos() with structured batch operations.
| Capability | Description |
|---|---|
| Batch collection | Queries for not_downloaded videos, groups into batch up to youtube_max_parallel_downloads size |
| Lifecycle management | Drives batches through collect → download → cooldown → repeat |
| Cooldown enforcement | Waits batch_cooldown_minutes between batches (configurable, default 5) |
| Pause/resume | Operator can pause processing; in-flight downloads complete gracefully |
| Circuit breaker integration | Batch transitions to circuit_broken when Phase 1 circuit breaker trips |
| State tracking | In-memory batch state exposed via API for UI consumption |
2.2 Batch Visibility (Story 2.2)
| Endpoint | Method | Purpose |
|---|---|---|
| /api/youtube/batch/status | GET | Current batch state, progress counts, item list |
| /api/youtube/batch/pause | POST | Pause batch processing |
| /api/youtube/batch/resume | POST | Resume batch processing |
2.3 Batch States
collect download cooldown
idle ---------> collecting ---------> downloading ---------> cooldown ---------> idle
| | |
v v v
paused paused paused
|
v
circuit_broken
| State | Meaning |
|---|---|
| idle | No batch running. Shows last batch summary if available. |
| collecting | Querying for ready videos. UI: "Preparing batch..." |
| downloading | Batch actively downloading. Progress bar + per-item status. |
| cooldown | Waiting between batches. Countdown timer displayed. |
| paused | Operator paused. Resume button available. |
| circuit_broken | Circuit breaker tripped. Reset in circuit breaker section. |
📋 Task Breakdown — 13/13 Complete
✅ 1. Implement BatchDownloadManager class (Story 2.1) Backend Dev
✅ 2. Add batch API endpoints (Story 2.2 backend) Backend Dev
✅ 3. Build batch progress UI (Story 2.2 frontend) Frontend Dev
✅ 4. Design batch UI component specs UI Designer
✅ 5. Validate operator workflow UX Researcher
✅ 6. Write unit tests for BatchDownloadManager QA Engineer
✅ 7. DB migration and config registry updates DevOps
✅ 8. Update operator runbook for Phase 2 BA
✅ 9. Write PRFAQ document BA
✅ 10. Code review all Phase 2 changes Reviewer
✅ 11. Build sprint report BA
✅ 12. Build sprint demo page BA
✅ 13. Update fc26-reports index BA
✅ Acceptance Criteria Scorecard
Story 2.1: BatchDownloadManager
AC-2.1.1
BatchDownloadManager extracts batch logic from autoDownloadNewVideos()
PASS
AC-2.1.2
Batch lifecycle: collect → download → cooldown → repeat
PASS
AC-2.1.3
batch_cooldown_minutes config (default: 5) in registry
PASS
AC-2.1.4
6 batch states tracked in memory
PASS
AC-2.1.5
Phase 1 circuit breaker integration
PASS
AC-2.1.6
Phase 1 error classifier integration
PASS
AC-2.1.7
Pause/resume controls
PASS
AC-2.1.8
Graceful in-flight completion on pause
PASS
AC-2.1.9
Server restart: resumeInterruptedDownloads()
PASS
Story 2.2: Batch Visibility
AC-2.2.1
GET /api/youtube/batch/status returns state, progress, items
PASS
AC-2.2.2
POST /api/youtube/batch/pause
PASS
AC-2.2.3
POST /api/youtube/batch/resume
PASS
AC-2.2.4
Batch progress bar (number, counts, state)
PASS
AC-2.2.5
Per-item download progress
PASS
AC-2.2.6
Pause/resume buttons with confirmation
PASS
AC-2.2.7
Cooldown countdown timer (MM:SS)
PASS
AC-2.2.8
Positioned between circuit breaker and connection card
PASS
AC-2.2.9
Collapsible "Last Batch" in idle
PASS
AC-2.2.10
Batch completion reason displayed
PASS
UX Refinements
UX-1
"Collecting" renamed to "Preparing batch..."
PASS
UX-2
Pause confirmation popup; one-click resume
PASS
UX-3
Adaptive polling intervals by state
PASS
🏗️ Architecture
Batch Lifecycle Flow
AutoSyncService.runSync()
|
v
BatchDownloadManager.startBatch()
|
+--> Phase 1: COLLECT
| Query DB: download_status = 'not_downloaded', is_live = false
| Limit: youtube_max_parallel_downloads (default 9)
| State: collecting
|
+--> Phase 2: DOWNLOAD
| Start all collected videos (existing semaphore handles concurrency)
| Track per-item progress via Phase 1 progress throttle
| State: downloading
| On circuit breaker trip --> State: circuit_broken (STOP)
| On operator pause --> State: paused (STOP)
|
+--> Phase 3: COOLDOWN
| Wait batch_cooldown_minutes (default 5 min)
| State: cooldown
| On operator pause --> State: paused (STOP timer)
|
+--> Phase 4: REPEAT or IDLE
More videos? --> Back to Phase 1
No more? --> State: idle (with lastBatch summary)
Integration with Phase 1
BatchDownloadManager
+---> uses DownloadErrorClassifier (Phase 1)
+---> uses DownloadCircuitBreaker (Phase 1)
+---> uses ProgressThrottle (Phase 1)
File Structure
| File | Change | Purpose |
|---|---|---|
| batchDownloadManager.ts | New | Batch lifecycle, state, pause/resume |
| youtubeMonitorService.ts | Modified | Delegates to BatchDownloadManager |
| youtube/routes.ts | Modified | New batch endpoints |
| config/registry.ts | Modified | batch_cooldown_minutes setting |
| YouTubeMonitor.tsx | Modified | BatchProgressSection component |
| auto-download-runbook.md | Modified | Section 6: Batch Manager |
| phase2-prfaq.md | New | PRFAQ document |
| phase2-batch-ui-design.md | New | UI design spec |
Data Contract
interface BatchStatus {
state: 'idle' | 'collecting' | 'downloading' | 'cooldown' | 'paused' | 'circuit_broken';
batchNumber: number | null;
totalItems: number;
completedItems: number;
failedItems: number;
cooldownEndsAt: string | null;
pausedAt: string | null;
items: BatchItem[];
lastBatch: { completedAt, total, succeeded, failed, reason, items } | null;
}
interface BatchItem {
videoId: string;
title: string;
status: 'queued' | 'downloading' | 'downloaded' | 'failed' | 'skipped';
progress: number | null;
error: string | null;
}
📈 Sprint Metrics
| Deliverable | Type | Status |
|---|---|---|
| batchDownloadManager.ts | New backend service | Complete |
| Batch API endpoints (3) | Backend routes | Complete |
| BatchProgressSection | Frontend UI | Complete |
| Config: batch_cooldown_minutes | Configuration | Complete |
| Unit tests | Test suite | Complete |
| Operator runbook (Section 6) | Documentation | Complete |
| PRFAQ document | Documentation | Complete |
| UI design spec | Design | Complete |
| Sprint report + demo | Reports | Complete |
Phase 1 vs Phase 2 Comparison
| Metric | Phase 1 | Phase 2 |
|---|---|---|
| Scope | Error handling + protection | Batch lifecycle + visibility |
| New endpoints | 3 | 3 |
| Download model | Fire-and-forget w/ classification | Structured batches w/ cooldown |
| Operator control | Circuit reset, retry | Pause/resume, batch monitoring |
| UI states | 3 | 6 |
| Pacing | Per-download delay only | Per-download + batch cooldown |
📖 Operator Runbook (Phase 2)
| Scenario | Action |
|---|---|
| Check batch progress | GET /api/youtube/batch/status |
| Pause all downloads | POST /api/youtube/batch/pause |
| Resume downloads | POST /api/youtube/batch/resume |
| Change cooldown | PUT /api/settings/batch_cooldown_minutes |
| Batch stuck in circuit_broken | Fix cookies → reset circuit breaker → auto-resumes |
📰 PRFAQ
Press Release
FC-26 Stats Capture Introduces Batch Download Manager
Harare, Zimbabwe — February 2026 — FC-26 Stats Capture today announced the Batch Download Manager — a structured download lifecycle that replaces the previous fire-and-forget approach with batch-level visibility, operator controls, and automatic pacing.
The Problem: Downloads ran as individual fire-and-forget operations. Operators had no way to see batch-level progress, pause or resume as a group, or control pacing between cycles.
The Solution: The Batch Download Manager wraps downloads into collect → download → cooldown → repeat, with pause/resume at any stage.
FAQ
Q1: What is batch download management?
Organizes video downloads into structured groups with visibility and control, rather than firing them individually.
Q2: How does cooldown work?
After a batch finishes, the system waits batch_cooldown_minutes (default 5) before the next batch. Configurable at runtime.
Q3: Can I pause and resume?
Yes. Pause via API or UI. In-flight downloads complete, no new batch starts. Resume is one-click.
Q4: Circuit breaker interaction?
3 consecutive cookie_expired errors trip the circuit → batch goes to circuit_broken. Auto-resumes when circuit resets.
Q5: Server restart during a batch?
Batch state is in-memory, lost on restart. Videos mid-download are reset by resumeInterruptedDownloads() and re-queued.
Q6: Configuration settings?
youtube_max_parallel_downloads (default 9) controls batch size. batch_cooldown_minutes (default 5) controls wait time. Both runtime-changeable.