# dora-rs/dora architecture

> Architecture diagram of the GitHub repository dora-rs/dora, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dora-rs/dora
- Repository: https://github.com/dora-rs/dora

## Overview

##### Project Type and Purpose
- dora-rs is a dataflow-oriented robotics framework written in Rust, with multi-language APIs (Rust, Python, C, C++), a CLI, a coordinator service, a daemon service, and a runtime engine.

##### High-Level Components
a. User-facing CLI (“dora-cli”)
- Parses YAML dataflow definitions
- Sends commands to the coordinator
b. Coordinator Service (“binaries/coordinator”)
- Receives directives from CLI
- Plans node placement, resource allocation
- Issues spawn/teardown commands to daemon(s)
c. Daemon Service (“binaries/daemon”)
- Manages node processes on one machine
- Handles control channel and health checks
- Provides shared-memory segments or TCP sockets for inter-process message exchange
d. Runtime Engine (“binaries/runtime”)
- Loads operator implementations (plugins or shared libraries)
- Drives execution loop of each node
e. Node Processes
- User code written against one of the language APIs under `apis/`
- Link to core libraries (`libraries/core`, `libraries/message`, `libraries/communication-layer`)
f. Core Libraries
- libraries/message: message definitions and serialization
- libraries/communication-layer: shared-memory, TCP, Zenoh abstractions
- libraries/core: dataflow descriptor, graph validation, schema generation

##### Relationships and Dataflows
- CLI → Coordinator: control/management RPC over a control channel
- Coordinator → Daemon(s): spawn, start, stop node processes via RPC
- Daemon ↔ Node Processes:
- Control channel for liveness and metrics
- Node Processes ↔ Node Processes: dataflow streams as defined in YAML
- All components emit Opentelemetry spans/metrics/logs to an external collector

##### Architectural Patterns and Principles
- Declarative Dataflow: nodes and their interconnections defined in a YAML graph
- Microservices / Service Orchestration: CLI, coordinator, daemon, runtime are separate binaries
- Plugin/Extension: language-specific API crates under `apis/`, ROS2 bridge, telemetry extensions

##### Key Technologies
- Rust for core, coordinator, daemon, runtime, libraries
- Python / C / C++ language bindings for nodes
- Shared-Memory, TCP, Zenoh transport layers
- Opentelemetry for distributed tracing/metrics
- YAML for configuration (dataflow definitions)
- Cargo and pip for package management

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Control Plane"
        CLI["CLI: dora-cli\nRust/Tokio/tonic"]:::control
        Coord["Coordinator Service\nRust/Tokio/tonic"]:::control
        Daemon["Daemon Service\nRust/Tokio"]:::control
        CLI -->|"RPC/control"| Coord
        Coord -->|"spawn/stop RPC"| Daemon
    end

    subgraph "Data Plane"
        Runtime["Runtime Engine\nRust"]:::data
        subgraph "Nodes"
            subgraph "Rust Nodes"
                RustNode["Rust Node Process"]:::data
                RustNode -->|"links to"| RustNodeAPI["Rust Node API"]:::lib
            end
            subgraph "Python Nodes"
                PyNode["Python Node Process"]:::data
                PyNode -->|"links to"| PyNodeAPI["Python Node API"]:::lib
            end
            subgraph "C Nodes"
                CNode["C Node Process"]:::data
                CNode -->|"links to"| CNodeAPI["C Node API"]:::lib
            end
            subgraph "C++ Nodes"
                CPPNode["C++ Node Process"]:::data
                CPPNode -->|"links to"| CPPNodeAPI["C++ Node API"]:::lib
            end
        end
        Runtime -->|"loads operators"| RustOpAPI["Rust Operator API"]:::lib
        Runtime -->|"loads operators"| PyOpAPI["Python Operator API"]:::lib
        Runtime -->|"loads operators"| COpAPI["C Operator API"]:::lib
        Runtime -->|"loads operators"| CPPOpAPI["C++ Operator API"]:::lib
    end

    Comms["Communication Layer\nSHM/TCP/Zenoh"]:::comm
    RustNode <-->|"Arrow messages"| Comms
    PyNode <-->|"Arrow messages"| Comms
    CNode <-->|"Arrow messages"| Comms
    CPPNode <-->|"Arrow messages"| Comms

    subgraph "Libraries"
        Core["Core Library\n(dataflow, validation)"]:::lib
        Message["Message Library"]:::lib
        CommLib["Comm Layer Library"]:::lib
        ArrowConv["Arrow Convert"]:::lib
        TelemetryM["Telemetry Metrics"]:::lib
        TelemetryT["Telemetry Tracing"]:::lib
        ROS2["ROS2 Bridge"]:::lib
    end

    Coord --> Core
    Daemon --> CommLib
    Runtime --> Core
    Runtime --> Message
    Runtime --> CommLib
    Runtime --> ArrowConv
    Runtime --> TelemetryM
    Runtime --> TelemetryT
    Runtime --> ROS2
    RustNode --> Core
    RustNode --> Message
    RustNode --> CommLib
    RustNode --> TelemetryM
    RustNode --> TelemetryT
    PyNode --> Core
    PyNode --> Message
    PyNode --> CommLib
    PyNode --> TelemetryM
    PyNode --> TelemetryT
    CNode --> Core
    CNode --> Message
    CNode --> CommLib
    CNode --> TelemetryM
    CNode --> TelemetryT
    CPPNode --> Core
    CPPNode --> Message
    CPPNode --> CommLib
    CPPNode --> TelemetryM
    CPPNode --> TelemetryT

    subgraph "External Services"
        TelemetryExt["Telemetry Collector"]:::external
        ZenohRouter["Zenoh Router"]:::external
    end

    Comms -->|"metrics/logs"| TelemetryExt
    Comms -->|"optional dataflow"| ZenohRouter

    %% Click Events
    click CLI "https://github.com/dora-rs/dora/tree/main/binaries/cli/"
    click Coord "https://github.com/dora-rs/dora/tree/main/binaries/coordinator/"
    click Daemon "https://github.com/dora-rs/dora/tree/main/binaries/daemon/"
    click Runtime "https://github.com/dora-rs/dora/tree/main/binaries/runtime/"
    click RustNodeAPI "https://github.com/dora-rs/dora/tree/main/apis/rust/node/"
    click RustOpAPI "https://github.com/dora-rs/dora/tree/main/apis/rust/operator/"
    click PyNodeAPI "https://github.com/dora-rs/dora/tree/main/apis/python/node/"
    click PyOpAPI "https://github.com/dora-rs/dora/tree/main/apis/python/operator/"
    click CNodeAPI "https://github.com/dora-rs/dora/tree/main/apis/c/node/"
    click COpAPI "https://github.com/dora-rs/dora/tree/main/apis/c/operator/"
    click CPPNodeAPI "https://github.com/dora-rs/dora/tree/main/apis/c++/node/"
    click CPPOpAPI "https://github.com/dora-rs/dora/tree/main/apis/c++/operator/"

    %% Styles
    classDef control fill:#a8e6cf,stroke:#333,stroke-width:1px
    classDef data fill:#85c1e9,stroke:#333,stroke-width:1px
    classDef comm fill:#f8b195,stroke:#333,stroke-width:1px
    classDef external fill:#d1c4e9,stroke:#333,stroke-width:1px
    classDef lib fill:#fff3b0,stroke:#333,stroke-width:1px
```
