vviz docs

Developer Docs

Architecture and Data Flow

How data moves through the API, job runners, database and browser.

Runtime pieces

apps/api/src/server.ts starts the Fastify API.

Background work is enqueued through apps/api/src/queue/index.ts:

  • Locally, jobs run in-process.
  • On Vercel (VERCEL=1, including preview), jobs are published to Vercel Queues

and handled by consumers in apps/api/api/queues/. QUEUE_BACKEND=local is ignored on Vercel.

Job runners live under apps/api/src/jobs/ (visual runs, crawls, page reruns). Scheduled recrawls are triggered by a Vercel Cron at /internal/cron/recrawl.

Suite discovery

  1. A suite is created with a baseUrl.
  2. A crawl job is queued.
  3. SiteCrawler discovers pages from sitemaps and same-origin links.
  4. Discovered pages are stored as SitePage documents.
  5. Users choose which pages are tracked.

Discovery finds candidates. Tracking decides what is tested.

Run execution

  1. RunService.startSuiteRun creates a TestRun.
  2. A job is enqueued on the visual-tests topic.
  3. The runner screenshots tracked pages with ScreenshotService.
  4. VisualComparison compares current screenshots with baselines.
  5. Results are stored as PageResult documents.
  6. RunOutcomeService finalises status, review state and GitHub check state.

Logs are stored as TestRunLog documents. The browser polls GET /test-runs/:id/logs while a run is active.

Review and promotion

Single-page approval and approve-all both go through review services.

For manual and branch runs, approval updates baselines immediately and appends a BaselineVersion.

For PR runs, approval marks the result accepted and unblocks the GitHub check. PromotionService promotes approved screenshots when the pull request is merged.

Frontend data flow

The web app uses a typed axios client and TanStack Query hooks. It does not call MongoDB directly and it does not own API types. Shared shapes come from @viz/types.

When adding a new endpoint, update the shared contract first, then the route, mapper and client hook.

Preview deployments

Web and API are separate Vercel projects linked with Related Projects so a preview web deploy talks to the matching preview API. Each preview uses an isolated Mongo database (viz_preview_pr_<n>), seeded on first boot when empty.