Skip to content

Compute thearchitectureProve therelationships

Local-first architectural intelligenceTypeScript · TSX · Pythonv0.1.0 · M17 in progress

A local-first engine that derives a cross-language architecture graph from source, and shows the evidence behind every edge it draws.

Cartograph reads a repository’s TypeScript, TSX and Python — symbols, imports, calls, HTTP requests, route declarations and ORM models — and joins them across languages that share no symbol table. One analysis core serves a CLI, a desktop application, an MCP server and a pull-request review workflow.

Read the writeup

1994

One file. One language.

You could read the whole program.

C:\> edit hello.c
#include <stdio.h>

int main(void) {
    printf("hello, world\n");
    return 0;
}

C:\> cc hello.c && hello
hello, world

2004

A page and a server.

HTTPindex.htmlserver

2014

Then services, APIs, frameworks.

More than one language in one system.

webmobileapiauthordersqueuedbworker

Today

One request crosses three languages.

An import graph tells you which files import which. It doesn’t tell you what a request reaches.

  1. TypeScriptonSubmit()CheckoutButton.tsx
  2. HTTPPOST /api/orders
  3. Pythoncreate_order()orders.py
  4. SQLorders

Illustrative example, from the README

Surfaces

One analysis core.
Five surfaces.

Install and commands

The command line

01

cartograph . · trace · blast · diff

What a repository contains, how one relationship crosses the stack, what depends on an artefact, and what a change did to the architecture.

Command-line reference

How it works

Source in. Evidence out.

  1. Deterministic analysis first.
  2. Evidence second.
  3. Inference third.
  4. The model last, and never in the graph.

Real output

One relationship,
all the way down.

All benchmarks
  1. TypeScriptenqueueConnectionTestfunction…/requests/services.gen.ts:834
  2. Pythonenqueue_connection_testfunction…/routes/public/connections.py:383
  3. PythonConnectionTestRequestclass…/airflow/models/connection_test.py:82
  4. Databaseconnection_test_requesttable
Evidence · HTTP-CALL

POST /api/v2/connections/enqueue-test matched POST /api/v2/connections/enqueue-test at …/routes/public/connections.py:383 (enqueue_connection_test); exact HTTP method; every path segment static and equal

Real output of cartograph trace enqueueConnectionTest on Apache Airflow at 9b43d6a. Directory paths are shortened to “…”; everything else is verbatim. Select a hop to read its evidence.
$ cartograph trace enqueueConnectionTest enqueueConnectionTest  (function)  .../ui/openapi-gen/requests/services.gen.ts:834  │  ↓ HTTP-CALL   confidence 0.98   provenance route-matcher  │   evidence   POST /api/v2/connections/enqueue-test matched POST /api/v2/connections/enqueue-test  │              at .../routes/public/connections.py:383 (enqueue_connection_test);  │              exact HTTP method; every path segment static and equal  │enqueue_connection_test  (function)  .../core_api/routes/public/connections.py:383  │  ↓ ORM-ACCESS   confidence 0.80   provenance orm-resolution  │   evidence   ConnectionTestRequest(...) in enqueue_connection_test at .../connections.py:427  │ConnectionTestRequest  (class)  .../airflow/models/connection_test.py:82  │  ↓ QUERIES   confidence 0.80   provenance orm-resolution  │   evidence   ConnectionTestRequest maps to table "connection_test_request"  │connection_test_request  (table) This path crosses the HTTP boundary and reaches a database table.
Apache Airflow at commit 9b43d6a. Directory paths are shortened to “...” and the per-hop observed line is omitted; everything else is verbatim.
Apache Airflow · 9b43d6a

A TypeScript function to a database table, across three languages.

An HTTP boundary, a Python handler and a SQLAlchemy model, with no shared symbol table — and every hop carries the evidence for itself.

How the resolver works

Measured

Failures included.

The M08 report
14,932 edges labelled1 false positive among 11,221 verified3,711 (24.9%) not verifiable from sourceM08, seven pinned repositories. Every figure is an upper bound. Positions are illustrative; counts are the report's.
0.907
HttpCall recall · Airflow only · 117 of 129 operations its generated client declares that a route serves
0.744
OrmAccess recall · Airflow only · 1,401 of 1,883 import-bound uses of models that declare a table
3 of 5
End-to-end chains · Airflow only · chains whose every hop is independently readable

Recall was measured in one repository, inside a stated scope. It is not recall across the corpus and must not be quoted as such.

Principles

Unknown stays
unknown.

A plausible-looking guess is worse than a gap, because it is indistinguishable from a derived fact. Where the evidence is thin, Cartograph refuses. Contributions are welcome — real repositories that break the resolver most of all.

Contributing guide
  1. No language model constructs graph structure — not as a fallback, not as a hint, not behind a flag. A model may explain a finished subgraph, and nothing else.

    ADR-0007 →
  2. Ambiguous candidates produce no edge, a prefix that cannot be determined statically stays {unknown}, and a call to an absolute host is never joined to a local route.

    Matching →
  3. Cartograph stores the claim and how it was known. The domain model will not construct an edge without its provenance, confidence and evidence.

    ADR-0004 →
  4. No accuracy or performance claim without a benchmark run on this codebase, and failures are published alongside successes.

    Benchmarks →
  5. No source code leaves the machine. AI is opt-in per repository and off by default; Cartograph is fully useful with no API key and no network.

    Security →

Corpus

Measured on seven pinned
production repositories.

  • Superset
  • PostHog
  • Zulip
  • Onyx
  • Airflow
  • AutoGPT
  • Full-stack FastAPI