Skip to main content

System overview

VideoQ separates the API that responds to user actions from time-consuming video processing. Start with the three application components in this diagram to understand each technology's role.

The frontend fetches state from the API. Once the worker saves transcripts and indexes, the frontend can use those results.

Responsibilities of the three apps​

AppResponsibilityMain code
WebDisplay, forms, question input, and playbackapps/web/src/
APIAuthentication, access control, business logic, and job requestsapps/api/src/
Python workerTranscription and indexingapps/worker/worker_python/

Web and API share operation names and input/output types through packages/trpc. SQS JSON messages and the database form the boundary with Python.

Local and production equivalents​

RoleLocalProduction
FrontendStatic nginx build or ViteCloudflare Workers Static Assets
APIWrangler development serverCloudflare Workers
DatabasePostgreSQL + pgvectorNeon PostgreSQL + pgvector
API-to-DB connectionLocal connection stringHyperdrive
Video, subtitle, and other storageGarageCloudflare R2
Job queueElasticMQAmazon SQS
Python workerContainer continuously polling the queueAWS Lambda triggered by SQS
Temporary API stateLocal Durable ObjectsCloudflare Durable Objects

Locally, Caddy routes http://localhost to the frontend and API. Development Vite uses port 3000, and the documentation site uses 3001.

Production layout​

The API reaches the shared database through Hyperdrive; the Python worker uses a PostgreSQL connection. Check both when changing database columns.

Hosted AI calls from both runtimes go through OpenRouter, authenticated with AWS workload identity federation in production. See the cloud AI runbook. On-premises deployments replace Durable Objects and hosted services as described in Run VideoQ on-premises.

Durable Object roles​

  • RATE_LIMITER: Limits excessive requests over short periods.
  • TASK_SCHEDULER: Schedules recovery of undelivered jobs and abandoned uploads.
  • CHAT_EXECUTION: Runs each chat answer in its own SQLite-backed object, so long tool loops do not depend on the ordinary Worker CPU limit. See answer streaming troubleshooting.

Recovery is scheduled with Durable Object alarms. The current cron schedule is daily at 17 3 * * * (UTC), for cleanup and recovery. Do not assume a five-minute cron schedule.

The implementation entry point is app.ts, and runtime configuration is in wrangler.jsonc.

Read next: Find your way around the code, Job delivery and recovery.