# dpdk/grout architecture

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

- Interactive diagram: https://gitdiagram.com/dpdk/grout
- Repository: https://github.com/dpdk/grout

## Overview

Grout is a userspace DPDK graph router. An operator configures interfaces and forwarding through grcli or the UNIX socket API; control-plane modules apply configuration, and graph workers process packets between interfaces. FRR can synchronize routes through its zebra dataplane plugin and the same API. The graph preserves major documented capabilities as separate domain subsystems. Evidence is limited to the README, tree, and sampled excerpts, so unsampled module-to-module wiring is not inferred.

Main entry points: [`main/api.c`](https://github.com/dpdk/grout/blob/main/main/api.c) (UNIX API), [`modules/infra/datapath/main_loop.c`](https://github.com/dpdk/grout/blob/main/modules/infra/datapath/main_loop.c) (Packet graph), [`modules/infra/control`](https://github.com/dpdk/grout/tree/main/modules/infra/control) (Interfaces and workers), [`main/main.c`](https://github.com/dpdk/grout/blob/main/main/main.c) (Daemon lifecycle)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Configuration entrypoints"]
  node_cli["grcli<br/>[main.c]"]
  node_socket["UNIX API<br/>[api.c]"]
end

subgraph group_runtime["Router runtime"]
  node_daemon["Daemon lifecycle<br/>[main.c]"]
  node_infra["Interfaces and workers"]
  node_workers["Graph workers<br/>[worker.c]"]
  node_datapath["Packet graph<br/>[main_loop.c]"]
end

subgraph group_forwarding["Forwarding domains"]
  node_ip4["IPv4 routing"]
  node_ip6["IPv6 routing and RA"]
  node_l2["Bridging and VXLAN"]
  node_nat["NAT and conntrack"]
  node_ipip["IP-in-IP tunnels<br/>[control.c]"]
  node_srv6["SRv6"]
  node_dhcp["DHCP client<br/>[client.c]"]
  node_ip4dp["IPv4 packet handling<br/>[ip_input.c]"]
  node_ip6dp["IPv6 packet handling<br/>[ip6_input.c]"]
  node_l2dp["L2 packet handling<br/>[bridge_input.c]"]
  node_policy_dp["NAT packet handling<br/>[nat_datapath.h]"]
  node_srv6dp["SRv6 packet handling<br/>[srv6_local.c]"]
end

subgraph group_integration["External integration"]
  node_frr(("FRR zebra"))
  node_plugin["Zebra dplane plugin"]
end

node_operator(("Operator"))
node_nic(("DPDK interfaces"))

node_operator -->|"runs commands"| node_cli
node_cli -->|"sends requests"| node_socket
node_operator -.->|"programs router"| node_socket
node_daemon -->|"starts socket"| node_socket
node_daemon -->|"initializes modules"| node_infra
node_socket -->|"dispatches requests"| node_infra
node_socket -->|"dispatches requests"| node_ip4
node_socket -->|"dispatches requests"| node_ip6
node_socket -->|"dispatches requests"| node_l2
node_socket -->|"dispatches requests"| node_nat
node_socket -->|"dispatches requests"| node_ipip
node_socket -->|"dispatches requests"| node_srv6
node_socket -->|"dispatches requests"| node_dhcp
node_infra -->|"configures affinity"| node_workers
node_workers -->|"runs graph"| node_datapath
node_nic -->|"receives packets"| node_datapath
node_datapath -->|"transmits packets"| node_nic
node_datapath -->|"dispatches packets"| node_ip4dp
node_datapath -->|"dispatches packets"| node_ip6dp
node_datapath -->|"dispatches packets"| node_l2dp
node_datapath -->|"dispatches packets"| node_policy_dp
node_datapath -->|"dispatches packets"| node_srv6dp
node_frr -->|"supplies routes"| node_plugin
node_plugin -->|"configures via API"| node_socket

click node_cli "https://github.com/dpdk/grout/blob/main/cli/main.c"
click node_socket "https://github.com/dpdk/grout/blob/main/main/api.c"
click node_daemon "https://github.com/dpdk/grout/blob/main/main/main.c"
click node_infra "https://github.com/dpdk/grout/tree/main/modules/infra/control"
click node_ip4 "https://github.com/dpdk/grout/tree/main/modules/ip/control"
click node_ip6 "https://github.com/dpdk/grout/tree/main/modules/ip6/control"
click node_l2 "https://github.com/dpdk/grout/tree/main/modules/l2/control"
click node_nat "https://github.com/dpdk/grout/tree/main/modules/policy/control"
click node_ipip "https://github.com/dpdk/grout/blob/main/modules/ipip/control.c"
click node_srv6 "https://github.com/dpdk/grout/tree/main/modules/srv6/control"
click node_dhcp "https://github.com/dpdk/grout/blob/main/modules/dhcp/control/client.c"
click node_workers "https://github.com/dpdk/grout/blob/main/modules/infra/control/worker.c"
click node_datapath "https://github.com/dpdk/grout/blob/main/modules/infra/datapath/main_loop.c"
click node_ip4dp "https://github.com/dpdk/grout/blob/main/modules/ip/datapath/ip_input.c"
click node_ip6dp "https://github.com/dpdk/grout/blob/main/modules/ip6/datapath/ip6_input.c"
click node_l2dp "https://github.com/dpdk/grout/blob/main/modules/l2/datapath/bridge_input.c"
click node_policy_dp "https://github.com/dpdk/grout/blob/main/modules/policy/datapath/nat_datapath.h"
click node_srv6dp "https://github.com/dpdk/grout/blob/main/modules/srv6/datapath/srv6_local.c"
click node_plugin "https://github.com/dpdk/grout/blob/main/frr/zebra_dplane_grout.c"

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_cli,node_socket toneBlue
class node_daemon,node_infra,node_workers,node_datapath toneAmber
class node_ip4,node_ip6,node_l2,node_nat,node_ipip,node_srv6,node_dhcp,node_ip4dp,node_ip6dp,node_l2dp,node_policy_dp,node_srv6dp toneMint
class node_frr,node_plugin toneRose
class node_operator,node_nic toneIndigo
```

## Components

### Configuration entrypoints

- [grcli](https://github.com/dpdk/grout/blob/main/cli/main.c): `cli/main.c`
- [UNIX API](https://github.com/dpdk/grout/blob/main/main/api.c): `main/api.c`

### Router runtime

- [Daemon lifecycle](https://github.com/dpdk/grout/blob/main/main/main.c): `main/main.c`
- [Interfaces and workers](https://github.com/dpdk/grout/tree/main/modules/infra/control): `modules/infra/control`
- [Graph workers](https://github.com/dpdk/grout/blob/main/modules/infra/control/worker.c): `modules/infra/control/worker.c`
- [Packet graph](https://github.com/dpdk/grout/blob/main/modules/infra/datapath/main_loop.c): `modules/infra/datapath/main_loop.c`

### Forwarding domains

- [IPv4 routing](https://github.com/dpdk/grout/tree/main/modules/ip/control): `modules/ip/control`
- [IPv6 routing and RA](https://github.com/dpdk/grout/tree/main/modules/ip6/control): `modules/ip6/control`
- [Bridging and VXLAN](https://github.com/dpdk/grout/tree/main/modules/l2/control): `modules/l2/control`
- [NAT and conntrack](https://github.com/dpdk/grout/tree/main/modules/policy/control): `modules/policy/control`
- [IP-in-IP tunnels](https://github.com/dpdk/grout/blob/main/modules/ipip/control.c): `modules/ipip/control.c`
- [SRv6](https://github.com/dpdk/grout/tree/main/modules/srv6/control): `modules/srv6/control`
- [DHCP client](https://github.com/dpdk/grout/blob/main/modules/dhcp/control/client.c): `modules/dhcp/control/client.c`
- [IPv4 packet handling](https://github.com/dpdk/grout/blob/main/modules/ip/datapath/ip_input.c): `modules/ip/datapath/ip_input.c`
- [IPv6 packet handling](https://github.com/dpdk/grout/blob/main/modules/ip6/datapath/ip6_input.c): `modules/ip6/datapath/ip6_input.c`
- [L2 packet handling](https://github.com/dpdk/grout/blob/main/modules/l2/datapath/bridge_input.c): `modules/l2/datapath/bridge_input.c`
- [NAT packet handling](https://github.com/dpdk/grout/blob/main/modules/policy/datapath/nat_datapath.h): `modules/policy/datapath/nat_datapath.h`
- [SRv6 packet handling](https://github.com/dpdk/grout/blob/main/modules/srv6/datapath/srv6_local.c): `modules/srv6/datapath/srv6_local.c`

### External integration

- **FRR zebra**
- [Zebra dplane plugin](https://github.com/dpdk/grout/blob/main/frr/zebra_dplane_grout.c): `frr/zebra_dplane_grout.c`

### Other components

- **Operator**
- **DPDK interfaces**

## Connections

- Operator → grcli: runs commands
- grcli → UNIX API: sends requests
- Operator → UNIX API: programs router
- Daemon lifecycle → UNIX API: starts socket
- Daemon lifecycle → Interfaces and workers: initializes modules
- UNIX API → Interfaces and workers: dispatches requests
- UNIX API → IPv4 routing: dispatches requests
- UNIX API → IPv6 routing and RA: dispatches requests
- UNIX API → Bridging and VXLAN: dispatches requests
- UNIX API → NAT and conntrack: dispatches requests
- UNIX API → IP-in-IP tunnels: dispatches requests
- UNIX API → SRv6: dispatches requests
- UNIX API → DHCP client: dispatches requests
- Interfaces and workers → Graph workers: configures affinity
- Graph workers → Packet graph: runs graph
- DPDK interfaces → Packet graph: receives packets
- Packet graph → DPDK interfaces: transmits packets
- Packet graph → IPv4 packet handling: dispatches packets
- Packet graph → IPv6 packet handling: dispatches packets
- Packet graph → L2 packet handling: dispatches packets
- Packet graph → NAT packet handling: dispatches packets
- Packet graph → SRv6 packet handling: dispatches packets
- FRR zebra → Zebra dplane plugin: supplies routes
- Zebra dplane plugin → UNIX API: configures via API
