# imikerussell/beebots architecture

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

- Interactive diagram: https://gitdiagram.com/imikerussell/beebots
- Repository: https://github.com/imikerussell/beebots

## Overview

beebots is a paper-first OKX perpetual-futures trading experiment with three independently styled AI bees and a live dashboard. Users configure keys, risk acknowledgements and bee playbooks in Setup; the engine gathers market data, gets Jev decisions, applies code-enforced risk controls and simulates or submits orders, then records and broadcasts outcomes. The dashboard presents live decisions and equity. Opt-in Hive reporting shares paper results for a public, replay-verified leaderboard. The engine and server excerpts are partial, so the graph omits uncertain internal wiring.

Main entry points: [`src/engine.ts`](https://github.com/imikerussell/beebots/blob/main/src/engine.ts) (Trading engine), [`src/server.ts`](https://github.com/imikerussell/beebots/blob/main/src/server.ts) (HTTP and SSE server), [`src/market/data.ts`](https://github.com/imikerussell/beebots/blob/main/src/market/data.ts) (Market feed), [`src/setup.ts`](https://github.com/imikerussell/beebots/blob/main/src/setup.ts) (Setup service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_setup["Setup and profiles"]
  node_setup_ui["Setup form<br/>[Setup.tsx]"]
  node_setup_service["Setup service<br/>[setup.ts]"]
  node_settings["Settings<br/>[settings.ts]"]
end

subgraph group_trading["Trading engine"]
  node_engine["Trading engine<br/>[engine.ts]"]
  node_styles["Bee styles<br/>[index.ts]"]
  node_custom_bee["Custom bee brain<br/>[custom.ts]"]
  node_jev["Jev decisions<br/>[jev.ts]"]
  node_risk["Risk controls<br/>[risk.ts]"]
  node_executor["Order execution<br/>[executor.ts]"]
end

subgraph group_market["Market and exchange"]
  node_market_feed["Market feed<br/>[data.ts]"]
  node_market_gates["Universe gates<br/>[universe.ts]"]
  node_indicators["Market indicators<br/>[indicators.ts]"]
  node_okx_public["OKX public API<br/>[public.ts]"]
  node_okx_rest["Public REST client<br/>[rest.ts]"]
end

subgraph group_state["State and events"]
  node_ledger["Trade ledger<br/>[ledger.ts]"]
  node_database[("SQLite database<br/>[db.ts]")]
  node_events["Event bus<br/>[events.ts]"]
  node_server["HTTP and SSE server<br/>[server.ts]"]
end

subgraph group_ui["Dashboard and Hive"]
  node_dashboard["Dashboard app<br/>[App.tsx]"]
  node_feed_hook["Live feed hook<br/>[useFeed.ts]"]
  node_hive["Hive reporting<br/>[hive.ts]"]
end

node_owner(("Owner"))
node_openai(("OpenAI"))
node_okx(("OKX exchange"))
node_leaderboard(("Public leaderboard"))

node_owner -->|"configures"| node_setup_ui
node_setup_ui -->|"submits setup"| node_setup_service
node_setup_service -.->|"designs bees"| node_openai
node_setup_service -->|"saves settings"| node_settings
node_settings -->|"configures"| node_engine
node_engine -->|"refreshes market"| node_market_feed
node_market_feed -->|"filters universe"| node_market_gates
node_market_feed -->|"computes stats"| node_indicators
node_market_feed -->|"requests data"| node_okx_public
node_okx_public -->|"uses client"| node_okx_rest
node_okx_rest -->|"fetches public data"| node_okx
node_engine -->|"selects style"| node_styles
node_engine -->|"loads custom brain"| node_custom_bee
node_engine -->|"requests decision"| node_jev
node_engine -->|"checks proposal"| node_risk
node_engine -->|"places orders"| node_executor
node_executor -->|"submits orders"| node_okx
node_engine -->|"updates positions"| node_ledger
node_ledger -->|"persists trades"| node_database
node_engine -->|"reads and records"| node_database
node_engine -->|"emits updates"| node_events
node_server -->|"serves history"| node_database
node_server -->|"streams events"| node_events
node_owner -->|"views"| node_dashboard
node_dashboard -->|"requests feed"| node_server
node_dashboard -->|"uses live feed"| node_feed_hook
node_feed_hook -->|"loads snapshots"| node_server
node_engine -.->|"reports paper results"| node_hive
node_hive -.->|"shares results"| node_leaderboard
node_owner -->|"joins or leaves Hive"| node_server
node_server -->|"handles membership"| node_hive

click node_setup_ui "https://github.com/imikerussell/beebots/blob/main/dashboard/src/Setup.tsx"
click node_setup_service "https://github.com/imikerussell/beebots/blob/main/src/setup.ts"
click node_settings "https://github.com/imikerussell/beebots/blob/main/src/settings.ts"
click node_engine "https://github.com/imikerussell/beebots/blob/main/src/engine.ts"
click node_styles "https://github.com/imikerussell/beebots/blob/main/src/bees/index.ts"
click node_custom_bee "https://github.com/imikerussell/beebots/blob/main/src/bees/custom.ts"
click node_jev "https://github.com/imikerussell/beebots/blob/main/src/jev.ts"
click node_risk "https://github.com/imikerussell/beebots/blob/main/src/risk.ts"
click node_executor "https://github.com/imikerussell/beebots/blob/main/src/exec/executor.ts"
click node_market_feed "https://github.com/imikerussell/beebots/blob/main/src/market/data.ts"
click node_market_gates "https://github.com/imikerussell/beebots/blob/main/src/market/universe.ts"
click node_indicators "https://github.com/imikerussell/beebots/blob/main/src/market/indicators.ts"
click node_okx_public "https://github.com/imikerussell/beebots/blob/main/src/okx/public.ts"
click node_okx_rest "https://github.com/imikerussell/beebots/blob/main/src/okx/rest.ts"
click node_ledger "https://github.com/imikerussell/beebots/blob/main/src/ledger.ts"
click node_database "https://github.com/imikerussell/beebots/blob/main/src/db.ts"
click node_events "https://github.com/imikerussell/beebots/blob/main/src/events.ts"
click node_server "https://github.com/imikerussell/beebots/blob/main/src/server.ts"
click node_dashboard "https://github.com/imikerussell/beebots/blob/main/dashboard/src/App.tsx"
click node_feed_hook "https://github.com/imikerussell/beebots/blob/main/dashboard/src/useFeed.ts"
click node_hive "https://github.com/imikerussell/beebots/blob/main/src/hive.ts"

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_setup_ui,node_setup_service,node_settings toneBlue
class node_engine,node_styles,node_custom_bee,node_jev,node_risk,node_executor toneAmber
class node_market_feed,node_market_gates,node_indicators,node_okx_public,node_okx_rest toneMint
class node_ledger,node_database,node_events,node_server toneRose
class node_dashboard,node_feed_hook,node_hive,node_owner,node_openai,node_okx,node_leaderboard toneIndigo
```

## Components

### Setup and profiles

- [Setup form](https://github.com/imikerussell/beebots/blob/main/dashboard/src/Setup.tsx): `dashboard/src/Setup.tsx`
- [Setup service](https://github.com/imikerussell/beebots/blob/main/src/setup.ts): `src/setup.ts`
- [Settings](https://github.com/imikerussell/beebots/blob/main/src/settings.ts): `src/settings.ts`

### Trading engine

- [Trading engine](https://github.com/imikerussell/beebots/blob/main/src/engine.ts): `src/engine.ts`
- [Bee styles](https://github.com/imikerussell/beebots/blob/main/src/bees/index.ts): `src/bees/index.ts`
- [Custom bee brain](https://github.com/imikerussell/beebots/blob/main/src/bees/custom.ts): `src/bees/custom.ts`
- [Jev decisions](https://github.com/imikerussell/beebots/blob/main/src/jev.ts): `src/jev.ts`
- [Risk controls](https://github.com/imikerussell/beebots/blob/main/src/risk.ts): `src/risk.ts`
- [Order execution](https://github.com/imikerussell/beebots/blob/main/src/exec/executor.ts): `src/exec/executor.ts`

### Market and exchange

- [Market feed](https://github.com/imikerussell/beebots/blob/main/src/market/data.ts): `src/market/data.ts`
- [Universe gates](https://github.com/imikerussell/beebots/blob/main/src/market/universe.ts): `src/market/universe.ts`
- [Market indicators](https://github.com/imikerussell/beebots/blob/main/src/market/indicators.ts): `src/market/indicators.ts`
- [OKX public API](https://github.com/imikerussell/beebots/blob/main/src/okx/public.ts): `src/okx/public.ts`
- [Public REST client](https://github.com/imikerussell/beebots/blob/main/src/okx/rest.ts): `src/okx/rest.ts`

### State and events

- [Trade ledger](https://github.com/imikerussell/beebots/blob/main/src/ledger.ts): `src/ledger.ts`
- [SQLite database](https://github.com/imikerussell/beebots/blob/main/src/db.ts): `src/db.ts`
- [Event bus](https://github.com/imikerussell/beebots/blob/main/src/events.ts): `src/events.ts`
- [HTTP and SSE server](https://github.com/imikerussell/beebots/blob/main/src/server.ts): `src/server.ts`

### Dashboard and Hive

- [Dashboard app](https://github.com/imikerussell/beebots/blob/main/dashboard/src/App.tsx): `dashboard/src/App.tsx`
- [Live feed hook](https://github.com/imikerussell/beebots/blob/main/dashboard/src/useFeed.ts): `dashboard/src/useFeed.ts`
- [Hive reporting](https://github.com/imikerussell/beebots/blob/main/src/hive.ts): `src/hive.ts`

### Other components

- **Owner**
- **OpenAI**
- **OKX exchange**
- **Public leaderboard**

## Connections

- Owner → Setup form: configures
- Setup form → Setup service: submits setup
- Setup service → OpenAI: designs bees
- Setup service → Settings: saves settings
- Settings → Trading engine: configures
- Trading engine → Market feed: refreshes market
- Market feed → Universe gates: filters universe
- Market feed → Market indicators: computes stats
- Market feed → OKX public API: requests data
- OKX public API → Public REST client: uses client
- Public REST client → OKX exchange: fetches public data
- Trading engine → Bee styles: selects style
- Trading engine → Custom bee brain: loads custom brain
- Trading engine → Jev decisions: requests decision
- Trading engine → Risk controls: checks proposal
- Trading engine → Order execution: places orders
- Order execution → OKX exchange: submits orders
- Trading engine → Trade ledger: updates positions
- Trade ledger → SQLite database: persists trades
- Trading engine → SQLite database: reads and records
- Trading engine → Event bus: emits updates
- HTTP and SSE server → SQLite database: serves history
- HTTP and SSE server → Event bus: streams events
- Owner → Dashboard app: views
- Dashboard app → HTTP and SSE server: requests feed
- Dashboard app → Live feed hook: uses live feed
- Live feed hook → HTTP and SSE server: loads snapshots
- Trading engine → Hive reporting: reports paper results
- Hive reporting → Public leaderboard: shares results
- Owner → HTTP and SSE server: joins or leaves Hive
- HTTP and SSE server → Hive reporting: handles membership