Architecture

🏗 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

⚙️ Collection Settings

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: Fix Checklist · API Reference