Skip to main content

Find your way around the code

VideoQ has three main parts: web displays the UI, api responds to requests, and worker runs time-consuming tasks.

Directories to learn first​

LocationResponsibilityExample changes
apps/web/React screens and user interactionsVideo lists, forms, chat UI
apps/api/Authentication, authorization, business logic, and DB accessFetching videos, editing courses, checking usage
packages/trpc/Procedure names and input/output types shared by the UI and APIAdding fields or operations to the API
apps/worker/Asynchronous Python processingTranscription and indexing
docs/English documentationUpdating instructions and design explanations
apps/docs/Documentation site configuration and Japanese translationsMenus, search, styles, translations
infra/Production infrastructure configuration and deployment documentationReviewing the operational setup

Node.js dependencies use the root package-lock.json. The Python worker uses apps/worker/pyproject.toml and uv.lock.

Trace one operation from end to end​

Start with fetching the tag list, which is smaller than the video processing pipeline.

StepFileWhat to look for
1useTags.tsWhere the UI fetches and updates data
2routers/tags.tsInputs, outputs, and login requirements for tags.list
3media-library.tsCalling the service with the user ID
4tags/service.tsCoordinating tag operations
5tag-repository.tsReading the DB within the user's scope

A contract is the input/output agreement between the caller and the API. Types flow from the shared contract, so type checking reveals which callers are affected by a change.

  • Frontend: App.tsx → pages/ → hooks/.
  • API: app.ts → trpc/context.ts → trpc/handlers/.
  • Video processing: tasks/registry.py → tasks/transcription.py → tasks/indexing.py.
  • Database: schema/index.ts → modern.ts and better-auth.ts.

Cloudflare Workers is the API runtime. apps/worker is the Python video processing service. They are separate programs with similar names.

Read next: Make your first change. For the deployment layout, see the system overview.