rabbitblood 40bd0cfdde fix: restore build infrastructure deleted by bad PR #59 merge

[Molecule-Platform-Evolvement-Manager]

PR #59 (commit dae42e2) was merged ~2 weeks ago with a bad diff that
deleted all Next.js/Fumadocs build files (package.json, app/, lib/,
source.config.ts, tsconfig.json, etc.) and most MDX content pages.
This broke the Vercel build, taking doc.moleculesai.app offline.

Root cause: the PR branch was likely rebased or reset to a state that
only contained the marketing/ subtree, so the merge diff showed
deletions for every other file.

This commit:
1. Restores all build infrastructure from the last good commit (86fa0e9)
2. Restores 25 deleted MDX content pages (concepts, quickstart, etc.)
3. Adds frontmatter (title) to 55 .md files added post-bad-merge that
   were missing the required YAML frontmatter for Fumadocs
4. Removes duplicate quickstart.mdx (superseded by quickstart.md)
5. Adds CI workflow (.github/workflows/ci.yml) to catch build failures
   on PRs before merge — this would have prevented the outage

Build verified: 99 static pages generated successfully.

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

2026-04-22 14:03:24 -07:00

3.7 KiB

Raw Blame History

title
System Architecture

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

Platform API — Go backend details
Workspace Runtime — Runtime layer details
Canvas UI — Next.js frontend details
Technology Choices — Why each piece was chosen

3.7 KiB Raw Blame History