Fundamentals

What this repo is

viz is a visual regression testing platform. It crawls sites, stores tracked pages, captures screenshots with Playwright, compares them against approved baselines and helps reviewers approve expected visual changes.

The repo is a pnpm monorepo:

• packages/types holds shared DTOs, enums and API contracts.
• apps/api is the Fastify API and Bull worker.
• apps/web is the Next.js dashboard.
• apps/docs is this public docs site.

The core rule

Execution status and visual review state are separate.

RunStatus answers: did the worker run properly?

VisualReviewState answers: do visual changes still need review?

A completed run can still need approval. Visual diffs should not be treated as worker failures.

The baseline rule

Baselines are approved screenshots for a (suite, path, viewport) key. Matching uses the URL path rather than the host, so production pages and preview URLs can be compared safely.

Baseline is the current pointer. BaselineVersion is the immutable history.

The shared contract rule

Anything that crosses the API boundary should live in packages/types. The API maps Mongoose documents into these DTOs before returning them. The web app consumes those same types.

This keeps route handlers, client hooks and docs talking about the same shapes.

Useful generated references

• API routes are generated from route comments and Fastify registrations.
• Shared contracts are generated from packages/types.
• Models are generated from the Mongoose schemas.