# hulks/hulk architecture

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

- Interactive diagram: https://gitdiagram.com/hulks/hulk
- Repository: https://github.com/hulks/hulk

## Overview

HULK is a RoboCup SPL robot-control system with supporting operator tools. The principal runtime starts a stack of concurrent nodes in `hulk_ros_z`; those nodes implement perception, state estimation, decision-making, and robot control. The tree identifies these domain stages, but most node internals and their message wiring were not sampled, so the graph shows the documented runtime dispatch rather than assuming a pipeline between siblings. `ros-z` is included as the repository’s communications layer; its use by individual nodes is not asserted here.

Main entry points: [`crates/hulk_ros_z/src/main.rs`](https://github.com/hulks/hulk/blob/main/crates/hulk_ros_z/src/main.rs) (Runtime Stack), [`crates/nodes/motor_commands_collector/src/lib.rs`](https://github.com/hulks/hulk/blob/main/crates/nodes/motor_commands_collector/src/lib.rs) (Motor Commands), [`crates/nodes/image_receiver/src/lib.rs`](https://github.com/hulks/hulk/blob/main/crates/nodes/image_receiver/src/lib.rs) (Image Receiver), [`crates/nodes/low_state_bridge/src/lib.rs`](https://github.com/hulks/hulk/blob/main/crates/nodes/low_state_bridge/src/lib.rs) (Low State Bridge)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Robot Runtime"]
  node_stack["Runtime Stack<br/>[main.rs]"]
end

subgraph group_perception["Perception And State"]
  node_image["Image Receiver<br/>[lib.rs]"]
  node_detection["Object Detection<br/>[lib.rs]"]
  node_fieldmarks["Field Mark Association<br/>[lib.rs]"]
  node_ballfilter["Ball Filter<br/>[lib.rs]"]
  node_localization["3D Localization<br/>[lib.rs]"]
  node_odometry["Odometry<br/>[lib.rs]"]
  node_world["World State Composer<br/>[lib.rs]"]
  node_gamecontroller["Game Controller State<br/>[lib.rs]"]
end

subgraph group_decision["Decision And Motion"]
  node_behavior["Behavior Node<br/>[lib.rs]"]
  node_planner["Path Planner<br/>[lib.rs]"]
  node_headmotion["Head Motion<br/>[lib.rs]"]
  node_kickselector["Kick Ball Selector<br/>[lib.rs]"]
end

subgraph group_platform["Robot Platform"]
  node_commands["Motor Commands<br/>[lib.rs]"]
  node_booster["Booster SDK Interface<br/>[lib.rs]"]
  node_lowstate["Low State Bridge<br/>[lib.rs]"]
end

subgraph group_middleware["Communications"]
  node_rosz["ROS-Z Messaging<br/>[lib.rs]"]
  node_schemas["Message Types"]
end

node_robot(("Robot Sensors And Actuators"))

node_stack -->|"starts node"| node_image
node_stack -->|"starts node"| node_detection
node_stack -->|"starts node"| node_fieldmarks
node_stack -->|"starts node"| node_ballfilter
node_stack -->|"starts node"| node_localization
node_stack -->|"starts node"| node_odometry
node_stack -->|"starts node"| node_world
node_stack -->|"starts node"| node_gamecontroller
node_stack -->|"starts node"| node_behavior
node_stack -->|"starts node"| node_planner
node_stack -->|"starts node"| node_headmotion
node_stack -->|"starts node"| node_kickselector
node_stack -->|"starts node"| node_commands
node_stack -->|"starts node"| node_booster
node_stack -->|"starts node"| node_lowstate
node_robot -.->|"image input"| node_image
node_robot -.->|"robot state"| node_lowstate
node_commands -.->|"motor output"| node_robot

click node_stack "https://github.com/hulks/hulk/blob/main/crates/hulk_ros_z/src/main.rs"
click node_image "https://github.com/hulks/hulk/blob/main/crates/nodes/image_receiver/src/lib.rs"
click node_detection "https://github.com/hulks/hulk/blob/main/crates/nodes/detection/src/lib.rs"
click node_fieldmarks "https://github.com/hulks/hulk/blob/main/crates/nodes/field_mark_association/src/lib.rs"
click node_ballfilter "https://github.com/hulks/hulk/blob/main/crates/nodes/ball_filter/src/lib.rs"
click node_localization "https://github.com/hulks/hulk/blob/main/crates/nodes/localization-3d/src/lib.rs"
click node_odometry "https://github.com/hulks/hulk/blob/main/crates/nodes/odometry/src/lib.rs"
click node_world "https://github.com/hulks/hulk/blob/main/crates/nodes/world_state_composer/src/lib.rs"
click node_gamecontroller "https://github.com/hulks/hulk/blob/main/crates/nodes/game_controller_state_filter/src/lib.rs"
click node_behavior "https://github.com/hulks/hulk/blob/main/crates/nodes/behavior_node/src/lib.rs"
click node_planner "https://github.com/hulks/hulk/blob/main/crates/path_planner/src/lib.rs"
click node_headmotion "https://github.com/hulks/hulk/blob/main/crates/nodes/head_motion/src/lib.rs"
click node_kickselector "https://github.com/hulks/hulk/blob/main/crates/nodes/visual_kick_ball_selector/src/lib.rs"
click node_commands "https://github.com/hulks/hulk/blob/main/crates/nodes/motor_commands_collector/src/lib.rs"
click node_booster "https://github.com/hulks/hulk/blob/main/crates/nodes/booster_sdk_interface/src/lib.rs"
click node_lowstate "https://github.com/hulks/hulk/blob/main/crates/nodes/low_state_bridge/src/lib.rs"
click node_rosz "https://github.com/hulks/hulk/blob/main/crates/ros-z/src/lib.rs"
click node_schemas "https://github.com/hulks/hulk/blob/main/crates/types/src/controller_input.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_stack toneBlue
class node_image,node_detection,node_fieldmarks,node_ballfilter,node_localization,node_odometry,node_world,node_gamecontroller toneAmber
class node_behavior,node_planner,node_headmotion,node_kickselector toneMint
class node_commands,node_booster,node_lowstate toneRose
class node_rosz,node_schemas,node_robot toneIndigo
```

## Components

### Robot Runtime

- [Runtime Stack](https://github.com/hulks/hulk/blob/main/crates/hulk_ros_z/src/main.rs): `crates/hulk_ros_z/src/main.rs`

### Perception And State

- [Image Receiver](https://github.com/hulks/hulk/blob/main/crates/nodes/image_receiver/src/lib.rs): `crates/nodes/image_receiver/src/lib.rs`
- [Object Detection](https://github.com/hulks/hulk/blob/main/crates/nodes/detection/src/lib.rs): `crates/nodes/detection/src/lib.rs`
- [Field Mark Association](https://github.com/hulks/hulk/blob/main/crates/nodes/field_mark_association/src/lib.rs): `crates/nodes/field_mark_association/src/lib.rs`
- [Ball Filter](https://github.com/hulks/hulk/blob/main/crates/nodes/ball_filter/src/lib.rs): `crates/nodes/ball_filter/src/lib.rs`
- [3D Localization](https://github.com/hulks/hulk/blob/main/crates/nodes/localization-3d/src/lib.rs): `crates/nodes/localization-3d/src/lib.rs`
- [Odometry](https://github.com/hulks/hulk/blob/main/crates/nodes/odometry/src/lib.rs): `crates/nodes/odometry/src/lib.rs`
- [World State Composer](https://github.com/hulks/hulk/blob/main/crates/nodes/world_state_composer/src/lib.rs): `crates/nodes/world_state_composer/src/lib.rs`
- [Game Controller State](https://github.com/hulks/hulk/blob/main/crates/nodes/game_controller_state_filter/src/lib.rs): `crates/nodes/game_controller_state_filter/src/lib.rs`

### Decision And Motion

- [Behavior Node](https://github.com/hulks/hulk/blob/main/crates/nodes/behavior_node/src/lib.rs): `crates/nodes/behavior_node/src/lib.rs`
- [Path Planner](https://github.com/hulks/hulk/blob/main/crates/path_planner/src/lib.rs): `crates/path_planner/src/lib.rs`
- [Head Motion](https://github.com/hulks/hulk/blob/main/crates/nodes/head_motion/src/lib.rs): `crates/nodes/head_motion/src/lib.rs`
- [Kick Ball Selector](https://github.com/hulks/hulk/blob/main/crates/nodes/visual_kick_ball_selector/src/lib.rs): `crates/nodes/visual_kick_ball_selector/src/lib.rs`

### Robot Platform

- [Motor Commands](https://github.com/hulks/hulk/blob/main/crates/nodes/motor_commands_collector/src/lib.rs): `crates/nodes/motor_commands_collector/src/lib.rs`
- [Booster SDK Interface](https://github.com/hulks/hulk/blob/main/crates/nodes/booster_sdk_interface/src/lib.rs): `crates/nodes/booster_sdk_interface/src/lib.rs`
- [Low State Bridge](https://github.com/hulks/hulk/blob/main/crates/nodes/low_state_bridge/src/lib.rs): `crates/nodes/low_state_bridge/src/lib.rs`

### Communications

- [ROS-Z Messaging](https://github.com/hulks/hulk/blob/main/crates/ros-z/src/lib.rs): `crates/ros-z/src/lib.rs`
- [Message Types](https://github.com/hulks/hulk/blob/main/crates/types/src/controller_input.rs): `crates/types/src/controller_input.rs`

### Other components

- **Robot Sensors And Actuators**

## Connections

- Runtime Stack → Image Receiver: starts node
- Runtime Stack → Object Detection: starts node
- Runtime Stack → Field Mark Association: starts node
- Runtime Stack → Ball Filter: starts node
- Runtime Stack → 3D Localization: starts node
- Runtime Stack → Odometry: starts node
- Runtime Stack → World State Composer: starts node
- Runtime Stack → Game Controller State: starts node
- Runtime Stack → Behavior Node: starts node
- Runtime Stack → Path Planner: starts node
- Runtime Stack → Head Motion: starts node
- Runtime Stack → Kick Ball Selector: starts node
- Runtime Stack → Motor Commands: starts node
- Runtime Stack → Booster SDK Interface: starts node
- Runtime Stack → Low State Bridge: starts node
- Robot Sensors And Actuators → Image Receiver: image input
- Robot Sensors And Actuators → Low State Bridge: robot state
- Motor Commands → Robot Sensors And Actuators: motor output