Architecture Overview

Talos has a strict dependency boundary around ROS 2:

flowchart LR
    subgraph Clients["Workstation tools"]
        CLI["talos-cli"]
        TUI["talos-tui"]
    end

    Common["talos-common<br/>protocol, session, transport, config, URDF"]

    subgraph Runtime["Robot runtime"]
        Agent["talos-agent"]
        ROS["rclrs / ROS 2"]
    end

    CLI -->|"uses"| Common
    TUI -->|"uses"| Common
    Agent -->|"uses"| Common
    Agent -->|"links to"| ROS

talos-common is the shared base. It defines protocol schema and framing, the application-facing client session trait, transport endpoint setup, configuration data, and URDF parsing helpers. It has no ROS 2 dependency.

talos-agent is the only crate that links to ROS 2. It creates the ROS 2 node, subscribes to configured topics, converts ROS 2 messages into DynValue, and serves Talos clients.

talos-cli and talos-tui are workstation tools. They only need the Talos protocol and a reachable agent.

Data Flow

1. The agent starts and loads configuration.
2. The ROS 2 bridge subscribes to configured topics.
3. Each ROS 2 message is converted to a transport-neutral DynValue.
4. Client tools connect to the agent and explicitly subscribe to topics.
5. The router forwards topic data only to clients subscribed to that topic.

Important Boundaries

The agent owns ROS 2 message typing and conversion. Clients receive generic Talos protocol data and do not need ROS 2 message definitions.

The session layer hides transport differences from the CLI and TUI through ProtocolClient. UDS uses a single framed connection. QUIC uses a bidirectional control stream plus server-initiated unidirectional data streams.

For a task-oriented guide to which source files own each change, see Source Map.

The terminal UI is a client of the protocol, not a special case inside the agent. It reconnects, lists topics, subscribes, and renders the latest data it has received.