# robo-arena/roboarena architecture

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

- Interactive diagram: https://gitdiagram.com/robo-arena/roboarena
- Repository: https://github.com/robo-arena/roboarena

## Overview

1. **What this repository is**
   - This is a small Python package that acts as an integration layer for RoboArena: it standardizes how a robot policy is exposed over the network so it can be queried by the RoboArena evaluator.
   - It is not the benchmark itself; it provides the policy-serving client/server boundary and a minimal local test harness.

2. **Primary architectural boundary**
   - The main boundary is **remote policy serving**: a policy implementation runs in one process, and an evaluator/client communicates with it over a **WebSocket** connection.
   - This boundary matters because it separates model inference from the benchmarking runtime and allows distributed evaluation.

3. **Core policy contract**
   - `roboarena/policy.py` defines the policy interface, centered on a `BasePolicy` abstraction.
   - Any custom model intended for RoboArena must conform to this interface so the server can call it consistently regardless of the underlying ML stack.

4. **Policy server subsystem**
   - `roboarena/policy_server.py` is the main serving layer.
   - It exposes `WebsocketPolicyServer` and a `PolicyServerConfig` that describes what the policy needs and returns: image resolution, wrist camera usage, number of external cameras, stereo support, and action-space type.
   - This config is the contract used to minimize data sent over the wire by only transmitting required observations.

5. **Policy client subsystem**
   - `roboarena/policy_client.py` is the consumer side of the architecture.
   - It queries the policy server and is used for local validation or as a stand-in for the evaluator-side request flow.
   - Together, client and server define the request/response loop around policy inference.

6. **Serialization and observation transport**
   - `roboarena/utils/msgpack_numpy.py` suggests the repo uses **MessagePack with NumPy support** for efficient transport of numeric tensors/arrays.
   - This is important because robot observations and actions are typically array-heavy, so serialization format affects latency and bandwidth.

7. **Validation and smoke testing**
   - `scripts/test_policy_server.py` is a standalone smoke test for the server path.
   - Its role is to verify the server can be started and queried end-to-end before connecting to RoboArena or simulation-based evaluation.

8. **Repository layout**
   - `roboarena/` contains the importable package and the reusable runtime components.
   - `scripts/` contains operational checks rather than reusable library code.
   - `docs/` contains product imagery and likely supporting documentation, but it is not part of the execution path.

9. **Runtime and tooling**
   - The project is Python-based and managed with `uv` (`pyproject.toml`, `uv.lock`, `.python-version`).
   - The README shows both editable installation and direct module execution, which indicates the package is meant to be run locally as a lightweight service.

10. **External ecosystem boundaries**
   - RoboArena is positioned as the upstream evaluation system, while DROID simulation evaluation and `openpi` are external downstream/upstream workflows.
   - This repo’s architectural role is to bridge a trained policy into those environments through a standardized serving interface.

11. **How data likely flows**
   - An evaluator or client sends a compact observation payload to the policy server.
   - The server deserializes it, converts it to the `BasePolicy` input format, runs inference, serializes the action output, and returns it over the WebSocket connection.

12. **What to draw in an architecture diagram**
   - Draw four main blocks: policy implementation, websocket policy server, client/evaluator, and serialization utilities.
   - Show `PolicyServerConfig` as metadata/control information that shapes the observation/action contract.
   - Show external arrows to RoboArena evaluation and simulation environments as the consumers of the serving interface.

Main entry points: [`roboarena/policy_server.py`](https://github.com/robo-arena/roboarena/blob/main/roboarena/policy_server.py) (WS server), [`roboarena/policy_client.py`](https://github.com/robo-arena/roboarena/blob/main/roboarena/policy_client.py) (Policy client), [`roboarena/policy.py`](https://github.com/robo-arena/roboarena/blob/main/roboarena/policy.py) (BasePolicy), [`roboarena/utils/msgpack_numpy.py`](https://github.com/robo-arena/roboarena/blob/main/roboarena/utils/msgpack_numpy.py) (Msgpack NumPy)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Core package"]
  node_base_policy["BasePolicy<br/>interface<br/>[policy.py]"]
  node_policy_impl["Policy impl<br/>user policy"]
  node_policy_server_config["Server config<br/>serving config<br/>[policy_server.py]"]
  node_websocket_server["WS server<br/>policy server<br/>[policy_server.py]"]
  node_obs_adapter["Obs adapter<br/>request decode<br/>[policy_server.py]"]
  node_action_encoder["Action encoder<br/>response encode<br/>[policy_server.py]"]
  node_policy_client["Policy client<br/>consumer client<br/>[policy_client.py]"]
  node_msgpack_numpy["Msgpack NumPy<br/>serialization<br/>[msgpack_numpy.py]"]
end

subgraph group_tooling["Tooling"]
  node_smoke_test["Smoke test<br/>server check"]
end

subgraph group_external["External systems"]
  node_roboarena_eval(("RoboArena<br/>evaluator"))
  node_sim_eval(("Sim eval<br/>simulation"))
  node_openpi(("openpi<br/>workflow"))
end

node_policy_impl -->|"implements"| node_base_policy
node_policy_server_config -->|"configures"| node_websocket_server
node_websocket_server -->|"invokes"| node_base_policy
node_websocket_server -->|"decodes"| node_obs_adapter
node_obs_adapter -->|"uses"| node_msgpack_numpy
node_websocket_server -->|"encodes"| node_action_encoder
node_action_encoder -->|"uses"| node_msgpack_numpy
node_policy_client -->|"queries"| node_websocket_server
node_smoke_test -->|"verifies"| node_websocket_server
node_roboarena_eval -->|"consumes"| node_websocket_server
node_sim_eval -->|"consumes"| node_websocket_server
node_openpi -.->|"supplies"| node_policy_impl
node_websocket_server -.->|"mirrors"| node_policy_client

click node_base_policy "https://github.com/robo-arena/roboarena/blob/main/roboarena/policy.py"
click node_policy_server_config "https://github.com/robo-arena/roboarena/blob/main/roboarena/policy_server.py"
click node_websocket_server "https://github.com/robo-arena/roboarena/blob/main/roboarena/policy_server.py"
click node_obs_adapter "https://github.com/robo-arena/roboarena/blob/main/roboarena/policy_server.py"
click node_action_encoder "https://github.com/robo-arena/roboarena/blob/main/roboarena/policy_server.py"
click node_policy_client "https://github.com/robo-arena/roboarena/blob/main/roboarena/policy_client.py"
click node_msgpack_numpy "https://github.com/robo-arena/roboarena/blob/main/roboarena/utils/msgpack_numpy.py"
click node_smoke_test "https://github.com/robo-arena/roboarena/blob/main/scripts/test_policy_server.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_base_policy,node_policy_impl,node_policy_server_config,node_websocket_server,node_obs_adapter,node_action_encoder,node_policy_client,node_msgpack_numpy toneBlue
class node_smoke_test toneAmber
class node_roboarena_eval,node_sim_eval,node_openpi toneMint
```

## Components

### Core package

Reusable runtime components that define policy serving and the policy contract.

- [BasePolicy](https://github.com/robo-arena/roboarena/blob/main/roboarena/policy.py): interface · Core policy contract that every RoboArena policy must implement. · `roboarena/policy.py`
- **Policy impl**: user policy · A concrete model or policy implementation that plugs into the BasePolicy contract.
- [Server config](https://github.com/robo-arena/roboarena/blob/main/roboarena/policy_server.py): serving config · Describes observation needs and action-space shape for efficient wire transfer. · `roboarena/policy_server.py`
- [WS server](https://github.com/robo-arena/roboarena/blob/main/roboarena/policy_server.py): policy server · WebSocket serving layer that receives observations and returns actions. · `roboarena/policy_server.py`
- [Obs adapter](https://github.com/robo-arena/roboarena/blob/main/roboarena/policy_server.py): request decode · Converts compact network payloads into the input format expected by the policy. · `roboarena/policy_server.py`
- [Action encoder](https://github.com/robo-arena/roboarena/blob/main/roboarena/policy_server.py): response encode · Serializes policy outputs back onto the wire for the evaluator or client. · `roboarena/policy_server.py`
- [Policy client](https://github.com/robo-arena/roboarena/blob/main/roboarena/policy_client.py): consumer client · Local consumer that exercises the same request/response flow as the evaluator. · `roboarena/policy_client.py`
- [Msgpack NumPy](https://github.com/robo-arena/roboarena/blob/main/roboarena/utils/msgpack_numpy.py): serialization · MessagePack-based transport helper with NumPy support for array-heavy observations and actions. · `roboarena/utils/msgpack_numpy.py`

### Tooling

Local validation and operational checks.

- [Smoke test](https://github.com/robo-arena/roboarena/blob/main/scripts/test_policy_server.py): server check · Standalone end-to-end check that starts the server path and verifies it can be queried. · `scripts/test_policy_server.py`

### External systems

Upstream or downstream systems that consume the serving interface.

- **RoboArena**: evaluator · Upstream evaluation system that queries the served policy over the network.
- **Sim eval**: simulation · External simulation-based evaluation workflow that can reuse the same serving boundary.
- **openpi**: workflow · External policy-training or policy-runtime workflow that can feed implementations into RoboArena serving.

## Connections

- Policy impl → BasePolicy: implements · A concrete policy conforms to the shared interface.
- Server config → WS server: configures · Server behavior and observation contract are shaped by the serving config.
- WS server → BasePolicy: invokes · The server calls the policy for inference.
- WS server → Obs adapter: decodes · Incoming observation payloads are transformed into policy inputs.
- Obs adapter → Msgpack NumPy: uses · Compact array transport is handled through MessagePack with NumPy support.
- WS server → Action encoder: encodes · Policy outputs are serialized back into network messages.
- Action encoder → Msgpack NumPy: uses · Responses use the same efficient numeric serialization layer.
- Policy client → WS server: queries · The client exercises the same request/response loop as the evaluator.
- Smoke test → WS server: verifies · Smoke test starts and queries the server end-to-end.
- RoboArena → WS server: consumes · RoboArena is the main upstream consumer of the serving interface.
- Sim eval → WS server: consumes · Simulation-based evaluation can also drive the same policy server.
- openpi → Policy impl: supplies · External policy workflows can provide implementations that satisfy the contract.
- WS server → Policy client: mirrors · Client and server define the same boundary from opposite sides.