# i-am-bee/beeai architecture

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

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

## Overview

##### Project Type and Purpose
- BeeAI is an open, framework-agnostic platform for discovering, running, and composing AI agents across different programming languages. It provides a comprehensive ecosystem with various components such as CLI tools, web and UI interfaces, backend services, agent registries, and SDK packages for both Python and TypeScript.
- The system is designed to support multi-agent workflows where agents – built either as official or community contributions – can be discovered and orchestrated through the BeeAI framework.

##### File Structure
- The top-level directories illustrate clear separation by concerns:
- The “agents” folder contains both community and official agents. Each agent is self-contained with its Dockerfile, configuration (“agent.yaml”), and code (either in Python or TypeScript). This indicates a plugin-like ecosystem that supports agent discoverability.
- The “apps” folder holds several sub-applications:
◦ beeai-cli – a command-line interface tool for interacting with the system.
◦ beeai-server – the backend service that likely handles API requests, agent orchestration, workflows, and integrations (e.g., FastAPI endpoints, crons, adapters for file systems, telemetry, etc.).
◦ beeai-ui – a front-end UI application (React/TypeScript) for a desktop-like client interface.
◦ beeai-web – a web-based (likely Next.js) interface for end-user interactions.
- The “packages” folder contains various SDKs:
◦ acp-python-sdk, acp-typescript-sdk, and beeai-sdk – these provide programmatic access and tools for integrating with BeeAI, reflecting both client and server side roles.
- Additional directories (“docs”, “.github”, etc.) suggest robust CI/CD pipelines, testing, and documentation that also form part of the ecosystem’s support infrastructure.

##### Key Components and Their Relationships
- Core Services and APIs:
- BeeAI Server: Acts as the backend API that connects the UI, CLI, and SDKs. It implements routes, adapters, telemetry, and orchestration logic.
- Agent Registry: Defined by configuration files (agent-registry.yaml, provider-registry.yaml), this manages the available agents (both official and community) and their metadata.
- Clients and Interfaces:
- BeeAI CLI: Provides a command-line interface for direct user interaction, invoking agent workflows and performing administrative tasks (e.g., “beeai run chat”, “beeai compose sequential”).
- BeeAI UI and BeeAI Web: The UI (React-based) and web (Next.js) front-ends provide graphical and interactive access. They interact with the backend API and might also consume SDKs for real-time updates and agent management.
- SDK Packages:
- These include both Python and TypeScript SDKs that allow external systems or agent developers to interact with BeeAI services efficiently. They wrap the communication protocols (SSE/WS/HTTP) and provide client libraries to connect with the BeeAI Server.
- Agents:
- Agents are individual, self-contained modules implemented in various languages (and organized into “community” and “official” directories). They interface with the BeeAI ecosystem through standardized configuration (agent.yaml) and SDK protocols. They can be composed into workflows using features like “compose sequential.”
- Integration and Communication:
- The system supports orchestration where the CLI and UI/web front-ends send commands or queries (via REST/GraphQL or similar APIs provided by beeai-server) that trigger the execution of one or more agents.
- The server further communicates with agents (possibly through asynchronous protocols, SSE, websocket, or standard streams) and collects telemetry information.

##### Architectural Patterns and Design Principles
- Modularity and Extensibility: The clear separation into agents, apps (CLI, server, UI, web), and SDK packages indicates a highly modular and pluggable design.
- Microservices or Multi-Component Architecture: Although deployed as one repo, the separation into distinct sub-systems (backend, frontend, CLI, etc.) suggests that they could be deployed independently or containerized for scalability.
- Loose Coupling: Communication between components (e.g., through API routes, configuration files, and registries) is managed in a decoupled manner. This allows different teams (Python vs. TypeScript agents) to work independently.
- Containerization: The presence of Dockerfiles in several agent directories and apps emphasizes containerized deployment, which can be highlighted as part of the overall deployment architecture.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Client Side"
        CLI["BeeAI CLI"]:::client
        UI["BeeAI UI"]:::client
        WEB["BeeAI Web"]:::client
    end

    subgraph "SDK Packages"
        PY_SDK1["ACP Python SDK"]:::sdk
        PY_SDK2["BeeAI Python SDK"]:::sdk
        TS_SDK1["ACP TypeScript SDK"]:::sdk
        TS_SDK2["BeeAI TypeScript SDK"]:::sdk
    end

    subgraph "Backend Services"
        SERVER["BeeAI Server"]:::server
        REGISTRY_A["Agent Registry"]:::config
        REGISTRY_P["Provider Registry"]:::config
        COMMUNITY["Community Agents"]:::agents
        OFFICIAL["Official Agents"]:::agents
    end

    %% Connections from Clients to Server
    CLI -->|"sendsCommand"| SERVER
    UI  -->|"apiCall"| SERVER
    WEB -->|"apiCall"| SERVER

    %% Connections from SDKs to Server
    PY_SDK1 -->|"communicates"| SERVER
    PY_SDK2 -->|"communicates"| SERVER
    TS_SDK1 -->|"communicates"| SERVER
    TS_SDK2 -->|"communicates"| SERVER

    %% Connections within Backend Services
    SERVER -->|"orchestrates"| REGISTRY_A
    SERVER -->|"orchestrates"| REGISTRY_P
    REGISTRY_A -->|"manages"| COMMUNITY
    REGISTRY_A -->|"manages"| OFFICIAL

    %% Click Events
    click SERVER "https://github.com/i-am-bee/beeai/tree/main/apps/beeai-server"
    click CLI "https://github.com/i-am-bee/beeai/tree/main/apps/beeai-cli"
    click UI "https://github.com/i-am-bee/beeai/tree/main/apps/beeai-ui"
    click WEB "https://github.com/i-am-bee/beeai/tree/main/apps/beeai-web"
    click REGISTRY_A "https://github.com/i-am-bee/beeai/blob/main/agent-registry.yaml"
    click REGISTRY_P "https://github.com/i-am-bee/beeai/blob/main/provider-registry.yaml"
    click COMMUNITY "https://github.com/i-am-bee/beeai/tree/main/agents/community"
    click OFFICIAL "https://github.com/i-am-bee/beeai/tree/main/agents/official"
    click PY_SDK1 "https://github.com/i-am-bee/beeai/tree/main/packages/acp-python-sdk"
    click PY_SDK2 "https://github.com/i-am-bee/beeai/tree/main/packages/beeai-sdk"
    click TS_SDK1 "https://github.com/i-am-bee/beeai/tree/main/packages/acp-typescript-sdk"
    click TS_SDK2 "https://github.com/i-am-bee/beeai/tree/main/packages/beeai-sdk"

    %% Styles
    classDef client fill:#a2d2ff,stroke:#000,stroke-width:2px;
    classDef server fill:#ffb6b9,stroke:#000,stroke-width:2px;
    classDef sdk fill:#baffc9,stroke:#000,stroke-width:2px;
    classDef config fill:#caffbf,stroke:#000,stroke-width:2px;
    classDef agents fill:#ffdfba,stroke:#000,stroke-width:2px;
```
