# conradlog/eliza architecture

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

- Interactive diagram: https://gitdiagram.com/conradlog/eliza
- Repository: https://github.com/conradlog/eliza

## Overview

##### Project Type and Purpose
- Eliza is an AI agent operating system with multi-agent capabilities, flexible connectors (Discord, X/Twitter, Telegram, etc.), and a plugin-based architecture. It is designed for use cases ranging from chatbots and autonomous agents to business process management and video game NPCs.
- The project is structured as a monorepo with multiple packages for core logic, client interfaces, plugins, and action modules. It also contains a dedicated “agent” that orchestrates the AI operations.

##### File Structure – Key Directories and Modules
a. Agent and Client:
– The “agent” folder: Contains the main TypeScript code that sets up the AI agent (including tests, default characters, configuration, etc.).
– The “client” folder: Holds a React-based frontend (with components, hooks, routes, and configurations for tools like Vite and Tailwind) that lets users interact with the agent via a web interface.
b. Packages and Modular Components:
– “packages/core”: Implements the core functionality of Eliza (actions, cache, embedding, environment, etc.).
– Other packages (e.g., “packages/adapter-sqlite”, “packages/cli”, “packages/client-direct”, “packages/plugin-bootstrap”, “packages/dynamic-imports”) indicate a modular architecture. Each provides adapters, direct client functionality, or plugin frameworks that extend the base functionality.
c. Infrastructure & Configuration:
– Dockerfiles and docker-compose files indicate containerized deployment.
– Numerous CI/CD workflows under the “.github/workflows” folder show automation for testing, linting, and documentation generation.
– Scripts, tests, and documentation (in “docs” and “scripts”) detail utilities to start, test, and maintain the project.
d. Documentation:

##### Suggested Components
a. User Interface:
– Clients: Browser-based UI from the “client” folder (React components, routes, and hooks) that handles user interactions and displays chat interfaces.
b. Agent Backend:
– The “agent” component handles multi-agent orchestration, configuration management, and routing of commands/actions.
– It integrates with the core modules (from the “packages/core” directory) that cover business logic (actions, memory management, context handling, etc.).
c. Modular Plugins and Adapters:
– Indicate the plugin framework that allows custom actions (plugins are loaded at runtime via configuration in a character file).
d. External Connectors and Services:
e. Supporting Infrastructure:
– Include code management and CI/CD pipelines (represented by GitHub Actions workflows) that automate testing, building, and deployment.
– Optionally, show deployment containers using Docker (with “Dockerfile”, “docker-compose.yaml”, etc.), indicating that parts of the system (agent, client) run in containerized environments.

##### Relationships and Interactions
– From the user’s browser to the client UI, and then to the agent backend.
– Between the agent backend and core modules (actions, memory, evaluators, etc.) where central processing happens.
– Inter-module communication for dynamic plugin loading and external connector invocation.
– Communication with external messaging platforms (Discord, Twitter, etc.).

##### Architectural Patterns and Design Principles Highlighted
- Modularity and extensibility: Emphasized by having separate packages for core functionality, plugins, adapters, and client connectors.
- Separation of concerns: Frontend (client) is decoupled from the backend logic (agent & core modules).
- Microservices-like architecture within a monorepo: Although packaged in one repository, each package (core, adapter, plugin) acts as a self-contained module.
- Containerization for deployment: Use of Docker provides portability and isolated environments.

##### Final Advice
- Refer to the “eliza_diagram.png” in the docs for inspiration and alignment with how the project’s creators envision the overall architecture.
– Highlight the clear separation between backend orchestration (agent and core modules) and the frontend client.
– Emphasize the extensibility through plugins and adapters, showing integration points for third-party services.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer"
        UI["Client UI"]:::presentation
    end

    %% Application Layer
    subgraph "Application Layer"
        Agent["Agent Backend"]:::application
    end

    %% Domain/Service Layer
    subgraph "Domain/Service Layer"
        Core["Core Modules"]:::domain
        Plugins["Modular Plugins"]:::domain
        DB["Database Adapter"]:::domain
        Direct["Direct Client Connector"]:::domain
        Dynamic["Dynamic Plugin Loader/Imports"]:::domain
    end

    %% Integration Layer
    subgraph "Integration Layer"
        Discord["Discord"]:::integration
        Twitter["X/Twitter"]:::integration
        Telegram["Telegram"]:::integration
    end

    %% Supporting Infrastructure
    subgraph "Supporting Infrastructure"
        CICD["CI/CD Pipelines"]:::infra
        Container["Deployment Infrastructure"]:::infra
        Docs["Documentation"]:::infra
    end

    %% Connections between layers
    UI -->|"APIcalls"| Agent
    Agent -->|"ProcessRequest"| Core
    Agent -->|"PluginIntegration"| Plugins
    Agent -->|"DirectCall"| Direct
    Agent -->|"DynamicLoader"| Dynamic
    Core -->|"DBAccess"| DB

    Discord -->|"EventDispatch"| Agent
    Twitter -->|"EventDispatch"| Agent
    Telegram -->|"EventDispatch"| Agent

    CICD -->|"Deploys"| Agent
    Container -->|"Hosts"| UI
    Container -->|"Hosts"| Agent

    %% Click Events
    click UI "https://github.com/conradlog/eliza/tree/main/client/"
    click Agent "https://github.com/conradlog/eliza/tree/main/agent/"
    click Core "https://github.com/conradlog/eliza/tree/main/packages/core/"
    click Plugins "https://github.com/conradlog/eliza/tree/main/packages/plugin-bootstrap/"
    click DB "https://github.com/conradlog/eliza/tree/main/packages/adapter-sqlite/"
    click Direct "https://github.com/conradlog/eliza/tree/main/packages/client-direct/"
    click Dynamic "https://github.com/conradlog/eliza/tree/main/packages/dynamic-imports/"
    click CICD "https://github.com/conradlog/eliza/tree/main/.github/workflows/"
    click Container "https://github.com/conradlog/eliza/tree/main/Dockerfile"
    click Docs "https://github.com/conradlog/eliza/tree/main/docs/"

    %% Styles
    classDef presentation fill:#AED6F1,stroke:#1F618D,stroke-width:2px;
    classDef application fill:#A9DFBF,stroke:#145A32,stroke-width:2px;
    classDef domain fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef integration fill:#F5CBA7,stroke:#C0392B,stroke-width:2px;
    classDef infra fill:#D2B4DE,stroke:#6C3483,stroke-width:2px;
```
