Molecule AI
ArchitectureTechnical Reference

System Architecture & Infrastructure

System architecture, database schema, Docker Compose orchestration, and environment variables.

Part of the Comprehensive Technical Documentation. Definitive reference based on a non-invasive scan of the molecule-core repository.

3. System Architecture

System Boundary Diagram

┌─────────────────────────────────────────────────────────────┐
│ Canvas (Next.js 15 · port 3000)                             │
│ React Flow + Zustand + WebSocket                            │
│ Visual drag-to-nest org chart · 10-tab ops panel            │
└──────────────────┬──────────────────────────────────────────┘
                   │ HTTP + WebSocket
┌──────────────────▼──────────────────────────────────────────┐
│ Platform (Go / Gin · port 8080)                             │
│ Control plane: workspace CRUD, registry, discovery,         │
│ A2A proxy, activity, memory APIs, secrets, approvals        │
└─────────┬────────────────────────────────────┬──────────────┘
          │                                    │
    Postgres 16                             Redis 7
    (internal: 5432)                        (internal: 6379)

┌─────────────────────────────────────────────────────────────┐
│ Workspace Runtime (Python 3.11+ Docker image)               │
│ Pluggable adapters: claude-code, langgraph, autogen,        │
│ openclaw, hermes, codex, google-adk, external               │
│ A2A protocol server · heartbeat · skills · HMA memory       │
└─────────────────────────────────────────────────────────────┘
          │
┌─────────────────────────────────────────────────────────────┐
│ Langfuse (self-hosted · ClickHouse + Postgres backend)      │
│ OpenTelemetry traces for every LLM call                     │
└─────────────────────────────────────────────────────────────┘

Network Model

PathProtocolPurpose
Canvas ↔ PlatformHTTP REST + WebSocketUI operations + real-time event fanout
Platform ↔ PostgresTCPSource of truth for all durable state
Platform ↔ RedisTCPEphemeral state (liveness TTL), caching, pub/sub
Workspace ↔ WorkspaceHTTP (A2A JSON-RPC 2.0)Direct peer-to-peer, platform not in data path
Workspace → LangfuseHTTPAutomatic OpenTelemetry tracing
Docker Networkmolecule-monorepo-netInternal-only by default, no exposed DB/Redis ports

Core Components

1. Canvas (Next.js 15)

  • React Flow for visual workspace graph
  • Zustand for state management
  • WebSocket for real-time updates
  • 10-tab side panel: Chat, Activity, Details, Skills, Terminal, Config, Files, Memory, Traces, Events
  • Drag-to-nest team building
  • Bundle import/export via drag-and-drop
  • Empty state with template palette + onboarding wizard

2. Platform (Go 1.25+ / Gin)

  • Gin-based REST API + WebSocket hub
  • Workspace lifecycle management (CRUD + pause/resume/restart)
  • Registry and heartbeat system (30s default)
  • Hierarchy-aware access control (CanCommunicate())
  • A2A proxy for browser-safe inter-workspace communication
  • Event broadcasting (Redis pub/sub → WebSocket fanout)
  • Docker provisioner with T1–T4 tier enforcement
  • Activity logging with configurable retention (default 7 days)
  • Secrets management (AES-256-GCM encryption)
  • File, terminal, bundle, template, traces APIs
  • Langfuse integration
  • Prometheus metrics endpoint

3. Workspace Runtime (Python 3.11+)

  • Unified workspace/ Docker image
  • Adapter-driven execution (7 runtimes)
  • A2A server via Uvicorn
  • Heartbeat loop (30s default)
  • Skill hot-reload system (~3 second propagation)
  • Memory tools with HMA scope support
  • Approval/human-in-the-loop integration
  • Activity reporting
  • Awareness namespace integration (optional)
  • Plugin-mounted shared rules and skills

4. Infrastructure

  • Postgres 16: Source of truth (workspaces, events, activity, secrets, memories)
  • Redis 7: Ephemeral state (liveness TTL 60s), URL caching, pub/sub
  • Langfuse 2.x: LLM tracing and observability (self-hosted, ClickHouse backend)
  • Docker: Workspace provisioning with T1–T4 tier system
  • LiteLLM proxy (optional): Unified API for multiple model providers
  • Ollama (optional): Local LLM models

4. Database Schema

11 migration files in workspace-server/migrations/.

Core Tables

TablePurposeKey Columns
workspacesCurrent state registryid, name, role, tier (1-4), status, parent_id, agent_card (JSONB), url, forwarded_to, last_heartbeat_at, last_error_rate, active_tasks, uptime_seconds, current_task, runtime
agentsAgent assignment historyworkspace_id, model, status, removed_at, removal_reason
workspace_secretsEncrypted credentialsworkspace_id, key, encrypted_value (BYTEA, AES-256-GCM)
agent_memoriesHMA-scoped memoryworkspace_id, content, scope (LOCAL/TEAM/GLOBAL)
structure_eventsImmutable event log (APPEND-ONLY, never UPDATE/DELETE)event_type, workspace_id, agent_id, target_id, payload (JSONB)
activity_logsOperational activity with retentionworkspace_id, activity_type, source_id, target_id, method, request_body, response_body, duration_ms, status, error_detail
canvas_layoutsNode visual positionsworkspace_id, x, y, collapsed
canvas_viewportCanvas pan/zoom stateSingle row, upserted

Redis Key Patterns

Key PatternValueTTLPurpose
ws:{id}"online"60sLiveness detection (heartbeat refreshes)
ws:{id}:urlHost-mapped URL5minURL cache for external discovery
ws:{id}:internal_urlDocker-internal URL—Container-to-container discovery
events:broadcastpub/sub channel—Event fanout to WebSocket hub

20. Docker Compose Orchestration

Full Stack (docker-compose.yml)

ServiceImagePortPurpose
postgrespostgres:165432 (internal)Primary database (wal_level=logical)
redisredis:76379 (internal)Cache + pub/sub (notify-keyspace-events=KEA)
langfuse-clickhouseclickhouse/clickhouse-serverinternalAnalytics backend
langfuse-weblangfuse/langfuse3100Observability UI
platformBuilt from Go8080Control plane
canvasBuilt from Next.js3000Frontend

Optional Profiles

ProfileServicePurpose
multi-providerLiteLLM proxyUnified API for OpenAI, Anthropic, Google, etc.
local-modelsOllamaLocal LLM inference

Infrastructure-Only (docker-compose.infra.yml)

Postgres + Redis + Langfuse only (for local development without containerized workspace-server/canvas).

21. Environment Variables

Platform (Go)

VariableDefaultPurpose
DATABASE_URLpostgres://dev:dev@localhost:5432/molecule?sslmode=preferPostgres connection
REDIS_URLredis://localhost:6379Redis connection
PORT8080Platform listen port
PLATFORM_URLhttp://host.docker.internal:8080Injected to workspace containers
SECRETS_ENCRYPTION_KEYOptionalAES-256 key (32 bytes) for secret encryption
CONFIGS_DIR/configsWorkspace config template directory
PLUGINS_DIR/pluginsShared plugin directory
ACTIVITY_RETENTION_DAYS7Activity log retention
ACTIVITY_CLEANUP_INTERVAL_HOURS6Cleanup frequency
CORS_ORIGINShttp://localhost:3000,...CORS whitelist
RATE_LIMIT600Requests per minute
WORKSPACE_DIROptionalShared workspace volume
AWARENESS_URLOptionalAwareness service URL

Canvas (Next.js)

VariableDefaultPurpose
NEXT_PUBLIC_PLATFORM_URLhttp://localhost:8080Platform backend URL
NEXT_PUBLIC_WS_URLws://localhost:8080/wsWebSocket URL
PORT3000Canvas listen port

Workspace Runtime (Python)

VariableDefaultPurpose
WORKSPACE_IDworkspace-defaultUnique workspace identifier
WORKSPACE_CONFIG_PATH/configsConfig directory mount
PLATFORM_URLhttp://host.docker.internal:8080Platform connection
PARENT_IDEmptyParent workspace ID (set if nested)
AWARENESS_URLOptionalAwareness service
AWARENESS_NAMESPACEOptionalScoped namespace for awareness memory
LANGFUSE_HOSThttp://langfuse-web:3000Langfuse endpoint
LANGFUSE_PUBLIC_KEYOptionalLangfuse auth
LANGFUSE_SECRET_KEYOptionalLangfuse auth
DEPLOYMENT_RETRY_ATTEMPTS3Delegation retry count
DELEGATION_TIMEOUT120Delegation timeout (seconds)
APPROVAL_TIMEOUT300Approval wait timeout (seconds)
AUDIT_LOG_PATH/var/log/molecule/audit.jsonlAudit log file path

Technical Overview

Executive summary and product positioning for the Molecule AI platform.

Workspace Lifecycle & Provisioning

Workspace state machine, provisioning and container lifecycle, and the workspace runtime.

On this page

3. System ArchitectureSystem Boundary DiagramNetwork ModelCore Components4. Database SchemaCore TablesRedis Key Patterns20. Docker Compose OrchestrationFull Stack (docker-compose.yml)Optional ProfilesInfrastructure-Only (docker-compose.infra.yml)21. Environment VariablesPlatform (Go)Canvas (Next.js)Workspace Runtime (Python)