diff --git a/README.md b/README.md
index 468577e..47dee84 100644
--- a/README.md
+++ b/README.md
@@ -20,27 +20,7 @@ The proxy sits between the ingress controller and workspace pods, handling:
 
 ## Architecture
 
-```
-Browser
-  │
-  ▼
-Ingress (/proxy/*)
-  │
-  ▼
-┌─────────────────────────────────────────────────┐
-│  Proxy Service (:8080)                          │
-│                                                 │
-│  Request Logging → CORS → Auth → Routing        │
-│                                                 │
-│  /healthz, /readyz  → 200 OK                    │
-│  /sw.js             → no-op ServiceWorker       │
-│  /proxy/{ns}/{name} → reverse proxy handler     │
-└────────────────────────┬────────────────────────┘
-                         │
-                         ▼
-          {name}.{namespace}.svc.cluster.local:80
-                    (Workspace Pod)
-```
+[![Architecture diagram](docs/architecture.svg)](docs/architecture.svg)
 
 ## Request Flow
 
diff --git a/docs/architecture.svg b/docs/architecture.svg
new file mode 100644
index 0000000..d4a9109
--- /dev/null
+++ b/docs/architecture.svg
@@ -0,0 +1,114 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 860 530" width="860" height="530"
+     font-family="ui-sans-serif,system-ui,-apple-system,BlinkMacSystemFont,'Segoe UI',sans-serif">
+
+  <defs>
+    <marker id="arr-blue" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="6" markerHeight="6" orient="auto-start-reverse">
+      <path d="M 0 0 L 10 5 L 0 10 z" fill="#1f6feb"/>
+    </marker>
+    <marker id="arr-blue-sm" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="6" markerHeight="6" orient="auto-start-reverse">
+      <path d="M 0 0 L 10 5 L 0 10 z" fill="#388bfd"/>
+    </marker>
+    <marker id="arr-gray" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="6" markerHeight="6" orient="auto-start-reverse">
+      <path d="M 0 0 L 10 5 L 0 10 z" fill="#484f58"/>
+    </marker>
+    <marker id="arr-orange" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="6" markerHeight="6" orient="auto-start-reverse">
+      <path d="M 0 0 L 10 5 L 0 10 z" fill="#db6d28"/>
+    </marker>
+    <marker id="arr-purple" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="6" markerHeight="6" orient="auto-start-reverse">
+      <path d="M 0 0 L 10 5 L 0 10 z" fill="#6e40c9"/>
+    </marker>
+  </defs>
+
+  <!-- Page background -->
+  <rect width="860" height="530" rx="12" fill="#0d1117"/>
+
+  <!-- ═══════════════════════════════════════════════════
+       INGRESS / ROUTING — outer container
+       ═══════════════════════════════════════════════════ -->
+  <rect x="435" y="36" width="402" height="462" rx="10" fill="#161b22" stroke="#30363d" stroke-width="1.5"/>
+  <!-- header band -->
+  <rect x="435" y="36" width="402" height="36" rx="10" fill="#1c2d4a" stroke="#30363d" stroke-width="1.5"/>
+  <rect x="435" y="54" width="402" height="18" fill="#1c2d4a"/>
+  <text x="636" y="59" text-anchor="middle" font-size="12.5" font-weight="600" fill="#58a6ff" letter-spacing="0.4">Ingress / Routing</text>
+
+  <!-- – Ingress – -->
+  <rect x="517" y="88" width="238" height="68" rx="8" fill="#0f1f3a" stroke="#1f6feb" stroke-width="1.2"/>
+  <text x="636" y="112" text-anchor="middle" font-size="12.5" font-weight="600" fill="#58a6ff">Ingress</text>
+  <text x="636" y="130" text-anchor="middle" font-size="10" fill="#388bfd">/proxy/*</text>
+
+  <!-- Arrow Ingress → Proxy Service -->
+  <line x1="636" y1="156" x2="636" y2="196" stroke="#484f58" stroke-width="1.5" marker-end="url(#arr-gray)"/>
+
+  <!-- – Proxy Service – -->
+  <rect x="457" y="196" width="358" height="150" rx="8" fill="#0f1f3a" stroke="#1f6feb" stroke-width="1.2"/>
+  <text x="636" y="220" text-anchor="middle" font-size="12.5" font-weight="600" fill="#58a6ff">Proxy Service (:8080)</text>
+
+  <!-- middleware chain pills -->
+  <rect x="473" y="232" width="322" height="26" rx="6" fill="#161b22" stroke="#21262d" stroke-width="1"/>
+  <text x="634" y="249" text-anchor="middle" font-size="10" fill="#c9d1d9">Request Logging → CORS → Auth → Routing</text>
+
+  <rect x="473" y="268" width="152" height="30" rx="6" fill="#161b22" stroke="#21262d" stroke-width="1"/>
+  <text x="549" y="287" text-anchor="middle" font-size="10.5" fill="#c9d1d9">/healthz, /readyz</text>
+  <rect x="637" y="268" width="152" height="30" rx="6" fill="#161b22" stroke="#21262d" stroke-width="1"/>
+  <text x="713" y="287" text-anchor="middle" font-size="10.5" fill="#c9d1d9">/sw.js (no-op)</text>
+
+  <rect x="473" y="308" width="322" height="26" rx="6" fill="#161b22" stroke="#21262d" stroke-width="1"/>
+  <text x="634" y="325" text-anchor="middle" font-size="10" fill="#c9d1d9">/proxy/{ns}/{name}/... → reverse proxy</text>
+
+  <!-- Arrow Proxy → Workspace Pod -->
+  <line x1="636" y1="346" x2="636" y2="400" stroke="#484f58" stroke-width="1.5" marker-end="url(#arr-gray)"/>
+
+  <!-- – Workspace Pod – -->
+  <rect x="457" y="400" width="358" height="80" rx="8" fill="#0f2a1a" stroke="#238636" stroke-width="1.2"/>
+  <text x="636" y="424" text-anchor="middle" font-size="12.5" font-weight="600" fill="#3fb950">Workspace Pod</text>
+  <text x="636" y="442" text-anchor="middle" font-size="10" fill="#56d364">{name}.{namespace}.svc.cluster.local:80</text>
+  <text x="636" y="459" text-anchor="middle" font-size="10" fill="#56d364" opacity="0.85">HTTP / WebSocket / SSE</text>
+
+  <!-- ═══════════════════════════════════════════════════
+       LEFT PANEL — Browser, Dex, API, Frontend
+       ═══════════════════════════════════════════════════ -->
+
+  <!-- Browser -->
+  <rect x="22" y="88" width="178" height="68" rx="8" fill="#1a1230" stroke="#6e40c9" stroke-width="1.2"/>
+  <text x="111" y="116" text-anchor="middle" font-size="12.5" font-weight="600" fill="#a371f7">Browser</text>
+  <text x="111" y="134" text-anchor="middle" font-size="10" fill="#8957e5">workspace web UI</text>
+
+  <!-- API -->
+  <rect x="22" y="196" width="178" height="68" rx="8" fill="#0f1f3a" stroke="#1f6feb" stroke-width="1.2"/>
+  <text x="111" y="224" text-anchor="middle" font-size="12.5" font-weight="600" fill="#58a6ff">API</text>
+  <text x="111" y="242" text-anchor="middle" font-size="10" fill="#388bfd">Goa / Go</text>
+
+  <!-- Dex / OIDC -->
+  <rect x="22" y="306" width="178" height="68" rx="8" fill="#1a1230" stroke="#6e40c9" stroke-width="1.2"/>
+  <text x="111" y="334" text-anchor="middle" font-size="12.5" font-weight="600" fill="#a371f7">Dex / OIDC</text>
+  <text x="111" y="352" text-anchor="middle" font-size="10" fill="#8957e5">optional IdP</text>
+
+  <!-- ═══════════════════════════════════════════════════
+       ARROWS — left panel
+       ═══════════════════════════════════════════════════ -->
+
+  <!-- Browser → Ingress (orange, user traffic) -->
+  <path d="M 200 122 L 400 122 L 400 110 L 517 110" fill="none" stroke="#db6d28" stroke-width="1.5" marker-end="url(#arr-orange)"/>
+
+  <!-- API → Proxy (dashed blue, issues session tokens / shares auth) -->
+  <path d="M 200 230 L 300 230 L 300 271 L 457 271" fill="none" stroke="#388bfd" stroke-width="1.2" stroke-dasharray="5,3" marker-end="url(#arr-blue-sm)"/>
+
+  <!-- API → Dex (dashed purple, auth flow) -->
+  <path d="M 111 196 L 111 168 L 111 152" fill="none" stroke="#6e40c9" stroke-width="1.2" stroke-dasharray="5,3" marker-end="url(#arr-purple)"/>
+
+  <!-- ═══════════════════════════════════════════════════
+       LEGEND
+       ═══════════════════════════════════════════════════ -->
+  <rect x="22" y="390" width="272" height="100" rx="8" fill="#161b22" stroke="#21262d" stroke-width="1"/>
+  <text x="38" y="412" font-size="10" font-weight="700" fill="#6e7681" letter-spacing="1">LEGEND</text>
+
+  <line x1="38" y1="430" x2="82" y2="430" stroke="#1f6feb" stroke-width="1.5" marker-end="url(#arr-blue)"/>
+  <text x="92" y="434" font-size="10" fill="#8b949e">Proxy / data flow</text>
+
+  <line x1="38" y1="452" x2="82" y2="452" stroke="#db6d28" stroke-width="1.5" marker-end="url(#arr-orange)"/>
+  <text x="92" y="456" font-size="10" fill="#8b949e">Browser → ingress traffic</text>
+
+  <line x1="38" y1="472" x2="82" y2="472" stroke="#388bfd" stroke-width="1.2" stroke-dasharray="5,3" marker-end="url(#arr-blue-sm)"/>
+  <text x="92" y="476" font-size="10" fill="#8b949e">Auth / token flow</text>
+
+</svg>