# santhasangar/microduck architecture

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

- Interactive diagram: https://gitdiagram.com/santhasangar/microduck
- Repository: https://github.com/santhasangar/microduck

## Overview

Microduck is the runtime software for a small biped robot. Its main operational loop runs through robotd, which owns motor control and exposes robot intents; padd turns gamepad input into those intents, while robotctl and duckctl provide local and Bluetooth-facing operator access. Separate daemons handle configuration, camera streaming, and depth sensing. updaterd manages verified installation and rollback using a robot health gate. The README documents these service responsibilities and their shared JSON-RPC contract; several subsystem links are omitted where sampled source did not establish caller-level wiring.

Main entry points: [`duck-ipc-proto/src/lib.rs`](https://github.com/santhasangar/microduck/blob/main/duck-ipc-proto/src/lib.rs) (JSON-RPC contract), [`robotd/src/main.rs`](https://github.com/santhasangar/microduck/blob/main/robotd/src/main.rs) (Control daemon), [`padd/src/main.rs`](https://github.com/santhasangar/microduck/blob/main/padd/src/main.rs) (Gamepad daemon), [`netpadd/src/main.rs`](https://github.com/santhasangar/microduck/blob/main/netpadd/src/main.rs) (UDP gamepad)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_control["Robot control"]
  node_robotd["Control daemon<br/>[main.rs]"]
  node_padd["Gamepad daemon<br/>[main.rs]"]
  node_netpadd["UDP gamepad<br/>[main.rs]"]
  node_padmap["Pad mapping<br/>[mapper.rs]"]
  node_robotparams["Control parameters<br/>[lib.rs]"]
end

subgraph group_operator["Operator access"]
  node_robotctl["Robot CLI<br/>[main.rs]"]
  node_duckctl["Bluetooth CLI<br/>[main.rs]"]
  node_btd["Bluetooth daemon<br/>[main.rs]"]
end

subgraph group_sensing["Perception and media"]
  node_mediad["Camera streaming<br/>[pipeline.rs]"]
  node_camera["Camera capture<br/>[camera.rs]"]
  node_mediaroute["Media routing<br/>[route.rs]"]
  node_tofd["Depth daemon<br/>[main.rs]"]
end

subgraph group_services["Robot services"]
  node_configd["Configuration daemon<br/>[main.rs]"]
  node_ipc["JSON-RPC contract<br/>[lib.rs]"]
end

subgraph group_updates["Software updates"]
  node_updater["Update engine<br/>[engine.rs]"]
  node_updateipc["Update IPC<br/>[ipc.rs]"]
  node_health["Health gate<br/>[main.rs]"]
end

node_operator(("Operator"))

node_operator -->|"operates locally"| node_robotctl
node_operator -->|"operates remotely"| node_duckctl
node_padd -->|"maps input"| node_padmap
node_netpadd -->|"shares mapping"| node_padmap
node_padd -->|"sends intents"| node_robotd
node_netpadd -->|"sends intents"| node_robotd
node_robotctl -->|"uses contract"| node_ipc
node_duckctl -->|"reaches by Bluetooth"| node_btd
node_btd -->|"uses contract"| node_ipc
node_configd -->|"uses contract"| node_ipc
node_robotd -->|"serves control API"| node_ipc
node_mediad -->|"captures from"| node_camera
node_mediad -->|"uses routes"| node_mediaroute
node_tofd -->|"publishes sensor data"| node_ipc
node_updater -.->|"exposes update API"| node_updateipc
node_updater -->|"gates on health"| node_health
node_robotd -.->|"loads parameters"| node_robotparams

click node_robotd "https://github.com/santhasangar/microduck/blob/main/robotd/src/main.rs"
click node_padd "https://github.com/santhasangar/microduck/blob/main/padd/src/main.rs"
click node_netpadd "https://github.com/santhasangar/microduck/blob/main/netpadd/src/main.rs"
click node_padmap "https://github.com/santhasangar/microduck/blob/main/pad-map/src/mapper.rs"
click node_robotparams "https://github.com/santhasangar/microduck/blob/main/robotd-params/src/lib.rs"
click node_robotctl "https://github.com/santhasangar/microduck/blob/main/robotctl/src/main.rs"
click node_duckctl "https://github.com/santhasangar/microduck/blob/main/duckctl/src/main.rs"
click node_btd "https://github.com/santhasangar/microduck/blob/main/btd/src/main.rs"
click node_configd "https://github.com/santhasangar/microduck/blob/main/configd/src/main.rs"
click node_mediad "https://github.com/santhasangar/microduck/blob/main/mediad/src/pipeline.rs"
click node_camera "https://github.com/santhasangar/microduck/blob/main/mediad/src/camera.rs"
click node_mediaroute "https://github.com/santhasangar/microduck/blob/main/mediad/src/route.rs"
click node_tofd "https://github.com/santhasangar/microduck/blob/main/tof/src/main.rs"
click node_ipc "https://github.com/santhasangar/microduck/blob/main/duck-ipc-proto/src/lib.rs"
click node_updater "https://github.com/santhasangar/microduck/blob/main/updater/src/engine.rs"
click node_updateipc "https://github.com/santhasangar/microduck/blob/main/updater/src/ipc.rs"
click node_health "https://github.com/santhasangar/microduck/blob/main/robotd/src/main.rs"

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_robotd,node_padd,node_netpadd,node_padmap,node_robotparams toneBlue
class node_robotctl,node_duckctl,node_btd toneAmber
class node_mediad,node_camera,node_mediaroute,node_tofd toneMint
class node_configd,node_ipc toneRose
class node_updater,node_updateipc,node_health,node_operator toneIndigo
```

## Components

### Robot control

- [Control daemon](https://github.com/santhasangar/microduck/blob/main/robotd/src/main.rs): `robotd/src/main.rs`
- [Gamepad daemon](https://github.com/santhasangar/microduck/blob/main/padd/src/main.rs): `padd/src/main.rs`
- [UDP gamepad](https://github.com/santhasangar/microduck/blob/main/netpadd/src/main.rs): `netpadd/src/main.rs`
- [Pad mapping](https://github.com/santhasangar/microduck/blob/main/pad-map/src/mapper.rs): `pad-map/src/mapper.rs`
- [Control parameters](https://github.com/santhasangar/microduck/blob/main/robotd-params/src/lib.rs): `robotd-params/src/lib.rs`

### Operator access

- [Robot CLI](https://github.com/santhasangar/microduck/blob/main/robotctl/src/main.rs): `robotctl/src/main.rs`
- [Bluetooth CLI](https://github.com/santhasangar/microduck/blob/main/duckctl/src/main.rs): `duckctl/src/main.rs`
- [Bluetooth daemon](https://github.com/santhasangar/microduck/blob/main/btd/src/main.rs): `btd/src/main.rs`

### Perception and media

- [Camera streaming](https://github.com/santhasangar/microduck/blob/main/mediad/src/pipeline.rs): `mediad/src/pipeline.rs`
- [Camera capture](https://github.com/santhasangar/microduck/blob/main/mediad/src/camera.rs): `mediad/src/camera.rs`
- [Media routing](https://github.com/santhasangar/microduck/blob/main/mediad/src/route.rs): `mediad/src/route.rs`
- [Depth daemon](https://github.com/santhasangar/microduck/blob/main/tof/src/main.rs): `tof/src/main.rs`

### Robot services

- [Configuration daemon](https://github.com/santhasangar/microduck/blob/main/configd/src/main.rs): `configd/src/main.rs`
- [JSON-RPC contract](https://github.com/santhasangar/microduck/blob/main/duck-ipc-proto/src/lib.rs): `duck-ipc-proto/src/lib.rs`

### Software updates

- [Update engine](https://github.com/santhasangar/microduck/blob/main/updater/src/engine.rs): `updater/src/engine.rs`
- [Update IPC](https://github.com/santhasangar/microduck/blob/main/updater/src/ipc.rs): `updater/src/ipc.rs`
- [Health gate](https://github.com/santhasangar/microduck/blob/main/robotd/src/main.rs): `robotd/src/main.rs`

### Other components

- **Operator**

## Connections

- Operator → Robot CLI: operates locally (evidence: `README.md`)
- Operator → Bluetooth CLI: operates remotely (evidence: `README.md`)
- Gamepad daemon → Pad mapping: maps input (evidence: `padd/src/main.rs`)
- UDP gamepad → Pad mapping: shares mapping (evidence: `netpadd/src/main.rs`)
- Gamepad daemon → Control daemon: sends intents (evidence: `README.md`)
- UDP gamepad → Control daemon: sends intents (evidence: `README.md`)
- Robot CLI → JSON-RPC contract: uses contract (evidence: `README.md`)
- Bluetooth CLI → Bluetooth daemon: reaches by Bluetooth (evidence: `README.md`)
- Bluetooth daemon → JSON-RPC contract: uses contract (evidence: `README.md`)
- Configuration daemon → JSON-RPC contract: uses contract (evidence: `README.md`)
- Control daemon → JSON-RPC contract: serves control API (evidence: `README.md`)
- Camera streaming → Camera capture: captures from
- Camera streaming → Media routing: uses routes (evidence: `mediad/src/pipeline.rs`)
- Depth daemon → JSON-RPC contract: publishes sensor data (evidence: `README.md`)
- Update engine → Update IPC: exposes update API (evidence: `updater/src/engine.rs`)
- Update engine → Health gate: gates on health (evidence: `README.md`)
- Control daemon → Control parameters: loads parameters