From 7b5d28a310307ae9221ee02f415cfd3ec081ada5 Mon Sep 17 00:00:00 2001
From: "molecule-ai[bot]" <276602405+molecule-ai[bot]@users.noreply.github.com>
Date: Tue, 21 Apr 2026 07:48:56 +0000
Subject: [PATCH] docs: add docs/architecture/architecture.md

---
 content/docs/architecture/architecture.md | 88 +++++++++++++++++++++++
 1 file changed, 88 insertions(+)
 create mode 100644 content/docs/architecture/architecture.md

diff --git a/content/docs/architecture/architecture.md b/content/docs/architecture/architecture.md
new file mode 100644
index 0000000..989c65e
--- /dev/null
+++ b/content/docs/architecture/architecture.md
@@ -0,0 +1,88 @@
+# System Architecture
+
+## Overview
+
+The platform is fully distributed — workspaces can run on different machines and communicate via the A2A (Agent-to-Agent) protocol.
+
+## System Boundaries
+
+The platform consists of four distinct systems:
+
+```
++-----------------------------------------------------------+
+|  canvas/              Next.js 15 frontend                  |
+|  React Flow visual canvas, Zustand state, WebSocket        |
++-----------------------------+-----------------------------+
+                              | HTTP + WebSocket
++-----------------------------v-----------------------------+
+|  workspace-server/            Go (gin) backend                     |
+|  Registry, hierarchy, event log, provisioner, bundles       |
++------+---------------------------------------+------------+
+       | Postgres                               | Redis
++------v------+                       +---------v---------+
+|  Postgres   |                       |     Redis         |
+|  (Docker)   |                       |    (Docker)       |
++-------------+                       +-------------------+
+
+       A2A HTTP (JSON-RPC 2.0) — direct workspace-to-workspace
++-----------------------------------------------------------+
+|  workspace/  pluggable workspace runtime          |
+|  LangGraph / DeepAgents / Claude Code / CrewAI / AutoGen   |
+|  / OpenClaw + a2a-sdk                                      |
++-----------------------------------------------------------+
+       |
++------v----------------------------------------------------+
+|  Langfuse             Observability (Docker)               |
+|  Traces every LLM call across all workspaces               |
++-----------------------------------------------------------+
+```
+
+### Plugins
+
+Shared skill/rule collections mounted into every workspace container at `/plugins/`:
+
+```
+plugins/
+├── ecc/                    # Everything Claude Code
+│   ├── rules/              # Always-on guidelines
+│   ├── skills/             # Shared skills (coding-standards, tdd-workflow, etc.)
+│   └── AGENTS.md           # Prompt fragment
+└── superpowers/            # obra/superpowers
+    └── skills/             # Shared skills (debugging, verification, etc.)
+```
+
+Plugins inject rules and skills into all agents automatically. Workspace-specific skills take priority over plugin skills (deduplicated by ID).
+
+### Data Flow Summary
+
+- **Canvas <-> Platform:** HTTP REST + WebSocket for real-time events
+- **Platform <-> Postgres:** Source of truth for registry, hierarchy, events
+- **Platform <-> Redis:** Ephemeral state — liveness, caching, pub/sub
+- **Platform -> Workspace:** Provisioning (tiered Docker deployment), discovery
+- **Workspace <-> Workspace:** Direct A2A (JSON-RPC 2.0) — platform not in path
+- **Workspace -> Langfuse:** Automatic LLM tracing
+
+## Folder Structure
+
+```
+molecule/
+|
++-- docker-compose.yml               # full local dev stack
++-- docker-compose.infra.yml         # postgres, redis, langfuse only
++-- .env.example
++-- README.md
+|
++-- canvas/                          # Next.js 15 frontend
++-- workspace-server/                        # Go backend
++-- workspace/              # Python agent runtime (generic image)
++-- workspace-configs-templates/     # workspace personality definitions
++-- infra/                           # scripts + langfuse compose
++-- docs/                            # documentation
+```
+
+## Related Docs
+
+- [Platform API](../api-protocol/platform-api.md) — Go backend details
+- [Workspace Runtime](../agent-runtime/workspace-runtime.md) — Runtime layer details
+- [Canvas UI](../frontend/canvas.md) — Next.js frontend details
+- [Technology Choices](./technology-choices.md) — Why each piece was chosen