Operator dashboard

The operator dashboard is an internal, authenticated SPA that surfaces the health of the thumbnail service. It is not customer-facing — embedders never see it — but it is a real, shipped part of the system, so it’s documented here.

Behavior

After signing in, the operator lands on a metrics view (the dashboard index; /dashboard redirects to it) that shows:

• R2 storage size — total and per-group breakdown (thumbnails, error logs, suffix-cleanup), so storage growth and cleanup are visible.
• Telemetry time-series — requests over time, cache hit/miss rates, and watermark-decision counts.
• Production health — request rates, error rates, and latency for the thumbnail Worker.
• Supporting views for analytics, reports, settings, and about, with search, sort, and refresh controls.

The data is pulled from a small set of metrics endpoints on the API Worker; the dashboard itself holds no business logic beyond presentation.

Inputs & outputs

Inputs: an authenticated operator session (Better Auth); metrics requests to /api/local-dashboard/metrics/*.

Outputs: rendered charts and tables of R2 size, telemetry summaries/ time-series, and production-health metrics.

Backing endpoints (on the API Worker):

• GET /api/local-dashboard/metrics/r2-bucket-size
• GET /api/local-dashboard/metrics/telem-r2-timeseries
• GET /api/local-dashboard/metrics/telem-summary
• GET /api/local-dashboard/metrics/prod-health

States & edge cases

• Unauthenticated — /login is the entry; an already-authenticated user hitting /login is redirected to the sanitized returnTo path (or /).
• Metric source stale — some panels depend on the video-metadata pipeline, which has been intermittently stale; affected panels can show gaps until that pipeline is repaired.
• Boilerplate routes — the underlying starter kit ships users, organization, and similar tRPC routers as stubs (TODO-marked, not wired to product logic). The live dashboard value is the metrics views above, not those stubs.

Data shape

type R2BucketSize = {
  totalBytes: number
  groups: { name: "thumbnails" | "error-logs" | "suffix-cleanup"; bytes: number }[]
  sampledAt: string
}

type TelemetrySummary = {
  windowHours: number
  requests: number
  cacheHits: number
  cacheMisses: number
  watermarkDecisions: { clean: number; wm: number }
}

type ProdHealth = {
  requestRate: number     // req/s
  errorRate: number       // 0.0–1.0
  p50LatencyMs: number
  p99LatencyMs: number
}

Open questions

• Metric provenance & richer charts. Adding provenance labels and pie/share charts is parked until the underlying operational signals (metadata pipeline, miss-path attribution) are repaired — polishing on top of stale data isn’t worthwhile yet.
• Customer-facing usage view. Whether any of this graduates into a customer-visible usage dashboard is undecided; today billing is allow-list based with no end-user metering UI. See the global Open questions.