forked from molecule-ai/molecule-core
479a027e4b
Renames: - platform/ → workspace-server/ (Go module path stays as "platform" for external dep compat — will update after plugin module republish) - workspace-template/ → workspace/ Removed (moved to separate repos or deleted): - PLAN.md — internal roadmap (move to private project board) - HANDOFF.md, AGENTS.md — one-time internal session docs - .claude/ — gitignored entirely (local agent config) - infra/cloudflare-worker/ → Molecule-AI/molecule-tenant-proxy - org-templates/molecule-dev/ → standalone template repo - .mcp-eval/ → molecule-mcp-server repo - test-results/ — ephemeral, gitignored Security scrubbing: - Cloudflare account/zone/KV IDs → placeholders - Real EC2 IPs → <EC2_IP> in all docs - CF token prefix, Neon project ID, Fly app names → redacted - Langfuse dev credentials → parameterized - Personal runner username/machine name → generic Community files: - CONTRIBUTING.md — build, test, branch conventions - CODE_OF_CONDUCT.md — Contributor Covenant 2.1 All Dockerfiles, CI workflows, docker-compose, railway.toml, render.yaml, README, CLAUDE.md updated for new directory names. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
89 lines
3.7 KiB
Markdown
89 lines
3.7 KiB
Markdown
# 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
|