Skip to content

Architecture

Jump to bottom
savvy773 edited this page May 26, 2026 · 2 revisions

Architecture

Full reference: docs/architecture.md

Runtime Flow

browser
  GET  /api/usage          → render cached JSON (SSR + localStorage)
  POST /api/usage/refresh  → start or join active collection
  GET  /api/usage (poll)   → update UI when refreshState.refreshing = false

server
  spawn CLI in node-pty (pwsh.exe shell)
  wait for readiness signal
  send slash command (/usage, /status, /model)
  capture raw terminal output
  normalize ANSI/control/redraw sequences
  parse provider usage
  write data/usage-history.json + data/usage-latest.json

If a refresh takes too long, /api/usage returns the last usable payload immediately and collection continues in the background.

Key Files

Path Role
src/routes/+page.svelte Dashboard UI, refresh controls, live log panel
src/routes/+page.server.ts SSR preload for first paint
src/routes/api/usage/+server.ts Returns stored usage payload
src/routes/api/usage/refresh/+server.ts Starts or joins a refresh
src/routes/api/server/logs/+server.ts SSE log stream
src/lib/server/usage/collector.ts CLI startup, readiness, retries, raw capture
src/lib/server/usage/parser.ts Provider-specific parsing
src/lib/server/usage/refresh-manager.ts Locking, cache, history write
src/lib/server/usage/storage.ts JSON persistence
scripts/start-server.ps1 Fixed-address launcher

Provider Collection

Collection is sequential. Each provider retries up to 5 times. A failed provider does not block the next.

Setting Value
CLI working directory D:\Code\_temp
Shell pwsh.exe -NoLogo -NoProfile
Retry delays 1.5 s → 5 s → 5 s → 10 s
History bucket 10 minutes
Quick refresh wait ~2 s
Manual refresh cooldown 10 s

Data Storage

All runtime files are under data/ (git-ignored).

Path Description
data/usage-history.json Durable history — 10-min buckets, last 12 kept
data/usage-latest.json Latest API-shaped payload
data/raw/{provider}-latest.txt Last raw terminal capture
data/raw/{provider}-latest.parsed.json Last parsed snapshot with diagnostics
data/raw/{provider}-last-failure.txt Last failed/partial raw capture
data/logs/collector.log Collector diagnostics
data/logs/server-error.log Warnings and errors

usage-history.json is the source of truth. If a new refresh is weaker than the last usable snapshot, storage keeps the usable values and only updates status/message.

API Contract

GET /api/usage

Returns the latest UsagePayload:

  • providers — per-provider status, usage, reset
  • history — last 6 buckets
  • generatedAt — ISO timestamp
  • nextRefreshAt — when the next auto-refresh fires
  • refreshState — present while a refresh is running

POST /api/usage/refresh

Starts collection or joins the active one. Must send {} with Content-Type: application/json and Origin header:

Invoke-RestMethod `
  -Method Post `
  -Uri 'http://127.0.0.1:5173/api/usage/refresh' `
  -ContentType 'application/json' `
  -Headers @{ Origin = 'http://127.0.0.1:5173' } `
  -Body '{}'

See Also

Clone this wiki locally