Hongming Wang 24fec62d7f initial commit — Molecule AI platform

Forked clean from public hackathon repo (Starfire-AgentTeam, BSL 1.1)
with full rebrand to Molecule AI under github.com/Molecule-AI/molecule-monorepo.

Brand: Starfire → Molecule AI.
Slug: starfire / agent-molecule → molecule.
Env vars: STARFIRE_* → MOLECULE_*.
Go module: github.com/agent-molecule/platform → github.com/Molecule-AI/molecule-monorepo/platform.
Python packages: starfire_plugin → molecule_plugin, starfire_agent → molecule_agent.
DB: agentmolecule → molecule.

History truncated; see public repo for prior commits and contributor
attribution. Verified green: go test -race ./... (platform), pytest
(workspace-template 1129 + sdk 132), vitest (canvas 352), build (mcp).

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

2026-04-13 11:55:37 -07:00

4.3 KiB

Raw Blame History

Technology Choices

This document explains why each technology was chosen for Molecule AI.

Next.js 15 (Canvas Frontend)

App router, React Server Components, and easy API proxying to the Go backend. React Flow is the industry standard for node-based canvas UIs and is what Sim.ai, Flowise, and most serious canvas tools use. Zustand is the state manager — lighter than Redux, works cleanly with React Flow's controlled flow pattern.

Go + Gin (Platform Backend)

The platform API handles high-concurrency concerns: hundreds of workspace heartbeats every 30 seconds, WebSocket connections from multiple canvas clients, Redis pub/sub event broadcasting. Go's goroutines handle this with minimal resource usage. The gin framework is minimal and well-documented.

Go is not used for agent logic — just infrastructure coordination.

Workspace Runtime Adapters

The workspace runtime is adapter-based. LangGraph and DeepAgents are Python-native, while Claude Code and OpenClaw are CLI-driven runtimes. The platform standardizes them behind the same A2A surface, heartbeat lifecycle, memory tools, and workspace contract instead of forcing one execution backend for every team.

Deep Agents + LangGraph

Deep Agents is an "agent harness" built on LangGraph, inspired by Claude Code's architecture. It provides four things out of the box:

A planning tool (TODO list)
Sub-agent spawning
Filesystem-backed memory
A detailed system prompt structure

LangGraph is the underlying runtime — it manages the agent loop, state persistence, retries, streaming, and human-in-the-loop.

Neither Deep Agents nor LangGraph provide AI models — they call whatever provider you configure.

a2a-sdk (A2A Wrapper)

a2a-sdk is the server package that exposes a workspace over HTTP with a standard A2A interface. It handles JSON-RPC 2.0 request parsing, Agent Card serving at /.well-known/agent-card.json, SSE streaming, and task management. LangGraph-based runtimes and CLI-based adapters both terminate into the same A2A contract.

A2A Protocol

The Agent-to-Agent protocol (Google, Linux Foundation) is the standard for agent-to-agent communication. Key properties:

Every workspace is an A2A server and can be an A2A client
Workspaces communicate directly without routing through the platform
Uses JSON-RPC 2.0 over HTTP — any language can implement it
Any A2A-compliant agent from any framework can plug in

The platform only handles discovery (resolving workspace URLs) and registry (knowing what workspaces exist).

Docker

Workspace instances are Docker containers. The generic workspace-template image is built once. Each instance gets different environment variables injecting the workspace ID, config path, model provider, and tier.

Docker gives process isolation, easy cleanup, portability, and a clear way to express tiered privilege. Tier 4 uses a full-host Docker configuration (privileged + host PID + host network + Docker socket) rather than a separate VM provisioner.

Postgres

Source of truth for workspace registry, workspace hierarchy, agent assignments, and the immutable structure event log. The event log is append-only — rows are never updated or deleted. The workspaces table is a projection of that log (current state).

Using wal_level=logical from the start enables future streaming of change events without a schema migration.

Redis

Handles everything ephemeral:

Liveness detection via TTL keys — if a workspace stops sending heartbeats, its key expires automatically
URL caching for fast workspace resolution
Pub/sub for broadcasting structure events to canvas WebSocket clients

Redis does not need to be durable — if it restarts, workspaces re-register on next heartbeat.

Langfuse (Observability)

Self-hosted, fully open source, runs in Docker. LangGraph has native Langfuse integration — setting LANGFUSE_HOST is all that's needed. Captures every LLM call across all workspaces in one unified view.

LangSmith (the managed version) requires an enterprise license for self-hosting and was ruled out for this reason.

Version Requirements

Go              1.25+ (go.mod)
Python          3.11+
Node.js         22+
Next.js         15
React Flow      12   (@xyflow/react)
a2a-sdk         0.3+ (A2A server SDK)
langfuse        3.x  (self-hosted Docker)
Postgres        16
Redis           7
Docker Compose  2.x

4.3 KiB Raw Blame History