# darshan-stack/ros2_watch architecture

> Architecture diagram of the GitHub repository darshan-stack/ros2_watch, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/darshan-stack/ros2_watch
- Repository: https://github.com/darshan-stack/ros2_watch

## Overview

This repository is a **Python-based CLI tool** that runs **inside a sourced ROS2 environment** and provides **unified health monitoring + debugging** for ROS2 robotic systems.

- introspects the **ROS2 graph** (nodes/topics/QoS),
- optionally observes message flows to approximate **end-to-end latency**,
- analyzes **recorded data (MCAP)** for regression (diff),
- produces **human-readable console output** (and possibly structured output later).

##### File tree → inferred architecture
Top-level structure:
- `robowatch/` is the package.
- Each top-level CLI command has its own module:
- `pulse.py`, `watch.py`, `trace_cmd.py`, `diff_cmd.py`, `doctor.py`
- CLI orchestration:
- `__main__.py` (enables `python -m robowatch ...`)
- `cli.py` (command routing / argument parsing)
- ROS2 integration / shell-outs:
- `ros2_command.py` (likely wrapper around invoking ROS2 CLI or querying graph)
- “Glue / shared logic”:
- `pulse.py` (snapshot aggregation)
- Tests:
- `tests/test_pulse.py`, `tests/test_diff_cmd.py` (non-ROS specific logic)

Meta/build:
- `setup.py`, `setup.cfg` → Python packaging
- `package.xml` → ROS2 package metadata (ament/colcon ecosystem compatibility)
- `requirements.txt` → Python deps (but ROS deps like `rclpy` come from ROS install)

##### Command module → integrations
- ROS2 graph queries, subscriptions, QoS checks (via `rclpy` or `ros2_command.py`)
- Filesystem reads for MCAP (diff)
- OS metrics collection (pulse/watch)

##### Command-specific dataflows (make these explicit)
- **pulse**
- Queries ROS graph → list nodes, topics, pub/sub relationships
- Pulls lightweight resource usage → CPU/mem (host-level and/or node processes)
- Produces “pipeline overview” → a derived graph summary
- **watch**
- Targets a node name → resolves publishers/subscribers and QoS
- Live loop: periodically polls/observes → emits updates
- **trace**
- Takes a topic chain string `"/a -> /b -> /c"`
- Subscribes/observes timestamps at each hop (approximation)
- Computes hop-by-hop and total latency
- **diff**
- Reads MCAP A and MCAP B
- Computes per-topic frequency deltas and regression report
- **doctor**
- Runs audits on graph structure (e.g., disconnected graphs, missing pubs/subs, QoS mismatches)
- `--deep` potentially invokes heavier checks (call this out as “optional deeper probes”)

##### Command pattern / subcommand architecture
- `cli.py` dispatches to per-command modules.
- Each command is independently testable (seen in `tests/`).

##### Adapter/Facade for ROS2 interaction
- `ros2_command.py` suggests abstraction over ROS2 CLI or graph querying.
- Helps later swap/extend implementation (e.g., C++ backend or tracing).

##### Separation of concerns
- (a) CLI parsing/dispatch
- (b) data collection (ROS2, OS, MCAP)
- (c) analysis/derivation (latency, diff, audits)
- (d) presentation (console report)

##### Technologies & artifacts to label
- Python 3.10+
- ROS2 (`rclpy`, ROS graph concepts: nodes/topics/QoS)
- DDS (as underlying transport; not necessarily directly called today)
- MCAP (offline recording format)
- Packaging: `setup.py`/`setup.cfg` + `package.xml` (signals both pip and ROS2 ecosystem)
- Tests: `pytest`

Artifacts:
- MCAP files as data inputs for `diff`
- Terminal stdout as primary output channel

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% =========================
  %% View A: System Context (L0)
  %% =========================
  subgraph "System Context (Level 0)"
    U["User / Operator (Terminal)"]:::external
    RW["robowatch CLI (Python)"]:::robowatch
    ROS["ROS2 Runtime (rclpy + ROS graph + running nodes)"]:::external
    DDS["DDS Middleware (CycloneDDS/FastDDS/...)"]:::external
    OS["Host OS (CPU/Mem/Process stats)"]:::external
    MCAP[("MCAP Files (Recordings)")]:::data
    OUT["Stdout / Console Report"]:::external
    FUT["Future: ros2_tracing / LTTng + DDS deep hooks / C++ backend"]:::future
  end

  U -->|"invokes robowatch <cmd> + args"| RW
  RW -->|"ROS graph introspection (nodes/topics/QoS) + subscriptions"| ROS
  ROS -->|"transport"| DDS
  RW -->|"CPU/mem sampling"| OS
  RW -->|"read recordings"| MCAP
  RW -->|"render human-readable report"| OUT
  RW -.->|"extension seam (optional deeper probes)"| FUT

  %% ==================================
  %% View B: Container/Runtime (Level 1)
  %% ==================================
  subgraph "Container / Runtime (Level 1)"
    subgraph "User Session"
      TERM["Terminal Session"]:::external
    end

    subgraph "robowatch Process"
      PYPROC["python -m robowatch (single process)"]:::robowatch
      RCLPY["rclpy (ROS2 Python client)"]:::dependency
      ROS2CLI["ros2 CLI (optional shell-out)"]:::external
    end

    subgraph "Robot System (Separate Processes)"
      ROSNODES["ROS2 Nodes (multiple processes)"]:::external
      ROSDAEMON["ROS2 Daemon/Discovery (if present)"]:::external
      DDSRT["DDS Runtime Layer"]:::external
    end

    FS[("Filesystem Storage (MCAP)")]:::data
  end

  TERM -->|"runs command"| PYPROC
  PYPROC -->|"uses"| RCLPY
  PYPROC -->|"may invoke"| ROS2CLI
  RCLPY -->|"discover/subscribe/publish APIs"| ROSNODES
  ROS2CLI -->|"query graph / list nodes/topics"| ROSDAEMON
  ROSNODES -->|"DDS traffic"| DDSRT
  PYPROC -->|"read/write files"| FS

  %% ==================================
  %% View C: robowatch Components (Level 2)
  %% ==================================
  subgraph "robowatch Package (Level 2 Components)"
    subgraph "Entry Points"
      MAIN["__main__.py"]:::robowatch
      CLI["cli.py"]:::robowatch
    end

    subgraph "Commands (Subcommand Architecture)"
      PULSE["pulse.py"]:::command
      WATCH["watch.py"]:::command
      TRACE["trace_cmd.py"]:::command
      DIFF["diff_cmd.py"]:::command
      DOCTOR["doctor.py"]:::command
    end

    subgraph "Integration / Adapters"
      ROS2AD["ros2_command.py"]:::adapter
    end

    subgraph "Conceptual Core (SoC seam)"
      COLLECT["Data Collection\n(ROS2 + OS + MCAP)"]:::core
      ANALYZE["Analysis / Derivation\n(latency/diff/audits/overview)"]:::core
      REPORT["Report Model\n(structured snapshot/findings)"]:::core
      RENDER["Presentation / Rendering\n(console output)"]:::core
    end
  end

  %% CLI routing
  MAIN -->|"launches"| CLI
  CLI -->|"dispatch subcommand"| PULSE
  CLI -->|"dispatch subcommand"| WATCH
  CLI -->|"dispatch subcommand"| TRACE
  CLI -->|"dispatch subcommand"| DIFF
  CLI -->|"dispatch subcommand"| DOCTOR

  %% Command-to-core flow
  PULSE -->|"collect graph + resources"| COLLECT
  WATCH -->|"poll/observe live state"| COLLECT
  TRACE -->|"subscribe + timestamp sampling"| COLLECT
  DIFF -->|"read MCAP A/B streams"| COLLECT
  DOCTOR -->|"graph audits (+ --deep probes)"| COLLECT

  COLLECT -->|"produce raw observations"| REPORT
  REPORT -->|"input"| ANALYZE
  ANALYZE -->|"emit derived findings"| REPORT
  REPORT -->|"format"| RENDER

  %% Command-specific callouts (derived outputs)
  subgraph "Key Outputs (Conceptual)"
    P1["Pipeline Overview\n(nodes/topics/pub-sub)"]:::note
    W1["Live Health Stream\n(QoS + resource metrics)"]:::note
    T1["Latency Report\n(hop-by-hop + end-to-end)"]:::note
    D1["Regression Summary\n(Δ topic frequency)"]:::note
    DR1["Audit Findings\n(disconnects/QoS mismatches)"]:::note
  end

  ANALYZE -->|"derive"| P1
  ANALYZE -->|"derive"| W1
  ANALYZE -->|"derive"| T1
  ANALYZE -->|"derive"| D1
  ANALYZE -->|"derive"| DR1
  RENDER -->|"print"| OUT

  %% Integrations
  COLLECT -->|"ROS2 graph/query + subscriptions"| RCLPY
  COLLECT -->|"optional shell-out queries"| ROS2AD
  ROS2AD -->|"invoke ros2 CLI"| ROS2CLI
  COLLECT -->|"CPU/mem/process sampling"| OS
  COLLECT -->|"read MCAP recordings"| MCAP
  TRACE -.->|"future deeper instrumentation"| FUT
  WATCH -.->|"future deeper instrumentation"| FUT
  DOCTOR -.->|"future deeper instrumentation"| FUT

  %% =========================
  %% Tests & Repository Artifacts
  %% =========================
  subgraph "Tests (Non-runtime)"
    TP["tests/test_pulse.py"]:::test
    TDIFF["tests/test_diff_cmd.py"]:::test
  end

  TP -->|"unit tests command logic"| PULSE
  TDIFF -->|"unit tests diff logic"| DIFF

  subgraph "Build / Docs / Metadata"
    ARCH["ARCHITECTURE.md"]:::doc
    WF["WORKFLOWS.md"]:::doc
    SETUP["setup.py"]:::meta
    SETUPCFG["setup.cfg"]:::meta
    PKGXML["package.xml"]:::meta
    REQ["requirements.txt"]:::meta
  end

  ARCH -.->|"defines module boundaries + flows"| CLI
  WF -.->|"documents command flows"| CLI
  SETUP -.->|"packaging/install entry points"| MAIN
  SETUPCFG -.->|"packaging config"| CLI
  PKGXML -.->|"ROS2 metadata (ament/colcon)"| RW
  REQ -.->|"python deps (mcap/psutil/etc)"| COLLECT

  %% =========================
  %% Sequence Diagram: trace flow
  %% =========================
  subgraph "Sequence (trace): topic-chain latency computation"
    direction TB
    S_U["User"]:::external
    S_CLI["cli.py"]:::robowatch
    S_TR["trace_cmd.py"]:::command
    S_COL["Data Collection"]:::core
    S_RCL["rclpy"]:::dependency
    S_AN["Analysis"]:::core
    S_REN["Rendering"]:::core

    S_U -->|"robowatch trace \"/a -> /b -> /c\""| S_CLI
    S_CLI -->|"dispatch"| S_TR
    S_TR -->|"parse chain; configure probes"| S_COL
    S_COL -->|"subscribe /a,/b,/c"| S_RCL
    S_RCL -->|"receive messages + header timestamps"| S_COL
    S_COL -->|"timestamps per hop"| S_AN
    S_AN -->|"compute hop + end-to-end latency"| S_REN
    S_REN -->|"print latency report"| S_U
  end

  %% =========================
  %% Sequence Diagram: diff flow
  %% =========================
  subgraph "Sequence (diff): MCAP regression report"
    direction TB
    SD_U["User"]:::external
    SD_CLI["cli.py"]:::robowatch
    SD_DF["diff_cmd.py"]:::command
    SD_COL["Data Collection"]:::core
    SD_FS[("MCAP Files")]:::data
    SD_AN["Analysis"]:::core
    SD_REN["Rendering"]:::core

    SD_U -->|"robowatch diff A.mcap B.mcap"| SD_CLI
    SD_CLI -->|"dispatch"| SD_DF
    SD_DF -->|"open A/B; iterate messages"| SD_COL
    SD_COL -->|"read streams"| SD_FS
    SD_COL -->|"msg counts per topic"| SD_AN
    SD_AN -->|"compute Δ frequency + regressions"| SD_REN
    SD_REN -->|"print regression summary"| SD_U
  end

  %% =========================
  %% Click Events (component mapping)
  %% =========================
  click MAIN "https://github.com/darshan-stack/ros2_watch/blob/main/robowatch/__main__.py"
  click CLI "https://github.com/darshan-stack/ros2_watch/blob/main/robowatch/cli.py"
  click PULSE "https://github.com/darshan-stack/ros2_watch/blob/main/robowatch/pulse.py"
  click WATCH "https://github.com/darshan-stack/ros2_watch/blob/main/robowatch/watch.py"
  click TRACE "https://github.com/darshan-stack/ros2_watch/blob/main/robowatch/trace_cmd.py"
  click DIFF "https://github.com/darshan-stack/ros2_watch/blob/main/robowatch/diff_cmd.py"
  click DOCTOR "https://github.com/darshan-stack/ros2_watch/blob/main/robowatch/doctor.py"
  click ROS2AD "https://github.com/darshan-stack/ros2_watch/blob/main/robowatch/ros2_command.py"
  click TP "https://github.com/darshan-stack/ros2_watch/blob/main/tests/test_pulse.py"
  click TDIFF "https://github.com/darshan-stack/ros2_watch/blob/main/tests/test_diff_cmd.py"
  click ARCH "https://github.com/darshan-stack/ros2_watch/blob/main/ARCHITECTURE.md"
  click WF "https://github.com/darshan-stack/ros2_watch/blob/main/WORKFLOWS.md"
  click SETUP "https://github.com/darshan-stack/ros2_watch/blob/main/setup.py"
  click SETUPCFG "https://github.com/darshan-stack/ros2_watch/blob/main/setup.cfg"
  click PKGXML "https://github.com/darshan-stack/ros2_watch/blob/main/package.xml"
  click REQ "https://github.com/darshan-stack/ros2_watch/blob/main/requirements.txt"

  %% =========================
  %% Styles (color coding)
  %% =========================
  classDef robowatch fill:#1E88E5,stroke:#0D47A1,color:#ffffff,stroke-width:1.5px
  classDef command fill:#1565C0,stroke:#0D47A1,color:#ffffff,stroke-width:1.5px
  classDef adapter fill:#1976D2,stroke:#0D47A1,color:#ffffff,stroke-width:1.5px
  classDef core fill:#42A5F5,stroke:#0D47A1,color:#0B1B2B,stroke-width:1.5px
  classDef external fill:#ECEFF1,stroke:#607D8B,color:#263238,stroke-width:1.2px
  classDef data fill:#FFF3E0,stroke:#EF6C00,color:#4E342E,stroke-width:1.5px
  classDef future fill:#ffffff,stroke:#8E24AA,color:#4A148C,stroke-width:1.5px,stroke-dasharray: 6 4
  classDef note fill:#FFFDE7,stroke:#F9A825,color:#4E342E,stroke-width:1.2px
  classDef test fill:#E8F5E9,stroke:#2E7D32,color:#1B5E20,stroke-width:1.2px
  classDef doc fill:#F3E5F5,stroke:#6A1B9A,color:#4A148C,stroke-width:1.2px
  classDef meta fill:#E0F2F1,stroke:#00695C,color:#004D40,stroke-width:1.2px
  classDef dependency fill:#E3F2FD,stroke:#1565C0,color:#0D47A1,stroke-width:1.2px
```
