# freelance22688-cloud/orca_ui architecture

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

- Interactive diagram: https://gitdiagram.com/freelance22688-cloud/orca_ui
- Repository: https://github.com/freelance22688-cloud/orca_ui

## Overview

ORCA Hand Console is a browser-based monitoring and control application for ORCA Hands, with an MCP interface for agents. The main workflow is browser or MCP request → backend API → hand service and connected hardware; live telemetry returns through the stream hub and WebSocket to the UI. Distinct product stages include hardware discovery, sensor/motor monitoring, motion and library playback, setup operations, and teleoperation. The graph also shows the frontend state layer and operation/teleop managers. Some subsystem links reflect README capabilities because their implementation files were not sampled.

Main entry points: [`orca_ui/hand/service.py`](https://github.com/freelance22688-cloud/orca_ui/blob/main/orca_ui/hand/service.py) (Hand service), [`orca_ui/server.py`](https://github.com/freelance22688-cloud/orca_ui/blob/main/orca_ui/server.py) (App server), [`orca_ui/api/rest.py`](https://github.com/freelance22688-cloud/orca_ui/blob/main/orca_ui/api/rest.py) (REST API), [`frontend/src/App.tsx`](https://github.com/freelance22688-cloud/orca_ui/blob/main/frontend/src/App.tsx) (App shell)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Browser interface"]
  node_app["App shell<br/>[App.tsx]"]
  node_views["Product views"]
  node_frontend_state["UI state<br/>[appStore.ts]"]
  node_stream_state["Stream state<br/>[streamStore.ts]"]
end

subgraph group_transport["API and streaming"]
  node_frontend_api["REST client<br/>[rest.ts]"]
  node_frontend_stream["Stream client<br/>[streamClient.ts]"]
  node_server["App server<br/>[server.py]"]
  node_rest["REST API<br/>[rest.py]"]
  node_ws["WebSocket API<br/>[ws.py]"]
  node_hub["Stream hub<br/>[hub.py]"]
  node_topics["Stream topics<br/>[topics.py]"]
end

subgraph group_hand["Hand runtime"]
  node_service["Hand service<br/>[service.py]"]
  node_supervisor["Hardware supervisor<br/>[supervisor.py]"]
  node_sessions["Connection sessions<br/>[sessions.py]"]
  node_states["Capability state<br/>[states.py]"]
  node_core["Hardware adapter<br/>[core_source.py]"]
  node_telemetry["Telemetry service<br/>[telemetry.py]"]
end

subgraph group_actions["Operations and teleop"]
  node_operations["Operation manager<br/>[manager.py]"]
  node_operation_types["Hand operations<br/>[hand_ops.py]"]
  node_player["Pose playback<br/>[player.py]"]
  node_teleop["Teleop manager<br/>[manager.py]"]
  node_teleop_runner["Teleop runner<br/>[runner.py]"]
end

subgraph group_agents["Agent and pose tools"]
  node_library[("Pose library<br/>[library.py]")]
  node_mcp_server["MCP server<br/>[server.py]"]
  node_mcp_tools["MCP tools<br/>[tools.py]"]
  node_mcp_client["Backend client<br/>[client.py]"]
end

node_operator(("Operator"))
node_browser(("Browser"))
node_agent(("MCP client"))
node_hardware{{"ORCA hand"}}
node_retargeter{{"Teleop process"}}

node_operator -->|"uses"| node_browser
node_browser -->|"opens"| node_app
node_app -->|"renders"| node_views
node_app -->|"initializes"| node_frontend_api
node_app -->|"starts"| node_frontend_stream
node_frontend_stream -->|"updates"| node_frontend_state
node_frontend_stream -->|"updates"| node_stream_state
node_frontend_api -->|"requests"| node_rest
node_frontend_stream -->|"subscribes"| node_ws
node_server -->|"mounts"| node_rest
node_server -->|"mounts"| node_ws
node_server -->|"creates"| node_hub
node_server -->|"creates"| node_service
node_server -->|"starts"| node_telemetry
node_rest -->|"delegates"| node_service
node_ws -->|"subscribes"| node_hub
node_ws -->|"reads"| node_service
node_hub -->|"uses"| node_topics
node_service -->|"owns"| node_supervisor
node_supervisor -->|"connects"| node_sessions
node_sessions -->|"describes"| node_states
node_sessions -.->|"connects through"| node_core
node_hardware -.->|"connects"| node_sessions
node_telemetry -.->|"publishes"| node_hub
node_operations -->|"controls"| node_service
node_operations -.->|"runs"| node_operation_types
node_player -->|"loads assets"| node_library
node_rest -->|"reads and writes"| node_library
node_teleop -.->|"coordinates"| node_service
node_teleop -.->|"launches"| node_teleop_runner
node_teleop_runner -.->|"starts"| node_retargeter
node_agent -->|"connects"| node_mcp_server
node_mcp_server -->|"registers"| node_mcp_tools
node_mcp_tools -->|"calls"| node_mcp_client
node_mcp_client -->|"requests"| node_rest

click node_app "https://github.com/freelance22688-cloud/orca_ui/blob/main/frontend/src/App.tsx"
click node_views "https://github.com/freelance22688-cloud/orca_ui/tree/main/frontend/src/components/views"
click node_frontend_api "https://github.com/freelance22688-cloud/orca_ui/blob/main/frontend/src/api/rest.ts"
click node_frontend_stream "https://github.com/freelance22688-cloud/orca_ui/blob/main/frontend/src/api/streamClient.ts"
click node_frontend_state "https://github.com/freelance22688-cloud/orca_ui/blob/main/frontend/src/state/appStore.ts"
click node_stream_state "https://github.com/freelance22688-cloud/orca_ui/blob/main/frontend/src/state/streamStore.ts"
click node_server "https://github.com/freelance22688-cloud/orca_ui/blob/main/orca_ui/server.py"
click node_rest "https://github.com/freelance22688-cloud/orca_ui/blob/main/orca_ui/api/rest.py"
click node_ws "https://github.com/freelance22688-cloud/orca_ui/blob/main/orca_ui/api/ws.py"
click node_hub "https://github.com/freelance22688-cloud/orca_ui/blob/main/orca_ui/streaming/hub.py"
click node_topics "https://github.com/freelance22688-cloud/orca_ui/blob/main/orca_ui/streaming/topics.py"
click node_service "https://github.com/freelance22688-cloud/orca_ui/blob/main/orca_ui/hand/service.py"
click node_supervisor "https://github.com/freelance22688-cloud/orca_ui/blob/main/orca_ui/hand/supervisor.py"
click node_sessions "https://github.com/freelance22688-cloud/orca_ui/blob/main/orca_ui/hand/sessions.py"
click node_states "https://github.com/freelance22688-cloud/orca_ui/blob/main/orca_ui/hand/states.py"
click node_core "https://github.com/freelance22688-cloud/orca_ui/blob/main/orca_ui/core_source.py"
click node_telemetry "https://github.com/freelance22688-cloud/orca_ui/blob/main/orca_ui/hand/telemetry.py"
click node_operations "https://github.com/freelance22688-cloud/orca_ui/blob/main/orca_ui/hand/operations/manager.py"
click node_operation_types "https://github.com/freelance22688-cloud/orca_ui/blob/main/orca_ui/hand/operations/hand_ops.py"
click node_player "https://github.com/freelance22688-cloud/orca_ui/blob/main/orca_ui/hand/operations/player.py"
click node_teleop "https://github.com/freelance22688-cloud/orca_ui/blob/main/orca_ui/hand/teleop/manager.py"
click node_teleop_runner "https://github.com/freelance22688-cloud/orca_ui/blob/main/orca_ui/hand/teleop/runner.py"
click node_library "https://github.com/freelance22688-cloud/orca_ui/blob/main/orca_ui/library.py"
click node_mcp_server "https://github.com/freelance22688-cloud/orca_ui/blob/main/orca_ui/mcp/server.py"
click node_mcp_tools "https://github.com/freelance22688-cloud/orca_ui/blob/main/orca_ui/mcp/tools.py"
click node_mcp_client "https://github.com/freelance22688-cloud/orca_ui/blob/main/orca_ui/mcp/client.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_app,node_views,node_frontend_state,node_stream_state,node_browser,node_agent toneBlue
class node_frontend_api,node_frontend_stream,node_server,node_rest,node_ws,node_hub,node_topics toneAmber
class node_service,node_supervisor,node_sessions,node_states,node_core,node_telemetry toneMint
class node_operations,node_operation_types,node_player,node_teleop,node_teleop_runner toneRose
class node_library,node_mcp_server,node_mcp_tools,node_mcp_client,node_operator,node_hardware,node_retargeter toneIndigo
```

## Components

### Browser interface

- [App shell](https://github.com/freelance22688-cloud/orca_ui/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Product views](https://github.com/freelance22688-cloud/orca_ui/tree/main/frontend/src/components/views): `frontend/src/components/views`
- [UI state](https://github.com/freelance22688-cloud/orca_ui/blob/main/frontend/src/state/appStore.ts): `frontend/src/state/appStore.ts`
- [Stream state](https://github.com/freelance22688-cloud/orca_ui/blob/main/frontend/src/state/streamStore.ts): `frontend/src/state/streamStore.ts`

### API and streaming

- [REST client](https://github.com/freelance22688-cloud/orca_ui/blob/main/frontend/src/api/rest.ts): `frontend/src/api/rest.ts`
- [Stream client](https://github.com/freelance22688-cloud/orca_ui/blob/main/frontend/src/api/streamClient.ts): `frontend/src/api/streamClient.ts`
- [App server](https://github.com/freelance22688-cloud/orca_ui/blob/main/orca_ui/server.py): `orca_ui/server.py`
- [REST API](https://github.com/freelance22688-cloud/orca_ui/blob/main/orca_ui/api/rest.py): `orca_ui/api/rest.py`
- [WebSocket API](https://github.com/freelance22688-cloud/orca_ui/blob/main/orca_ui/api/ws.py): `orca_ui/api/ws.py`
- [Stream hub](https://github.com/freelance22688-cloud/orca_ui/blob/main/orca_ui/streaming/hub.py): `orca_ui/streaming/hub.py`
- [Stream topics](https://github.com/freelance22688-cloud/orca_ui/blob/main/orca_ui/streaming/topics.py): `orca_ui/streaming/topics.py`

### Hand runtime

- [Hand service](https://github.com/freelance22688-cloud/orca_ui/blob/main/orca_ui/hand/service.py): `orca_ui/hand/service.py`
- [Hardware supervisor](https://github.com/freelance22688-cloud/orca_ui/blob/main/orca_ui/hand/supervisor.py): `orca_ui/hand/supervisor.py`
- [Connection sessions](https://github.com/freelance22688-cloud/orca_ui/blob/main/orca_ui/hand/sessions.py): `orca_ui/hand/sessions.py`
- [Capability state](https://github.com/freelance22688-cloud/orca_ui/blob/main/orca_ui/hand/states.py): `orca_ui/hand/states.py`
- [Hardware adapter](https://github.com/freelance22688-cloud/orca_ui/blob/main/orca_ui/core_source.py): `orca_ui/core_source.py`
- [Telemetry service](https://github.com/freelance22688-cloud/orca_ui/blob/main/orca_ui/hand/telemetry.py): `orca_ui/hand/telemetry.py`

### Operations and teleop

- [Operation manager](https://github.com/freelance22688-cloud/orca_ui/blob/main/orca_ui/hand/operations/manager.py): `orca_ui/hand/operations/manager.py`
- [Hand operations](https://github.com/freelance22688-cloud/orca_ui/blob/main/orca_ui/hand/operations/hand_ops.py): `orca_ui/hand/operations/hand_ops.py`
- [Pose playback](https://github.com/freelance22688-cloud/orca_ui/blob/main/orca_ui/hand/operations/player.py): `orca_ui/hand/operations/player.py`
- [Teleop manager](https://github.com/freelance22688-cloud/orca_ui/blob/main/orca_ui/hand/teleop/manager.py): `orca_ui/hand/teleop/manager.py`
- [Teleop runner](https://github.com/freelance22688-cloud/orca_ui/blob/main/orca_ui/hand/teleop/runner.py): `orca_ui/hand/teleop/runner.py`

### Agent and pose tools

- [Pose library](https://github.com/freelance22688-cloud/orca_ui/blob/main/orca_ui/library.py): `orca_ui/library.py`
- [MCP server](https://github.com/freelance22688-cloud/orca_ui/blob/main/orca_ui/mcp/server.py): `orca_ui/mcp/server.py`
- [MCP tools](https://github.com/freelance22688-cloud/orca_ui/blob/main/orca_ui/mcp/tools.py): `orca_ui/mcp/tools.py`
- [Backend client](https://github.com/freelance22688-cloud/orca_ui/blob/main/orca_ui/mcp/client.py): `orca_ui/mcp/client.py`

### Other components

- **Operator**
- **Browser**
- **MCP client**
- **ORCA hand**
- **Teleop process**

## Connections

- Operator → Browser: uses
- Browser → App shell: opens
- App shell → Product views: renders (evidence: `frontend/src/App.tsx`)
- App shell → REST client: initializes (evidence: `frontend/src/App.tsx`)
- App shell → Stream client: starts (evidence: `frontend/src/App.tsx`)
- Stream client → UI state: updates (evidence: `frontend/src/api/streamClient.ts`)
- Stream client → Stream state: updates (evidence: `frontend/src/api/streamClient.ts`)
- REST client → REST API: requests
- Stream client → WebSocket API: subscribes
- App server → REST API: mounts (evidence: `orca_ui/server.py`)
- App server → WebSocket API: mounts (evidence: `orca_ui/server.py`)
- App server → Stream hub: creates (evidence: `orca_ui/server.py`)
- App server → Hand service: creates (evidence: `orca_ui/server.py`)
- App server → Telemetry service: starts (evidence: `orca_ui/server.py`)
- REST API → Hand service: delegates (evidence: `orca_ui/api/rest.py`)
- WebSocket API → Stream hub: subscribes (evidence: `orca_ui/api/ws.py`)
- WebSocket API → Hand service: reads (evidence: `orca_ui/api/ws.py`)
- Stream hub → Stream topics: uses (evidence: `orca_ui/streaming/hub.py`)
- Hand service → Hardware supervisor: owns (evidence: `orca_ui/hand/service.py`)
- Hardware supervisor → Connection sessions: connects (evidence: `orca_ui/hand/supervisor.py`)
- Connection sessions → Capability state: describes (evidence: `orca_ui/hand/sessions.py`)
- Connection sessions → Hardware adapter: connects through
- ORCA hand → Connection sessions: connects
- Telemetry service → Stream hub: publishes
- Operation manager → Hand service: controls (evidence: `orca_ui/hand/operations/manager.py`)
- Operation manager → Hand operations: runs
- Pose playback → Pose library: loads assets (evidence: `orca_ui/hand/operations/player.py`)
- REST API → Pose library: reads and writes (evidence: `orca_ui/api/rest.py`)
- Teleop manager → Hand service: coordinates (evidence: `orca_ui/hand/teleop/manager.py`)
- Teleop manager → Teleop runner: launches (evidence: `orca_ui/hand/teleop/manager.py`)
- Teleop runner → Teleop process: starts
- MCP client → MCP server: connects
- MCP server → MCP tools: registers (evidence: `orca_ui/mcp/server.py`)
- MCP tools → Backend client: calls (evidence: `orca_ui/mcp/tools.py`)
- Backend client → REST API: requests
