From bc1c14015d006fed60b85414545ee3fcd126fa22 Mon Sep 17 00:00:00 2001
From: Wojciech Nawrocki <13901751+Vtec234@users.noreply.github.com>
Date: Wed, 8 Jul 2026 15:49:18 -0400
Subject: [PATCH 1/2] doc: mermaid diagram of processes

Add architecture diagram using mermaid syntax.
---
 DEVELOPMENT.md | 122 +++++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 114 insertions(+), 8 deletions(-)

diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md
index ec135f8..a2869f3 100644
--- a/DEVELOPMENT.md
+++ b/DEVELOPMENT.md
@@ -106,14 +106,120 @@ make clean
 
 ## Architecture
 
-```
-Browser
-    |
-    v
-nginx (reverse proxy, port 3000)
-    |
-    |-- /_vs/{viewer}/{owner}/{project}/* --> code-server (port 3010+N, in bwrap)
-    |-- everything else                   --> Next.js server (port 3002)
+```mermaid
+---
+config:
+  flowchart:
+    subGraphTitleMargin:
+      bottom: 20
+---
+flowchart TB
+  subgraph CLIENTS[" "]
+    direction LR
+
+    subgraph LEGEND["Legend"]
+      LegendMachine["Machine"]
+      class LegendMachine machine
+
+      LegendBubblewrap["Bubblewrap"]
+      class LegendBubblewrap bwrap
+
+      subgraph LegendProcess["Process"]
+        LegendSubprocess["Subprocess"]
+      end
+    end
+    style LEGEND fill:transparent
+
+    subgraph MACHINE_A["Computer A"]
+        C1["VSC Client<br/>User A<br/>Project A/foo"]
+        C2["VSC Client<br/>User A<br/>Project B/bar"]
+    end
+    class MACHINE_A machine
+
+    subgraph MACHINE_B["Computer B"]
+        C3["VSC Client<br/>User B<br/>Project B/bar"]
+    end
+    class MACHINE_B machine
+  end
+  class CLIENTS logical
+
+  subgraph WORKBENCH["Workbench Server > Docker Container"]
+    direction TB
+
+    subgraph CENTRAL_SERVERS[" "]
+      direction LR
+      Nginx["Nginx<br/>localhost:3000"]
+      NextJS["Next.js<br/>localhost:3002"]
+
+      Nginx -->|"HTTP/WebSocket over local inet"| NextJS
+    end
+    class CENTRAL_SERVERS logical
+
+    C1 -->|"HTTP/WebSocket over inet"| Nginx
+    C2 --> Nginx
+    C3 --> Nginx
+
+    subgraph VSC_LAYER[" "]
+      direction LR
+
+      subgraph BWVSC1["Editor Session 1"]
+        direction TB
+        subgraph S1["VSC Server<br/>User A<br/>Project A/foo"]
+          subgraph EH1["VSC Extension Host"]
+            LSP1["Lean LSP"]
+          end
+        end
+      end
+      class BWVSC1 bwrap
+
+      subgraph BWVSC2["Editor Session 2"]
+        direction TB
+        subgraph S2["VSC Server<br/>User A<br/>Project B/bar"]
+          subgraph EH2["VSC Extension Host"]
+            LSP2["Lean LSP"]
+          end
+        end
+      end
+      class BWVSC2 bwrap
+
+      subgraph BWVSC3["Editor Session 3"]
+        direction TB
+        subgraph S3["VSC Server<br/>User B<br/>Project B/bar"]
+          EH3["VSC Extension Host"]
+        end
+      end
+      class BWVSC3 bwrap
+    end
+    class VSC_LAYER logical
+
+    Nginx -->|"HTTP/WebSocket over UDS<br/>(VSC Servers don't open ports)"| S1
+    Nginx --> S2
+    Nginx --> S3
+
+    subgraph COLLAB_LAYER[" "]
+      direction LR
+
+      subgraph BWCSFoo[" "]
+        CollabFoo["Collab Server<br/>Project A/foo"]
+      end
+      class BWCSFoo bwrap
+
+      subgraph BWCSBar[" "]
+        CollabBar["Collab Server<br/>Project B/bar"]
+      end
+      class BWCSBar bwrap
+    end
+    class COLLAB_LAYER logical
+
+    EH1 <-->|"WebSocket over UDS"| CollabFoo
+    EH2 <--> CollabBar
+    EH3 <--> CollabBar
+  end
+  class WORKBENCH machine
+
+  classDef logical fill:transparent,stroke:transparent
+  classDef machine fill:#5790FC33,stroke:transparent
+  classDef bwrap fill:#E4253633,stroke:transparent
 ```
 
 Three processes run inside the Docker container:

From 89aca07c39448d9db9a3bfbc575a937e24a02e05 Mon Sep 17 00:00:00 2001
From: Wojciech Nawrocki <13901751+Vtec234@users.noreply.github.com>
Date: Wed, 8 Jul 2026 15:55:30 -0400
Subject: [PATCH 2/2] doc: add routes

---
 DEVELOPMENT.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md
index a2869f3..6636251 100644
--- a/DEVELOPMENT.md
+++ b/DEVELOPMENT.md
@@ -151,7 +151,7 @@ flowchart TB
       Nginx["Nginx<br/>localhost:3000"]
       NextJS["Next.js<br/>localhost:3002"]
 
-      Nginx -->|"HTTP/WebSocket over local inet"| NextJS
+      Nginx -->|"Other routes<br/>HTTP/WebSocket over local inet"| NextJS
     end
     class CENTRAL_SERVERS logical
 
@@ -192,7 +192,7 @@ flowchart TB
     end
     class VSC_LAYER logical
 
-    Nginx -->|"HTTP/WebSocket over UDS<br/>(VSC Servers don't open ports)"| S1
+    Nginx -->|"/_vs/* routes<br/>HTTP/WebSocket over UDS<br/>(VSC Servers don't open ports)"| S1
     Nginx --> S2
     Nginx --> S3