# i-am-bee/beeai-framework-starter architecture

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

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

## Overview

##### Main Components
- Agent Modules: Represent the agent implementations found in the src directory. These include:
- src/agent.ts (basic agent execution)
- src/agent_code_interpreter.ts (agent that uses the Bee Code Interpreter service)
- src/agent_observe.ts (agent integrated with observability instrumentation)
- src/agent_workflow.ts (if it coordinates additional workflows)
- Support Libraries and Modules: Include the helpers (e.g., src/helpers/reader.ts) and hooks (e.g., src/hooks/telemetry.ts) which encapsulate shared functionality.
- External Services:
- Bee Code Interpreter: A gRPC-based service configured via the infra folder (infra/bee-code-interpreter.yaml) running on http://127.0.0.1:50081. This service receives code from agent_code_interpreter and executes Python code safely.
- Observability Service: Represents the integration with OpenInference Instrumentation. Optionally, include Phoenix as a visualizer if running.
- Infrastructure/Deployment Setup:
- Docker Compose (docker-compose.yml) and other .env and infra-related files that set up the containerized environment.
- Container orchestration tools (Docker, Rancher, or Podman as documented).

##### Out Their Relationships and Interactions
- If applicable, show shared modules like helpers and hooks connecting to the agents that use their functionality.
- Infrastructure components (Docker Compose, .env configuration, infra YAML) as part of the deployment environment that orchestrates these services.

##### Architectural Patterns and Design Principles
- Modular Architecture: The separation of concerns is clear—different agents handle specific tasks (i.e., code execution vs. observability).
- External Service Integration: Using gRPC for service communication with the Bee Code Interpreter and an instrumentation layer for observability shows a decoupled design.
- Containerized Deployment: The inclusion of Docker Compose and other infra files indicates that the project is designed for containerized environments.
- Maintainability via proper tooling: The use of linting (eslint.config.js), formatting (prettier.config.js), and environment configuration ensures best practices for a production-level setup.

- At the top, have an “Input / Trigger” node (e.g., CLI input or npm run command).
- On the left, group Agent Modules (agent.ts, agent_code_interpreter.ts, agent_observe.ts, agent_workflow.ts) in a container labeled “Agent Core.”
- Similarly, connect agent_observe.ts to a node labeled “OpenInference Instrumentation Service / Phoenix (Observability)” to indicate trace and telemetry exporting.
- Optionally, include a node for “Shared Utilities” covering helpers and hooks, linking to the agent modules.
- Use annotations to note critical ports, protocols (gRPC), and tools (Docker, NodeJS, TypeScript).

## Diagram (Mermaid)

```mermaid
flowchart TD
    TRIGGER["Input/Trigger"]:::trigger

    subgraph "Agent Core"
        A["Agent Module (agent.ts)"]:::agent
        AI["Agent Code Interpreter (agent_code_interpreter.ts)"]:::agent
        AO["Agent Observability (agent_observe.ts)"]:::agent
        AW["Agent Workflow Coordinator (agent_workflow.ts)"]:::agent
    end

    subgraph "Shared Utilities"
        U1["Shared Utilities – Helpers"]:::utility
        U2["Shared Utilities – Hooks for Telemetry"]:::utility
    end

    EX1["Bee Code Interpreter Service (gRPC on 127.0.0.1:50081)"]:::external
    EX2["Observability / OpenInference Instrumentation Service / Phoenix"]:::external

    INF["Configuration & Infrastructure\n(docker-compose.yml, .env.template, infra/bee-code-interpreter.yaml)"]:::infra

    %% Data flow from trigger to agents
    TRIGGER --> A
    TRIGGER --> AI
    TRIGGER --> AO
    TRIGGER --> AW

    %% Agents interacting with external services and utilities
    AI -->|"gRPC"| EX1
    AO -->|"telemetry"| EX2

    A --> U1
    AI --> U1
    AO --> U2

    %% Infrastructure deployment connections
    INF --> EX1
    INF --> EX2

    %% Click Events
    click A "https://github.com/i-am-bee/beeai-framework-starter/blob/main/src/agent.ts"
    click AI "https://github.com/i-am-bee/beeai-framework-starter/blob/main/src/agent_code_interpreter.ts"
    click AO "https://github.com/i-am-bee/beeai-framework-starter/blob/main/src/agent_observe.ts"
    click AW "https://github.com/i-am-bee/beeai-framework-starter/blob/main/src/agent_workflow.ts"
    click U1 "https://github.com/i-am-bee/beeai-framework-starter/blob/main/src/helpers/reader.ts"
    click U2 "https://github.com/i-am-bee/beeai-framework-starter/blob/main/src/hooks/telemetry.ts"
    click EX1 "https://github.com/i-am-bee/beeai-framework-starter/blob/main/infra/bee-code-interpreter.yaml"
    click INF "https://github.com/i-am-bee/beeai-framework-starter/blob/main/docker-compose.yml"

    %% Styles
    classDef agent fill:#AEDFF7,stroke:#333,stroke-width:2px;
    classDef external fill:#FFF2CC,stroke:#333,stroke-width:2px;
    classDef infra fill:#D9EAD3,stroke:#333,stroke-width:2px;
    classDef utility fill:#FCE5CD,stroke:#333,stroke-width:2px;
    classDef trigger fill:#C9DAF8,stroke:#333,stroke-width:2px;
```
