understand-codebase

name	understand-codebase
description	Use when: onboard onto an unfamiliar or large codebase by mapping its structure, dependencies, and business logic before editing.
license	MIT

Goal: turn a codebase into a navigable knowledge graph you can explore, search, and explain — not a graph that just looks complex.

Use for:

• joining a large unfamiliar project and needing to know where to start
• learning how files, functions, and classes connect before changing one
• mapping code to business domains, flows, and process steps
• assessing which parts a change ripples into before committing

Workflow:

1. Scan the project: detect languages and frameworks, discover every file.
2. Extract structure deterministically (tree-sitter): imports, exports, function/class definitions, call sites, inheritance. Same input -> same edges every run.
3. Layer in semantics (LLM): plain-English summaries, architectural layer per node (API / Service / Data / UI / Utility), business domains and flows.
4. Build the graph — nodes are files/functions/classes, edges are dependencies.
5. Generate guided tours ordered by dependency so the codebase is learned in the right order.
6. Re-run incrementally: only re-analyze files whose fingerprint changed.

Outputs:

• structural + domain graph with nodes searchable by name and by meaning
• guided tours, layer view, and an onboarding guide for new contributors
• diff impact: which parts a current change affects

Rules:

• Keep structure deterministic; reserve the LLM for intent, summaries, and layering.
• Scope to a subdirectory for huge monorepos.
• Commit the graph so teammates skip the pipeline; refresh it on changed files.