Open source · Java · Spring Boot · Angular
Stratigraph reads a large codebase and its git history and gives you the map nobody drew: the deployables and how they depend on each other, the data model, the HTTP API, and where the risk is. Every claim points at a file and line or a commit. Every view says how much of the code it was built from.
Apache 2.0 · runs locally · no code leaves your machine
You inherit a 300,000-line Spring monolith with an Angular front end. The architecture diagram on the wiki is four years old. The people who designed the data model have left. Every change is a guess about what else it touches.
Most tools either draw boxes that look confident and are wrong, or give you a thousand lint warnings. Stratigraph is built on one rule: static analysis produces the facts, and nothing is ever asserted without a citation. When it could not see something — no JDK, an unread module, a type from a jar — it says so on the page, and withholds a view rather than draw a partial one as if it were whole.
What you get
C4 diagrams at context, container and component level. A container is a real deployable — a Spring Boot app, a WAR, an Angular or Nx application — proved by its build file or main class. Aggregator and BOM poms are grouping, not boxes. Test code is left out and counted.
Tables, columns and foreign keys from Liquibase, Flyway and SQL DDL, overlaid with JPA mappings — default naming strategies, inheritance, embedded ids, @MappedSuperclass. Where the classes and the migrations disagree, that is a finding.
Spring Data repositories, JPQL and native @Query, and JDBC SQL become read/write edges, so “what touches orders?” has a cited answer.
Spring MVC, JAX-RS, custom meta-annotations, paths built from constants, API-first controllers joined to their OpenAPI spec, Koa and Express routes — and Angular calls linked to the endpoints they hit.
Hotspots rank recent change in source files, scaled by complexity — never lockfiles or generated code. Co-change coupling finds files that move together with no dependency between them. Knowledge silos flag files one person owns that the rest of the code depends on.
Package cycles with the shortest path and the lines that close it, schema drift, hidden coupling, bus factor. Each finding cites the edges, files or commits it rests on; one that cannot is not shown.
“Built from 412 of 1,030 Java files; the Java extractor did not run: no JDK 17+.” Every diagram, ranking and answer states its coverage. Below 50%, a view is withheld with the reason instead of drawn.
Point Claude Code or any MCP client at the fact store: what_breaks_if, who_knows, where_is_table_written, find_callers, check_cycle and more — each answer cited and carrying its coverage.
--format json on every command, --fail-on severity gates, and stratigraph diff to fail a build only on findings that are new — the gate a repository with existing debt can switch on today.
The report
Self-contained, no server, no scripts, prints cleanly. These are real reports of public repositories, generated by stratigraph scan.
Use cases
Get the parts, the data model and the risky corners of a system you did not build in an hour, with every claim checkable at a file and line.
Find the seams before you cut: package cycles, co-change clusters that ignore module boundaries, and the tables each part of the code writes.
Hand new joiners a map that is regenerated from the code, not a wiki page that went stale the week after it was written.
Assess an acquisition or a vendor codebase with a scorecard of structure, risk and knowledge concentration — and an explicit statement of what could not be read.
Compare the intended structure with the real one; clusters that cut across declared modules become ADR candidates with evidence attached.
Give Claude Code or another MCP client structural answers it can cite — callers, impact, table writers — instead of letting it guess from grep.
How it works
Separate extractors parse Java/Kotlin (OpenRewrite), TypeScript/Angular (the TS compiler API) and migrations, emitting facts as NDJSON.
Nodes and edges land in a local SQLite fact store, each with a file and line. Every file gets a role — source, test, generated, migration, lockfile.
git log gives recent change, authorship and co-change, with bulk sweeps and .git-blame-ignore-revs left out.
Cycles, clusters, hotspots, schema drift and coupling become findings with citations. An optional model may name clusters — marked as inference.
HTML report, Mermaid and Structurizr diagrams, findings.md, JSON, and an MCP server — all projections of the same stored facts.
A confidently wrong dependency map is worse than no map. If a relationship cannot be cited, the answer is “no evidence found” — not a plausible guess.
For agents
Run stratigraph mcp and connect it to Claude Code, Cursor or any MCP client. Thirteen read-only tools answer structural questions from the stored facts — and every answer ends with the coverage of the view it came from, so the agent knows when an empty answer means “unknown”.
what_breaks_if — transitive dependents, the tests that reach them, the endpoints they servewho_knows — authors, share and recency, from gitwhere_is_table_written — repositories, queries and SQL, citedexplain_hotspot — every number behind a file's rankThe answer shown is illustrative; its shape is the tool's.
# what_breaks_if com.acme.billing.InvoiceService 6 element(s) depend on it within 3 hop(s): [1] com.acme.billing.InvoiceController — injects (billing/web/InvoiceController.java:38) [1] com.acme.billing.DunningJob — calls issue(Invoice) (billing/jobs/DunningJob.java:71) [2] com.acme.api.AccountResource — injects DunningJob (api/AccountResource.java:22) … 2 HTTP endpoint(s) served by impacted code: POST /api/invoices — InvoiceController#create POST /api/accounts/{id}/dunning — AccountResource#dun Coverage (architecture): Built from 1,204 of 1,230 main source files parsed (97%).
Upgrade agent
stratigraph upgrade run takes a Maven project from Boot 2.7 to 3.5, or from 3.x to 4.0. It runs OpenRewrite's recipe, then works through what the recipe leaves broken, on its own branch. Every change is rebuilt and kept only if the build gets further and no passing test turns red.
--ai claude-code), each reviewable on its own| 10 public Spring Boot apps | OpenRewrite alone | Stratigraph |
|---|---|---|
| Every test that passed before still passes, no human edits | 0 / 10 | 5 / 10 |
| Stopped at a decision that is yours to make, with options | — | 2 / 10 |
| Time per app · AI cost per app | — | 1–14 min · $0–2.54 |
| 9 more apps it had never seen: tests still passing | — | 8 / 9 |
The benchmark, per app, with what is left for each → · the unseen apps, and how thin some of their test suites are →
$ stratigraph upgrade run --to 4.0 --ai claude-code upgrade: baseline 183/183 tests pass upgrade: running …boot4.UpgradeSpringBoot_4_0 upgrade: known fix kept: generate Jakarta API code upgrade: AI attempt 2 on removed-spring-api (1 failure(s)) upgrade: needs-decision — see upgrade-report.md ## Needs your decision ### Two security filter chains match the same requests Evidence: 118 tests fail to start a context (UnreachableFilterChainException) Options: 1. Scope the API chain with securityMatcher("/api/**") 2. Merge the chains into one, rules made explicit 3. Keep one chain, if the other was dead config Recipe · 1 known fix · 3 AI fixes (authored by a model) Abridged from the spring-petclinic-reactjs run.
Measured, not asserted
stratigraph bench runs the full pipeline over a pinned corpus — Spring PetClinic and its variants, JHipster, eladmin, killbill, OpenMRS, nacos, Apache Dubbo, Spring Cloud Gateway, Spring Boot Admin, bitwarden/clients, analog and more — and scores it against ground truth labelled from the source, without the tool.
| Metric | Target | Stratigraph 2.0 |
|---|---|---|
| Non-source files (lockfiles, manifests, tests) in the hotspot top 20 | 0 | 0 |
| Hotspot top-10 overlap with a senior engineer's list | ≥ 60% | 66% |
| JPA entity recall, with the physical table name | ≥ 90% | 100% (146/146) |
| Table recall | ≥ 90% | 100% (274/274) |
| HTTP endpoint recall | ≥ 95% | 99% (519/520) |
| Dependency-injection edges resolved | ≥ 85% | 95% (215/226) |
| Deployables found as containers / containers that are deployables | 100% | 100% / 100% |
| Views rendered without a coverage statement | 0 | 0 |
Get started
# Node 18.18+; a JDK 17+ for Java code npm install -g stratigraph stratigraph doctor # what this machine can analyse stratigraph fetch-extractor # the Java extractor, checksum-verified # the whole pipeline, then open the report stratigraph scan path/to/repo --no-llm open stratigraph-report/index.html # let your agent query it stratigraph mcp --repo path/to/repo
Prefer containers? docker run --rm -v "$PWD:/repo:ro" ghcr.io/imashishsharma/stratigraph doctor
No. Extraction and history mining run entirely on your machine with no network access. The optional interpretation layer sends structural metadata to a model API only if you configure a key, and never raw source unless you pass --send-source. Everything works with --no-llm. The upgrade agent's AI fixer is opt-in (--ai claude-code): it runs the Claude Code CLI on your machine, under your own Claude account, and says so before it starts.
Java and Kotlin with Spring, Spring Boot, JPA/Hibernate, Spring Data and JAX-RS; Liquibase, Flyway and SQL DDL; TypeScript and Angular — NgModules, standalone components, routes and DI; OpenAPI specs; Koa and Express routes.
Only for the Java half, which needs a JDK 17+. Analysis never runs your build. If your Maven dependencies are already in the local cache it uses them offline for richer types; otherwise it reads source only — and says so in every view. stratigraph upgrade is the exception: upgrading means building, so it runs Maven (which downloads the new versions) on a branch of its own, and never pushes.
It builds and tests the project before touching it, so every later failure is measured against that baseline. Each failure is sorted from its log: mechanical failures get an exact known fix; judgment calls can go to the AI fixer; decisions — an authorisation rule, an HTTP contract — are never attempted and come back with the options. A change is kept only if the build gets further and no passing test turns red.
SonarQube reports rule violations file by file; Structurizr draws the architecture you describe. Stratigraph derives the architecture, data model and API from the code and its history, cites every element, and tells you how much of the code each view covers.