# ryunosuke0115/ot-br-posix architecture

> Architecture diagram of the GitHub repository ryunosuke0115/ot-br-posix, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ryunosuke0115/ot-br-posix
- Repository: https://github.com/ryunosuke0115/ot-br-posix

## Overview

1. **Overall role**
   OpenThread Border Router (OTBR) is a POSIX-based border-router stack that bridges a Thread network to an infrastructure IP network such as Wi‑Fi or Ethernet. The architecture splits cleanly into a **Thread-side control/data plane**, an **infrastructure-side networking plane**, and several **management/service planes**.

2. **Primary runtime: `otbr-agent`**
   The central daemon is in `src/agent`. It is the main process that wires together the Thread stack, routing services, discovery services, and platform/network abstractions. Most deployment targets ultimately start this agent, either directly or through service wrappers, init scripts, or Docker/OpenWrt packaging.

3. **Thread stack integration and device modes**
   The `src/host` layer manages the OpenThread device connection in different modes: **NCP** and **RCP**. Files like `ncp_host`, `rcp_host`, `ncp_spinel`, and `thread_host` show that OTBR can talk to a separate Thread radio coprocessor over Spinel, while `thread_helper` and `async_task` provide the supporting execution model.

4. **Control-plane boundary: DBus**
   `src/dbus` exposes OTBR functionality over DBus, with separate server and client implementations. The server side models Thread objects differently for NCP and RCP (`dbus_thread_object_ncp`, `dbus_thread_object_rcp`), while the client side (`thread_api_dbus`) is used by higher-level components that need to manage or query the Thread stack remotely.

5. **Infrastructure networking and packet handling**
   The POSIX networking layer in `src/host/posix` handles the interface to the external LAN/WAN side. This includes infrastructure interface control (`infra_if`), network interface management (`netif`), UDP proxying, multicast routing, and DNS-SD integration. These pieces are what connect Thread traffic and service discovery to the host OS networking stack.

6. **Border routing and backbone behavior**
   `src/backbone_router` contains the logic for Thread backbone routing, including **DUA routing** and **neighbor discovery proxying**. This is one of the key data-path subsystems: it makes Thread nodes reachable from the infrastructure network and helps maintain IPv6 reachability semantics across the border.

7. **Service discovery and commissioning**
   OTBR supports bidirectional service discovery and commissioning through several focused subsystems: `src/mdns`, `src/trel_dnssd`, `src/border_agent`, and `src/sdp_proxy`. `mdns` has multiple backends (`avahi`, `mdnssd`, `openthread`), showing that the design abstracts over different host DNS-SD providers. `border_agent` is the commissioning-facing boundary for external Thread commissioners.

8. **Higher-level APIs: REST and web UI**
   `src/rest` provides a REST service with OpenAPI documentation, using JSON serialization helpers and embedded web server support. `src/web/web-service` adds a web-facing service and static frontend assets for browser-based management. These are management surfaces rather than core routing components, and they sit above the agent/host subsystems.

9. **OpenWrt-specific integration**
   The `src/openwrt` tree provides platform integration for OpenWrt, including UBus bindings, controller logic, UI views, and init/config templates. This is a separate management/deployment boundary for routers running OpenWrt, not a core protocol implementation.

10. **Deployment and packaging**
   The repository includes multiple packaging targets under `etc/`, including Docker images, OpenWrt packaging, Yocto recipes, and example platform configs for Raspberry Pi, Debian, Ubuntu, Fedora, and NXP Linux. Service templates and init scripts in `src/agent` and `src/web` indicate the same core binaries are adapted into different system managers and container layouts.

11. **Shared libraries and protocol assets**
   Common infrastructure lives in `src/common` and `src/utils` for logging, event loops, task runners, byte/string utilities, DNS helpers, PSKc/steering data, and socket/system helpers. `src/proto` defines protobufs for capabilities and telemetry, which support cross-component reporting but are not the main control path.

12. **Testing and validation boundaries**
   The test structure mirrors the architecture: gtests for core utilities and host/network logic, DBus integration tests, mDNS tests, REST tests, and script-based end-to-end scenarios under `tests/scripts`. `tools/reference_device` and `tests/mdns` indicate the repo also validates against external device behavior, not just unit-level contracts.

13. **Key architectural flow to diagram**
   A useful diagram should show: **OpenThread radio/NCP/RCP ↔ host/posix and dbus layers ↔ otbr-agent ↔ infrastructure interface**. From that central path, branch out to **routing/backbone services**, **service discovery/commissioning services**, and **management surfaces** such as DBus, REST, web UI, and OpenWrt integration.

Main entry points: [`src/agent`](https://github.com/ryunosuke0115/ot-br-posix/tree/main/src/agent) (otbr-agent), [`src/host/posix`](https://github.com/ryunosuke0115/ot-br-posix/tree/main/src/host/posix) (Infra network), [`src/host`](https://github.com/ryunosuke0115/ot-br-posix/tree/main/src/host) (Host stack), [`src/mdns`](https://github.com/ryunosuke0115/ot-br-posix/tree/main/src/mdns) (mDNS)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_agent["otbr-agent<br/>daemon"]
  node_host["Host stack<br/>thread host"]
  node_ncp_host["NCP host<br/>ncp client<br/>[ncp_host.cpp]"]
  node_rcp_host["RCP host<br/>rcp client<br/>[rcp_host.cpp]"]
  node_thread_host["Thread host<br/>stack adapter<br/>[thread_host.cpp]"]
end

subgraph group_control["Control Plane"]
  node_dbus_server["DBus server<br/>control api"]
  node_dbus_client["DBus client<br/>control client"]
end

subgraph group_networking["Networking"]
  node_infra["Infra network<br/>posix networking"]
  node_backbone["Backbone router<br/>routing"]
  node_mdns["mDNS<br/>dns-sd"]
end

subgraph group_services["Services"]
  node_border_agent["Border agent<br/>commissioning"]
  node_sdp_proxy["SDP proxy<br/>service proxy"]
  node_trel_dnssd["TREL DNSSD<br/>service bridge"]
  node_rest["REST API<br/>http service"]
  node_web["Web service<br/>ui service"]
  node_openwrt["OpenWrt<br/>platform integration"]
end

subgraph group_shared["Shared"]
  node_common["Common<br/>shared core"]
  node_utils["Utilities<br/>shared utils"]
  node_proto["Protobufs<br/>telemetry schema"]
end

node_agent -->|"uses"| node_host
node_agent -->|"serves"| node_dbus_server
node_agent -->|"binds"| node_infra
node_agent -->|"routes"| node_backbone
node_agent -->|"publishes"| node_mdns
node_agent -->|"commissioning"| node_border_agent
node_agent -->|"proxies"| node_sdp_proxy
node_agent -->|"bridges"| node_trel_dnssd
node_agent -->|"manages"| node_rest
node_agent -->|"hosts"| node_web
node_agent -->|"shares"| node_common
node_agent -->|"shares"| node_utils
node_host -->|"abstracts"| node_thread_host
node_thread_host -->|"mode"| node_ncp_host
node_thread_host -->|"mode"| node_rcp_host
node_host -.->|"queries"| node_dbus_client
node_dbus_server -->|"controls"| node_host
node_infra -->|"uses"| node_common
node_backbone -->|"depends"| node_infra
node_mdns -->|"announces"| node_infra
node_rest -->|"uses"| node_common
node_web -->|"uses"| node_common
node_openwrt -.->|"wraps"| node_agent
node_openwrt -.->|"configures"| node_infra
node_border_agent -.->|"exposes"| node_dbus_server
node_sdp_proxy -->|"leverages"| node_mdns
node_trel_dnssd -->|"integrates"| node_mdns
node_rest -.->|"serializes"| node_proto
node_agent -.->|"reports"| node_proto

click node_agent "https://github.com/ryunosuke0115/ot-br-posix/tree/main/src/agent"
click node_host "https://github.com/ryunosuke0115/ot-br-posix/tree/main/src/host"
click node_ncp_host "https://github.com/ryunosuke0115/ot-br-posix/blob/main/src/host/ncp_host.cpp"
click node_rcp_host "https://github.com/ryunosuke0115/ot-br-posix/blob/main/src/host/rcp_host.cpp"
click node_thread_host "https://github.com/ryunosuke0115/ot-br-posix/blob/main/src/host/thread_host.cpp"
click node_dbus_server "https://github.com/ryunosuke0115/ot-br-posix/tree/main/src/dbus/server"
click node_dbus_client "https://github.com/ryunosuke0115/ot-br-posix/tree/main/src/dbus/client"
click node_infra "https://github.com/ryunosuke0115/ot-br-posix/tree/main/src/host/posix"
click node_backbone "https://github.com/ryunosuke0115/ot-br-posix/tree/main/src/backbone_router"
click node_mdns "https://github.com/ryunosuke0115/ot-br-posix/tree/main/src/mdns"
click node_border_agent "https://github.com/ryunosuke0115/ot-br-posix/tree/main/src/border_agent"
click node_sdp_proxy "https://github.com/ryunosuke0115/ot-br-posix/tree/main/src/sdp_proxy"
click node_trel_dnssd "https://github.com/ryunosuke0115/ot-br-posix/tree/main/src/trel_dnssd"
click node_rest "https://github.com/ryunosuke0115/ot-br-posix/tree/main/src/rest"
click node_web "https://github.com/ryunosuke0115/ot-br-posix/tree/main/src/web/web-service"
click node_openwrt "https://github.com/ryunosuke0115/ot-br-posix/tree/main/src/openwrt"
click node_common "https://github.com/ryunosuke0115/ot-br-posix/tree/main/src/common"
click node_utils "https://github.com/ryunosuke0115/ot-br-posix/tree/main/src/utils"
click node_proto "https://github.com/ryunosuke0115/ot-br-posix/tree/main/src/proto"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_agent,node_host,node_ncp_host,node_rcp_host,node_thread_host toneBlue
class node_dbus_server,node_dbus_client toneAmber
class node_infra,node_backbone,node_mdns toneMint
class node_border_agent,node_sdp_proxy,node_trel_dnssd,node_rest,node_web,node_openwrt toneRose
class node_common,node_utils,node_proto toneIndigo
```

## Components

### Runtime

Core daemon, host stack integration, and platform boundary

- [otbr-agent](https://github.com/ryunosuke0115/ot-br-posix/tree/main/src/agent): daemon · Main border-router process that wires together host, routing, and service subsystems · `src/agent`
- [Host stack](https://github.com/ryunosuke0115/ot-br-posix/tree/main/src/host): thread host · OpenThread device integration layer for NCP/RCP and async execution · `src/host`
- [NCP host](https://github.com/ryunosuke0115/ot-br-posix/blob/main/src/host/ncp_host.cpp): ncp client · Controls a separate radio coprocessor in NCP mode · `src/host/ncp_host.cpp`
- [RCP host](https://github.com/ryunosuke0115/ot-br-posix/blob/main/src/host/rcp_host.cpp): rcp client · Coordinates the host side of an RCP-based Thread setup · `src/host/rcp_host.cpp`
- [Thread host](https://github.com/ryunosuke0115/ot-br-posix/blob/main/src/host/thread_host.cpp): stack adapter · Top-level host abstraction shared by the device-mode implementations · `src/host/thread_host.cpp`

### Control Plane

DBus and agent-facing management interfaces

- [DBus server](https://github.com/ryunosuke0115/ot-br-posix/tree/main/src/dbus/server): control api · Exports OTBR state and actions over DBus · `src/dbus/server`
- [DBus client](https://github.com/ryunosuke0115/ot-br-posix/tree/main/src/dbus/client): control client · Client-side DBus access used by higher-level components · `src/dbus/client`

### Networking

Infrastructure-side networking, routing, and discovery

- [Infra network](https://github.com/ryunosuke0115/ot-br-posix/tree/main/src/host/posix): posix networking · POSIX infrastructure-side interface, netif, multicast, and UDP proxying · `src/host/posix`
- [Backbone router](https://github.com/ryunosuke0115/ot-br-posix/tree/main/src/backbone_router): routing · Thread backbone routing, DUA routing, and ND proxy behavior · `src/backbone_router`
- [mDNS](https://github.com/ryunosuke0115/ot-br-posix/tree/main/src/mdns): dns-sd · Abstraction over host DNS-SD backends for service discovery · `src/mdns`

### Services

Commissioning, telemetry, REST, web, and OpenWrt surfaces

- [Border agent](https://github.com/ryunosuke0115/ot-br-posix/tree/main/src/border_agent): commissioning · Commissioning-facing boundary for external Thread commissioners · `src/border_agent`
- [SDP proxy](https://github.com/ryunosuke0115/ot-br-posix/tree/main/src/sdp_proxy): service proxy · Advertising and discovery proxying between Thread and infrastructure networks · `src/sdp_proxy`
- [TREL DNSSD](https://github.com/ryunosuke0115/ot-br-posix/tree/main/src/trel_dnssd): service bridge · Bridges TREL traffic with DNS-SD service discovery · `src/trel_dnssd`
- [REST API](https://github.com/ryunosuke0115/ot-br-posix/tree/main/src/rest): http service · REST management service with JSON and OpenAPI support · `src/rest`
- [Web service](https://github.com/ryunosuke0115/ot-br-posix/tree/main/src/web/web-service): ui service · Browser-facing management service and static frontend assets · `src/web/web-service`
- [OpenWrt](https://github.com/ryunosuke0115/ot-br-posix/tree/main/src/openwrt): platform integration · OpenWrt-specific UBus, controller, init, and UI integration · `src/openwrt`

### Shared

Common helpers, protocol definitions, and utilities

- [Common](https://github.com/ryunosuke0115/ot-br-posix/tree/main/src/common): shared core · Logging, main loop, task runner, and basic shared primitives · `src/common`
- [Utilities](https://github.com/ryunosuke0115/ot-br-posix/tree/main/src/utils): shared utils · Reusable crypto, DNS, socket, string, and system helpers · `src/utils`
- [Protobufs](https://github.com/ryunosuke0115/ot-br-posix/tree/main/src/proto): telemetry schema · Capability and telemetry message definitions shared across components · `src/proto`

## Connections

- otbr-agent → Host stack: uses · The daemon drives Thread device integration through the host layer
- otbr-agent → DBus server: serves · Exposes agent functionality over DBus
- otbr-agent → Infra network: binds · Connects Thread traffic to the infrastructure interface
- otbr-agent → Backbone router: routes · Installs backbone routing and ND proxy behavior
- otbr-agent → mDNS: publishes · Coordinates service discovery publishing and subscription
- otbr-agent → Border agent: commissioning · Provides the commissioning boundary for external controllers
- otbr-agent → SDP proxy: proxies · Handles service discovery proxying across the border
- otbr-agent → TREL DNSSD: bridges · Connects TREL with DNS-SD discovery
- otbr-agent → REST API: manages · Offers HTTP management services
- otbr-agent → Web service: hosts · Serves browser-based management UI
- otbr-agent → Common: shares · Uses core runtime utilities and main loop primitives
- otbr-agent → Utilities: shares · Uses common helper libraries
- Host stack → Thread host: abstracts · Provides the common Thread device abstraction
- Thread host → NCP host: mode · Implements NCP device mode
- Thread host → RCP host: mode · Implements RCP device mode
- Host stack → DBus client: queries · Can consume DBus-managed Thread state remotely
- DBus server → Host stack: controls · DBus server mediates host and Thread stack operations
- Infra network → Common: uses · Relies on shared main-loop and task infrastructure
- Backbone router → Infra network: depends · Uses infrastructure-side networking to forward reachability
- mDNS → Infra network: announces · Uses host networking for service discovery traffic
- REST API → Common: uses · Builds on shared runtime support
- Web service → Common: uses · Builds on shared runtime support
- OpenWrt → otbr-agent: wraps · Integrates deployment and UI around the core agent
- OpenWrt → Infra network: configures · Configures platform networking and firewall behavior
- Border agent → DBus server: exposes · Sits on the management/control boundary
- SDP proxy → mDNS: leverages · Uses DNS-SD backends for proxying discovery
- TREL DNSSD → mDNS: integrates · Connects TREL advertisement with mDNS/DNS-SD
- REST API → Protobufs: serializes · Uses shared schemas for capability and telemetry data
- otbr-agent → Protobufs: reports · Can emit capabilities and telemetry through shared schemas
