How do you understand the architecture of a large ROS 2 workspace?

ROS ROS General
,
1

Hi everyone,

I’m curious about how other ROS 2 developers approach understanding a large or unfamiliar workspace.

When joining an existing project or reviewing a large codebase, I often find myself asking questions like:

  • Which packages depend on each other?
  • Which nodes communicate together?
  • What topics, services, and actions are used?
  • Are there isolated nodes or communication issues?
  • Does the implementation still match the intended architecture?
  • How do you quickly get a high-level understanding before running the system?

I’m interested in learning about your workflow.

For example:

  • Which tools do you use?
  • Do you rely mostly on runtime tools such as rqt_graph, Foxglove, or RViz?
  • Do you have internal scripts or documentation that help?
  • Do you manually inspect the source code?
  • Do you perform any kind of static analysis before launching the system?
  • How do you review architectural changes in CI?

I’m particularly interested in workflows for medium-to-large industrial projects where a workspace may contain dozens (or even hundreds) of packages.

Looking forward to hearing how everyone approaches this problem and what has worked well in practice.

2 Likes
ROS News for the Week of July 27th, 2026
2

For quick orientation, I search for a README, wiki or docs folder.

When there are examples how to run the system, rqt_graph is your friend.

Regarding architectural decisions, it’s great if you find ADRs or design docs like https://design.ros2.org/ .

3 Likes
3

Thanks for sharing your workflow!

I completely agree that good documentation, READMEs, ADRs, and design documents are invaluable when they’re available. They often provide context that no automated tool can infer.

I’m particularly interested in the situations where documentation is outdated, incomplete, or missing. In those cases, how do you usually rebuild your understanding of the system?

For example, do you mostly rely on reading the source code, runtime tools like rqt_graph, or do you have any scripts or internal tooling that help you analyze the workspace?

1 Like
4

In such case, I do all of the things you mention. Plus grep, github search, blaming, debugging…

6

As a beginner, I just want to say AI is so useful that I basically don’t use my own brain anymore :smiling_face_with_tear:

7

One thing I do is to make sure all the ROS2 systems are in place (rviz2, rqt, etc) and that they work with the network and that the correct versions (Humble, Jazzy, etc) are functional in and out of the container. For instance, some wifi routers block multicast, maybe there’s a device on the network that causes a delay, maybe there’s a version mismatch with pytorch. Making sure the ground isn’t shifting during the implementation saves a lot of headaches later on. (Manually inspect the code…LOL)

8

When documentation is missing or outdated, I usually start from the launch tree rather than the node source.

The reason is that any static reading of the workspace—grep, IDE navigation, or even handing the source to an LLM—recovers the declared topology, while in ROS 2 the effective topology is assembled at launch time.

To me, the launch tree is the closest thing to an executable architecture document. I walk it first, collecting IncludeLaunchDescriptions, namespaces, remappings, parameter YAMLs, and conditional branches. Only then do I read the node source.

rqt_graph is still valuable, but I tend to treat it as a runtime snapshot rather than the architecture itself.

3 Likes
9

Thanks everyone for the feedback here. The discussion around source inspection, grep, runtime tools, and especially the launch tree helped me think more clearly about this problem.

I’ve been working on an open-source tool called ROS 2 Inspector to explore whether part of that initial architecture-discovery work can be automated.

For a first architectural pass:

ros2inspector scan .

It statically scans a ROS 2 workspace and produces a compact summary of the discovered packages, together with health signals that can help identify where deeper review may be useful.

And when you want to explore the architecture visually:

ros2inspector viz

It generates an interactive visualization of the discovered ROS 2 architecture, so you can explore nodes and their communication relationships rather than only reading a summary.

The project also includes node and connection discovery, dependency and communication graphs, launch-file analysis, architecture audits, and policy checks.

I also want to be clear that this is static analysis, not a replacement for runtime inspection. As several people mentioned here, the effective ROS 2 topology can depend on launch-time conditions, dynamic names, plugins, remappings, networking, and other runtime behavior.

My goal is more modest:

Can we make the first architectural pass over an unfamiliar ROS 2 workspace faster and easier to explore?

I’d really appreciate feedback from people working on real ROS 2 systems, especially larger workspaces.

GitHub: GitHub - aminebensaid66/ros2_inspector · GitHub
Website: https://ros2-inspector-theta.vercel.app/
LinkedIn post: ROS2 Inspector v0.1.0 Alpha Released | Amine Bensaid posted on the topic | LinkedIn

In particular, I’d be interested to know:

What would you want to see in the first summary and visualization of an unfamiliar ROS 2 workspace?