From d8852753cc3f72e05b7ed9a8082781a72664feee Mon Sep 17 00:00:00 2001
From: Username <user@mymx.me>
Date: Wed, 24 Dec 2025 00:20:29 +0100
Subject: [PATCH] docs: add dashboard documentation

---
 documentation/dashboard.md | 169 +++++++++++++++++++++++++++++++++++++
 1 file changed, 169 insertions(+)
 create mode 100644 documentation/dashboard.md

diff --git a/documentation/dashboard.md b/documentation/dashboard.md
new file mode 100644
index 0000000..5c91360
--- /dev/null
+++ b/documentation/dashboard.md
@@ -0,0 +1,169 @@
+# PPF Dashboard
+
+Web dashboard available at `/dashboard` endpoint. Dark theme UI with auto-refresh (3s polling).
+
+## Header
+
+| Element | Description |
+|---------|-------------|
+| Checktype Badge | Current validation mode (SSL/HTTP) |
+| Profiling Badge | Shown when profiling is enabled |
+| Status Indicator | Connection status (green dot = connected) |
+| Last Update | Timestamp of last data refresh |
+
+## System Monitor Bar
+
+Real-time system resource monitoring:
+
+| Metric | Description |
+|--------|-------------|
+| Load | System load average (1m/5m/15m) |
+| Memory | RAM usage with progress bar and percentage |
+| Disk | Disk usage with progress bar and percentage |
+| Process | PPF process memory (RSS) |
+
+## Primary Stats
+
+Five key metrics displayed prominently:
+
+| Stat | Description |
+|------|-------------|
+| Working Proxies | Count of currently valid proxies (of total in database) |
+| Tests This Session | Total tests run, with passed/failed breakdown |
+| Success Rate | Percentage of successful proxy validations with progress bar |
+| Test Rate | Average tests per second |
+| Uptime | Session duration |
+
+## Charts
+
+### Test Rate History (10 min)
+- Sparkline chart showing test rate over time
+- Current rate, peak rate, pass rate indicators
+
+### Success Rate History
+- Sparkline chart showing success rate over time
+- Recent success rate indicator
+
+## Latency Analysis
+
+| Metric | Description |
+|--------|-------------|
+| Average | Mean response time |
+| Min/Max | Range of response times |
+| P50/P90/P99 | Percentile latencies |
+| Histogram | Response time distribution chart |
+
+## Protocol Performance
+
+Per-protocol statistics for HTTP, SOCKS4, and SOCKS5:
+
+| Field | Description |
+|-------|-------------|
+| Passed | Number of successful validations |
+| Tested | Total tests for this protocol |
+| Rate | Success rate percentage |
+
+## Test Results
+
+### Results Pie Chart
+- Visual breakdown of passed vs failed tests
+- Legend with counts and percentages
+
+### Failure Breakdown
+- Pie chart categorizing failure reasons:
+  - timeout
+  - refused
+  - ssl
+  - proxy (protocol error)
+  - closed (connection closed)
+  - unreachable
+  - auth (authentication required)
+  - judge_block (judge service blocked)
+  - other
+
+## Geographic Distribution
+
+### Top Countries
+- Leaderboard of countries with most working proxies (session)
+
+### Top ASNs
+- Leaderboard of autonomous system numbers with most proxies
+
+## Worker Pool
+
+| Metric | Description |
+|--------|-------------|
+| Active Threads | Current worker thread count with progress bar |
+| Job Queue | Pending validation jobs |
+
+## Judge Services
+
+| Metric | Description |
+|--------|-------------|
+| Available | Judges ready to use |
+| In Cooldown | Judges temporarily rate-limited |
+| Top Performers | Leaderboard of most successful judges |
+
+## Tor Pool
+
+| Metric | Description |
+|--------|-------------|
+| Total Requests | Cumulative Tor requests |
+| Success Rate | Tor circuit success percentage |
+| Healthy Nodes | Number of working exit nodes |
+| Avg Latency | Mean Tor circuit latency |
+| Exit Nodes | Visual grid of Tor host status |
+
+## Anonymity Levels
+
+Breakdown of proxy anonymity classifications:
+
+| Level | Description |
+|-------|-------------|
+| Elite | No proxy headers revealed |
+| Anonymous | Adds proxy headers but hides real IP |
+| Transparent | Reveals original IP address |
+
+## Search Engines
+
+Scraper engine status:
+
+| Metric | Description |
+|--------|-------------|
+| Available | Engines ready to query |
+| In Backoff | Engines temporarily rate-limited |
+| Total | Total configured engines |
+| Top Engines | Leaderboard by successful queries |
+
+## SSL/TLS Security
+
+| Metric | Description |
+|--------|-------------|
+| SSL Tests | Total SSL validations performed |
+| Passed | Successful SSL handshakes |
+| Failed | SSL validation failures |
+| MITM Detected | Proxies intercepting/modifying TLS |
+| Cert Errors | Certificate validation failures |
+
+## Database Overview
+
+### Summary Stats
+| Metric | Description |
+|--------|-------------|
+| Database Size | Total proxies in database |
+| Tested (1h) | Proxies tested in last hour |
+| Added (24h) | New proxies added in last 24 hours |
+| Dead Proxies | Proxies marked as non-working |
+
+### Working by Protocol
+- Bar chart showing working proxy counts per protocol
+
+### Top Countries (All Time)
+- Leaderboard of countries in database
+
+## Technical Details
+
+- Endpoint: `GET /dashboard`
+- Refresh: 3 second polling via JavaScript
+- Data source: `/api/stats` JSON endpoint
+- Theme: Dark mode with color-coded status indicators