Architecture¶

Data Flow¶

Frontend Components → Custom Hooks → CallDebuggerContext → CallDebuggerService → S3/API
                                  → useDBCalls/useCallDbData → /api/db/* → Hyperdrive → PlanetScale

Call listings (prod): Database-backed via /api/db/calls with agent metadata, pagination
Call listings (dev): S3-backed via /api/calls (no database access in dev yet)
Call artifacts: Fetched directly from S3 URLs (logs, traffic, prompts, state, audio)
Call data (prod): Database records via /api/db/calls/:callId/data
Short URLs: /d/:callId server-side redirect to debugger

API Endpoints¶

Endpoint	Auth	Purpose
`GET /api/calls?env=&date=`	Yes	List calls from S3 (dev environment)
`GET /api/db/calls?date=&offset=&limit=`	Yes	List calls from DB with pagination
`GET /api/db/calls/summary?startDate=&endDate=`	Yes	Date range summary (counts per day)
`GET /api/db/calls/lookup?id=`	No	Lookup call by retell/arini call ID
`GET /api/db/calls/:callId/data`	Yes	Full call data with related records
`GET /d/:callId`	No	Server-side redirect to debugger

S3 Structure¶

{bucket}/{YYYY-MM-DD}/{call_id}/
  ├── logs.json       # Application logs (JSONL)
  ├── traffic.json    # WebSocket traffic - Retell API events (JSONL)
  ├── prompt.json     # LLM prompts (JSONL)
  ├── state.json      # State machine events (JSONL)
  └── recording.wav   # Call audio

Database Tables (PlanetScale)¶

retell_calls: Call metadata (retell_call_id, arini_call_id, agent info, timestamps)
calls: Arini call details (optional, may not exist for all calls)
intakes: Intake records linked to calls
intake_actions: Actions taken during intakes

Key Files¶

Location	Purpose
`src/worker/index.ts`	Worker entry point, route mounting
`src/worker/lib/db.ts`	Hyperdrive connection helper
`src/worker/modules/debug/router.ts`	Debug API routes
`src/ui/routes.tsx`	Frontend router configuration
`src/ui/modules/debug/contexts/CallDebuggerContext.tsx`	Centralized state, caching
`src/ui/modules/debug/types/debugger.ts`	TypeScript types