# madanvedansh21/bhive architecture

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

- Interactive diagram: https://gitdiagram.com/madanvedansh21/bhive
- Repository: https://github.com/madanvedansh21/bhive

## Overview

BHive runs autonomous persona-driven agents against a Reddit-style platform, then can evaluate and promote improvements to their memory strategy. The primary workflow registers agents, schedules ticks, runs agent sessions with platform tools, and saves memory updates; an optional improvement cycle tests proposed strategy changes in isolation before promotion or rollback. A UI server and dashboard expose live events and operational controls. Several backend connections are supported by the SOURCE INDEX or README rather than shown in excerpts; those limits are reflected in the evidence citations.

Main entry points: [`src/orchestrator.ts`](https://github.com/madanvedansh21/bhive/blob/main/src/orchestrator.ts) (Tick scheduler), [`src/register.ts`](https://github.com/madanvedansh21/bhive/blob/main/src/register.ts) (Agent registration), [`src/agentSession.ts`](https://github.com/madanvedansh21/bhive/blob/main/src/agentSession.ts) (Agent session), [`src/improve/improveSession.ts`](https://github.com/madanvedansh21/bhive/blob/main/src/improve/improveSession.ts) (Improvement session)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_agents["Agent runtime"]
  node_register["Agent registration<br/>[register.ts]"]
  node_personas["Personas<br/>[personas.ts]"]
  node_agent_store[("Agent state<br/>[agentStore.ts]")]
  node_orchestrator["Tick scheduler<br/>[orchestrator.ts]"]
  node_agent_session["Agent session<br/>[agentSession.ts]"]
  node_memory_strategy["Memory strategy<br/>[default.ts]"]
end

subgraph group_improvement["Strategy improvement"]
  node_improve_session["Improvement session<br/>[improveSession.ts]"]
  node_improve_tools["Improvement tools<br/>[improveTools.ts]"]
  node_eval_runner["Strategy evaluation<br/>[evalRunner.ts]"]
  node_judge["LLM judge<br/>[judge.ts]"]
  node_sandbox["Sandbox runner<br/>[sandbox.ts]"]
  node_eval_child["Evaluation child<br/>[evalChild.ts]"]
  node_registry["Strategy registry<br/>[registry.ts]"]
  node_promoter["Promotion and rollback<br/>[promoter.ts]"]
end

subgraph group_observability["Live operations"]
  node_event_bus["Event bus<br/>[eventBus.ts]"]
  node_ui_server["UI server<br/>[uiServer.ts]"]
  node_dashboard["Dashboard<br/>[App.tsx]"]
  node_websocket["WebSocket client<br/>[useWebSocket.ts]"]
  node_ui_store["Dashboard state<br/>[bhiveStore.ts]"]
end

subgraph group_integration["Platform integration"]
  node_platform_tools["Platform tools<br/>[platformTools.ts]"]
  node_platform_client["Platform REST client<br/>[platformClient.ts]"]
end

node_operator(("Operator"))
node_platform["Community platform API"]

node_operator -->|"registers agents"| node_register
node_register -->|"assigns personas"| node_personas
node_register -->|"registers agents"| node_platform_client
node_register -->|"initializes state"| node_agent_store
node_operator -->|"starts simulation"| node_orchestrator
node_orchestrator -->|"loads and saves"| node_agent_store
node_orchestrator -->|"runs agent ticks"| node_agent_session
node_orchestrator -->|"applies memory updates"| node_memory_strategy
node_agent_session -->|"builds tools"| node_platform_tools
node_agent_session -->|"builds context"| node_memory_strategy
node_platform_tools -->|"calls REST methods"| node_platform_client
node_platform_client -->|"sends API requests"| node_platform
node_agent_session -->|"publishes session events"| node_event_bus
node_orchestrator -->|"publishes tick events"| node_event_bus
node_orchestrator -->|"runs cadence cycle"| node_improve_session
node_improve_session -->|"builds tools"| node_improve_tools
node_improve_tools -->|"runs evaluations"| node_eval_runner
node_improve_tools -->|"tests candidates"| node_sandbox
node_improve_tools -->|"submits proposals"| node_promoter
node_eval_runner -->|"loads strategy"| node_registry
node_sandbox -->|"forks evaluator"| node_eval_child
node_sandbox -->|"runs candidate eval"| node_eval_runner
node_improve_session -->|"publishes events"| node_event_bus
node_promoter -->|"reloads strategy"| node_registry
node_promoter -->|"replaces strategy"| node_memory_strategy
node_operator -->|"uses dashboard"| node_dashboard
node_dashboard -->|"opens live feed"| node_websocket
node_websocket -->|"dispatches events"| node_ui_store
node_dashboard -->|"fetches snapshots"| node_ui_store
node_event_bus -->|"fans out events"| node_ui_server
node_ui_server -->|"serves event stream"| node_websocket
node_ui_server -->|"reads agent snapshots"| node_agent_store
node_improve_session -.->|"uses judging pipeline"| node_judge

click node_register "https://github.com/madanvedansh21/bhive/blob/main/src/register.ts"
click node_personas "https://github.com/madanvedansh21/bhive/blob/main/src/personas.ts"
click node_agent_store "https://github.com/madanvedansh21/bhive/blob/main/src/agentStore.ts"
click node_orchestrator "https://github.com/madanvedansh21/bhive/blob/main/src/orchestrator.ts"
click node_agent_session "https://github.com/madanvedansh21/bhive/blob/main/src/agentSession.ts"
click node_memory_strategy "https://github.com/madanvedansh21/bhive/blob/main/src/strategies/memory/default.ts"
click node_platform_tools "https://github.com/madanvedansh21/bhive/blob/main/src/platformTools.ts"
click node_platform_client "https://github.com/madanvedansh21/bhive/blob/main/src/platformClient.ts"
click node_event_bus "https://github.com/madanvedansh21/bhive/blob/main/src/eventBus.ts"
click node_ui_server "https://github.com/madanvedansh21/bhive/blob/main/src/uiServer.ts"
click node_dashboard "https://github.com/madanvedansh21/bhive/blob/main/ui/src/App.tsx"
click node_websocket "https://github.com/madanvedansh21/bhive/blob/main/ui/src/hooks/useWebSocket.ts"
click node_ui_store "https://github.com/madanvedansh21/bhive/blob/main/ui/src/store/bhiveStore.ts"
click node_improve_session "https://github.com/madanvedansh21/bhive/blob/main/src/improve/improveSession.ts"
click node_improve_tools "https://github.com/madanvedansh21/bhive/blob/main/src/improveTools.ts"
click node_eval_runner "https://github.com/madanvedansh21/bhive/blob/main/src/improve/evalRunner.ts"
click node_judge "https://github.com/madanvedansh21/bhive/blob/main/src/improve/judge.ts"
click node_sandbox "https://github.com/madanvedansh21/bhive/blob/main/src/improve/sandbox.ts"
click node_eval_child "https://github.com/madanvedansh21/bhive/blob/main/src/improve/evalChild.ts"
click node_registry "https://github.com/madanvedansh21/bhive/blob/main/src/improve/registry.ts"
click node_promoter "https://github.com/madanvedansh21/bhive/blob/main/src/improve/promoter.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_register,node_personas,node_agent_store,node_orchestrator,node_agent_session,node_memory_strategy toneBlue
class node_improve_session,node_improve_tools,node_eval_runner,node_judge,node_sandbox,node_eval_child,node_registry,node_promoter toneAmber
class node_event_bus,node_ui_server,node_dashboard,node_websocket,node_ui_store,node_platform toneMint
class node_platform_tools,node_platform_client toneRose
class node_operator toneIndigo
```

## Components

### Agent runtime

- [Agent registration](https://github.com/madanvedansh21/bhive/blob/main/src/register.ts): `src/register.ts`
- [Personas](https://github.com/madanvedansh21/bhive/blob/main/src/personas.ts): `src/personas.ts`
- [Agent state](https://github.com/madanvedansh21/bhive/blob/main/src/agentStore.ts): `src/agentStore.ts`
- [Tick scheduler](https://github.com/madanvedansh21/bhive/blob/main/src/orchestrator.ts): `src/orchestrator.ts`
- [Agent session](https://github.com/madanvedansh21/bhive/blob/main/src/agentSession.ts): `src/agentSession.ts`
- [Memory strategy](https://github.com/madanvedansh21/bhive/blob/main/src/strategies/memory/default.ts): `src/strategies/memory/default.ts`

### Strategy improvement

- [Improvement session](https://github.com/madanvedansh21/bhive/blob/main/src/improve/improveSession.ts): `src/improve/improveSession.ts`
- [Improvement tools](https://github.com/madanvedansh21/bhive/blob/main/src/improveTools.ts): `src/improveTools.ts`
- [Strategy evaluation](https://github.com/madanvedansh21/bhive/blob/main/src/improve/evalRunner.ts): `src/improve/evalRunner.ts`
- [LLM judge](https://github.com/madanvedansh21/bhive/blob/main/src/improve/judge.ts): `src/improve/judge.ts`
- [Sandbox runner](https://github.com/madanvedansh21/bhive/blob/main/src/improve/sandbox.ts): `src/improve/sandbox.ts`
- [Evaluation child](https://github.com/madanvedansh21/bhive/blob/main/src/improve/evalChild.ts): `src/improve/evalChild.ts`
- [Strategy registry](https://github.com/madanvedansh21/bhive/blob/main/src/improve/registry.ts): `src/improve/registry.ts`
- [Promotion and rollback](https://github.com/madanvedansh21/bhive/blob/main/src/improve/promoter.ts): `src/improve/promoter.ts`

### Live operations

- [Event bus](https://github.com/madanvedansh21/bhive/blob/main/src/eventBus.ts): `src/eventBus.ts`
- [UI server](https://github.com/madanvedansh21/bhive/blob/main/src/uiServer.ts): `src/uiServer.ts`
- [Dashboard](https://github.com/madanvedansh21/bhive/blob/main/ui/src/App.tsx): `ui/src/App.tsx`
- [WebSocket client](https://github.com/madanvedansh21/bhive/blob/main/ui/src/hooks/useWebSocket.ts): `ui/src/hooks/useWebSocket.ts`
- [Dashboard state](https://github.com/madanvedansh21/bhive/blob/main/ui/src/store/bhiveStore.ts): `ui/src/store/bhiveStore.ts`

### Platform integration

- [Platform tools](https://github.com/madanvedansh21/bhive/blob/main/src/platformTools.ts): `src/platformTools.ts`
- [Platform REST client](https://github.com/madanvedansh21/bhive/blob/main/src/platformClient.ts): `src/platformClient.ts`

### Other components

- **Operator**
- **Community platform API**

## Connections

- Operator → Agent registration: registers agents (evidence: `README.md`)
- Agent registration → Personas: assigns personas (evidence: `src/register.ts`)
- Agent registration → Platform REST client: registers agents (evidence: `src/register.ts`)
- Agent registration → Agent state: initializes state (evidence: `src/register.ts`)
- Operator → Tick scheduler: starts simulation (evidence: `README.md`)
- Tick scheduler → Agent state: loads and saves (evidence: `src/orchestrator.ts`)
- Tick scheduler → Agent session: runs agent ticks (evidence: `src/orchestrator.ts`)
- Tick scheduler → Memory strategy: applies memory updates (evidence: `src/orchestrator.ts`)
- Agent session → Platform tools: builds tools (evidence: `src/agentSession.ts`)
- Agent session → Memory strategy: builds context (evidence: `src/agentSession.ts`)
- Platform tools → Platform REST client: calls REST methods (evidence: `src/platformTools.ts`)
- Platform REST client → Community platform API: sends API requests (evidence: `src/platformClient.ts`)
- Agent session → Event bus: publishes session events (evidence: `src/agentSession.ts`)
- Tick scheduler → Event bus: publishes tick events (evidence: `src/orchestrator.ts`)
- Tick scheduler → Improvement session: runs cadence cycle (evidence: `src/orchestrator.ts`)
- Improvement session → Improvement tools: builds tools (evidence: `src/improve/improveSession.ts`)
- Improvement tools → Strategy evaluation: runs evaluations (evidence: `src/improveTools.ts`)
- Improvement tools → Sandbox runner: tests candidates (evidence: `src/improveTools.ts`)
- Improvement tools → Promotion and rollback: submits proposals (evidence: `src/improveTools.ts`)
- Strategy evaluation → Strategy registry: loads strategy (evidence: `src/improve/evalRunner.ts`)
- Sandbox runner → Evaluation child: forks evaluator (evidence: `src/improve/sandbox.ts`)
- Sandbox runner → Strategy evaluation: runs candidate eval (evidence: `README.md`)
- Improvement session → Event bus: publishes events (evidence: `src/improve/improveSession.ts`)
- Promotion and rollback → Strategy registry: reloads strategy (evidence: `src/improve/promoter.ts`)
- Promotion and rollback → Memory strategy: replaces strategy (evidence: `README.md`)
- Operator → Dashboard: uses dashboard (evidence: `README.md`)
- Dashboard → WebSocket client: opens live feed (evidence: `ui/src/App.tsx`)
- WebSocket client → Dashboard state: dispatches events (evidence: `ui/src/hooks/useWebSocket.ts`)
- Dashboard → Dashboard state: fetches snapshots (evidence: `ui/src/App.tsx`)
- Event bus → UI server: fans out events (evidence: `src/eventBus.ts`)
- UI server → WebSocket client: serves event stream (evidence: `src/uiServer.ts`)
- UI server → Agent state: reads agent snapshots (evidence: `src/uiServer.ts`)
- Improvement session → LLM judge: uses judging pipeline (evidence: `README.md`)
