Add dual-tier diagram generation: simple overview + detailed views

Update backend diagram system to generate both a simplified (5-8 node)
overview diagram and the existing detailed diagram in a single LLM call.

- DiagramData schema: add optional layerLevel and simplifiedMermaidSource
  fields (backward-compatible with existing cached wikis)
- STRUCTURED_DIAGRAM_DATA_PROMPT: instruct LLM to produce a simplified
  Mermaid source alongside the detailed version, with clear guidelines
  for executive-summary-level diagrams
- diagram_extract: validate simplified diagrams have fewer nodes than
  the full version, gracefully falling back to detailed-only on failure

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: 2 people

api/diagram_extract.py

@@ -18,6 +18,36 @@
     re.DOTALL,
 )
 
+# Lightweight regex to find node IDs with shape declarations in Mermaid source.
+# Matches patterns like A[Label], B(Label), C{Label}, D((Label)), etc.
+_MERMAID_NODE_RE = re.compile(r'\b(\w+)\s*[\[\(\{<]')
+
+# Mermaid keywords to exclude from node counting.
+_MERMAID_KEYWORDS = frozenset({
+    'graph', 'flowchart', 'sequenceDiagram', 'classDiagram', 'erDiagram',
+    'TD', 'TB', 'LR', 'RL', 'BT', 'subgraph', 'end', 'style', 'class',
+    'click', 'linkStyle', 'classDef',
+})
+
+
+def _count_mermaid_nodes(mermaid_src: str) -> int:
+    """Return a rough count of unique node declarations in a Mermaid source string."""
+    matches = _MERMAID_NODE_RE.findall(mermaid_src)
+    return len({m for m in matches if m not in _MERMAID_KEYWORDS})
+
+
+def _validate_simplified(simplified: str, full: str) -> bool:
+    """Check that the simplified diagram has fewer (or equal) nodes than the full one."""
+    simplified_count = _count_mermaid_nodes(simplified)
+    full_count = _count_mermaid_nodes(full)
+    if simplified_count > full_count:
+        logger.warning(
+            "Simplified diagram has more nodes (%d) than the full diagram (%d); discarding",
+            simplified_count, full_count,
+        )
+        return False
+    return True
+
 
 def extract_diagram_data(content: str) -> List[Dict]:
     """Extract all structured diagram JSON blocks from wiki page content.
@@ -38,7 +68,14 @@ def extract_diagram_data(content: str) -> List[Dict]:
             try:
                 data = json.loads(raw_json)
                 validated = DiagramData(**data)
-                results.append(validated.model_dump())
+                dumped = validated.model_dump()
+
+                # Validate simplified diagram if present
+                if dumped.get("simplifiedMermaidSource") and dumped.get("mermaidSource"):
+                    if not _validate_simplified(dumped["simplifiedMermaidSource"], dumped["mermaidSource"]):
+                        dumped["simplifiedMermaidSource"] = None
+
+                results.append(dumped)
             except json.JSONDecodeError as exc:
                 logger.warning("Skipping diagram data block with invalid JSON: %s", exc)
             except Exception as exc:

api/diagram_schema.py

@@ -23,3 +23,5 @@ class DiagramData(BaseModel):
     edges: List[DiagramEdge]
     mermaidSource: str
     diagramType: Literal['flowchart', 'sequence', 'class', 'er'] = 'flowchart'
+    layerLevel: Optional[int] = None  # 1 = simple overview, 2 = detailed
+    simplifiedMermaidSource: Optional[str] = None  # Pre-generated simple version

api/prompts.py

@@ -203,24 +203,38 @@
 code block MUST still follow — the JSON is supplementary metadata, NOT a
 replacement for the Mermaid diagram.
 
+The JSON MUST include a "simplifiedMermaidSource" field containing a simplified
+overview version of the diagram. This simplified version is critical for users
+who want a high-level understanding at a glance.
+
 Format:
 <!-- DIAGRAM_DATA_START -->
 {
   "nodes": [
     { "id": "A", "label": "Frontend App", "technology": "react", "files": ["src/App.tsx"], "description": "Main React application", "depth": 0 },
-    { "id": "B", "label": "API Server", "technology": "fastapi", "files": ["api/api.py"], "description": "REST API backend", "depth": 0 }
+    { "id": "B", "label": "API Server", "technology": "fastapi", "files": ["api/api.py"], "description": "REST API backend", "depth": 0 },
+    { "id": "C", "label": "Database", "technology": "postgresql", "files": ["db/models.py"], "description": "Data persistence layer", "depth": 0 },
+    { "id": "D", "label": "Auth Service", "technology": "python", "files": ["api/auth.py"], "description": "Authentication and authorization", "depth": 1 },
+    { "id": "E", "label": "Cache Layer", "technology": "redis", "files": ["api/cache.py"], "description": "Response caching", "depth": 1 }
   ],
   "edges": [
-    { "source": "A", "target": "B", "label": "HTTP requests", "type": "api_call" }
+    { "source": "A", "target": "B", "label": "HTTP requests", "type": "api_call" },
+    { "source": "B", "target": "C", "label": "queries", "type": "data_flow" },
+    { "source": "B", "target": "D", "label": "validates tokens", "type": "dependency" },
+    { "source": "B", "target": "E", "label": "reads/writes", "type": "data_flow" }
   ],
-  "mermaidSource": "graph TD\n    A[Frontend App] --> B[API Server]",
-  "diagramType": "flowchart"
+  "mermaidSource": "graph TD\n    A[Frontend App] -->|HTTP requests| B[API Server]\n    B -->|queries| C[Database]\n    B -->|validates tokens| D[Auth Service]\n    B -->|reads/writes| E[Cache Layer]",
+  "diagramType": "flowchart",
+  "simplifiedMermaidSource": "graph TD\n    A[Frontend App] --> B[API Server]\n    B --> C[Database]\n    B --> D[External Services]"
 }
 <!-- DIAGRAM_DATA_END -->
 
 ```mermaid
 graph TD
-    A[Frontend App] --> B[API Server]
+    A[Frontend App] -->|HTTP requests| B[API Server]
+    B -->|queries| C[Database]
+    B -->|validates tokens| D[Auth Service]
+    B -->|reads/writes| E[Cache Layer]
 ```
 
 Rules for the structured JSON:
@@ -232,6 +246,16 @@
 - "mermaidSource" must contain the exact Mermaid source used in the code fence
 - If a diagram has no meaningful structured metadata, you may omit the JSON block
 - The JSON must be valid — if you are unsure, omit it rather than produce invalid JSON
+
+Rules for "simplifiedMermaidSource" (the simplified overview diagram):
+- MUST contain a valid Mermaid diagram with MAXIMUM 5-8 nodes
+- Show ONLY the highest-level architectural components (think "executive summary")
+- Use clear, short labels (2-4 words each, e.g., "User Interface", "API Layer", "Database")
+- Use simple relationships WITHOUT detailed edge labels (just arrows, no labels)
+- Collapse related sub-components into a single node (e.g., merge "Auth Service" + "User Service" into "Backend Services")
+- The simplified diagram must be immediately understandable at a glance by a non-technical person
+- If the full diagram already has 8 or fewer nodes, simplifiedMermaidSource can match mermaidSource
+- Do NOT include implementation details, file names, or technical jargon in the simplified version
 </structured_diagram_data>
 """