Architecture and Data Flow

Runtime pieces

apps/api/src/server.ts starts the Fastify API and Socket.io bridge.

apps/api/src/worker.ts starts Bull processors for crawl, screenshot, diff and rerun jobs.

The API and worker communicate through MongoDB and Redis. The API stays responsive while the worker handles the expensive Playwright work.

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 Bull job is added to the test run queue.
3. The worker 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 and also published through Redis so Socket.io can stream them to the browser.

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.