claude-code-proxy icon indicating copy to clipboard operation
claude-code-proxy copied to clipboard

Add Apple Screen Time-inspired usage dashboard with virtual scrolling

Open ejc3 opened this issue 4 weeks ago • 0 comments

Note: This PR should be merged after #20 (request comparison feature)

Overview

This PR adds a comprehensive usage analytics dashboard inspired by Apple Screen Time, along with performance optimizations for displaying thousands of API requests.

Screenshot 2025-11-29 at 1 00 26 PM

New Features

📊 Usage Dashboard

A visual analytics interface showing Claude API usage patterns:

Weekly View

  • Bar chart showing token usage by day (Sunday-Saturday)
  • Color-coded by model (Purple=Opus, Blue=Sonnet, Green=Haiku)
  • Hover tooltips with per-model breakdown
  • Average usage line indicator
  • Displays total week usage

Today by Hour

  • Hourly activity distribution throughout the day
  • Current time indicator (vertical line at present hour)
  • Per-model breakdown in each hour
  • Identify peak usage times

Model Statistics

  • Horizontal bars showing proportional usage across models
  • Total tokens and request counts per model
  • Visual comparison of model distribution

Summary Metrics

  • Total tokens with K/M formatting
  • Request count
  • Average response time
  • Average tokens per request

⚡ Virtual Scrolling

  • Handles 5000+ requests without browser freezing
  • Only renders visible items + 10 overscan
  • Smooth 60fps scrolling
  • Uses TanStack Virtual v3.13.12

🗓️ Smart Date Navigation

  • Previous/Next day buttons
  • Shows "Today" when viewing current date
  • Shows date (e.g., "Nov 29") for other dates
  • Consistent labeling in selector and dashboard

🔧 New API Endpoints

  • GET /api/stats/hourly?start={UTC}&end={UTC} - Hourly breakdown
  • GET /api/stats/models?start={UTC}&end={UTC} - Model statistics
  • GET /api/requests/summary?start={UTC}&end={UTC} - Lightweight summaries
  • GET /api/requests/{id} - Single request details
  • GET /api/stats?start={UTC}&end={UTC} - Enhanced with per-model breakdowns

🌍 Timezone Handling

  • Browser calculates local day boundaries → UTC timestamps
  • Backend timezone-agnostic (receives exact UTC ranges)
  • SQLite uses datetime() for proper comparisons
  • "Today" always correct regardless of timezone

🗄️ Database Improvements

  • WAL mode for concurrent access
  • 5000ms busy timeout prevents lock errors
  • Per-model statistics in aggregates
  • Cache tokens included in calculations

Performance

Before: 5000 requests → 30s browser freeze
After: Instant render, 60fps scrolling

Stats loading: 3 parallel requests in ~200ms
Week navigation: 3x faster (only reloads when changing weeks)

Implementation

Frontend:

  • UsageDashboard.tsx - Dashboard component
  • UsageDashboard.css - Custom styling
  • Virtual scrolling with useVirtualizer
  • getLocalDayBoundaries() for timezone calc
  • Parallel stats loading

Backend:

  • GetHourlyStats() - Hourly breakdown with models
  • GetModelStats() - Model aggregates
  • Enhanced GetStats() with per-model data
  • All queries use datetime() for timezone awareness

Testing

✅ 5000+ requests
✅ Multiple timezones (PST/EST/UTC)
✅ Week navigation
✅ Model filtering
✅ Concurrent DB access

Breaking Changes

None - fully backward compatible

ejc3 avatar Nov 29 '25 21:11 ejc3