Render architecture diagram as embedded static PNG in docs section

app.py

@@ -5,6 +5,7 @@ import time
 import json
 import csv
 import re
+import base64
 from datetime import datetime
 from functools import lru_cache
 from PIL import Image
@@ -24,6 +25,10 @@ from psq_rag.retrieval.state import (
 )
 from psq_rag.ui.group_ranked_display import rank_groups_from_tfidf, _load_enabled_groups
 
+APP_DIR = Path(__file__).parent
+DOCS_DIR = APP_DIR / "docs"
+ARCH_DIAGRAM_FILE = DOCS_DIR / "assets" / "architecture_overview.png"
+
 
 _CORPORATE_HARDBLOCK_PATTERNS = [
     # Rating-like explicitness markers.
@@ -114,8 +119,8 @@ def _load_tag_wiki_defs() -> Dict[str, str]:
 @lru_cache(maxsize=1)
 def _load_about_docs_markdown() -> str:
     candidates = [
-        Path("docs/space_overview.md"),
-        Path("PROJECT_SUMMARY.md"),
+        DOCS_DIR / "space_overview.md",
+        APP_DIR / "PROJECT_SUMMARY.md",
     ]
     for p in candidates:
         if not p.exists():
@@ -132,6 +137,15 @@ def _load_about_docs_markdown() -> str:
             parts = text.split("---", 2)
             if len(parts) >= 3:
                 text = parts[2].strip()
+        if "{{ARCHITECTURE_DIAGRAM}}" in text:
+            arch_uri = _load_arch_diagram_data_uri()
+            if arch_uri:
+                text = text.replace(
+                    "{{ARCHITECTURE_DIAGRAM}}",
+                    f'<img src="{arch_uri}" alt="Architecture diagram" />',
+                )
+            else:
+                text = text.replace("{{ARCHITECTURE_DIAGRAM}}", "`(architecture diagram unavailable)`")
         if text:
             return text
     return (
@@ -155,6 +169,20 @@ def _tooltip_text_for_tag(tag: str) -> str:
     return "\n".join(parts).strip()
 
 
+@lru_cache(maxsize=1)
+def _load_arch_diagram_data_uri() -> str:
+    if not ARCH_DIAGRAM_FILE.exists():
+        return ""
+    try:
+        raw = ARCH_DIAGRAM_FILE.read_bytes()
+    except Exception:
+        return ""
+    if not raw:
+        return ""
+    b64 = base64.b64encode(raw).decode("ascii")
+    return f"data:image/png;base64,{b64}"
+
+
 def _selection_source_rank(origin: str) -> int:
     o = _normalize_selection_origin(origin)
     if o == "structural":
@@ -1399,29 +1427,12 @@ css = """
   line-height: 1.42 !important;
 }
 
-.about-docs pre code.language-mermaid {
-  font-size: 0.92rem !important;
-}
-
-.about-docs .mermaid-diagram {
-  background: #ffffff;
+.about-docs img {
+  max-width: 100% !important;
+  height: auto !important;
   border: 1px solid #d2d7e0;
   border-radius: 10px;
-  padding: 8px;
-  margin: 10px 0;
-  overflow-x: auto;
-}
-
-.about-docs .mermaid-diagram svg {
-  min-width: 920px;
-  max-width: none;
-  height: auto !important;
-}
-
-.about-docs .mermaid-diagram .nodeLabel p,
-.about-docs .mermaid-diagram .edgeLabel p {
-  margin: 0 !important;
-  line-height: 1.2 !important;
+  background: #ffffff;
 }
 
 .top-instruction {
@@ -1472,108 +1483,6 @@ css = """
 
 client_js = """
 () => {
-  let mermaidInit = null;
-
-  const ensureMermaid = async () => {
-    if (window.mermaid) return window.mermaid;
-    if (mermaidInit) return mermaidInit;
-    mermaidInit = new Promise((resolve, reject) => {
-      const script = document.createElement("script");
-      script.src = "https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.min.js";
-      script.async = true;
-      script.onload = () => {
-        try {
-          window.mermaid.initialize({
-            startOnLoad: false,
-            securityLevel: "loose",
-            theme: "base",
-            flowchart: {
-              htmlLabels: false,
-              padding: 18,
-              nodeSpacing: 42,
-              rankSpacing: 56,
-            },
-            themeVariables: {
-              primaryColor: "#e8f0ff",
-              primaryTextColor: "#111827",
-              primaryBorderColor: "#365e9d",
-              secondaryColor: "#edf7ef",
-              secondaryTextColor: "#111827",
-              secondaryBorderColor: "#2f7a3f",
-              lineColor: "#334155",
-              textColor: "#111827",
-              fontSize: "15px",
-              noteBkgColor: "#fffbe8",
-              noteBorderColor: "#8b6c00",
-              noteTextColor: "#111827"
-            },
-          });
-          resolve(window.mermaid);
-        } catch (e) {
-          reject(e);
-        }
-      };
-      script.onerror = () => reject(new Error("mermaid load failed"));
-      document.head.appendChild(script);
-    });
-    try {
-      return await mermaidInit;
-    } catch (_) {
-      return null;
-    }
-  };
-
-  const renderAboutMermaid = async () => {
-    const root = document.querySelector("#about-docs");
-    if (!root) return;
-    const extractMermaid = (text) => {
-      const raw = (text || "").trim();
-      if (!raw) return "";
-      const rx = /(flowchart|sequenceDiagram|graph|classDiagram|stateDiagram|erDiagram)\\b[\\s\\S]*/i;
-      const m = raw.match(rx);
-      if (!m) return "";
-      return (m[0] || "").trim();
-    };
-
-    const candidates = [];
-    const codeBlocks = root.querySelectorAll("pre code.language-mermaid");
-    for (const codeEl of codeBlocks) {
-      const pre = codeEl.closest("pre");
-      if (!pre || pre.dataset.psqMermaidDone === "1") continue;
-      const src = extractMermaid(codeEl.textContent || "");
-      if (src) candidates.push({ container: pre, src });
-    }
-
-    // Hugging Face sometimes flattens mermaid blocks into plain paragraph text.
-    const paraBlocks = root.querySelectorAll("p");
-    for (const p of paraBlocks) {
-      if (!p || p.dataset.psqMermaidDone === "1") continue;
-      if (p.closest("pre")) continue;
-      if (p.classList.contains("mermaid-diagram")) continue;
-      const src = extractMermaid(p.textContent || "");
-      if (src) candidates.push({ container: p, src });
-    }
-
-    if (!candidates.length) return;
-    const mermaid = await ensureMermaid();
-    if (!mermaid) return;
-
-    for (const { container, src } of candidates) {
-      if (!container || container.dataset.psqMermaidDone === "1") continue;
-      try {
-        const id = "psq-mermaid-" + Math.random().toString(36).slice(2);
-        const out = await mermaid.render(id, src);
-        const host = document.createElement("div");
-        host.className = "mermaid-diagram";
-        host.innerHTML = out.svg;
-        container.replaceWith(host);
-        container.dataset.psqMermaidDone = "1";
-      } catch (_) {
-        // Keep raw markdown mermaid block visible if render fails.
-      }
-    }
-  };
-
   const readTooltipMap = () => {
     const el = document.querySelector("#psq-tooltip-map textarea, #psq-tooltip-map input");
     if (!el) return { rows: [], tips: {} };
@@ -1620,7 +1529,6 @@ client_js = """
     requestAnimationFrame(() => {
       scheduled = false;
       applyTooltips();
-      void renderAboutMermaid();
     });
   };
 
@@ -2384,5 +2292,5 @@ with gr.Blocks(css=css, js=client_js) as app:
             show_progress="hidden",
         )
 
-if __name__ == "__main__":
-    app.queue().launch(allowed_paths=[str(MASCOT_DIR)])
+if __name__ == "__main__":
+    app.queue().launch(allowed_paths=[str(MASCOT_DIR), str(DOCS_DIR)])

docs/space_overview.md

@@ -15,42 +15,7 @@ Design goals:
 
 ## Architecture At A Glance
 
-```mermaid
-flowchart TB
-    U["User Prompt"] --> P["Orchestrator app.py"]
-
-    subgraph LLM["LLM Calls"]
-      direction LR
-      R["Rewrite"]
-      S["Structural Inference"]
-      Q["Probe Inference"]
-      X["Closed-Set Selection"]
-    end
-
-    C["Retrieval Candidates"]
-
-    subgraph OUT["Output"]
-      direction LR
-      I["Implication Expansion"]
-      G["Ranked Rows"]
-      UI["Toggle UI and Suggested Prompt"]
-    end
-
-    P --> R
-    P --> S
-    P --> Q
-    R --> C
-    S --> C
-    Q --> C
-    C --> X
-    S --> X
-    Q --> X
-    X --> I
-    I --> G
-    G --> UI
-
-    style LLM fill:#f3e8ff,stroke:#6d28d9,stroke-width:2px,color:#111827
-```
+{{ARCHITECTURE_DIAGRAM}}
 
 ## What Each Step Does