# eigent-ai/eigent architecture

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

- Interactive diagram: https://gitdiagram.com/eigent-ai/eigent
- Repository: https://github.com/eigent-ai/eigent

## Overview

##### Project type and purpose
- This is a self-hosted, full-stack desktop application built on Electron.
- The user interface is powered by React (TypeScript, Tailwind, Radix UI, Zustand), packaged in an Electron renderer process.
- The application embeds a FastAPI backend (Uvicorn/uv) that implements a multi-agent workforce using the CAMEL framework.
- Agents use plugin-style “toolkits” for tasks (web search, code execution, file I/O, 3rd-party APIs like Google, Slack, Notion).

##### High-level file-structure analysis
- Top-level directories:
- backend/: FastAPI application (app/command, controller, service, component, middleware, utils, model)
- electron/: Electron main/preload scripts (TypeScript)
- src/: React frontend (components/, pages/, routers/, store/, hooks/, lib/)
- package/, @stackframe/, @stackframe/stack-shared/: Published UI libraries and shared utilities
- Config and build artifacts: tsconfig, vite.config, electron-builder.json, GitHub workflows.
- docs/, resources/scripts: docs and installer scripts.

##### README insights
- Tech stack: Frontend: React + Electron + TypeScript; Backend: FastAPI + Uvicorn; Multi‐agent via CAMEL; OAuth 2.0; no external DB.
- Features: Multi‐agent coordination, human-in-loop, local model support, MCP tool integration.

##### Main components
a. Client layer (Electron desktop app)
- Renderer process: React UI, Zustand stores, React Flow for workflow editing
- Preload script: securely exposes IPC / HTTP bridge
- Main process: window lifecycle, updater, native shell interactions
b. API layer (FastAPI server)
- Controllers (chat_controller, task_controller, model_controller, tool_controller)
- Services (chat_service, task_service) orchestrating multi-agent workflows
- Components: Camel-AI core, Pydantic validation, encryption, environment loader, debug
- Middleware & exception handlers: logging, error translation
c. Multi-Agent Core & Toolkits
- Multi-agent engine (CAMEL) coordinates agents in parallel
- Toolkit plugins (audio, image, browser, code execution, Slack, Google, GitHub, file I/O, etc.)
- Workforce manager (sync_step, single_agent_worker)
d. External integrations
- Third-party REST APIs: OpenAI or local model endpoints, Google Calendar/Drive/Gmail, Notion, Slack, Twitter, LinkedIn, etc.
- Local OS: file system, terminal (for code execution toolkit)
e. Data flow / storage
- In-memory stores (Zustand in UI; Python objects in FastAPI)
- Local file store for user data, logs, report HTML (no external database shown)

##### Relationships & interactions
1. User clicks in the React UI → React sends HTTP requests (via http.ts) through Electron’s preload to FastAPI endpoints.
2. FastAPI controller routes the request → invokes the appropriate service.
3. Service initializes a multi-agent “workforce” → divides task into subtasks, spins up agents via Camel.
4. Each agent uses toolkit components to perform actions (web requests, code runs, file reads/writes, human-in-loop prompts).
5. Agents emit events/results back to the service → aggregated results returned via controller to UI.

##### Architectural patterns & design principles
- Layered architecture: Presentation (UI), API (controllers), Business (services), Core (Camel engine), Plugins (toolkits)
- Plugin pattern for toolkits: each toolkit implements a common abstract interface
- MVC-style separation (controller → service → component)
- Event-driven multi-agent orchestration
- Local first / zero-setup: backend runs locally via uv, no external infra required

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Desktop Client Layer
    subgraph "Desktop Client" 
        direction LR
        Renderer["Renderer Process (React UI)"]:::ui
        HTTPClient["HTTP Client Module"]:::ui
        Preload["Preload Script (IPC/HTTP Bridge)"]:::ui
        MainProc["Main Process (Window lifecycle, updater, native shell)"]:::ui
        Store["State Management (Zustand stores)"]:::ui
    end

    %% Backend Layer
    subgraph "Embedded Backend" 
        direction LR
        FastAPI["FastAPI Server"]:::api

        subgraph "Controllers"
            ChatCtrl["ChatController"]:::api
            TaskCtrl["TaskController"]:::api
            ModelCtrl["ModelController"]:::api
            ToolCtrl["ToolController"]:::api
        end

        subgraph "Services"
            ChatSvc["ChatService"]:::api
            TaskSvc["TaskService"]:::api
        end

        subgraph "Components"
            EnvLoader["Environment Loader"]:::api
            Encrypt["Encryption"]:::api
            DebugComp["Debugging"]:::api
            CmdHelpers["Command Helpers"]:::api
            ModelVal["Model Validation"]:::api
        end

        Middleware["Middleware & Exception Handlers"]:::api

        subgraph "Multi-Agent Core & Toolkits"
            direction LR
            Workforce["Workforce Orchestration"]:::core
            SyncStep["Sync Step Coordination"]:::core
            SingleWorker["Single Agent Worker"]:::core
            ToolkitAbstract["Abstract Toolkit Interface"]:::core
            AudioToolkit["Audio Analysis Toolkit"]:::core
            CodeExecToolkit["Code Execution Toolkit"]:::core
            WebSearchToolkit["Web Search Toolkit"]:::core
            FileIOToolkit["File I/O Toolkit"]:::core
            ThirdPartyToolkit["Third-Party API Toolkits"]:::core
        end
    end

    %% External Services & Local OS
    subgraph "External Services & Local OS"
        direction LR
        OpenAI["OpenAI/Local Model APIs"]:::external
        Google["Google Calendar/Drive/Gmail"]:::external
        SlackExt["Slack"]:::external
        NotionExt["Notion"]:::external
        FileSys["Local File System"]:::external
        Terminal["Terminal/OS"]:::external
    end

    %% Client to Backend Flow
    Renderer -->|click/UI action| HTTPClient
    HTTPClient -->|"HTTP requests"| Preload
    Preload -->|"forwards API calls"| FastAPI

    %% Backend internal routing
    FastAPI --> ChatCtrl
    FastAPI --> TaskCtrl
    FastAPI --> ModelCtrl
    FastAPI --> ToolCtrl

    ChatCtrl --> ChatSvc
    TaskCtrl --> TaskSvc

    ChatSvc --> Workforce
    TaskSvc --> Workforce

    Workforce --> SyncStep
    Workforce --> SingleWorker

    SingleWorker --> ToolkitAbstract
    SyncStep --> ToolkitAbstract

    ToolkitAbstract --> AudioToolkit
    ToolkitAbstract --> CodeExecToolkit
    ToolkitAbstract --> WebSearchToolkit
    ToolkitAbstract --> FileIOToolkit
    ToolkitAbstract --> ThirdPartyToolkit

    %% Toolkits to External
    AudioToolkit --> FileSys
    CodeExecToolkit --> Terminal
    WebSearchToolkit --> OpenAI
    ThirdPartyToolkit --> Google
    ThirdPartyToolkit --> SlackExt
    ThirdPartyToolkit --> NotionExt
    FileIOToolkit --> FileSys

    %% Response flow
    FastAPI -->|"HTTP response"| Preload
    Preload --> HTTPClient
    HTTPClient --> Renderer

    %% Click Events
    click Renderer "https://github.com/eigent-ai/eigent/tree/main/src/"
    click HTTPClient "https://github.com/eigent-ai/eigent/blob/main/src/api/http.ts"
    click Preload "https://github.com/eigent-ai/eigent/blob/main/electron/preload/index.ts"
    click MainProc "https://github.com/eigent-ai/eigent/blob/main/electron/main/index.ts"
    click Store "https://github.com/eigent-ai/eigent/tree/main/src/store/"
    click FastAPI "https://github.com/eigent-ai/eigent/blob/main/backend/main.py"
    click ChatCtrl "https://github.com/eigent-ai/eigent/blob/main/backend/app/controller/chat_controller.py"
    click TaskCtrl "https://github.com/eigent-ai/eigent/blob/main/backend/app/controller/task_controller.py"
    click ModelCtrl "https://github.com/eigent-ai/eigent/blob/main/backend/app/controller/model_controller.py"
    click ToolCtrl "https://github.com/eigent-ai/eigent/blob/main/backend/app/controller/tool_controller.py"
    click ChatSvc "https://github.com/eigent-ai/eigent/blob/main/backend/app/service/chat_service.py"
    click TaskSvc "https://github.com/eigent-ai/eigent/blob/main/backend/app/service/task.py"
    click EnvLoader "https://github.com/eigent-ai/eigent/blob/main/backend/app/component/environment.py"
    click Encrypt "https://github.com/eigent-ai/eigent/blob/main/backend/app/component/encrypt.py"
    click DebugComp "https://github.com/eigent-ai/eigent/blob/main/backend/app/component/debug.py"
    click CmdHelpers "https://github.com/eigent-ai/eigent/blob/main/backend/app/component/command.py"
    click ModelVal "https://github.com/eigent-ai/eigent/blob/main/backend/app/component/model_validation.py"
    click Middleware "https://github.com/eigent-ai/eigent/tree/main/backend/app/middleware/"
    click Workforce "https://github.com/eigent-ai/eigent/blob/main/backend/app/utils/workforce.py"
    click SyncStep "https://github.com/eigent-ai/eigent/blob/main/backend/app/utils/server/sync_step.py"
    click SingleWorker "https://github.com/eigent-ai/eigent/blob/main/backend/app/utils/single_agent_worker.py"
    click ToolkitAbstract "https://github.com/eigent-ai/eigent/blob/main/backend/app/utils/toolkit/abstract_toolkit.py"
    click AudioToolkit "https://github.com/eigent-ai/eigent/blob/main/backend/app/utils/toolkit/audio_analysis_toolkit.py"
    click CodeExecToolkit "https://github.com/eigent-ai/eigent/blob/main/backend/app/utils/toolkit/code_execution_toolkit.py"
    click WebSearchToolkit "https://github.com/eigent-ai/eigent/blob/main/backend/app/utils/toolkit/search_toolkit.py"
    click FileIOToolkit "https://github.com/eigent-ai/eigent/blob/main/backend/app/utils/toolkit/file_write_toolkit.py"
    click ThirdPartyToolkit "https://github.com/eigent-ai/eigent/tree/main/backend/app/utils/toolkit/"

    %% Styles
    classDef ui fill:#D0E8FF,stroke:#0366D6,color:#0366D6;
    classDef api fill:#E6F4EA,stroke:#22863A,color:#22863A;
    classDef core fill:#FFF5E5,stroke:#D15704,color:#D15704;
    classDef external fill:#F0F0F0,stroke:#6A737D,color:#6A737D;
```
