Skip to content

Architecture overview

This section explains how DDS AutoDiag is built and why. It follows the C4 model: from the system in its environment, to the deployable parts, to the components inside them.

Interfaces Server Engines System CLIdds-autodiag check Web dashboard127.0.0.1:8080 RViz2 panelhealth · topics · AI AutoDiag serverFastAPI · read-onlyREST + streaming Rule engineQoS · domain · discovery RAG + AIlocal or cloud models RViz plannervalidated display plans ROS 2DDSgraph

System context

flowchart TB
    dev(["👤 ROS 2 developer"])
    dev -- "CLI · browser · RViz panel" --> ad
    ad["<b>DDS AutoDiag</b><br/>read-only diagnostics + AI assistance"]
    subgraph local["Same machine"]
        direction LR
        ros["ROS 2 / DDS graph"]
        rviz["RViz2"]
        docker["Docker Engine"]
        ollama["Ollama<br/>(optional)"]
    end
    subgraph remote["Other machines (optional)"]
        direction LR
        peer["Peer collector"]
        cloud["Cloud AI APIs<br/>Claude · OpenAI · Gemini"]
    end
    ad -- "introspection (read-only)" --> ros
    ad -- "view changes (confirmed)" --> rviz
    ad -- "docker ps" --> docker
    ad -- "loopback" --> ollama
    ad -- "token · private IP" --> peer
    ad -. "sanitized, opt-in" .-> cloud
Boundary What crosses it Direction
ROS 2 / DDS graph Topic lists, endpoint QoS, one sample message, ros2 doctor Read only
RViz2 Display tree changes, only after the user presses Apply Write (view only)
Docker Running container metadata Read only
Peer collector A snapshot, authenticated with a token Read only
Ollama Prompts and embeddings, loopback only Local
Cloud AI Assistant: question, earlier turns, rule code/severity/summary, top-3 doc excerpts, and only with "Include the topic" (panel) or for a live topic the question names (dashboard) its name, type, endpoint counts and QoS. RViz planning: request, earlier turns, display names/types/topics/properties and status, Fixed Frame, TF frame names, live topic names and types, diagnosed QoS facts. Node names, hostname, IPs and home paths are masked; snapshots, message contents and keys never leave Opt-in, outbound

Quality goals

These goals drive most design decisions; see Design decisions.

Priority Goal What it means in practice
1 Safety Never change the robot or ROS configuration. RViz changes need confirmation and are reversible
2 Trustworthiness Deterministic rules decide; findings carry evidence; unverifiable things are labeled "not verified"
3 Works offline Diagnosis, documentation search and local AI need no network
4 Responsiveness Overview in ~3 s; AI answers start streaming within 1–2 s
5 Low setup cost One Python package; RViz panel, native core and AI are optional add-ons

How to read this section