forked from molecule-ai/molecule-core
24fec62d7f
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>
89 lines
4.3 KiB
Markdown
89 lines
4.3 KiB
Markdown
# 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:
|
|
|
|
1. A planning tool (TODO list)
|
|
2. Sub-agent spawning
|
|
3. Filesystem-backed memory
|
|
4. 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
|
|
```
|