Route graph
The route graph is the static model TrueClara uses to scope which routes and edges an experiment measures, plus Map, deploy diffs, and the broken-URL guardrail.
The route graph is generated by @trueclara/parser at build or CI time. It is the structural model of your Next.js app: routes, layouts, segments, route groups, dynamic params, and navigation edges that can be discovered from source.
Why it matters
Runtime analytics can tell you that /checkout/review received fewer visits. The graph tells TrueClara where that route sits, what changed around it, and which release shipped the changed structure — so a reward experiment knows exactly which routes and edges to scope itself to.
The graph powers:
- Map rendering.
- Path pattern matching for runtime events.
- Deploy graph diffs that scope which routes an experiment measures.
- Broken-URL guardrail checks.
- Setup health.
What the parser sees
| Input | Output |
|---|---|
app/ or pages/ route files | Route patterns such as /projects/[id]. |
| Layout files | Parent shells and route hierarchy. |
| Route groups | Grouped structure without changing public paths. |
| Navigation primitives | Edges between known routes when statically discoverable. |
| Middleware matchers | Middleware coverage and change detection. |
What the parser does not see
The parser is intentionally static. It does not execute your app, call APIs, inspect production data, or guess runtime-only destinations.
Use runtime traffic and deploy attribution to complete the picture. The graph is the frame that scopes an experiment; runtime events, tagged by arm, are the measured flow through that frame.
Upload policy
Upload the full parser output:
npx @trueclara/parser . --pretty -o trueclara-graph.json
curl -X POST https://api.trueclara.com/v1/static-graphs \
-H "Content-Type: application/json" \
-H "X-Trueclara-Project-Key: $TRUECLARA_PROJECT_KEY" \
--data-binary @trueclara-graph.jsonTreat parser failures as setup failures. An incomplete graph can make Map misleading and can mis-scope which routes a reward experiment measures.