# hexdocom/lemonai architecture

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

- Interactive diagram: https://gitdiagram.com/hexdocom/lemonai
- Repository: https://github.com/hexdocom/lemonai

## Overview

##### Project type and purpose
- This is a desktop-focused, full-stack Electron application (“Lemon”) with a Vue.js frontend, a Node.js/Express-style backend, multiple microservices (Python browser automation), and a sandboxed execution/runtime layer (Docker & Local).
- Purpose: Provide a self-contained AI agent platform that accepts user tasks via GUI, orchestrates planning and tool invocations, executes code/browsing commands in sandboxes, and streams results back to the UI.

##### File structure
- Top-level “frontend” directory: Vue 3 + Vite SPA (auth, chat UI, settings, assets).
- Top-level “src” directory: Node.js app (app.js, routers/, models/, middlewares/, services), agent logic (src/agent), LLM wrappers (src/completion), runtime plugins (src/runtime), tools (src/tools), and utilities.
- “browser_server”: Python microservice for headful browser automation (agent.py + server.py).
- “containers” + docker-compose.yml + Dockerfiles: containerized deployment (app container, runtime sandbox container).
- preload.js + setup-renderer.js + setup.html + vite.*.config.js: Electron main/renderer bootstrap.

##### README
- Confirms Electron desktop app for macOS/Windows/Linux, Docker-based quick deployment, LLM-driven AI agent, self-subscription of custom models, real-time task tracking via sidebar.

a. Frontend (Electron + Vue.js)
- Electron Main Process
- Renderer Process (Vue SPA)
- Communicates with local backend via HTTP + Server-Sent Events (sse.js)
b. Backend API Server (Node.js/Express)
- Routers (agent/, conversation/, message/, user/, etc.)
- Middleware (authentication, context wrapping)
- Services: agent service, SSE broadcaster, file/membership/chat services
- Models: ORM or file-based persistence (users, conversations, tasks)
- Completion Layer: LLM adapters (OpenAI, Azure, Gemini)
- Agentic Pipeline: TaskManager → planners → reflection → summary
- Tools Facade: read/write code, run terminal, web search
- Runtime Orchestrator: selects DockerRuntime or LocalRuntime
c. Runtime Layer
- DockerRuntime (spawns sandboxed containers via Docker Socket)
- LocalRuntime (executes on host)
- Plugins: browser, vscode, action_execution_server
d. Browser Automation Service (Python)
- Exposed via HTTP (Flask/FastAPI) at port (e.g., 5005)
- Agent through backend calls browser_server for page navigation, scraping
e. External & Persistent Services
- LLM APIs (OpenAI, Azure, Gemini)
- Docker Engine (host socket)
- Persistent Storage (e.g., disk-based JSON/SQLite, volume at /app/data)
- Third-party APIs (payment gateways, membership plans)

##### Architectural patterns & design principles
- Layered/MVC: UI ↔ API ↔ Business Logic ↔ Data Persistence
- Microservices: Python browser_server decoupled from Node backend
- Plugin architecture: runtime/plugins for adding new execution contexts
- Agent-tool pattern: decouples “thinking” (prompt + planning) from “doing” (tools/runtime)
- Containerization: isolates code execution in sandboxed DockerRuntime

##### Essential elements
- Component labels (e.g., “Electron Main”, “Vue SPA”, “Express API Server”)
- Container boundaries: host machine vs. Docker runtime sandbox vs. Python service

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Frontend (UI Layer)"
        direction TB
        ElectronMain["Electron Main Process"]:::ui
        PreloadSetup["Preload & Renderer Setup"]:::ui
        VueRenderer["Vue SPA (Renderer Process)"]:::ui
        SSEClient["SSE Client (SSE)"]:::ui
    end

    subgraph "Backend (API & Business Logic)"
        direction TB
        ExpressAPI["Express API Server"]:::api
        Routers["API Routers"]:::api
        Middleware["Auth & Context Middleware"]:::api
        Services["Services"]:::api
        Models["Models (Persistence)"]:::data
        CompletionLayer["LLM Completion Layer"]:::external
        AgentPipeline["Agentic Pipeline"]:::api
        ToolsFacade["Tools Facade"]:::api
        RuntimeOrch["Runtime Orchestrator"]:::api
    end

    subgraph "Runtime & Plugins"
        direction TB
        DockerRuntime["DockerRuntime"]:::runtime
        LocalRuntime["LocalRuntime"]:::runtime
        PluginBrowser["Browser Plugin"]:::runtime
        PluginVSCode["VSCode Plugin"]:::runtime
        PluginAction["Action Execution Server"]:::runtime
    end

    subgraph "External Services & Data"
        direction TB
        LLMAPIs["LLM APIs"]:::external
        DockerEngine["Docker Engine"]:::external
        Storage["Persistent Storage"]:::data
        ThirdParty["Payment & Membership APIs"]:::external
        BrowserService["Browser Automation Service"]:::external
    end

    ElectronMain --> VueRenderer
    ElectronMain --> PreloadSetup
    PreloadSetup --> VueRenderer
    VueRenderer -->|"HTTP"| ExpressAPI
    VueRenderer -->|"SSE"| SSEClient
    SSEClient --> ExpressAPI
    ExpressAPI --> Routers
    Routers --> Middleware
    Middleware --> Services
    Services --> Models
    Services --> CompletionLayer
    Services --> AgentPipeline
    AgentPipeline --> ToolsFacade
    Services --> RuntimeOrch
    ExpressAPI -->|"HTTP"| BrowserService
    RuntimeOrch --> DockerRuntime
    RuntimeOrch --> LocalRuntime
    RuntimeOrch --> PluginBrowser
    RuntimeOrch --> PluginVSCode
    RuntimeOrch --> PluginAction
    CompletionLayer -->|"HTTPS"| LLMAPIs
    DockerRuntime -->|"Docker Socket"| DockerEngine
    Models --> Storage
    ExpressAPI -->|"HTTPS"| ThirdParty

    click ElectronMain "https://github.com/hexdocom/lemonai/blob/main/main.js"
    click PreloadSetup "https://github.com/hexdocom/lemonai/blob/main/preload.js"
    click VueRenderer "https://github.com/hexdocom/lemonai/tree/main/frontend/src/"
    click SSEClient "https://github.com/hexdocom/lemonai/blob/main/frontend/src/services/sse.js"
    click ExpressAPI "https://github.com/hexdocom/lemonai/blob/main/src/app.js"
    click Routers "https://github.com/hexdocom/lemonai/tree/main/src/routers/"
    click Middleware "https://github.com/hexdocom/lemonai/blob/main/src/middlewares/setGlobalToken.js"
    click Models "https://github.com/hexdocom/lemonai/tree/main/src/models/"
    click CompletionLayer "https://github.com/hexdocom/lemonai/tree/main/src/completion/"
    click AgentPipeline "https://github.com/hexdocom/lemonai/tree/main/src/agent/"
    click ToolsFacade "https://github.com/hexdocom/lemonai/tree/main/src/tools/"
    click DockerRuntime "https://github.com/hexdocom/lemonai/blob/main/src/runtime/DockerRuntime.js"
    click LocalRuntime "https://github.com/hexdocom/lemonai/blob/main/src/runtime/LocalRuntime.js"
    click PluginBrowser "https://github.com/hexdocom/lemonai/blob/main/src/runtime/plugins/browser/index.js"
    click PluginVSCode "https://github.com/hexdocom/lemonai/blob/main/src/runtime/plugins/vscode/index.js"
    click PluginAction "https://github.com/hexdocom/lemonai/blob/main/src/runtime/action_execution_server.js"
    click BrowserService "https://github.com/hexdocom/lemonai/blob/main/browser_server/browser_use/server.py"

    classDef ui fill:#E0F7FA,stroke:#006064,color:#000;
    classDef api fill:#E8F5E9,stroke:#1B5E20,color:#000;
    classDef runtime fill:#FFF3E0,stroke:#E65100,color:#000;
    classDef external fill:#ECEFF1,stroke:#90A4AE,color:#000;
    classDef data fill:#F3E5F5,stroke:#6A1B9A,color:#000;
```
