molecule-core/docs/architecture.md

Architecture Overview

Molecule AI is a distributed platform for orchestrating AI agent teams. Three components form the core system, connected by HTTP, WebSocket, and JSON-RPC protocols.

System Components

Browser ──HTTP/WS──> Canvas (Next.js :3000)
                        │
                    HTTP + WS
                        │
                    Platform (Go :8080)
                     ┌──┴──┐
                 Postgres  Redis
                     │
                 Docker API
                     │
           ┌─────────┼─────────┐
       Agent-1    Agent-2    Agent-N
      (Python)   (Python)   (Python)
           └──A2A JSON-RPC 2.0──┘

Canvas (Next.js 15 + React Flow)

The browser-based visual UI. Built with @xyflow/react v12, Zustand for state, and Tailwind CSS.

• Renders workspaces as draggable nodes on a canvas
• Connects to Platform via REST (http://localhost:8080) and WebSocket (ws://localhost:8080/ws)
• Sends user messages to agents through the Platform's A2A proxy
• Receives real-time updates via WebSocket events (status changes, agent messages, A2A responses)

Source: canvas/

Platform (Go / Gin)

The control plane. Manages workspace lifecycle, provisions containers, proxies A2A communication, and broadcasts events.

Key responsibilities:

• Workspace CRUD -- create, list, update, delete workspaces
• Container provisioning -- starts Docker containers for each workspace agent, injects secrets as env vars
• A2A proxy -- forwards JSON-RPC requests from canvas to workspace agents, avoiding CORS/Docker network issues
• Registry -- agents self-register on startup, send heartbeats, update their AgentCard
• Discovery -- workspaces discover peers via hierarchy-based access control rules
• WebSocket hub -- broadcasts events to canvas clients (all events) and workspace clients (filtered by access)
• Secrets management -- global (/settings/secrets) + workspace-level encrypted secrets (AES-256-GCM) with inheritance (workspace overrides global)
• Liveness monitoring -- 3-layer health detection: passive (Redis TTL), proactive (Docker health sweep), reactive (A2A proxy check)

Source: workspace-server/

Workspace Runtime (Python)

The execution engine for individual agents. Each workspace runs in its own Docker container.

• Loads config from /configs/config.yaml
• Discovers the appropriate adapter (LangGraph, Claude Code, etc.)
• Wraps the agent in an A2A server (using a2a-sdk)
• Self-registers with Platform on startup (POST /registry/register)
• Sends periodic heartbeats (POST /registry/heartbeat)
• Communicates with other workspaces via A2A JSON-RPC 2.0

Source: workspace/

Message Flow

User sends a message to an agent

1. User types in ChatTab
2. Canvas sends POST /workspaces/:id/a2a with JSON-RPC body
3. Platform resolves workspace URL (cache or DB)
4. Platform wraps body in JSON-RPC 2.0 envelope if needed
5. Platform forwards to agent container (5-min timeout for canvas, 30-min for agent-to-agent)
6. Agent processes via LangGraph/adapter, returns JSON-RPC response
7. Platform broadcasts A2A_RESPONSE via WebSocket (canvas-initiated requests only)
8. Platform logs activity asynchronously
9. Canvas receives A2A_RESPONSE event, extracts text, displays in ChatTab

Agent-to-agent delegation

1. Agent A calls message/send targeting Agent B
2. Request goes through Platform A2A proxy (POST /workspaces/:id/a2a with X-Workspace-ID header)
3. Platform verifies access via CanCommunicate(callerID, targetID)
4. Platform forwards to Agent B's container (30-min timeout)
5. Agent B responds, Platform returns response to Agent A
6. Activity logged for both workspaces

Core Concepts

Workspace

The fundamental unit. A workspace represents an organizational role (not a task). Each workspace:

• Has a unique UUID, name, role description, and tier (1-4)
• Runs in its own Docker container
• Exposes a single A2A endpoint
• Can be expanded into a sub-team (Team Lead + children)
• Has a lifecycle: provisioning -> online -> degraded -> offline -> removed

Agent Card

An A2A protocol discovery document. Each workspace agent publishes an AgentCard containing:

• Name, description, version
• URL endpoint
• Capabilities (streaming, push notifications)
• Skills (id, name, description, tags, examples)
• Supported input/output modes

Updated via POST /registry/update-card and broadcast as AGENT_CARD_UPDATED.

A2A Protocol (Agent-to-Agent)

Industry-standard JSON-RPC 2.0 protocol for agent communication:

• message/send -- synchronous request/response
• message/stream -- SSE streaming variant
• tasks/get -- poll async task status

All agent-to-agent traffic flows through the Platform A2A proxy for access control and observability.

Hierarchy & Access Control

The organizational structure IS the network topology. CanCommunicate(callerID, targetID) rules:

• Same workspace: allowed
• Parent <-> child: allowed
• Siblings (same parent_id): allowed
• Root-level workspaces (both parent_id IS NULL): allowed
• Everything else: denied

Team Expansion (Fractal Architecture)

Any workspace can recursively expand into a sub-team. From the outside, it still exposes a single A2A endpoint. Inside, a Team Lead coordinates child agents.

Before:                     After expand:
┌──────────┐               ┌──────────────────────┐
│ Marketing│               │ Marketing (Team Lead)│
│          │   ──expand──> │  ├─ SEO Agent        │
│          │               │  ├─ Content Writer   │
│          │               │  └─ Analytics Agent  │
└──────────┘               └──────────────────────┘

• POST /workspaces/:id/expand provisions child workspaces from config
• POST /workspaces/:id/collapse removes children, reverting to single workspace
• Children are auto-wired: Team Lead ↔ children can communicate, children are siblings
• On the canvas, children render as chips inside the parent node

Tiered Security

Tier	Name	Isolation
1	Sandboxed	Read-only root FS, tmpfs /tmp, no /workspace mount
2	Standard	512 MiB memory, 1.0 CPU limit
3	Privileged	Privileged mode, host PID, Docker network
4	Full Access	Privileged, host PID, host network, Docker socket

Database (PostgreSQL)

Key tables:

Table	Purpose
workspaces	Core entity: id, name, role, tier, status, url, parent_id, agent_card (JSONB), heartbeat timestamps
workspace_secrets	Per-workspace encrypted secrets (AES-256-GCM). UNIQUE(workspace_id, key)
global_secrets	Platform-wide secrets. Workspace secrets with same key override globals
activity_logs	A2A communication logs: source, target, method, request/response bodies, duration, status
agent_memories	Hierarchical Memory Architecture: LOCAL, TEAM, GLOBAL scoped memories
structure_events	Append-only event log (WORKSPACE_ONLINE, AGENT_CARD_UPDATED, etc.)
workspace_config	Arbitrary JSONB config per workspace
workspace_memory	Key-value store with optional TTL per workspace
canvas_layouts	Node x/y positions on the canvas

Migrations: workspace-server/migrations/ (12 files, auto-applied on startup).

Directory Structure

molecule/
├── canvas/                        # Frontend (Next.js 15)
│   └── src/
│       ├── app/                   # Next.js app router pages
│       ├── components/            # React components (tabs/, workspace-node)
│       ├── store/                 # Zustand stores (canvas, socket, events)
│       ├── hooks/                 # Custom React hooks
│       └── lib/                   # Utilities
├── workspace-server/                      # Backend (Go / Gin)
│   ├── cmd/server/main.go        # Entry point
│   ├── cmd/cli/                   # molecli TUI dashboard
│   ├── internal/
│   │   ├── handlers/              # 24 HTTP handler files
│   │   ├── ws/                    # WebSocket hub + client management
│   │   ├── events/                # Broadcaster (WS + Redis pub/sub)
│   │   ├── db/                    # PostgreSQL + Redis connections
│   │   ├── provisioner/           # Docker container lifecycle
│   │   ├── registry/              # Liveness, health sweep, access rules
│   │   ├── crypto/                # AES-256-GCM encryption
│   │   └── models/                # Data types
│   └── migrations/                # 12 SQL migration files
├── workspace/            # Agent Runtime (Python)
│   ├── main.py                    # Entry point
│   ├── a2a_executor.py            # A2A request handler
│   ├── config.py                  # YAML config loader
│   ├── heartbeat.py               # Platform heartbeat loop
│   ├── adapters/                  # Runtime backends (langgraph, claude-code, ...)
│   └── tools/                     # Agent tools (delegation, sandbox, ...)
├── docker-compose.yml             # Full stack
└── docker-compose.infra.yml       # Infrastructure only (dev)

Supporting Infrastructure

Service	Image	Purpose
PostgreSQL 16	postgres:16-alpine	Primary database
Redis 7	redis:7-alpine	URL caching, pub/sub, TTL-based liveness
Langfuse	langfuse/langfuse:2 + ClickHouse	LLM call tracing and observability
LiteLLM (optional)	ghcr.io/berriai/litellm	Unified multi-provider LLM routing
Ollama (optional)	ollama/ollama	Local model inference