diff --git a/content/docs/architecture/architecture.md b/content/docs/architecture/architecture.mdx
similarity index 50%
rename from content/docs/architecture/architecture.md
rename to content/docs/architecture/architecture.mdx
index ef9cbaa..aee2c0f 100644
--- a/content/docs/architecture/architecture.md
+++ b/content/docs/architecture/architecture.mdx
@@ -10,36 +10,13 @@ The platform is fully distributed — workspaces can run on different machines a
 
 ## System Boundaries
 
-The platform consists of four distinct systems:
+Operator surfaces reach a thin central control plane that provisions one isolated tenant per org; each tenant runs its own control core (the `workspace-server`, with its own Postgres + Redis) above a hierarchy of workspaces. Runtimes and model providers are pluggable:
 
-```
-+-----------------------------------------------------------+
-|  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 / Claude Code / AutoGen / OpenClaw / Hermes    |
-|  / Codex / Google ADK + a2a-sdk                            |
-+-----------------------------------------------------------+
-       |
-+------v----------------------------------------------------+
-|  Langfuse             Observability (Docker)               |
-|  Traces every LLM call across all workspaces               |
-+-----------------------------------------------------------+
-```
+<img
+  src="/diagrams/platform-architecture.svg"
+  alt="Molecule AI platform architecture: operator surfaces reach a thin central Control Plane (orgs, billing, tenant provisioning, LLM proxy, provider registry) that provisions one isolated tenant per org. Each tenant runs its own control core — the workspace-server with provisioner, registry/discovery, A2A proxy, WebSocket hub, scheduler, secrets, audit, and its own Postgres + Redis — above a hierarchy of workspaces, each one agent on its own machine, communicating peer-to-peer over A2A. Runtimes (claude-code, langgraph, autogen, openclaw, hermes, codex, google-adk) and model providers are pluggable."
+  style={{ width: '100%', height: 'auto', margin: '1rem 0' }}
+/>
 
 ### Plugins
 
@@ -59,12 +36,12 @@ Plugins inject rules and skills into all agents automatically. Workspace-specifi
 
 ### 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
+- **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