From 20d025c6462dfc2cf7498cf12141068e66fd0e69 Mon Sep 17 00:00:00 2001 From: technical-writer Date: Tue, 2 Jun 2026 10:05:48 -0700 Subject: [PATCH] docs(architecture): reconcile prose to corrected CP/tenant split MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Follow-up to the hero-diagram fix: the prose still called the :8080 workspace-server 'the central control plane' with provisioner/scheduler/Postgres/Redis, which contradicted the corrected diagram (those are tenant-side). Aligned the prose to the real two-layer design (confirmed in code: molecule-controlplane vs workspace-server; subdomain table already had api vs *.moleculesai.app): - '### Platform' section: reframed as the per-tenant control core (workspace-server, one instance per org on *.moleculesai.app / self-host); renamed 'Docker provisioner' → 'Provisioner' (workspace machines); added an explicit note that it is NOT the central control plane — a separate molecule-controlplane (api.moleculesai.app, /cp/*) handles orgs/members, billing, LLM proxy, provider registry, and tenant provisioning, and the Platform's Postgres/Redis are the tenant's own. - Text-summary caption: marked it the per-tenant view + noted the central control plane above all tenants. - Subdomain table: api.moleculesai.app row now describes the central control plane's real responsibilities (/cp/*) instead of 'Platform REST + WebSocket'. Build green. Co-Authored-By: Claude Opus 4.8 (1M context) --- content/docs/architecture.mdx | 20 +++++++++++++++----- 1 file changed, 15 insertions(+), 5 deletions(-) diff --git a/content/docs/architecture.mdx b/content/docs/architecture.mdx index aa0ddbe..699f0ff 100644 --- a/content/docs/architecture.mdx +++ b/content/docs/architecture.mdx @@ -32,7 +32,7 @@ Canvas (Next.js :3000) <--WebSocket--> Platform (Go :8080) <--HTTP--> Postgres + +------ Platform ----+ ``` -The Canvas provides the visual interface, the Platform acts as the control plane, and Workspaces are isolated containers running AI agent runtimes. All inter-agent communication is mediated by the Platform via the A2A proxy, which enforces hierarchical access control. +This is the **per-tenant** view: the Canvas provides the visual interface, the Platform (the tenant's `workspace-server`) is the tenant's control core, and Workspaces are isolated machines running AI agent runtimes. All inter-agent communication is mediated by the Platform via the A2A proxy, which enforces hierarchical access control. Above all tenants sits the central control plane (`api.moleculesai.app`), which provisions tenants and handles orgs and billing. --- @@ -69,9 +69,11 @@ The Canvas is the browser-based visual workspace graph. It provides: ### Platform -**Stack:** Go / Gin +**Stack:** Go / Gin (`workspace-server`) -The Platform is the central control plane responsible for: +The Platform is the **per-tenant control core** — one instance runs on each org's +tenant (a `*.moleculesai.app` instance in SaaS, or your own host when self-hosted) +and owns everything for that org's workspaces: - **Workspace CRUD** -- create, read, update, delete workspaces - **Registry** -- workspace registration, heartbeat tracking, agent card management @@ -79,10 +81,18 @@ The Platform is the central control plane responsible for: - **WebSocket hub** -- real-time event broadcasting to Canvas clients - **Liveness monitoring** -- three-layer container health detection - **A2A proxy** -- routes inter-agent messages with hierarchical access control -- **Docker provisioner** -- container lifecycle management with tier-based resource limits +- **Provisioner** -- workspace machine/container lifecycle with tier-based resource limits - **Scheduler** -- cron-based scheduled tasks per workspace - **Channel adapters** -- social integrations (Telegram, Slack, etc.) +It is **not** the central SaaS control plane. A separate +[central control plane](#subdomain-architecture) (`api.moleculesai.app`, +`molecule-controlplane`) handles org & member management, billing & credits, the +LLM proxy, the provider registry, and **tenant provisioning** — it spins up each +org's tenant, and that tenant then runs its own Platform instance above. The +Platform's Postgres and Redis (below) are the **tenant's own**, not shared +across orgs. + **Key environment variables:** | Variable | Default | Purpose | @@ -321,7 +331,7 @@ Hosted at `moleculesai.app` with per-tenant isolation. Each tenant gets a dedica |-----------|---------|---------| | `moleculesai.app` | Landing page | Marketing site | | `app.moleculesai.app` | SaaS dashboard | Tenant management UI | -| `api.moleculesai.app` | Control plane API | Platform REST + WebSocket | +| `api.moleculesai.app` | Central control plane (`molecule-controlplane`) | Orgs, members, billing/credits, tenant provisioning, LLM proxy, provider registry (`/cp/*`) | | `doc.moleculesai.app` | Documentation | This documentation site | | `status.moleculesai.app` | Status page | Uptime and incident tracking | | `*.moleculesai.app` | Tenant instances | Per-org isolated platform instances | -- 2.52.0