# elizaos/eliza architecture

> Architecture diagram of the GitHub repository elizaos/eliza, 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/elizaos/eliza
- Repository: https://github.com/elizaos/eliza

## Overview

Based on our analysis of the provided file tree and README, we can see that this project is a full-featured, multi-agent AI operating system—named “Eliza”—that is designed to run autonomous agents with support for various client connectors (Discord, Twitter/X, Telegram, etc.), document ingestion, memory management, and a highly extensible plugin system. It is architected as a monorepo with several packages (e.g., core functionality, client integration, plugins like adapter-sqlite and client-direct) as well as separate directories for agent logic, client UI, scripts, and extensive documentation.

##### Main Components
- Frontend/Client: Represented by the “client” directory, which contains React-based UI components (e.g., Chat UI, sidebar, inputs) for interacting with the agent through a browser.
- Backend/Agent: The “agent” directory houses the core agent logic that orchestrates processing, while the “packages/core” contains the main business logic, such as how actions, memory, document ingestion, and plugin integrations are handled.
- Plugin/Extension System: Multiple packages (e.g., packages/plugin-bootstrap, packages/adapter-sqlite, packages/client-direct) show that the system supports modular extensions. These plugins can add connectors, change behavior, or support specific integrations.
- Connectors/Integrations: Highlight the connectors (Discord, Twitter/X, Telegram) that are referenced in both the README and the various client files. They allow the agent to interface with external systems.
- External Services: Identify any external services or databases (like caching, document stores, and retrievable memory) that may be used by the core agent, as indicated by files in packages/core (e.g., database.ts, cache.ts), as well as in the agent’s source code.
- Infrastructure & Deployment Tools: Dockerfiles, GitHub workflows, and deployment scripts (in scripts, docker-compose files, etc.) should be represented to show how the system is built, tested, and deployed.

##### Relationships & Interactions
- The Agent core uses its plugins to process actions, interact with third‐party APIs, manage memory, ingest documents, and handle tasks like text generation and preprocessing.
- The Plugin Manager (or extension loader) dynamically loads available plugins from the “packages” directory. These then integrate with the core’s action and evaluator modules.
- External connectors and integrations (to services like Discord/Twitter, etc.) should be shown as separate modules that feed input into the agent and receive output, completing a loop.
- Infrastructure components – such as the Docker environment, CI/CD workflows from the “.github/workflows” directory, and configuration files (.env, pnpm files) – should also be included as supporting artifacts that enable deployment and development.

##### Architectural Patterns & Technology Stacks
- Monorepo Pattern: Because multiple packages, shared configurations (pnpm-workspace.yaml, lerna.json), and common tooling are used, indicate that the project uses a monorepo structure to manage interdependent modules.
- Modular and Extensible Design: Emphasize the plugin system and modular packages (agent, client, core, plugins) that allow new actions, connectors, or evaluators to be added seamlessly.
- Integration with External APIs: Note the connectors and integration points for external services, which could also be modular.
- Use of TypeScript & Modern Tooling: Multiple TypeScript configuration files (tsconfig.json, tsconfig.app.json, etc.) and build scripts signal a modern development stack. Although not a primary architectural element, it can be mentioned as part of the tech stack.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend"
        Client_UI["Client UI (React)"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend"
        Agent_Core["Agent Logic"]:::backend
        Core_Business["Core Business Logic"]:::backend
        Agent_Core -->|"processes"| Core_Business
    end

    %% Plugin/Extension System
    subgraph "Plugin System"
        Plugin_Bootstrap["Plugin Bootstrap"]:::plugin
        Plugin_Adapter["Adapter SQLite"]:::plugin
        Plugin_ClientDirect["Client Direct Plugin"]:::plugin
    end

    %% External Services
    subgraph "External Services"
        Database["Database Module"]:::external
        Cache["Cache Module"]:::external
        Memory["Memory Management"]:::external
    end

    %% External Connectors Integration
    External_Connectors["External Connectors: Discord/Twitter/X/Telegram"]:::plugin

    %% Infrastructure & Deployment
    subgraph "Infrastructure"
        CI_CD["CI/CD Workflows"]:::infra
        Dockerfile_Node["Dockerfile"]:::infra
        DockerCompose_Node["docker-compose.yaml"]:::infra
        Deployment_Scripts["Deployment Scripts"]:::infra
    end

    %% Relationships between Layers
    Client_UI -->|"sendsInteractions"| Agent_Core
    Agent_Core -->|"callsPlugins"| Plugin_Bootstrap
    Agent_Core -->|"callsPlugins"| Plugin_Adapter
    Agent_Core -->|"callsPlugins"| Plugin_ClientDirect
    Plugin_ClientDirect -->|"providesConnector"| External_Connectors
    External_Connectors -->|"feedsData"| Agent_Core
    Core_Business -->|"integratesWith"| Database
    Core_Business -->|"integratesWith"| Cache
    Core_Business -->|"integratesWith"| Memory

    %% Infrastructure supporting components
    CI_CD -->|"buildTests"| Client_UI
    CI_CD -->|"buildTests"| Agent_Core
    CI_CD -->|"buildTests"| Plugin_Bootstrap
    CI_CD -->|"buildTests"| Plugin_Adapter
    CI_CD -->|"buildTests"| Plugin_ClientDirect
    Dockerfile_Node -->|"definesEnv"| Agent_Core
    Dockerfile_Node -->|"definesEnv"| Client_UI
    DockerCompose_Node -->|"orchestrates"| Agent_Core
    Deployment_Scripts -->|"deployAutomation"| Agent_Core

    %% Styling Classes
    classDef frontend fill:#ffcccc,stroke:#990000,stroke-width:2px;
    classDef backend fill:#ccffcc,stroke:#006600,stroke-width:2px;
    classDef plugin fill:#ccccff,stroke:#000099,stroke-width:2px;
    classDef external fill:#ffffcc,stroke:#999900,stroke-width:2px;
    classDef infra fill:#e0e0e0,stroke:#666666,stroke-width:2px;

    %% Click Events
    click Client_UI "https://github.com/elizaos/eliza/tree/main/client/"
    click Agent_Core "https://github.com/elizaos/eliza/tree/main/agent/"
    click Core_Business "https://github.com/elizaos/eliza/tree/main/packages/core/"
    click Plugin_Bootstrap "https://github.com/elizaos/eliza/tree/main/packages/plugin-bootstrap/"
    click Plugin_Adapter "https://github.com/elizaos/eliza/tree/main/packages/adapter-sqlite/"
    click Plugin_ClientDirect "https://github.com/elizaos/eliza/tree/main/packages/client-direct/"
    click Database "https://github.com/elizaos/eliza/blob/main/packages/core/src/database.ts"
    click Cache "https://github.com/elizaos/eliza/blob/main/packages/core/src/cache.ts"
    click Memory "https://github.com/elizaos/eliza/blob/main/packages/core/src/memory.ts"
    click CI_CD "https://github.com/elizaos/eliza/tree/main/.github/workflows/"
    click Dockerfile_Node "https://github.com/elizaos/eliza/tree/main/Dockerfile"
    click DockerCompose_Node "https://github.com/elizaos/eliza/blob/main/docker-compose.yaml"
    click Deployment_Scripts "https://github.com/elizaos/eliza/tree/main/scripts/"
```
