What it is
A map of a codebase generated by static analysis. It reads the source with the TypeScript compiler and Python's own parser, resolves every import through the project's real config, and draws one diagram per folder with Pele. The same commit always produces the same page; nothing is guessed by AI.
Reading a view
Each view is one folder. Bands run top to bottom:
- Dependents · outside
- What uses this folder from elsewhere.
- Frame
- The folder itself. Its parts sit in tiers from Ln · Entry (nothing in here uses it) down to L0 · Base (uses nothing else in here). A part sits one tier above the highest thing it imports or calls.
- Dependencies · outside
- Other code in the repo this folder uses.
- External dependencies
- Every third-party package the code imports. Known drivers and SDKs are named by the system they reach, such as PostgreSQL or Stripe.
A dashed red box is an import cycle: its parts import each other, so they share a tier.
Boxes and lines
- Border colour
- Green library, blue service, pink app. Dashed boxes are outside the current folder.
- +
- The box has inner parts you can zoom into.
- Lines
- Import (solid), RPC call (thick), HTTP call (blue dashed), event subscription (amber, dot end), external dependency (grey dotted). Each points from the part that depends to the part it depends on.
Roles
A package is a folder with a package.json and tsconfig.json, or a pyproject.toml. Its role comes from a declared type when there is one (Backstage catalog-info.yaml, Nx project.json), otherwise from the code:
- App
- An entry file that nothing imports mounts a UI.
- Service
- An entry file starts a server or worker, or there is a Dockerfile or start script.
- Library
- None of those: it only runs inside something else.
Findings
Fixed rules over the same facts. Severity: design issue, smell, worth checking.
Controls
- Click
- A box or line to inspect it. Lines list the files and names behind them.
- Double-click
- A box marked + to zoom in. Empty space in a band to fit it. Outside every band to zoom out.
- Drag, scroll, pinch
- Pan and zoom. Ctrl or ⌘ with scroll zooms.
- Legend
- Click a line type to switch it between always shown and shown only for the hovered box.
- Esc
- Clear the selection, then zoom out a level.
Running it
npx repo-blueprint build <repo> writes a standalone HTML file. npx repo-blueprint watch <repo> serves it and rebuilds on code changes. A repo can name more external systems, add message-bus method names and folder-role hints in a .blueprint.json at its root.