evident

Architecture maps for JS/TS and Python web apps

Every arrow on this map has a receipt.

Evident reads a codebase and draws what talks to what: routes, middleware, database tables and external services. Click anything and it shows the exact lines of code that prove it.

Or give it to your coding agent

One command adds the Evident skill to Claude Code, Codex, Cursor and other agents. It checks the blast radius before an edit and cites file:line instead of guessing.

$npx skills add aadilsal/Evident
  • 100.0% route precision
  • 100.0% route→table recall
  • 8 benchmark repos
  • 0 lines of your code executed
Request traceGET /cars/:idaadilsal/MotorAi @ c10fa5d
  1. 1GET /cars/:idapp/(main)/cars/[id]/page.jsx:28-41
  2. 2middleware.js:52 middlewareguardsmiddleware.js:52
  3. 3CarPage()handlesapp/(main)/cars/[id]/page.jsx:28-41
  4. 4Clerkusesmiddleware.js:55
  5. 5NotFound()callsapp/(main)/cars/[id]/page.jsx:33
  6. 6getCarById()callsapp/(main)/cars/[id]/page.jsx:30
  7. 7serializedCarData()callsactions/car-listing.js:300
  8. 8Carreadsactions/car-listing.js:245-247
  9. 9DealershipInforeadsactions/car-listing.js:291-295
  10. 10TestDriveBookingreadsactions/car-listing.js:270-279
  11. 11Userreadsactions/car-listing.js:240-242
  12. 12UserSavedCarreadsactions/car-listing.js:258-265

A real trace from the gallery. Each hop cites the line that creates it.

motoraiOpen full map

What GET /cars/:id touches, hop by hop. Click a box for the line of code behind it.

Why Evident

Most architecture diagrams are guesses. This one shows its work.

AI diagram tools ask a model to imagine your system from its folders. The result looks right until a box turns out not to exist. Evident extracts the facts first and lets the model do one small, checked job.

Typical AI diagram toolsEvident
Where boxes come fromAn LLM reading the file tree and READMEStatic analysis of the code
Level of detailFolders and modulesRoutes → middleware → handlers → tables, services, env vars
Proof for an arrowNonefile:line at the exact commit, one click away
AccuracyNot measuredHand-labelled benchmark, re-run in CI on every change
What the LLM decidesWhat exists and how it connectsOnly group names, over nodes that already exist; it can't add a box

How it works

Five stops from repo to map

The same pipeline runs on the web, in the CLI and in the Claude skill. Only the last stop involves an LLM, and its output is validated against the graph.

  1. 01Parse

    tree-sitter reads every file as text. Nothing is installed, imported or run.

    npm install: never · eval: never

  2. 02Extract

    Framework and ORM adapters find routes, middleware, handlers, models, SDK calls and env vars.

    route:POST /api/orders

  3. 03Link

    Imports, aliases and calls are resolved, so each route connects to the tables it touches.

    POST /api/orders → createOrder() → Order

  4. 04Check

    Health rules flag writes without auth, unvalidated bodies, import cycles and unused models.

    unguarded-write · POST /api/orders

  5. 05Group

    An LLM may only label groups of nodes that already exist. Anything else is rejected.

    group:orders (inferred)

What it answers

The questions you have on day one of a new codebase

What does this request do?

Pick a route. The path lights up through middleware, handlers and calls to every table and service it touches, with the code for each hop.

GET /cars/:id → 11 hops

What breaks if I change this?

Select a table, file or env var and see everything that depends on it before you edit it.

TestDriveBooking: 25 routes, 59 dependents

Is this endpoint safe?

Health checks flag writes with no auth guard, unvalidated request bodies, import cycles, unused models and undocumented env vars.

info ARCJET_KEY is read but not listed in .env.example.

Examples from aadilsal/MotorAi, 39 routes, 6 models, 4 services.

Accuracy

Measured, not promised

8 repos, each pinned to a commit and labelled by hand. Every engine change is scored in CI, and the build fails if any number drops by more than 2 points.

CategoryPrecisionRecallLabelled items
routes100.0%100.0%460
models100.0%100.0%26
services100.0%100.0%16
route → table edges100.0%100.0%168

Full results and history · Supports Express, Fastify, NestJS, Next.js, FastAPI, Flask, Django with Prisma, Drizzle, TypeORM, Mongoose, Django ORM, SQLAlchemy. Per-adapter scores

Three ways to use it

Same engine, wherever you work

On the web

Paste a public GitHub URL and get the map in under a minute. Every view has a link you can share, pinned to the commit.

github.com/owner/repo  →  Map this repo

In your terminal

The same engine runs offline on private code. It writes only inside .evident/ and opens this map on localhost.

evident analyze .
evident trace "POST /api/orders"
evident impact Order
evident open

In your coding agent

The Evident skill works in Claude Code, Codex, Cursor and other agents. It checks the blast radius before an edit and cites file:line instead of guessing. It installs the CLI on first use, after asking.

npx skills add aadilsal/Evident

> what breaks if I change User?
“3 routes write User: …”