Todd
220
docs/DASHBOARD.md
Normal file
220
docs/DASHBOARD.md
Normal file
@@ -0,0 +1,220 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user