How it works

This page explains Cairn's core concepts — what each part does and how they fit together. For the code-level view, see Architecture.

Flows

A flow is a real user journey through your app (e.g. "Sign in", "Checkout"). Cairn discovers flows by reading your repository — pages, layouts, routes, and code evidence — rather than recording clicks. Each flow records the routes it touches, the code that backs it, and whether it requires auth.

Flows are scoped by (repo, app root, branch), so a monorepo with several apps and a staging branch keeps its flows independent.

Tests

Each flow is turned into a complete Playwright spec — selectors, assertions, and session-based auth — generated from your actual code. You never write or maintain these by hand.

Sync on push

When you push to a tracked branch (main or staging), Cairn diffs the change, finds the affected flows, updates their tests, and writes new specs for new pages. Tests stay in lockstep with the code instead of rotting behind it. The touched flows are then run automatically so you get immediate feedback.

Runs

Tests execute in real Chromium via Playwright, on a schedule (every 20 minutes up to weekly) and on every merge to a tracked branch (after a push, Cairn re-runs just the flows the change touched). You can also run on demand from the dashboard. Each run captures video and a Playwright trace so you can replay exactly what happened. Runs are scoped to an environment (a deployed URL + branch + app root).

Issues & auto-fix

When a test fails, Cairn doesn't just flag it — it writes a root-caused issue:

It reads the run's network capture and leads with the failing API call (e.g. POST /api/billing → 500), not the Playwright assertion.
It includes likely cause, the files to check (inferred route handlers
- flow components), and a link to the replayable trace.
It classifies the failure (bug, test-bug, timeout, infra) so noise stays out of your tracker.

For real bugs, Claude triages the root cause, writes the patch, and opens a merge-ready pull request for review. Cairn never merges on its own.

API contract tracking

On every run, Cairn fingerprints the structural contract of each API response your flows touch — fields, types, status — with values stripped so normal variance isn't noise. Each run is compared to the last-green baseline. A breaking change (a field changes type, is removed, etc.) is flagged as drift and tied to the UI failure it caused. This is how a front-end break gets traced to the backend change behind it.

Security recon

A deterministic scan probes each deployed environment for exposure — exposed files, VCS leaks, source maps, admin surfaces, and secrets leaked in your client JavaScript bundles (with smart grading, so a publishable Firebase web key isn't treated like a real server key). Findings are recorded by severity (info → critical) and filed as issues for confirmed, high-severity exposures. Deeper application probes such as access-control (IDOR) testing are planned for a later phase, not part of the scan today.

Weekly recap

Once a week Cairn emails a digest of what it observed per app: pass-rate trend, regressions caught, auto-fix rate, mean time to fix, new flows, security findings by severity, and API drift — each compared to the prior week. It's the "is this getting better?" view.

Putting it together

push → sync flows/tests → run (merge + schedule) → capture network + trace
     → failure? → root-caused issue → Claude fix PR
     → API drift? → flagged + linked to the failure
     → security scan → findings by severity
     → end of week → recap email

Next: Architecture for how this is built.