# disolaterx/bolna architecture

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

- Interactive diagram: https://gitdiagram.com/disolaterx/bolna
- Repository: https://github.com/disolaterx/bolna

## Overview

##### Main Components
- Bolna Core – Represented by the “bolna” directory, it contains the heart of the framework. Within the core, there are several logical sub-components:
- Agent Manager (bolna/agent_manager): Responsible for managing, dispatching, and orchestrating agents.
- Agent Types (bolna/agent_types): Different types of agents are implemented here to address specific tasks (e.g., conversational, extraction, summarization, etc.).
- Classification (bolna/classification): Likely used to classify or route incoming audio/text.
- Helpers and Constants: Utility functions and configurations that support the application’s operations.
- LLMS (bolna/llms): Abstraction layer for interacting with various LLM providers.
- Memory (bolna/memory): Caching mechanism (both in-memory scalar and vector caches) for prompt and agent data.
- Synthesizer and Transcriber: These modules (bolna/synthesizer and bolna/transcriber) connect the system to various TTS and ASR providers.
- Input and Output Handlers (bolna/input_handlers and bolna/output_handlers): These parts handle voice input streams from telephony or web calls and emit the processed responses.
- Providers (bolna/providers.py) and Prompts: Define how external providers are integrated.

- Local Setup – Present in the “local_setup” directory:
- Docker Compose files, Dockerfiles, and configuration files set up containerized environments including telephony servers (Twilio, Plivo), ngrok for tunneling, and Redis for caching persisting session or agent data.
- Quickstart scripts to launch client/server setups locally.

##### Relationships and Interactions
- The bolna core acts as the central orchestrator. It listens for incoming interactions via input handlers (e.g., telephony, daily web calls).
- Once a call or voice input is received, the appropriate agent (from one of the types in bolna/agent_types) is selected and routed via the agent manager.
- The agents interface with LLMs (through the bolna/llms modules) for conversation processing.
- Depending on the need, synthesized responses are generated using TTS providers via the synthesizer module.
- For telephony functionality, the system manages provider-specific logic via dedicated input/output handler sub-modules (in particular under telephony_providers).
- The memory/cache modules store conversation context, while the classification module may help route input data.
- In a local development or production deployment, the local_setup containerized environment wraps key services: a dedicated Bolna server container, telephony server containers for handling Twilio/Plivo requests, a tunneling layer (ngrok) for external connectivity, and a Redis container for persistence.

##### Architectural Patterns and Design Principles
- Modular/Plug-in Architecture: Notice how different providers and agents are implemented as separate modules – this facilitates extensibility.
- Separation of Concerns: Distinct modules for orchestration, agent management, transcription, synthesis, and input/output handling underline a clean separation of concerns.
- Dependency Injection / Configuration Driven: Environment variables (from .env) help plug in API credentials and configurations making it flexible.
- Use of Containers: The “local_setup” directory demonstrates containerization best practices using Docker Compose, reinforcing the microservices-style separation for telephony servers and core logic.

##### Including Technologies, Frameworks, and Libraries
- Telephony providers: Twilio, Plivo, potentially others.
- ASR Providers: Deepgram (and others as mentioned), integrated via custom transcribers.
- TTS Providers: AWS Polly, ElevenLabs, OpenAI, etc., via the synthesizer implementations.
- LLM Providers: OpenAI, DeepSeek, Llama, etc. via the “bolna/llms” implementation.
- Auxiliary: Docker for containerization; Redis for caching; ngrok for tunneling.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Bolna Core"
        A["Agent Manager"]:::core
        B["Agent Types"]:::core
        C["Classification"]:::core
        D["Helpers"]:::core
        E["Constants"]:::core
        F["LLMS"]:::core
        G["Memory"]:::core
        H["Synthesizer"]:::core
        I["Transcriber"]:::core
        J["Input Handlers"]:::core
        K["Telephony Input"]:::core
        L["Telephony Providers (Input)"]:::core
        M["Output Handlers"]:::core
        N["Telephony Providers (Output)"]:::core
        O["Providers"]:::external
        P["Prompts"]:::external
    end

    subgraph "Local Setup"
        Q["Bolna Server Container"]:::infra
        R["Telephony Server Container"]:::infra
        S["ngrok Tunnel"]:::infra
        T["Redis Container"]:::infra
    end

    %% Deployment and External Phone Routing
    S --> R

    %% Telephony input flow from infrastructure to core
    R --> K
    J --> K
    K --> I

    %% Core orchestration flow
    I --> A
    A --> B
    A --> C
    A --> F
    F --> H
    H --> M
    M --> N

    %% Memory as support for orchestration and LLM operations
    A -- "cache" --> G
    F -- "cache" --> G

    %% Providers integration used by transcription and synthesis
    O --> H
    P --> H
    O --> I
    P --> I

    %% Utility modules support Agent Manager
    D --- A
    E --- A

    %% Local setup hosting Bolna Core
    Q --> T

    %% Click Events
    click A "https://github.com/disolaterx/bolna/tree/master/bolna/agent_manager"
    click B "https://github.com/disolaterx/bolna/tree/master/bolna/agent_types"
    click C "https://github.com/disolaterx/bolna/tree/master/bolna/classification"
    click D "https://github.com/disolaterx/bolna/tree/master/bolna/helpers"
    click E "https://github.com/disolaterx/bolna/blob/master/bolna/constants.py"
    click F "https://github.com/disolaterx/bolna/tree/master/bolna/llms"
    click G "https://github.com/disolaterx/bolna/tree/master/bolna/memory"
    click H "https://github.com/disolaterx/bolna/tree/master/bolna/synthesizer"
    click I "https://github.com/disolaterx/bolna/tree/master/bolna/transcriber"
    click J "https://github.com/disolaterx/bolna/tree/master/bolna/input_handlers"
    click K "https://github.com/disolaterx/bolna/tree/master/bolna/input_handlers/telephony"
    click L "https://github.com/disolaterx/bolna/tree/master/bolna/input_handlers/telephony_providers"
    click M "https://github.com/disolaterx/bolna/tree/master/bolna/output_handlers"
    click N "https://github.com/disolaterx/bolna/tree/master/bolna/output_handlers/telephony_providers"
    click O "https://github.com/disolaterx/bolna/blob/master/bolna/providers.py"
    click P "https://github.com/disolaterx/bolna/blob/master/bolna/prompts.py"
    click Q "https://github.com/disolaterx/bolna/tree/master/local_setup"
    click R "https://github.com/disolaterx/bolna/tree/master/local_setup"
    click S "https://github.com/disolaterx/bolna/tree/master/local_setup"
    click T "https://github.com/disolaterx/bolna/tree/master/local_setup"

    %% Styles
    classDef core fill:#CEF6F5,stroke:#2E64FE,stroke-width:2px;
    classDef external fill:#F5ECCE,stroke:#B45F04,stroke-width:2px;
    classDef infra fill:#D8F6CE,stroke:#239B56,stroke-width:2px;
```
