Merge pull request #11 from GACWR/doc/arch-diagram

Jovonni · web-flow · commit aed643e85bd2 · 2026-03-08T15:11:01.000-04:00
updated arch diagram
diff --git a/README.md b/README.md
@@ -156,27 +156,7 @@ This will:
 
 ## Architecture
 
-```
-                          Kind Cluster
-
-  +-----------+  +----------+  +-------------+  +------------+
-  | Frontend  |  | Rust API |  | PostGraphile|  | JupyterHub |
-  | Next.js   |  |  Axum    |  |  GraphQL    |  |            |
-  | :31000    |  |  :31001  |  |  :31002     |  |  :31003    |
-  +-----+-----+  +----+-----+  +------+------+  +------+-----+
-        |              |               |                |
-        |         +----+---------------+----+           |
-        |         |     PostgreSQL 16       |           |
-        |         |       :5432             |           |
-        |         +-------------------------+           |
-        |              |                                |
-        |         +----+-----------+                    |
-        |         | Model Runner   |   +------------+   |
-        |         | Pods (ephemeral|   | User        |   |
-        |         | - Python       |   | Notebook    |   |
-        |         | - Rust         |   | Pods        |   |
-        |         +----------------+   +------------+   |
-```
+![Architecture](docs/diagrams/architecture.svg)
 
 ### Components
 
diff --git a/docs/diagrams/architecture.svg b/docs/diagrams/architecture.svg
@@ -0,0 +1,113 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1100 700" width="1100" height="700">
+<defs>
+  <marker id="ah" markerWidth="7" markerHeight="5" refX="6" refY="2.5" orient="auto"><path d="M0,0 L7,2.5 L0,5Z" fill="rgba(230,237,243,0.3)"/></marker>
+  <marker id="ah-r" markerWidth="7" markerHeight="5" refX="1" refY="2.5" orient="auto"><path d="M7,0 L0,2.5 L7,5Z" fill="rgba(230,237,243,0.3)"/></marker>
+</defs>
+<rect width="1100" height="700" fill="#0d1117"/>
+<text x="550" y="28" font-family="'Inter','Segoe UI',system-ui,sans-serif" font-size="16" font-weight="600" fill="#e6edf3" text-anchor="middle">OpenModelStudio — System Architecture</text>
+<rect x="310" y="48" width="110" height="34" rx="6" fill="rgba(148,163,184,0.06)" stroke="rgba(148,163,184,0.20)" stroke-width="1"/>
+<text x="365" y="69" font-family="'Inter','Segoe UI',system-ui,sans-serif" font-size="10" font-weight="600" fill="#94a3b8" text-anchor="middle">Browser</text>
+<rect x="530" y="48" width="110" height="34" rx="6" fill="rgba(148,163,184,0.06)" stroke="rgba(148,163,184,0.20)" stroke-width="1"/>
+<text x="585" y="69" font-family="'Inter','Segoe UI',system-ui,sans-serif" font-size="10" font-weight="600" fill="#94a3b8" text-anchor="middle">Python SDK</text>
+<rect x="750" y="48" width="110" height="34" rx="6" fill="rgba(148,163,184,0.06)" stroke="rgba(148,163,184,0.20)" stroke-width="1"/>
+<text x="805" y="69" font-family="'Inter','Segoe UI',system-ui,sans-serif" font-size="10" font-weight="600" fill="#94a3b8" text-anchor="middle">CLI</text>
+<rect x="250" y="100" width="820" height="540" rx="14" fill="rgba(255,255,255,0.015)" stroke="rgba(255,255,255,0.05)" stroke-width="1"/>
+<text x="264" y="116" font-family="'Inter','Segoe UI',system-ui,sans-serif" font-size="10" font-weight="600" fill="rgba(230,237,243,0.3)" text-anchor="start">Kubernetes Cluster</text>
+<text x="1056" y="116" font-family="'JetBrains Mono','SF Mono','Fira Code',monospace" font-size="8" font-weight="400" fill="rgba(230,237,243,0.3)" text-anchor="end">ns: openmodelstudio</text>
+<text x="280" y="124" font-family="'Inter','Segoe UI',system-ui,sans-serif" font-size="9" font-weight="600" fill="rgba(230,237,243,0.3)" text-anchor="start">CORE SERVICES</text>
+<rect x="280" y="130" width="175" height="58" rx="8" fill="rgba(139,92,246,0.10)" stroke="rgba(139,92,246,0.35)" stroke-width="1"/>
+<text x="367.5" y="150" font-family="'Inter','Segoe UI',system-ui,sans-serif" font-size="12" font-weight="600" fill="#a78bfa" text-anchor="middle">Frontend</text>
+<text x="367.5" y="165" font-family="'Inter','Segoe UI',system-ui,sans-serif" font-size="9" font-weight="400" fill="rgba(230,237,243,0.5)" text-anchor="middle">Next.js + shadcn/ui</text>
+<text x="367.5" y="180" font-family="'JetBrains Mono','SF Mono','Fira Code',monospace" font-size="8" font-weight="400" fill="rgba(230,237,243,0.3)" text-anchor="middle">:31000</text>
+<rect x="473" y="130" width="175" height="58" rx="8" fill="rgba(59,130,246,0.10)" stroke="rgba(59,130,246,0.35)" stroke-width="1"/>
+<text x="560.5" y="150" font-family="'Inter','Segoe UI',system-ui,sans-serif" font-size="12" font-weight="600" fill="#60a5fa" text-anchor="middle">Rust API</text>
+<text x="560.5" y="165" font-family="'Inter','Segoe UI',system-ui,sans-serif" font-size="9" font-weight="400" fill="rgba(230,237,243,0.5)" text-anchor="middle">Axum + SQLx</text>
+<text x="560.5" y="180" font-family="'JetBrains Mono','SF Mono','Fira Code',monospace" font-size="8" font-weight="400" fill="rgba(230,237,243,0.3)" text-anchor="middle">:31001</text>
+<rect x="666" y="130" width="175" height="58" rx="8" fill="rgba(59,130,246,0.10)" stroke="rgba(59,130,246,0.35)" stroke-width="1"/>
+<text x="753.5" y="150" font-family="'Inter','Segoe UI',system-ui,sans-serif" font-size="12" font-weight="600" fill="#60a5fa" text-anchor="middle">PostGraphile</text>
+<text x="753.5" y="165" font-family="'Inter','Segoe UI',system-ui,sans-serif" font-size="9" font-weight="400" fill="rgba(230,237,243,0.5)" text-anchor="middle">Auto-gen GraphQL</text>
+<text x="753.5" y="180" font-family="'JetBrains Mono','SF Mono','Fira Code',monospace" font-size="8" font-weight="400" fill="rgba(230,237,243,0.3)" text-anchor="middle">:31002</text>
+<rect x="859" y="130" width="175" height="58" rx="8" fill="rgba(16,185,129,0.08)" stroke="rgba(16,185,129,0.30)" stroke-width="1"/>
+<text x="946.5" y="150" font-family="'Inter','Segoe UI',system-ui,sans-serif" font-size="12" font-weight="600" fill="#34d399" text-anchor="middle">JupyterHub</text>
+<text x="946.5" y="165" font-family="'Inter','Segoe UI',system-ui,sans-serif" font-size="9" font-weight="400" fill="rgba(230,237,243,0.5)" text-anchor="middle">Workspace Manager</text>
+<text x="946.5" y="180" font-family="'JetBrains Mono','SF Mono','Fira Code',monospace" font-size="8" font-weight="400" fill="rgba(230,237,243,0.3)" text-anchor="middle">:31003</text>
+<line x1="365" y1="82" x2="365" y2="130" stroke="rgba(139,92,246,0.35)" stroke-width="1" marker-end="url(#ah)"/>
+<text x="372" y="109" font-family="'Inter','Segoe UI',system-ui,sans-serif" font-size="8" font-weight="400" fill="rgba(230,237,243,0.3)" text-anchor="start">HTTP</text>
+<line x1="585" y1="82" x2="585" y2="130" stroke="rgba(59,130,246,0.35)" stroke-width="1" marker-end="url(#ah)"/>
+<text x="592" y="109" font-family="'Inter','Segoe UI',system-ui,sans-serif" font-size="8" font-weight="400" fill="rgba(230,237,243,0.3)" text-anchor="start">REST</text>
+<path d="M805,82 V106 H580.5 V130" fill="none" stroke="rgba(59,130,246,0.35)" stroke-width="1" marker-end="url(#ah)"/>
+<text x="574.5" y="109" font-family="'Inter','Segoe UI',system-ui,sans-serif" font-size="8" font-weight="400" fill="rgba(230,237,243,0.3)" text-anchor="end">REST</text>
+<line x1="455" y1="159" x2="473" y2="159" stroke="rgba(139,92,246,0.35)" stroke-width="1" marker-start="url(#ah-r)" marker-end="url(#ah)"/>
+<text x="464" y="153" font-family="'Inter','Segoe UI',system-ui,sans-serif" font-size="8" font-weight="400" fill="rgba(230,237,243,0.3)" text-anchor="middle">REST + SSE</text>
+<path d="M367.5,188 V196 H753.5 V188" fill="none" stroke="rgba(59,130,246,0.35)" stroke-width="1" stroke-dasharray="4,3" marker-start="url(#ah-r)" marker-end="url(#ah)"/>
+<text x="560.5" y="208" font-family="'Inter','Segoe UI',system-ui,sans-serif" font-size="8" font-weight="400" fill="rgba(230,237,243,0.3)" text-anchor="middle">GraphQL</text>
+<text x="280" y="254" font-family="'Inter','Segoe UI',system-ui,sans-serif" font-size="9" font-weight="600" fill="rgba(230,237,243,0.3)" text-anchor="start">DATA LAYER</text>
+<rect x="520" y="260" width="280" height="55" rx="8" fill="rgba(20,184,166,0.10)" stroke="rgba(20,184,166,0.35)" stroke-width="1"/>
+<text x="660" y="278" font-family="'Inter','Segoe UI',system-ui,sans-serif" font-size="13" font-weight="600" fill="#2dd4bf" text-anchor="middle">PostgreSQL 16</text>
+<text x="660" y="293" font-family="'Inter','Segoe UI',system-ui,sans-serif" font-size="9" font-weight="400" fill="rgba(230,237,243,0.5)" text-anchor="middle">27 tables · System of Record</text>
+<text x="660" y="307" font-family="'JetBrains Mono','SF Mono','Fira Code',monospace" font-size="8" font-weight="400" fill="rgba(230,237,243,0.3)" text-anchor="middle">:5432</text>
+<line x1="560.5" y1="188" x2="560.5" y2="260" stroke="rgba(20,184,166,0.35)" stroke-width="1" marker-start="url(#ah-r)" marker-end="url(#ah)"/>
+<text x="567.5" y="227" font-family="'Inter','Segoe UI',system-ui,sans-serif" font-size="8" font-weight="400" fill="rgba(230,237,243,0.3)" text-anchor="start">SQL</text>
+<path d="M753.5,208 V234 H700 V260" fill="none" stroke="rgba(20,184,166,0.35)" stroke-width="1" marker-start="url(#ah-r)" marker-end="url(#ah)"/>
+<text x="694" y="237" font-family="'Inter','Segoe UI',system-ui,sans-serif" font-size="8" font-weight="400" fill="rgba(230,237,243,0.3)" text-anchor="end">SQL</text>
+<text x="280" y="369" font-family="'Inter','Segoe UI',system-ui,sans-serif" font-size="9" font-weight="600" fill="rgba(230,237,243,0.3)" text-anchor="start">EPHEMERAL PODS</text>
+<rect x="280" y="375" width="370" height="70" rx="8" fill="rgba(245,158,11,0.08)" stroke="rgba(245,158,11,0.30)" stroke-width="1" stroke-dasharray="6,4"/>
+<text x="465" y="392" font-family="'Inter','Segoe UI',system-ui,sans-serif" font-size="11" font-weight="600" fill="#fbbf24" text-anchor="middle">Model Runner Pods</text>
+<text x="465" y="407" font-family="'Inter','Segoe UI',system-ui,sans-serif" font-size="9" font-weight="400" fill="rgba(230,237,243,0.5)" text-anchor="middle">Ephemeral K8s Jobs</text>
+<text x="465" y="421" font-family="'Inter','Segoe UI',system-ui,sans-serif" font-size="8" font-weight="400" fill="rgba(230,237,243,0.3)" text-anchor="middle">Python (PyTorch / sklearn) · Rust (tch-rs)</text>
+<text x="465" y="435" font-family="'JetBrains Mono','SF Mono','Fira Code',monospace" font-size="8" font-weight="400" fill="rgba(230,237,243,0.3)" text-anchor="middle">oms-job-*</text>
+<rect x="670" y="375" width="370" height="70" rx="8" fill="rgba(16,185,129,0.08)" stroke="rgba(16,185,129,0.30)" stroke-width="1" stroke-dasharray="6,4"/>
+<text x="855" y="392" font-family="'Inter','Segoe UI',system-ui,sans-serif" font-size="11" font-weight="600" fill="#34d399" text-anchor="middle">Workspace Pods</text>
+<text x="855" y="407" font-family="'Inter','Segoe UI',system-ui,sans-serif" font-size="9" font-weight="400" fill="rgba(230,237,243,0.5)" text-anchor="middle">Per-User JupyterLab</text>
+<text x="855" y="421" font-family="'Inter','Segoe UI',system-ui,sans-serif" font-size="8" font-weight="400" fill="rgba(230,237,243,0.3)" text-anchor="middle">SDK + Tutorial Notebooks + Datasets</text>
+<text x="855" y="435" font-family="'JetBrains Mono','SF Mono','Fira Code',monospace" font-size="8" font-weight="400" fill="rgba(230,237,243,0.3)" text-anchor="middle">oms-ws-*</text>
+<path d="M545.5,325 V350 H465 V375" fill="none" stroke="rgba(245,158,11,0.30)" stroke-width="1" stroke-dasharray="4,3" marker-end="url(#ah)"/>
+<text x="459" y="353" font-family="'Inter','Segoe UI',system-ui,sans-serif" font-size="8" font-weight="400" fill="rgba(230,237,243,0.3)" text-anchor="end">Job orchestration</text>
+<path d="M505,375 V350 H575.5 V325" fill="none" stroke="rgba(245,158,11,0.30)" stroke-width="1" marker-end="url(#ah)"/>
+<text x="581.5" y="353" font-family="'Inter','Segoe UI',system-ui,sans-serif" font-size="8" font-weight="400" fill="rgba(230,237,243,0.3)" text-anchor="start">Metrics + Logs</text>
+<line x1="946.5" y1="208" x2="946.5" y2="375" stroke="rgba(16,185,129,0.30)" stroke-width="1" stroke-dasharray="4,3" marker-end="url(#ah)"/>
+<text x="953.5" y="294.5" font-family="'Inter','Segoe UI',system-ui,sans-serif" font-size="8" font-weight="400" fill="rgba(230,237,243,0.3)" text-anchor="start">Pod spawning</text>
+<path d="M815,375 V350 H600.5 V325" fill="none" stroke="rgba(59,130,246,0.35)" stroke-width="1" stroke-dasharray="4,3" marker-start="url(#ah-r)" marker-end="url(#ah)"/>
+<text x="821" y="353" font-family="'Inter','Segoe UI',system-ui,sans-serif" font-size="8" font-weight="400" fill="rgba(230,237,243,0.3)" text-anchor="start">SDK → REST</text>
+<text x="280" y="494" font-family="'Inter','Segoe UI',system-ui,sans-serif" font-size="9" font-weight="600" fill="rgba(230,237,243,0.3)" text-anchor="start">PERSISTENT VOLUMES</text>
+<rect x="280" y="500" width="178" height="40" rx="6" fill="rgba(255,255,255,0.025)" stroke="rgba(255,255,255,0.06)" stroke-width="1"/>
+<text x="369" y="516" font-family="'JetBrains Mono','SF Mono','Fira Code',monospace" font-size="9" font-weight="400" fill="rgba(230,237,243,0.5)" text-anchor="middle">models-pvc</text>
+<text x="369" y="530" font-family="'Inter','Segoe UI',system-ui,sans-serif" font-size="8" font-weight="400" fill="rgba(230,237,243,0.3)" text-anchor="middle">Model Code</text>
+<rect x="474" y="500" width="178" height="40" rx="6" fill="rgba(255,255,255,0.025)" stroke="rgba(255,255,255,0.06)" stroke-width="1"/>
+<text x="563" y="516" font-family="'JetBrains Mono','SF Mono','Fira Code',monospace" font-size="9" font-weight="400" fill="rgba(230,237,243,0.5)" text-anchor="middle">datasets-pvc</text>
+<text x="563" y="530" font-family="'Inter','Segoe UI',system-ui,sans-serif" font-size="8" font-weight="400" fill="rgba(230,237,243,0.3)" text-anchor="middle">Training Data</text>
+<rect x="668" y="500" width="178" height="40" rx="6" fill="rgba(255,255,255,0.025)" stroke="rgba(255,255,255,0.06)" stroke-width="1"/>
+<text x="757" y="516" font-family="'JetBrains Mono','SF Mono','Fira Code',monospace" font-size="9" font-weight="400" fill="rgba(230,237,243,0.5)" text-anchor="middle">artifacts-pvc</text>
+<text x="757" y="530" font-family="'Inter','Segoe UI',system-ui,sans-serif" font-size="8" font-weight="400" fill="rgba(230,237,243,0.3)" text-anchor="middle">Job Outputs</text>
+<rect x="862" y="500" width="178" height="40" rx="6" fill="rgba(255,255,255,0.025)" stroke="rgba(255,255,255,0.06)" stroke-width="1"/>
+<text x="951" y="516" font-family="'JetBrains Mono','SF Mono','Fira Code',monospace" font-size="9" font-weight="400" fill="rgba(230,237,243,0.5)" text-anchor="middle">postgres-data</text>
+<text x="951" y="530" font-family="'Inter','Segoe UI',system-ui,sans-serif" font-size="8" font-weight="400" fill="rgba(230,237,243,0.3)" text-anchor="middle">Database</text>
+<text x="30" y="132" font-family="'Inter','Segoe UI',system-ui,sans-serif" font-size="9" font-weight="600" fill="rgba(230,237,243,0.3)" text-anchor="start">EXTERNAL SERVICES</text>
+<rect x="30" y="140" width="190" height="50" rx="6" fill="rgba(148,163,184,0.06)" stroke="rgba(148,163,184,0.20)" stroke-width="1"/>
+<text x="125" y="161" font-family="'Inter','Segoe UI',system-ui,sans-serif" font-size="10" font-weight="600" fill="#94a3b8" text-anchor="middle">GitHub Registry</text>
+<text x="125" y="175" font-family="'Inter','Segoe UI',system-ui,sans-serif" font-size="8" font-weight="400" fill="rgba(230,237,243,0.3)" text-anchor="middle">Open Model Registry</text>
+<rect x="30" y="204" width="190" height="50" rx="6" fill="rgba(148,163,184,0.06)" stroke="rgba(148,163,184,0.20)" stroke-width="1"/>
+<text x="125" y="225" font-family="'Inter','Segoe UI',system-ui,sans-serif" font-size="10" font-weight="600" fill="#94a3b8" text-anchor="middle">LLM Providers</text>
+<text x="125" y="239" font-family="'Inter','Segoe UI',system-ui,sans-serif" font-size="8" font-weight="400" fill="rgba(230,237,243,0.3)" text-anchor="middle">OpenAI / Anthropic / Ollama</text>
+<rect x="30" y="268" width="190" height="50" rx="6" fill="rgba(148,163,184,0.06)" stroke="rgba(148,163,184,0.20)" stroke-width="1"/>
+<text x="125" y="289" font-family="'Inter','Segoe UI',system-ui,sans-serif" font-size="10" font-weight="600" fill="#94a3b8" text-anchor="middle">S3 / MinIO</text>
+<text x="125" y="303" font-family="'Inter','Segoe UI',system-ui,sans-serif" font-size="8" font-weight="400" fill="rgba(230,237,243,0.3)" text-anchor="middle">Artifact Storage</text>
+<path d="M220,165 H272 V194 H545.5 V188" fill="none" stroke="rgba(148,163,184,0.20)" stroke-width="1" marker-start="url(#ah-r)" marker-end="url(#ah)"/>
+<text x="416.25" y="206" font-family="'Inter','Segoe UI',system-ui,sans-serif" font-size="8" font-weight="400" fill="rgba(230,237,243,0.3)" text-anchor="middle">Model fetch</text>
+<path d="M220,229 H264 V202 H560.5 V188" fill="none" stroke="rgba(148,163,184,0.20)" stroke-width="1" marker-start="url(#ah-r)" marker-end="url(#ah)"/>
+<text x="416.25" y="214" font-family="'Inter','Segoe UI',system-ui,sans-serif" font-size="8" font-weight="400" fill="rgba(230,237,243,0.3)" text-anchor="middle">HTTPS</text>
+<path d="M220,293 H256 V210 H575.5 V188" fill="none" stroke="rgba(148,163,184,0.20)" stroke-width="1" marker-start="url(#ah-r)" marker-end="url(#ah)"/>
+<text x="416.25" y="222" font-family="'Inter','Segoe UI',system-ui,sans-serif" font-size="8" font-weight="400" fill="rgba(230,237,243,0.3)" text-anchor="middle">Presigned URLs</text>
+<rect x="40" y="669" width="10" height="10" rx="2" fill="rgba(139,92,246,0.10)" stroke="rgba(139,92,246,0.35)" stroke-width="1"/>
+<text x="56" y="678" font-family="'Inter','Segoe UI',system-ui,sans-serif" font-size="9" font-weight="400" fill="rgba(230,237,243,0.5)" text-anchor="start">Frontend / UI</text>
+<rect x="210" y="669" width="10" height="10" rx="2" fill="rgba(59,130,246,0.10)" stroke="rgba(59,130,246,0.35)" stroke-width="1"/>
+<text x="226" y="678" font-family="'Inter','Segoe UI',system-ui,sans-serif" font-size="9" font-weight="400" fill="rgba(230,237,243,0.5)" text-anchor="start">API / Backend</text>
+<rect x="380" y="669" width="10" height="10" rx="2" fill="rgba(20,184,166,0.10)" stroke="rgba(20,184,166,0.35)" stroke-width="1"/>
+<text x="396" y="678" font-family="'Inter','Segoe UI',system-ui,sans-serif" font-size="9" font-weight="400" fill="rgba(230,237,243,0.5)" text-anchor="start">Data Layer</text>
+<rect x="550" y="669" width="10" height="10" rx="2" fill="rgba(245,158,11,0.08)" stroke="rgba(245,158,11,0.30)" stroke-width="1"/>
+<text x="566" y="678" font-family="'Inter','Segoe UI',system-ui,sans-serif" font-size="9" font-weight="400" fill="rgba(230,237,243,0.5)" text-anchor="start">Ephemeral Pods</text>
+<rect x="720" y="669" width="10" height="10" rx="2" fill="rgba(16,185,129,0.08)" stroke="rgba(16,185,129,0.30)" stroke-width="1"/>
+<text x="736" y="678" font-family="'Inter','Segoe UI',system-ui,sans-serif" font-size="9" font-weight="400" fill="rgba(230,237,243,0.5)" text-anchor="start">Workspaces</text>
+<rect x="890" y="669" width="10" height="10" rx="2" fill="rgba(148,163,184,0.06)" stroke="rgba(148,163,184,0.20)" stroke-width="1"/>
+<text x="906" y="678" font-family="'Inter','Segoe UI',system-ui,sans-serif" font-size="9" font-weight="400" fill="rgba(230,237,243,0.5)" text-anchor="start">External</text>
+</svg>
diff --git a/docs/diagrams/generate-architecture.js b/docs/diagrams/generate-architecture.js
