# starvla/starvla-wbc architecture

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

- Interactive diagram: https://gitdiagram.com/starvla/starvla-wbc
- Repository: https://github.com/starvla/starvla-wbc

## Overview

StarVLA-WBC trains and serves vision-language-action policies that produce humanoid joint-reference chunks; controller adapters translate those into controller-native inputs, while the external WBC stack retains real-time control and safety. The README documents the larger model and controller capabilities; sampled sources confirm training setup, dataset transforms, checkpoint normalization, and portions of the client and BFM-Zero runtime. Unsampled subsystem wiring is represented only where the README states the interface or capability.

Main entry points: [`starVLA/model/framework`](https://github.com/starvla/starvla-wbc/tree/starVLA-WBC/starVLA/model/framework) (VLA frameworks), [`deployment/model_server/policy_wrapper.py`](https://github.com/starvla/starvla-wbc/blob/starVLA-WBC/deployment/model_server/policy_wrapper.py) (Policy wrapper), [`deployment/model_server/server_policy.py`](https://github.com/starvla/starvla-wbc/blob/starVLA-WBC/deployment/model_server/server_policy.py) (Policy server), [`deployment/model_server/tools/websocket_policy_client.py`](https://github.com/starvla/starvla-wbc/blob/starVLA-WBC/deployment/model_server/tools/websocket_policy_client.py) (WebSocket client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Data preparation"]
  node_datasets[("LeRobot datasets<br/>[datasets.py]")]
  node_transforms["Modality transforms<br/>[state_action.py]"]
  node_vlmdata["VLM datasets<br/>[vlm_datasets.py]"]
end

subgraph group_model["Models and training"]
  node_trainer["VLA trainer<br/>[train_starvla.py]"]
  node_frameworks["VLA frameworks"]
  node_vlm["Qwen VLMs"]
  node_worldmodel["World models"]
  node_actionheads["Action heads"]
end

subgraph group_serving["Policy serving"]
  node_normalization["Policy normalization"]
  node_policywrapper["Policy wrapper<br/>[policy_wrapper.py]"]
  node_policyserver["Policy server<br/>[server_policy.py]"]
  node_wsserver["WebSocket transport"]
  node_zmqserver["ZMQ transport"]
  node_client["WebSocket client"]
end

subgraph group_control["Humanoid control"]
  node_command["Humanoid command interface<br/>[humanoid.py]"]
  node_adapters["Controller adapters"]
  node_bfm["BFM-Zero runtime<br/>[bfm_zero.py]"]
  node_backend["Controller backend<br/>[simple_native.py]"]
end

node_operator(("Policy consumer"))
node_observations(("Camera, language, state"))
node_wbc["External WBC"]
node_robot(("Robot or simulator"))

node_datasets -->|"transform samples"| node_transforms
node_vlmdata -->|"provide batches"| node_trainer
node_trainer -->|"build and train"| node_frameworks
node_frameworks -->|"use backbone"| node_vlm
node_frameworks -->|"use conditioning"| node_worldmodel
node_frameworks -->|"predict actions"| node_actionheads
node_observations -->|"submit observations"| node_client
node_client -->|"request policy"| node_wsserver
node_wsserver -->|"dispatch request"| node_policyserver
node_zmqserver -.->|"dispatch request"| node_policyserver
node_policyserver -->|"invoke policy"| node_policywrapper
node_policywrapper -->|"run inference"| node_frameworks
node_policywrapper -->|"process actions"| node_normalization
node_policyserver -->|"return actions"| node_client
node_operator -->|"request action"| node_client
node_policywrapper -->|"decode action chunk"| node_command
node_command -->|"translate command"| node_adapters
node_adapters -->|"provide native input"| node_backend
node_bfm -.->|"produce joint targets"| node_backend
node_backend -->|"return joint targets"| node_wbc
node_wbc -->|"control"| node_robot

click node_datasets "https://github.com/starvla/starvla-wbc/blob/starVLA-WBC/starVLA/dataloader/gr00t_lerobot/datasets.py"
click node_transforms "https://github.com/starvla/starvla-wbc/blob/starVLA-WBC/starVLA/dataloader/gr00t_lerobot/transform/state_action.py"
click node_vlmdata "https://github.com/starvla/starvla-wbc/blob/starVLA-WBC/starVLA/dataloader/vlm_datasets.py"
click node_trainer "https://github.com/starvla/starvla-wbc/blob/starVLA-WBC/starVLA/training/train_starvla.py"
click node_frameworks "https://github.com/starvla/starvla-wbc/tree/starVLA-WBC/starVLA/model/framework"
click node_vlm "https://github.com/starvla/starvla-wbc/tree/starVLA-WBC/starVLA/model/modules/vlm"
click node_worldmodel "https://github.com/starvla/starvla-wbc/tree/starVLA-WBC/starVLA/model/modules/world_model"
click node_actionheads "https://github.com/starvla/starvla-wbc/tree/starVLA-WBC/starVLA/model/modules/action_model"
click node_normalization "https://github.com/starvla/starvla-wbc/blob/starVLA-WBC/deployment/model_server/policy_norm_processor.py"
click node_policywrapper "https://github.com/starvla/starvla-wbc/blob/starVLA-WBC/deployment/model_server/policy_wrapper.py"
click node_policyserver "https://github.com/starvla/starvla-wbc/blob/starVLA-WBC/deployment/model_server/server_policy.py"
click node_wsserver "https://github.com/starvla/starvla-wbc/blob/starVLA-WBC/deployment/model_server/tools/websocket_policy_server.py"
click node_zmqserver "https://github.com/starvla/starvla-wbc/blob/starVLA-WBC/deployment/model_server/tools/zmq_policy_server.py"
click node_client "https://github.com/starvla/starvla-wbc/blob/starVLA-WBC/deployment/model_server/tools/websocket_policy_client.py"
click node_command "https://github.com/starvla/starvla-wbc/blob/starVLA-WBC/starVLA/controller/humanoid.py"
click node_adapters "https://github.com/starvla/starvla-wbc/tree/starVLA-WBC/starVLA/controller"
click node_bfm "https://github.com/starvla/starvla-wbc/blob/starVLA-WBC/starVLA/controller/bfm_zero.py"
click node_backend "https://github.com/starvla/starvla-wbc/blob/starVLA-WBC/starVLA/controller/simple_native.py"

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_datasets,node_transforms,node_vlmdata toneBlue
class node_trainer,node_frameworks,node_vlm,node_worldmodel,node_actionheads toneAmber
class node_normalization,node_policywrapper,node_policyserver,node_wsserver,node_zmqserver,node_client toneMint
class node_command,node_adapters,node_bfm,node_backend toneRose
class node_operator,node_observations,node_wbc,node_robot toneIndigo
```

## Components

### Data preparation

- [LeRobot datasets](https://github.com/starvla/starvla-wbc/blob/starVLA-WBC/starVLA/dataloader/gr00t_lerobot/datasets.py): `starVLA/dataloader/gr00t_lerobot/datasets.py`
- [Modality transforms](https://github.com/starvla/starvla-wbc/blob/starVLA-WBC/starVLA/dataloader/gr00t_lerobot/transform/state_action.py): `starVLA/dataloader/gr00t_lerobot/transform/state_action.py`
- [VLM datasets](https://github.com/starvla/starvla-wbc/blob/starVLA-WBC/starVLA/dataloader/vlm_datasets.py): `starVLA/dataloader/vlm_datasets.py`

### Models and training

- [VLA trainer](https://github.com/starvla/starvla-wbc/blob/starVLA-WBC/starVLA/training/train_starvla.py): `starVLA/training/train_starvla.py`
- [VLA frameworks](https://github.com/starvla/starvla-wbc/tree/starVLA-WBC/starVLA/model/framework): `starVLA/model/framework`
- [Qwen VLMs](https://github.com/starvla/starvla-wbc/tree/starVLA-WBC/starVLA/model/modules/vlm): `starVLA/model/modules/vlm`
- [World models](https://github.com/starvla/starvla-wbc/tree/starVLA-WBC/starVLA/model/modules/world_model): `starVLA/model/modules/world_model`
- [Action heads](https://github.com/starvla/starvla-wbc/tree/starVLA-WBC/starVLA/model/modules/action_model): `starVLA/model/modules/action_model`

### Policy serving

- [Policy normalization](https://github.com/starvla/starvla-wbc/blob/starVLA-WBC/deployment/model_server/policy_norm_processor.py): `deployment/model_server/policy_norm_processor.py`
- [Policy wrapper](https://github.com/starvla/starvla-wbc/blob/starVLA-WBC/deployment/model_server/policy_wrapper.py): `deployment/model_server/policy_wrapper.py`
- [Policy server](https://github.com/starvla/starvla-wbc/blob/starVLA-WBC/deployment/model_server/server_policy.py): `deployment/model_server/server_policy.py`
- [WebSocket transport](https://github.com/starvla/starvla-wbc/blob/starVLA-WBC/deployment/model_server/tools/websocket_policy_server.py): `deployment/model_server/tools/websocket_policy_server.py`
- [ZMQ transport](https://github.com/starvla/starvla-wbc/blob/starVLA-WBC/deployment/model_server/tools/zmq_policy_server.py): `deployment/model_server/tools/zmq_policy_server.py`
- [WebSocket client](https://github.com/starvla/starvla-wbc/blob/starVLA-WBC/deployment/model_server/tools/websocket_policy_client.py): `deployment/model_server/tools/websocket_policy_client.py`

### Humanoid control

- [Humanoid command interface](https://github.com/starvla/starvla-wbc/blob/starVLA-WBC/starVLA/controller/humanoid.py): `starVLA/controller/humanoid.py`
- [Controller adapters](https://github.com/starvla/starvla-wbc/tree/starVLA-WBC/starVLA/controller): `starVLA/controller`
- [BFM-Zero runtime](https://github.com/starvla/starvla-wbc/blob/starVLA-WBC/starVLA/controller/bfm_zero.py): `starVLA/controller/bfm_zero.py`
- [Controller backend](https://github.com/starvla/starvla-wbc/blob/starVLA-WBC/starVLA/controller/simple_native.py): `starVLA/controller/simple_native.py`

### Other components

- **Policy consumer**
- **Camera, language, state**
- **External WBC**
- **Robot or simulator**

## Connections

- LeRobot datasets → Modality transforms: transform samples
- VLM datasets → VLA trainer: provide batches
- VLA trainer → VLA frameworks: build and train
- VLA frameworks → Qwen VLMs: use backbone
- VLA frameworks → World models: use conditioning
- VLA frameworks → Action heads: predict actions
- Camera, language, state → WebSocket client: submit observations
- WebSocket client → WebSocket transport: request policy
- WebSocket transport → Policy server: dispatch request
- ZMQ transport → Policy server: dispatch request
- Policy server → Policy wrapper: invoke policy
- Policy wrapper → VLA frameworks: run inference
- Policy wrapper → Policy normalization: process actions
- Policy server → WebSocket client: return actions
- Policy consumer → WebSocket client: request action
- Policy wrapper → Humanoid command interface: decode action chunk
- Humanoid command interface → Controller adapters: translate command
- Controller adapters → Controller backend: provide native input
- BFM-Zero runtime → Controller backend: produce joint targets
- Controller backend → External WBC: return joint targets
- External WBC → Robot or simulator: control