# 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