# How it works

The path from an expert's recording to a spider in production.

Graphdom turns recordings into a spider in five stages. Each stage reads what the one before it wrote to disk, so you can stop, inspect and resume at any point.

1. **record**: An expert does the task in Chrome. `graphdom record <url>`
1. **archive**: Events, bodies and a causal graph, on disk. `graphdom studio`
1. **sandbox**: The site, served offline from the recording. `graphdom sandbox`
1. **build**: One spider, tested on every session. `graphdom build [root]`
1. **run**: The spider on the real site. `graphdom runtime run`

## Record

The recorder drives Chrome over the DevTools Protocol and writes every network exchange, user action, snapshot and dialog of a session. It runs in a Chrome it launches (`graphdom record`) or in the expert's own Chrome through the extension (`graphdom relay`). Both write the same archive.

Passwords are never stored. Other personal data stays in clear unless you turn on redaction.

## Archive

Each session is an append-only event log plus content-addressed blobs. A deterministic builder turns the log into a graph of actions, requests, pages and values, with an edge for every cause it observed or inferred. See [The archive](/concepts/archive/).

## Sandbox

The sandbox serves a recorded session offline, so a spider can be tested without touching the real site. It has three levels:

| Level | Answers |
|---|---|
| 1 | Exactly what was recorded, in order |
| 2 | Recorded answers, tolerant of cache busters, nonces, rotating tokens and IDs the page mints |
| 3 | Generalised answers for inputs no session recorded, flagged as such |

## Build

The build derives a spider from all the sessions of a task. A spider is a graph IR: states, the steps between them, the locators each step tries in order, and the inputs, secrets and outputs it declares. The build runs each candidate in each session's sandbox and compares requests and final DOM with the recording. When a model is configured, it repairs failing candidates from their failures. A spider ships only when it passes every session.

## Run

The same IR runs on two targets with the same tests:

- **Playwright**, as a compiled script you can read and run anywhere
- **Graphdom's runtime**, which also handles closed shadow DOM, pauses before submits, and stops on drift

In production, the fleet runs spiders on a cluster: a control plane schedules jobs, pull workers run them, and sessions are kept per account. A run that meets a page it does not know reports drift instead of guessing. A CAPTCHA or new terms is handed over to a person. [The fleet](/fleet/overview/) explains how it works and how to run it.