Meridian

Fly over your codebase like a city. Meridian turns any repository into an explorable, zoomable map: every file is a building, a building's height is how often it changes (your hot spots), and the districts are your folders. On top of that structure it traces the real flows through your code (what actually happens when a user signs up, checks out, uploads a file…), and lights up the data and outside services each step touches.

It only reads your code and its local git history. It never runs, deploys, or changes anything, and it writes its output into its own folder — your repo is never touched.

Requires Node 20.12+.

---

Quick start

npm install      # one time — downloads the tools it needs
npm run go

The first time, npm run go asks you two things:

1. Which repo to map. Paste either:

   • a local folder path — e.g. /Users/you/my-app or C:\Users\you\my-app, or
   • a public Git URL — e.g. https://github.com/honojs/hono — and Meridian clones it for you.

   (For a private repo, clone it locally first and give the folder path. That needs no login; a private URL would require your own git credentials.)

2. (Optional) an AI key. Paste an OpenAI or Anthropic key to get clean, human-named flows, or just press Enter to skip — the map builds fully either way.

It saves your answers to a local, gitignored .env, builds the map, and opens it in your browser.

On later runs, it remembers and just asks you to confirm — press Enter to reuse, or n to switch:

Reuse the last repo?  C:\Users\you\my-app  [Y/n]
Reuse your saved Anthropic key for AI flow-naming?  [Y/n]

So a typical re-run after you commit code is npm run go then two Enters.

Everything Meridian generates lands in this folder's data/ and out/ — your target repo is only ever read.

---

What you'll get (it scales with the repo)

• Any repo, any language → the city, churn heights (tall = changes often), a 🔥 Risk lens, and a 🕰 Time machine that replays the repo's git history.
• JavaScript / TypeScript → the full dependency graph and blast-radius (click a building to see what it imports and everything that breaks if you change it) — any layout: a single src/, a monorepo's packages/*, lib/, etc.
• Firebase / Expo apps → the richest view: flows (real request paths through the code), collections (your data, and who reads/writes each), and external services (the off-city pills — what calls Stripe, Twilio, Sentry…). Flow detection is JS/TS-tuned today; other stacks still get the full city + dependencies.

---

Getting around the map

• Fly: scroll to zoom, drag to pan, hover any building for its details.
• Click anything to see its connections:
  • a building → what it imports, and its blast radius (what breaks if you change it)
  • a collection (the data markers below the city) → every function that reads or writes it
  • an external service (the pills off to the side) → everything that uses it
• Flows (top-left button): pick a flow, press ▶ Play, and watch one request travel through your code step by step, lighting up the data and services it touches.
• Lenses (top bar): 🔥 Risk (danger = churn × how much depends on it), 🗄 Data (pick a collection/service to see who touches it + its security rules), 🕰 Time (watch the codebase grow over its history).
• 🌙 / ☀ toggles light/dark. Links keeps dependency lines drawn while a building is selected.

---

The optional AI step

Meridian builds your map and a full set of flows with no account and no key — those flows are just named after the code (function/file names).

Optionally, an AI model can rename and group them into clean, human flows — e.g. "Sign Up", "Checkout", "Reset Password" — and connect a few steps that are hard to detect automatically. It's the only feature that uses an API key.

• Turn it on: run npm run go and paste an OpenAI or Anthropic key when asked. (Or by hand: copy .env.example to .env and add OPENAI_API_KEY=… or ANTHROPIC_API_KEY=….)
• Cost: roughly a few cents per run — one model call. You bring your own key; you're never billed through Meridian.
• Privacy: to see exactly what would be sent before sending anything, run node src/build/llmFlows.mjs --dry-run — it prints the full request and makes no API call. Only your code's structure and a few wiring snippets are sent; never secrets.
• Turn it off: answer n at the key prompt and press Enter to skip, or remove the key line from .env.
• If the key is missing, wrong, or the call fails, Meridian skips the AI step and still builds your map — it never breaks the build.

When AI is on, the Flows button shows Hybrid (AI-named flows + a deterministic backfill so nothing is dropped). With no key, it shows Max (the best purely-deterministic set).

---

How it works under the hood

A small chain of scripts, each writing a JSON file the next one reads:

census (classify files) → imports (dependency graph) → churn (git history) → assemble (combine + integrity-check) → functionTouches (what each function reads/writes/calls) → deriveFlowsMax (deterministic flows) → (optional) llmFlows → mergeFlows → atlas + city (render the single out/city.html).

Big repos are handled gracefully: tests and build output are excluded from the dependency graph (they still appear as buildings), and if a file trips the parser, Meridian salvages the rest and tells you what it skipped. The renderer has no runtime dependencies — it's plain Canvas in one self-contained HTML file you can open anywhere.