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.

2 Likes