Phases 3-5 Demo
Smart Retry, Download Schedule & History Timeline
Visual Walkthrough
UI Mockups
Operator Guide
1. Smart Retry — UI Mockups
Feed Item with Active Retry
+------------------------------------------------------------------+
| EA FC 25 - Match vs Arsenal |
| Published: Feb 14, 2026 at 20:15 |
| |
| Status: FAILED Retry 1/3 Next retry in 12m |
| Error: Connection timed out (transient) |
| |
| [Retry Now] [Skip] [View Details] |
+------------------------------------------------------------------+
Feed Item with Exhausted Retries
+------------------------------------------------------------------+
| EA FC 25 - Weekend League Highlights |
| Published: Feb 13, 2026 at 18:00 |
| |
| Status: FAILED Max retries reached (3/3) |
| Error: HTTP Error 500: Internal Server Error |
| Last retry: Feb 14 at 09:15 |
| |
| [Retry Now (resets counter)] [Skip] [View Details] |
+------------------------------------------------------------------+
Retry Badge States
| State | Badge Display | Color |
|---|---|---|
| 1st retry pending | Retry 1/3 · Next retry in 14m | Orange |
| 2nd retry pending | Retry 2/3 · Next retry in 48m | Orange |
| 3rd retry pending | Retry 3/3 · Next retry in 3h 52m | Orange |
| Retries exhausted | Max retries reached (3/3) | Red |
| No retries (success) | No badge shown | — |
| Permanent failure | Skipped (permanent) | Yellow |
2. Download Schedule — UI Mockups
Schedule Settings Panel
+------------------------------------------------------------------+
| DOWNLOAD SCHEDULE [Collapse] |
| ---------------------------------------------------------------- |
| |
| Enable schedule: [ON] |
| |
| Timezone: [Africa/Johannesburg (UTC+2) v] |
| |
| Active days: |
| [Mon] [Tue] [Wed] [Thu] [Fri] [Sat] [Sun] |
| |
| Download window: [22] : 00 -- [08] : 00 |
| (overnight window: 22:00 to 08:00) |
| |
| [Save Schedule] |
+------------------------------------------------------------------+
Outside-Window Warning Banner
+------------------------------------------------------------------+
| ⚠ Downloads paused: outside schedule window |
| Downloads resume at 22:00 SAST today |
| |
| [Download Now (ignore schedule)] |
+------------------------------------------------------------------+
Schedule States
| State | Indicator | Downloads |
|---|---|---|
| Schedule disabled | No indicator shown | Allowed anytime |
| Within window | Downloads active (schedule window) | Allowed |
| Outside window | Paused: outside schedule window | Blocked (unless override) |
| Override active | Manual download in progress | Single batch allowed |
3. Download History Timeline — UI Mockup
Timeline View
+------------------------------------------------------------------+
| DOWNLOAD HISTORY [Collapse] |
| ---------------------------------------------------------------- |
| |
| Filter: [All events v] From: [2026-02-14] To: [2026-02-15]|
| |
| ● download_completed Match vs Arsenal 2m ago |
| 720p, 1.2 GB, 45s download time |
| |
| ● retry_scheduled Weekend League Highlights 5m ago |
| Retry 2/3, next attempt in 1h (backoff) |
| |
| ● download_failed Weekend League Highlights 5m ago |
| Error: Connection timed out (transient) |
| |
| ● batch_completed Batch #3 6m ago |
| 8 completed, 1 failed, 0 skipped |
| |
| ● batch_started Batch #3 (9 videos) 12m ago |
| |
| ● schedule_blocked Auto-sync skipped 2h ago |
| Outside window (resumes at 22:00 SAST) |
| |
| ● circuit_tripped 3 consecutive cookie errors 4h ago |
| Auto-reset in 30 minutes |
| |
| [Prev] Page 1 of 3 [Next] |
+------------------------------------------------------------------+
Event Type Icons & Colors
| Event Type | Icon | Color |
|---|---|---|
| download_started | Play | Blue |
| download_completed | CheckCircle | Green |
| download_failed | AlertCircle | Red |
| download_skipped | SkipForward | Yellow |
| circuit_tripped | ShieldAlert | Red |
| circuit_reset | ShieldAlert | Green |
| batch_started | Download | Blue |
| batch_completed | CheckCircle | Green |
| retry_scheduled | RotateCcw | Orange |
| schedule_blocked | Clock | Amber |
4. Architecture — Data Flow
AutoSyncService (timer: every N min)
|
+---------+---------+
| |
Schedule Check syncYouTubeContent()
(isWithinSchedule) |
| New videos?
Outside? ------> log schedule_blocked
| |
Within? <--------+------+
|
BatchDownloadManager.startBatch()
|
+---------+---------+---------+
| | | |
Video 1 Video 2 Video 3 ... Video N
| | | |
downloadVideo() for each (sequential, with delay)
|
+----+----+
| |
SUCCESS FAILURE
| |
log event classifyError()
record |
success +----+----+----+
| | |
permanent transient cookie
| | |
SKIP RETRY? circuit
log count++ breaker
event compute check
backoff
log retry_scheduled
|
next_retry_at stored in DB
|
(picked up by next sync cycle)
5. Operator Guide
5.1 Smart Retry — What You Need to Know
- Automatic recovery: When a download fails due to a network issue or temporary error, the system schedules an automatic retry. You'll see an orange "Retry 1/3" badge on the feed item.
- Escalating wait times: Each retry waits longer: 15 minutes, then 1 hour, then 4 hours. This avoids hammering a server that's having issues.
- Max 3 attempts: After 3 failed retries, the item shows "Max retries reached" in red. You can manually retry (which resets the counter) or skip the video.
- Permanent failures skip retries: Videos that are deleted, private, or copyright-blocked are immediately marked as "skipped" — no retries wasted.
5.2 Download Schedule — Setup Guide
- Open YouTube Monitor in the operator dashboard
- Expand the "Download Schedule" section
- Toggle "Enable schedule" to ON
- Select your timezone (default: Africa/Johannesburg)
- Check the days you want downloads to run (all days by default)
- Set the time window (default: 22:00 to 08:00 = overnight)
- Click "Save Schedule"
- When outside the window, you'll see an amber banner. Use "Download Now" for urgent downloads.
5.3 Download History — Checking What Happened
- Open YouTube Monitor and expand the "Download History" section
- By default, you see the most recent events across all types
- Use the event type filter to focus on specific events (e.g., "download_failed" to see all failures)
- Use the date range picker to look at a specific time period
- Click on an event to see its details (error messages, retry counts, batch info)
- Use pagination to browse older events
5.4 Common Scenarios
| Scenario | What to Do |
|---|---|
| Video keeps failing after 3 retries | Check the error in download history. If it's a network issue, wait and retry manually. If it's a server error, check YouTube status. |
| Downloads not starting during the day | Check if schedule is enabled. If so, either wait for the window or use "Download Now". |
| Want to see overnight activity | Open Download History, set date range to last night, review the timeline. |
| Circuit breaker tripped during retry | Same as before: refresh cookies, reset circuit breaker. Retries will resume on next cycle. |
| Too many retries consuming bandwidth | Reduce max_retry_attempts via settings API, or increase the backoff by modifying retry intervals. |
6. API Reference
GET /api/youtube/download-history
Retrieve paginated download event history with optional filters.
curl example
curl -H "Authorization: Bearer <token>" \
"http://localhost:3002/api/youtube/download-history?page=1&limit=20&event_type=download_failed&from=2026-02-14"Response
{
"data": [
{
"id": "a1b2c3d4-...",
"feed_item_id": "e5f6g7h8-...",
"event_type": "download_failed",
"details": {
"videoId": "dQw4w9WgXcQ",
"title": "Match vs Arsenal",
"error": "Connection timed out",
"errorCategory": "transient",
"retryCount": 1
},
"created_at": "2026-02-15T10:30:00.000Z"
}
],
"meta": {
"total": 5,
"page": 1,
"limit": 20,
"totalPages": 1
}
}POST /api/youtube/batch/start-now
Start a download batch immediately, ignoring the schedule window.
curl example
curl -X POST -H "Authorization: Bearer <token>" \
http://localhost:3002/api/youtube/batch/start-nowResponse
{
"ok": true,
"message": "Batch started (schedule override)"
}Complete Endpoint List (Phases 1-5)
| Method | Endpoint | Phase | Purpose |
|---|---|---|---|
| GET | /api/youtube/downloads/circuit-status | 1 | Circuit breaker state |
| POST | /api/youtube/downloads/circuit-reset | 1 | Reset circuit breaker |
| GET | /api/youtube/batch/status | 2 | Batch progress |
| POST | /api/youtube/batch/pause | 2 | Pause batch |
| POST | /api/youtube/batch/resume | 2 | Resume batch |
| GET | /api/youtube/download-history | 5 | Event history |
| POST | /api/youtube/batch/start-now | 4 | Schedule override |