# i-am-bee/beekeeper architecture

> Architecture diagram of the GitHub repository i-am-bee/beekeeper, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/i-am-bee/beekeeper
- Repository: https://github.com/i-am-bee/beekeeper

## Overview

##### Project type and purpose
- This is a TypeScript-based, full-stack (CLI + backend) application called **Beekeeper**.
- Purpose: orchestrate multi-agent AI systems via a central supervisor agent and a conversational (terminal/UI) interface, dynamically allocating and coordinating specialized agents to tackle user-defined objectives.

##### File structure
Top-level directories and roles:
- src/ui           → presentation layer (interactive/autonomous CLI UI, monitors)
- src/runtime      → core engine that boots the supervisor, agents, task manager
- src/agents       → agent definitions, factories, registry, state management
- src/tasks        → task management (breaking down high-level objectives, tracking state)
- src/tools        → external tool integrations (e.g., Tavily search client)
- src/workspaces   → persistence of agent/task configurations
- src/access-control, src/base, src/helpers, src/utils → cross-cutting concerns (RBAC, DTOs, factories, service locator, misc helpers)

Configuration & orchestration:
- .env.template    → environment variables (LLM backend, tools)
- mise.toml        → tool-version manager and build orchestrator
- GitHub workflows → CI/CD for build and release
- package.json     → dependencies (BeeAI framework, blessed UI, LLM SDKs, etc.)

##### Key architectural insights from README
- Core components: Supervision (central agent), Agent Registry, Task Management
- Interaction modes: Interactive (real-time CLI UI) vs. Autonomous (one-shot, batch)
- Persistence layer: workspaces under ./outputs/workspaces
- External dependencies: LLM backends (OpenAI/Ollama), search tools (Tavily, DuckDuckGo)

##### Main components and relationships
1. **CLI/UI Layer**
- Chat Monitor, Agent Monitor, Task Monitor (src/ui)
2. **Runtime Engine**
- Entry points (src/index.ts, src/main.ts)
- Runtime factory & orchestrator (src/runtime)
3. **Supervisor Agent**
- Orchestrates specialized agents; central coordinator
4. **Agent Registry**
- Repository of available agents, metadata, DTOs, factory (src/agents/registry)
5. **Task Manager**
- Splits objectives into sub-tasks, tracks state (src/tasks/manager)
6. **Workspace Manager**
- Persists and restores workspace state (src/workspaces)
7. **Access Control**
- RBAC for resources and actions (src/access-control)
8. **Tools Factory & Integrations**
- LLM helper (src/helpers/llm.ts)
- Search client (Tavily, DuckDuckGo)
9. **External Services**
- LLM API (OpenAI or Ollama)
- Search API (Tavily, DuckDuckGo)
10. **Persistent Storage**
- Filesystem workspace outputs, .env config

- **User** → CLI/UI Layer (input commands or prompts)
- CLI/UI Layer → Runtime Engine (RPC or function calls)
- Runtime Engine → Supervisor Agent (initialize & delegate)
- Supervisor Agent ↔ Agent Registry (look up or spin up specialized agents)
- Supervisor Agent → Task Manager (submit high-level goals)
- Task Manager → Supervisor Agent (return sub-tasks)
- Supervisor Agent → Agents (Operator, specialized agents via Agent Factory)
- Agents → Tools Factory → External Services (LLM API, search API)
- Agents/Task Manager → Workspace Manager (save state, logs)
- Workspace Manager ↔ Persistent Storage (read/write workspace files)
- Access Control enforces permissions on calls between components

c. Architectural patterns & principles:
- **Factory Pattern** – agent and runtime instantiation (src/agents/factory, src/runtime/factory)
- **Builder Pattern** – state builders for agents/tasks (src/agents/state/builder, src/tasks/state/builder)
- **Service Locator** – centralized DI for utils, config, services (src/utils/service-locator)
- **DTOs** – data transfer objects define messaging contracts across modules
- **Observer/Logger** – state loggers track lifecycle events for debugging/monitoring

d. Key technologies & frameworks:
- Node.js + TypeScript, PNPM for package management
- Mise for tool versioning and build
- neo-blessed terminal UI library (types/neo-blessed)
- OpenAI/Ollama SDKs for LLM calls
- Tavily client for search
- GitHub Actions for CI/CD

##### Diagramming conventions
- Rectangles for internal modules/components
- Clouds for external services/APIs
- Blue for core orchestration modules (Runtime, Supervisor, Task Manager)
- Green for extension/plugin modules (Agents, Tools, Registry)
- Orange for UI components
- Gray for utilities/cross-cutting concerns

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% UI Layer
    subgraph "CLI/UI Layer"
        direction TB
        UICLI["CLI/UI Layer"]:::ui
        ChatMon["Chat Monitor"]:::ui
        AgentMon["Agent Monitor"]:::ui
        TaskMon["Task Monitor"]:::ui
        BaseMon["Base Monitor"]:::ui
    end

    %% Runtime Engine
    subgraph "Runtime Engine"
        direction TB
        EntryIndex["src/index.ts"]:::core
        EntryMain["src/main.ts"]:::core
        RTIndex["src/runtime/index.ts"]:::core
        RTFactory["src/runtime/factory.ts"]:::core
        RTRuntime["src/runtime/runtime.ts"]:::core
    end

    %% Core Orchestration
    Supervisor["Supervisor Agent"]:::core
    TaskManager["Task Manager"]:::core
    AgentRegistry["Agent Registry"]:::ext
    WorkspaceManager["Workspace Manager"]:::ext
    AccessControl["Access Control"]:::util

    %% Tools & Integrations
    subgraph "Tools Factory & Integrations"
        direction TB
        ToolsFactory["Tools Factory"]:::ext
        LLMHelper["LLM Helper"]:::ext
        TavilyClient["Tavily Client"]:::ext
        TavilySearch["Tavily Search"]:::ext
        TavilyExtract["Tavily Extract"]:::ext
    end

    %% External Services
    subgraph "External Services"
        direction TB
        LLMAPI["LLM API"]:::cloud
        SearchAPI["Search API"]:::cloud
    end

    %% Persistent Storage
    subgraph "Persistent Storage"
        direction TB
        WorkspaceFS["Workspace Filesystem"]:::storage
        EnvConfig[".env.template"]:::storage
    end

    %% Relationships
    User[/"User"/]:::external --> UICLI
    UICLI -->|calls| EntryIndex
    EntryIndex --> EntryMain
    EntryMain --> RTIndex
    RTIndex --> RTFactory
    RTFactory --> RTRuntime
    RTRuntime -->|initializes| Supervisor
    Supervisor -->|lookup/register| AgentRegistry
    Supervisor -->|submit goals| TaskManager
    TaskManager -->|return subtasks| Supervisor
    Supervisor -->|spawn agents| AgentRegistry
    Supervisor -->|delegate tasks| TaskManager
    TaskManager -.->|persist state| WorkspaceManager
    Supervisor -.->|persist logs| WorkspaceManager
    WorkspaceManager -->|read/write| WorkspaceFS
    WorkspaceManager -->|read config| EnvConfig
    AccessControl -.->|enforce| Supervisor
    AccessControl -.->|enforce| TaskManager
    AccessControl -.->|enforce| WorkspaceManager
    %% Tools and External
    Supervisor -->|uses| ToolsFactory
    ToolsFactory -->|calls| LLMAPI
    ToolsFactory -->|calls| SearchAPI

    %% Click Events - UI Layer
    click UICLI "https://github.com/i-am-bee/beekeeper/tree/main/src/ui"
    click ChatMon "https://github.com/i-am-bee/beekeeper/blob/main/src/ui/chat-monitor/monitor.ts"
    click AgentMon "https://github.com/i-am-bee/beekeeper/blob/main/src/ui/agent-monitor/monitor.ts"
    click TaskMon "https://github.com/i-am-bee/beekeeper/blob/main/src/ui/task-monitor/monitor.ts"
    click BaseMon "https://github.com/i-am-bee/beekeeper/blob/main/src/ui/base/monitor.ts"
    click EntryIndex "https://github.com/i-am-bee/beekeeper/blob/main/src/index.ts"
    click EntryMain "https://github.com/i-am-bee/beekeeper/blob/main/src/main.ts"
    click RTIndex "https://github.com/i-am-bee/beekeeper/blob/main/src/runtime/index.ts"
    click RTFactory "https://github.com/i-am-bee/beekeeper/blob/main/src/runtime/factory.ts"
    click RTRuntime "https://github.com/i-am-bee/beekeeper/blob/main/src/runtime/runtime.ts"
    click Supervisor "https://github.com/i-am-bee/beekeeper/blob/main/src/agents/supervisor.ts"
    click AgentRegistry "https://github.com/i-am-bee/beekeeper/blob/main/src/agents/registry/index.ts"
    click TaskManager "https://github.com/i-am-bee/beekeeper/blob/main/src/tasks/manager/manager.ts"
    click WorkspaceManager "https://github.com/i-am-bee/beekeeper/blob/main/src/workspaces/manager/manager.ts"
    click AccessControl "https://github.com/i-am-bee/beekeeper/blob/main/src/access-control/dto.ts"
    click ToolsFactory "https://github.com/i-am-bee/beekeeper/blob/main/src/base/tools-factory.ts"
    click LLMHelper "https://github.com/i-am-bee/beekeeper/blob/main/src/helpers/llm.ts"
    click TavilyClient "https://github.com/i-am-bee/beekeeper/blob/main/src/tools/tavily/client.ts"
    click TavilySearch "https://github.com/i-am-bee/beekeeper/blob/main/src/tools/tavily/tavily-search.ts"
    click TavilyExtract "https://github.com/i-am-bee/beekeeper/blob/main/src/tools/tavily/tavily-extract.ts"

    %% Styles
    classDef ui fill:#FFA500,stroke:#333,stroke-width:1px
    classDef core fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef ext fill:#90EE90,stroke:#333,stroke-width:1px
    classDef util fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef cloud fill:#E0FFFF,stroke:#333,stroke-width:1px
    classDef storage fill:#F0E68C,stroke:#333,stroke-width:1px
    classDef external fill:#FFFFFF,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
```
