media-downloader/docs/DASHBOARD.md

Dashboard Features

Overview

The Dashboard provides real-time monitoring and control of your media downloader system with automatic refresh capabilities and quick actions for scheduled tasks.

Auto-Refresh Functionality

The Dashboard automatically refreshes data at different intervals to provide real-time updates without manual page refreshes:

Refresh Intervals

• Stats & System Status: Every 30 seconds

  • Total downloads
  • Last 24 hours activity
  • Total storage size
  • Duplicates prevented
  • Scheduler running status
  • Active WebSocket connections

• Recent Downloads: Every 10 seconds

  • Shows the latest 5 downloads
  • Includes thumbnails and metadata
  • Click thumbnails to view in lightbox

• Current Activity: Every 2 seconds

  • Real-time status of active scraping jobs
  • Platform and account being scraped
  • Elapsed time since start

• Next Scheduled Run: Every 10 seconds

  • Shows upcoming scheduled task
  • Platform and account details
  • Time until next run (relative format)

Quick Actions

Currently Scraping Controls

When a download is actively running, the Dashboard displays:

Stop Button (Red Button)

• Function: Immediately stops the running download task
• Behavior:
  • Terminates the active download process
  • Shows "Stopping..." while processing
  • Clears the current activity display
  • Returns to showing next scheduled run (if any)
  • Sends SIGTERM signal to the process
• Use Case: When you need to cancel an in-progress download

Next Scheduled Run Controls

When a task is scheduled, the Dashboard displays three action buttons:

1. Run Now (Blue Button)

• Function: Immediately triggers the scheduled download task
• Behavior:
  • Starts the download without waiting for the scheduled time
  • Shows "Starting..." while processing
  • Updates to "Currently Scraping" view when active
  • Original schedule remains unchanged
• Use Case: When you want to manually trigger a download immediately

2. Skip Run (Amber Button)

• Function: Skips the next scheduled run by advancing the next_run time
• Behavior:
  • Adds one interval period to the next_run time
  • Example: If scheduled in 2 hours with 4-hour interval, skip moves it to 6 hours
  • Shows "Skipping..." while processing
  • Updates display with new next run time
• Use Case: When you want to postpone a specific scheduled run

3. View Schedule (Gray Button)

• Function: Navigate to the Scheduler page
• Behavior: Links to full scheduler view with all tasks
• Use Case: When you need to see or manage all scheduled tasks

Statistics Cards

Total Downloads

• All-time download count
• Blue icon with download symbol
• Updates every 30 seconds

Last 24 Hours

• Recent activity count
• Green icon with activity symbol
• Updates every 30 seconds

Total Size

• Disk space used by all downloads
• Purple icon with database symbol
• Formatted in human-readable units (GB, MB, etc.)
• Updates every 30 seconds

Duplicates Prevented

• Number of duplicate files avoided
• Orange icon with trending up symbol
• Shows space savings through deduplication
• Updates every 30 seconds

Charts

Downloads by Platform

• Bar chart showing download distribution across platforms
• Platforms: Instagram (multiple methods), TikTok, Snapchat, Forums
• Responsive design adjusts to screen size
• Updates when stats refresh (every 30 seconds)

Recent Downloads

• Visual list of last 5 downloads
• Thumbnail previews (click to view full size in lightbox)
• Shows filename, platform, source, and relative time
• Updates every 10 seconds

Current Activity Display

When a download is actively running:

• Animated pulsing activity indicator
• Platform and account being scraped
• Elapsed time (relative format like "2 minutes ago")
• Blue gradient background for visibility
• Updates in real-time (every 2 seconds)

System Status

Shows three key system metrics:

Scheduler Status

• Running: Green badge - Scheduler is active
• Stopped: Gray badge - Scheduler is not running

Active Connections

• Number of active WebSocket connections
• Indicates how many users/browsers are connected

Last Update

• Timestamp of last system status update
• Relative format (e.g., "10 seconds ago")

Lightbox Viewer

Click any thumbnail in Recent Downloads to view full media:

Features

• Full-screen overlay with dark background
• Close button (X) or click outside to exit
• Displays full resolution image or video
• Video controls (play, pause, volume) for video files

Metadata Display

• Filename (with break-all to prevent overflow)
• Platform (formatted name)
• Source (username/account)
• File size (human-readable format)
• Download date (formatted)
• Resolution: Dynamically detected on load
  • Images: Natural width × height
  • Videos: Video width × height

Responsive Design

The Dashboard adapts to different screen sizes:

• Desktop (≥1024px): 4-column stats grid, full chart layout
• Tablet (≥768px): 2-column stats grid, stacked charts
• Mobile (<768px): Single column layout, optimized spacing

Performance Considerations

Efficient Polling

• Uses React Query's refetchInterval for intelligent polling
• Automatically pauses when window loses focus (browser optimization)
• Background tabs reduce polling frequency

Lazy Loading

• Thumbnails load on demand
• Images use loading="lazy" attribute
• Prevents unnecessary network requests

Caching

• React Query caches responses
• Reduces redundant API calls
• Provides instant updates when cache is valid

Best Practices

1. Keep Dashboard Open: For real-time monitoring during active scraping
2. Use Quick Actions: Avoid navigating away to trigger or skip runs
3. Monitor Stats: Watch for unusual patterns in downloads or duplicates
4. Check System Status: Ensure scheduler is running if expecting automated downloads

Troubleshooting

Dashboard Not Updating

1. Check browser console for errors
2. Verify API service is running: systemctl status media-downloader-api
3. Check WebSocket connection status in Network tab

Quick Actions Not Working

1. Ensure you're logged in with valid session
2. Check API logs: journalctl -u media-downloader-api -n 50
3. Verify scheduler service is running: systemctl status media-downloader

Stats Show Zero

1. Database may be empty or new installation
2. Run manual download to populate data
3. Check database connectivity

API Endpoints Used

• GET /api/stats - Dashboard statistics
• GET /api/status - System status
• GET /api/downloads?limit=5 - Recent downloads
• GET /scheduler/current-activity - Active scraping info
• GET /scheduler/status - Scheduler and tasks status
• POST /platforms/{platform}/trigger - Run Now action
• POST /scheduler/tasks/{task_id}/skip - Skip Run action
• POST /scheduler/current-activity/stop - Stop current download