# shruichan/virtual-bee-swarm architecture

> Architecture diagram of the GitHub repository shruichan/virtual-bee-swarm, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/shruichan/virtual-bee-swarm
- Repository: https://github.com/shruichan/virtual-bee-swarm

## Overview

HONEYMOON is a mixed-reality Quest bee-swarm game, supported by a Hive backend and Mentra glasses companion. The main player journey is signing the clipboard, then calming and feeding bees, defending the hive, and resolving the meadow-window what-if. The graph also shows the operator/dialogue backend, glasses scan-and-voice flow, and Bee Scout vision path. Unity gameplay sources are not represented in the supplied tree, so that subsystem is identified by its documented project directory; edges are limited to README statements or sampled/indexed references.

Main entry points: [`hive/src/server.ts`](https://github.com/shruichan/virtual-bee-swarm/blob/main/hive/src/server.ts) (Hive server), [`glasses/src/background/app.ts`](https://github.com/shruichan/virtual-bee-swarm/blob/main/glasses/src/background/app.ts) (Glasses session app), [`unity/BeeswaxClient/Runtime/BeeswaxBus.cs`](https://github.com/shruichan/virtual-bee-swarm/blob/main/unity/BeeswaxClient/Runtime/BeeswaxBus.cs) (Unity Hive client), [`bee-scout/hive/scout-vision/worker.py`](https://github.com/shruichan/virtual-bee-swarm/blob/main/bee-scout/hive/scout-vision/worker.py) (Vision worker)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_game["Quest gameplay"]
  node_unity_game["Mixed-reality game"]
  node_client_bus["Unity Hive client<br/>[BeeswaxBus.cs]"]
  node_client_protocol["Unity protocol<br/>[BeeswaxProtocol.cs]"]
end

subgraph group_hive["Hive backend"]
  node_hive_server["Hive server<br/>[server.ts]"]
  node_board["Beat Board<br/>[board.ts]"]
  node_ask["What-if answers<br/>[ask.ts]"]
  node_director["Dialogue director<br/>[director.ts]"]
  node_services["Service health<br/>[services.ts]"]
  node_hive_protocol["Hive protocol<br/>[protocol.ts]"]
end

subgraph group_glasses["Glasses companion"]
  node_glasses_ui["Glasses status UI<br/>[App.tsx]"]
  node_glasses_app["Glasses session app<br/>[app.ts]"]
  node_scanner["Photo scanner<br/>[scan.ts]"]
  node_glasses_ear["Speech capture<br/>[ear.ts]"]
  node_glasses_hive["Hive connection<br/>[hive.ts]"]
  node_channels["UI channels<br/>[channels.ts]"]
end

subgraph group_scout["Bee Scout vision"]
  node_vision_worker["Vision worker<br/>[worker.py]"]
  node_vision_recognizer["Visual recognizer<br/>[recognizer.py]"]
end

subgraph group_integrations["External services"]
  node_orbis_relay["Orbis relay<br/>[relay.py]"]
  node_external_ai(("AI and speech providers"))
  node_orbis(("Visko Orbis"))
  node_mentra(("MentraOS"))
end

node_player(("Quest player"))

node_player -->|"plays"| node_unity_game
node_unity_game -->|"connects through"| node_client_bus
node_client_bus -->|"uses contract"| node_client_protocol
node_client_bus -->|"connects to"| node_hive_server
node_hive_server -->|"serves"| node_board
node_hive_server -->|"routes what-ifs"| node_ask
node_hive_server -->|"loads"| node_director
node_hive_server -->|"reports health"| node_services
node_hive_server -->|"uses contract"| node_hive_protocol
node_glasses_ui -->|"uses types"| node_channels
node_glasses_app -->|"publishes status"| node_channels
node_glasses_app -->|"wires"| node_scanner
node_glasses_app -->|"wires"| node_glasses_ear
node_glasses_app -->|"wires"| node_glasses_hive
node_glasses_hive -.->|"sends requests"| node_hive_server
node_glasses_app -->|"uses session SDK"| node_mentra
node_vision_worker -->|"recognizes frames"| node_vision_recognizer
node_vision_worker -->|"posts frames"| node_hive_server
node_hive_server -->|"uses for speech and answers"| node_external_ai
node_orbis_relay -.->|"relays live scenes"| node_orbis
node_hive_server -.->|"optional live-video path"| node_orbis_relay

click node_unity_game "https://github.com/shruichan/virtual-bee-swarm/tree/main/unity/VirtualBeeSwarm"
click node_client_bus "https://github.com/shruichan/virtual-bee-swarm/blob/main/unity/BeeswaxClient/Runtime/BeeswaxBus.cs"
click node_client_protocol "https://github.com/shruichan/virtual-bee-swarm/blob/main/unity/BeeswaxClient/Runtime/BeeswaxProtocol.cs"
click node_hive_server "https://github.com/shruichan/virtual-bee-swarm/blob/main/hive/src/server.ts"
click node_board "https://github.com/shruichan/virtual-bee-swarm/blob/main/hive/src/board.ts"
click node_ask "https://github.com/shruichan/virtual-bee-swarm/blob/main/hive/src/ask.ts"
click node_director "https://github.com/shruichan/virtual-bee-swarm/blob/main/hive/src/director.ts"
click node_services "https://github.com/shruichan/virtual-bee-swarm/blob/main/hive/src/services.ts"
click node_hive_protocol "https://github.com/shruichan/virtual-bee-swarm/blob/main/hive/src/protocol.ts"
click node_glasses_ui "https://github.com/shruichan/virtual-bee-swarm/blob/main/glasses/src/ui/App.tsx"
click node_glasses_app "https://github.com/shruichan/virtual-bee-swarm/blob/main/glasses/src/background/app.ts"
click node_scanner "https://github.com/shruichan/virtual-bee-swarm/blob/main/glasses/src/background/scan.ts"
click node_glasses_ear "https://github.com/shruichan/virtual-bee-swarm/blob/main/glasses/src/background/ear.ts"
click node_glasses_hive "https://github.com/shruichan/virtual-bee-swarm/blob/main/glasses/src/background/hive.ts"
click node_channels "https://github.com/shruichan/virtual-bee-swarm/blob/main/glasses/src/shared/channels.ts"
click node_vision_worker "https://github.com/shruichan/virtual-bee-swarm/blob/main/bee-scout/hive/scout-vision/worker.py"
click node_vision_recognizer "https://github.com/shruichan/virtual-bee-swarm/blob/main/bee-scout/hive/scout-vision/scout_vision/recognizer.py"
click node_orbis_relay "https://github.com/shruichan/virtual-bee-swarm/blob/main/hive/orbis-relay/relay.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_unity_game,node_client_bus,node_client_protocol toneBlue
class node_hive_server,node_board,node_ask,node_director,node_services,node_hive_protocol toneAmber
class node_glasses_ui,node_glasses_app,node_scanner,node_glasses_ear,node_glasses_hive,node_channels toneMint
class node_vision_worker,node_vision_recognizer toneRose
class node_orbis_relay,node_external_ai,node_orbis,node_mentra,node_player toneIndigo
```

## Components

### Quest gameplay

- [Mixed-reality game](https://github.com/shruichan/virtual-bee-swarm/tree/main/unity/VirtualBeeSwarm): `unity/VirtualBeeSwarm`
- [Unity Hive client](https://github.com/shruichan/virtual-bee-swarm/blob/main/unity/BeeswaxClient/Runtime/BeeswaxBus.cs): `unity/BeeswaxClient/Runtime/BeeswaxBus.cs`
- [Unity protocol](https://github.com/shruichan/virtual-bee-swarm/blob/main/unity/BeeswaxClient/Runtime/BeeswaxProtocol.cs): `unity/BeeswaxClient/Runtime/BeeswaxProtocol.cs`

### Hive backend

- [Hive server](https://github.com/shruichan/virtual-bee-swarm/blob/main/hive/src/server.ts): `hive/src/server.ts`
- [Beat Board](https://github.com/shruichan/virtual-bee-swarm/blob/main/hive/src/board.ts): `hive/src/board.ts`
- [What-if answers](https://github.com/shruichan/virtual-bee-swarm/blob/main/hive/src/ask.ts): `hive/src/ask.ts`
- [Dialogue director](https://github.com/shruichan/virtual-bee-swarm/blob/main/hive/src/director.ts): `hive/src/director.ts`
- [Service health](https://github.com/shruichan/virtual-bee-swarm/blob/main/hive/src/services.ts): `hive/src/services.ts`
- [Hive protocol](https://github.com/shruichan/virtual-bee-swarm/blob/main/hive/src/protocol.ts): `hive/src/protocol.ts`

### Glasses companion

- [Glasses status UI](https://github.com/shruichan/virtual-bee-swarm/blob/main/glasses/src/ui/App.tsx): `glasses/src/ui/App.tsx`
- [Glasses session app](https://github.com/shruichan/virtual-bee-swarm/blob/main/glasses/src/background/app.ts): `glasses/src/background/app.ts`
- [Photo scanner](https://github.com/shruichan/virtual-bee-swarm/blob/main/glasses/src/background/scan.ts): `glasses/src/background/scan.ts`
- [Speech capture](https://github.com/shruichan/virtual-bee-swarm/blob/main/glasses/src/background/ear.ts): `glasses/src/background/ear.ts`
- [Hive connection](https://github.com/shruichan/virtual-bee-swarm/blob/main/glasses/src/background/hive.ts): `glasses/src/background/hive.ts`
- [UI channels](https://github.com/shruichan/virtual-bee-swarm/blob/main/glasses/src/shared/channels.ts): `glasses/src/shared/channels.ts`

### Bee Scout vision

- [Vision worker](https://github.com/shruichan/virtual-bee-swarm/blob/main/bee-scout/hive/scout-vision/worker.py): `bee-scout/hive/scout-vision/worker.py`
- [Visual recognizer](https://github.com/shruichan/virtual-bee-swarm/blob/main/bee-scout/hive/scout-vision/scout_vision/recognizer.py): `bee-scout/hive/scout-vision/scout_vision/recognizer.py`

### External services

- [Orbis relay](https://github.com/shruichan/virtual-bee-swarm/blob/main/hive/orbis-relay/relay.py): `hive/orbis-relay/relay.py`
- **AI and speech providers**
- **Visko Orbis**
- **MentraOS**

### Other components

- **Quest player**

## Connections

- Quest player → Mixed-reality game: plays (evidence: `README.md`)
- Mixed-reality game → Unity Hive client: connects through (evidence: `README.md`)
- Unity Hive client → Unity protocol: uses contract (evidence: `unity/BeeswaxClient/Runtime/BeeswaxBus.cs`)
- Unity Hive client → Hive server: connects to (evidence: `README.md`)
- Hive server → Beat Board: serves (evidence: `hive/src/server.ts`)
- Hive server → What-if answers: routes what-ifs (evidence: `hive/src/server.ts`)
- Hive server → Dialogue director: loads (evidence: `hive/src/server.ts`)
- Hive server → Service health: reports health (evidence: `hive/src/server.ts`)
- Hive server → Hive protocol: uses contract (evidence: `hive/src/server.ts`)
- Glasses status UI → UI channels: uses types (evidence: `glasses/src/ui/App.tsx`)
- Glasses session app → UI channels: publishes status (evidence: `glasses/src/background/app.ts`)
- Glasses session app → Photo scanner: wires (evidence: `glasses/src/background/app.ts`)
- Glasses session app → Speech capture: wires (evidence: `glasses/src/background/app.ts`)
- Glasses session app → Hive connection: wires (evidence: `glasses/src/background/app.ts`)
- Hive connection → Hive server: sends requests
- Glasses session app → MentraOS: uses session SDK (evidence: `README.md`)
- Vision worker → Visual recognizer: recognizes frames (evidence: `bee-scout/hive/scout-vision/worker.py`)
- Vision worker → Hive server: posts frames (evidence: `bee-scout/hive/scout-vision/worker.py`)
- Hive server → AI and speech providers: uses for speech and answers (evidence: `README.md`)
- Orbis relay → Visko Orbis: relays live scenes (evidence: `README.md`)
- Hive server → Orbis relay: optional live-video path
