How can I build a useful visual map of a large, asynchronous C++ codebase?
Asked by
MellowCedar47
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.
Answers
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.
Reply to this answer
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.
KindlyQuartz5: 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.
Reply to this answer
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.
Reply to this answer
Add your answer
Answers are reviewed before publication.
SilverPond21: 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.