How to understand a new codebase with a graph

Why is reading a codebase file by file so slow?

Flat reading has no ranking. With thousands of files, there is no way to tell which ones carry the architecture, and relationships between files appear only after you already know where to look. Notes from the effort also do not survive into the next session.

• No signal about which files are structural and which are leaf nodes.
• Cross-file relationships surface late, after context is already wrong.
• Understanding is rebuilt from scratch by every new engineer and assistant.

What should you look at first in a code graph?

Start from the centers. God nodes are the highest-degree files that everything connects through. Communities show subsystem boundaries. Then trace paths from the feature you must change to its dependencies, reading GRAPH_REPORT.md for plain-language summaries along the way.

• Begin with god nodes: the files everything depends on.
• Use community clusters to learn subsystem boundaries quickly.
• Trace paths from a feature you own to everything it touches.

How do you make onboarding stick for the next person?

Leave the map behind. A refreshed graph plus a short report turns onboarding into reading, not archaeology, and it gives AI assistants the same structured context when they answer questions later.

• Share the report and subsystem notes with the project.
• Point AI assistants at the same artifacts for consistent answers.
• Refresh after big changes so the map stays trustworthy.

What should the first 30 minutes look like?

Open graph.html before reading any file. Spend the first five minutes on the largest god nodes, the files everything depends on. Use the next ten to sketch the communities you can see and name each subsystem in your own words. Then trace one path from a feature you already understand to the parts you do not, and finish by skimming GRAPH_REPORT.md to confirm or correct the picture.

• Minutes 0-5: identify the god nodes at the center of the graph.
• Minutes 5-15: name the communities and their boundaries.
• Minutes 15-25: trace one path from known code to unknown.
• Minutes 25-30: check the picture against GRAPH_REPORT.md.

How do you choose which subsystem to read first?

Follow your work, not the folder tree. Find the community that contains the feature you were asked to change, read outward along its strongest edges, and stop when a path reaches stable, well-understood modules such as shared utilities. The goal of a first pass is a correct map plus a short list of questions, not total coverage.

• Anchor on the feature you must change, not on the entry point.
• Read outward along edges until paths hit stable modules.
• Record open questions instead of chasing every branch.

How do you make onboarding repeatable for the whole team?

Treat the graph as onboarding material. New engineers start day one from the artifacts, walk the map with a mentor, and correct anything the report gets wrong; those corrections are valuable documentation. Keeping the refreshed graph and report in the repository means the next hire, and every AI assistant, starts from the same accumulated understanding.

• Make the artifacts required reading on day one.
• Walk the map together and fix what the report misses.
• Refresh the graph after team changes or refactors so it stays honest.

How do you verify your picture of the codebase is correct?

Treat the first read as a hypothesis. Open the two files the graph calls most central and check that the reported relationships match what the code actually does. Rename clusters in your notes when the folder structure disagrees with the map, and ask a teammate one targeted question about the subsystem you understand least. Corrections are the point: they turn the map from a guess into a reference.

• Spot-check the most central files against the map.
• Rename clusters when reality disagrees with first impressions.
• Ask one targeted question and fold the answer back into your notes.