I recently joined a firmware team working on a roughly 50,000-line C++ codebase. The project uses a lot of asynchronous behavior and multiple layers of interacting state machines. Several teams in different countries contribute to it, and some modules are shared with other projects, so tracing dependencies and runtime behavior has become increasingly difficult.
I've been asked to create an internal tool that helps developers understand the system when they start working on a bug or feature. I'm considering generating flowcharts and sequence diagrams, but I'd like to know whether there's a good way to connect those smaller diagrams into a navigable, higher-level overview.
What formats or modeling approaches work well for representing a large codebase holistically? I'd also appreciate suggestions for storing the intermediate information used to generate the diagrams. The exploration and documentation will likely be assisted by coding agents, so I'm considering a phased process to reduce inaccurate conclusions. Ideally, the result would show task entry points, component responsibilities, execution handoffs, dependencies, and known areas that are risky to modify.
3 Answers
For the intermediate representation, use structured data rather than storing only rendered images. A graph model with nodes for modules, classes, functions, tasks, states, and events, plus typed edges such as calls, owns, publishes, consumes, or transitions-to, gives you more options later. Store source locations and confidence levels with each fact, and regenerate the graph incrementally when relevant files change. Then render different views from the same data: architecture, dependencies, sequence paths, and state transitions.
Be careful about documenting the entire system as one giant flowchart. It will be unreadable and will become stale as soon as the code changes. A better approach is to generate dependency graphs from the source, then create focused maps for important execution paths, feature areas, and state-machine transitions. Developers usually need the path for the task they’re investigating, not a complete map of the whole application.
A C4-style model is a good foundation: start with the system and major subsystems, then allow people to drill down into containers, components, and selected implementation details. Use sequence diagrams for important runtime paths rather than trying to draw every interaction. Mermaid or another text-based diagram format can work well because the files are reviewable and easy to regenerate.
I’d keep the high-level diagrams stable and link them to generated, source-derived details. Otherwise the overview becomes just as difficult to maintain as the code.
You can run parts of this in CI, but treat the output as generated evidence rather than unquestioned truth. Have the agent cite the files and symbols supporting each relationship, and require human review for behavioral claims.