How hexdocom/lemonai works
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