Architecture

EleAgent uses a distributed architecture with a controller node that serves the web UI and orchestrates queries across a pool of worker containers.

System Diagram

Components

Controller

The controller is a lean Node.js container that serves the web frontend and API. It does not have Python or Tesseract installed — all AI query execution is delegated to workers.

Responsibilities:

• Serve the React frontend (built by Vite)
• Expose Express REST API and WebSocket endpoint
• Manage authentication (JWT + API keys)
• Session slot management (SQLite-backed, max 5 concurrent)
• Route queries to available workers via WebSocket
• Relay streaming responses back to the browser

Workers (x5)

Each worker is a heavier container with the full analysis toolchain. Workers receive queries from the controller, execute them via the Claude Agent SDK, and stream results back.

Responsibilities:

• Execute AI queries using @anthropic-ai/claude-agent-sdk
• Run Python scripts for IFC, PDF, and Excel analysis
• Perform OCR via Tesseract
• Write generated artefacts (CSV, summaries) to the shared volume

Pre-installed tools:

• claude CLI (globally installed)
• Python 3 venv with: ifcopenshell, openpyxl, pandas, pdfplumber, PyMuPDF, pytesseract
• System tools: ripgrep, jq, sqlite3, tesseract-ocr, git

Egress Proxy

A Squid HTTP proxy on the internal network controls all outbound traffic from workers. Only HTTPS connections to Anthropic API and auth endpoints are permitted.

Allowed destinations:

• *.anthropic.com (API calls)
• *.claude.com (OAuth / platform authentication)

All other outbound traffic is denied. See Security for details.

Networks

Network	Scope	Members
internal	Private, no external routing	Controller, Workers, Egress Proxy
external	Bridge to host network	Controller (port 3001), Egress Proxy

Workers cannot reach the internet directly. All external traffic is routed through the egress proxy on the internal network.

Technology Stack

Component	Technology
Backend	Node.js 22 (ESM), Express 4
Frontend	React 18, Vite, Tailwind CSS
AI Integration	@anthropic-ai/claude-agent-sdk 0.2.56
Database	SQLite (better-sqlite3) with WAL mode
WebSocket	ws library
Container Base	node:22-bookworm-slim
Egress Proxy	Ubuntu Squid
Auth	JWT tokens, bcrypt password hashing

Docker Build Targets

The Dockerfile uses a multi-stage build with three targets:

Target	Purpose	Includes Python	Includes Tesseract
builder	Compile native addons (node-pty, better-sqlite3, bcrypt)	No	No
controller	Web UI + API server	No	No
worker	AI query execution	Yes (venv)	Yes