Instruction file imported from gargislalom/so-ai-training-101-pnw-team2 (.github/instructions/intake/workflows/interactive-mermaid-diagrams.instructions.md). Copyright stays with the author.

Interactive Mermaid Diagrams in Workshop Prototype

Key Files

• docs/xd-playground/workshops/prototype/src/components/architecture/MermaidDiagram.tsx - shared rendering component
• docs/xd-playground/workshops/prototype/src/pages/ProgramArchitecturePage.tsx - C1/C2/C3 architecture views
• docs/xd-playground/workshops/prototype/src/data/c4-model.json - C4 model data source
• docs/xd-playground/workshops/prototype/src/types/architecture.ts - TypeScript interfaces

Two Click Mechanisms

MermaidDiagram supports two mutually exclusive click mechanisms. Choose based on diagram type.

1. DOM Label Click (mindmaps only)

For mindmap diagrams, use useLabelClick. The component walks SVG <g> elements post-render, extracts visible text, and fires onNodeClick(label) with the text content.

<MermaidDiagram definition={diagram} onNodeClick={handleLabelClick} useLabelClick />

Handler matches label text against known names:

const handleLabelClick = (label: string) => {
  const norm = (t: string) => t.replace(/\s+/g, ' ').trim();
  const sys = systems.find((s) => norm(s.shortName ?? s.name) === norm(label));
  if (sys) navigate(`/systems/${sys.id}`);
};

2. Mermaid Native click Directives (flowcharts)

For graph / flowchart diagrams, DOM-based click detection is unreliable due to nested SVG <g> structure (the <rect> and <text> are siblings, not parent-child). Use Mermaid's native click directive instead.

Requirements:

• securityLevel: 'loose' in mermaid.initialize() (already set)
• MermaidDiagram registers window.__onMermaidNodeClick which delegates to onNodeClick

In the diagram definition, add click lines for each clickable node:

// CRITICAL: include parentheses after the function name
def += `  click ${nodeId} call __onMermaidNodeClick()\n`;

In the page component, handle the node ID:

<MermaidDiagram definition={diagram} onNodeClick={handleNodeClick} />

Handler maps Mermaid node IDs to routes:

const handleNodeClick = (nodeId: string) => {
  const routes: Record<string, string> = { ndcExt: '/systems/ndc', /* ... */ };
  const route = routes[nodeId];
  if (route) navigate(route);
};

Common Gotchas

Adding a New Domain C2 Diagram

1. Populate data in c4-model.json under components["{domainId}"] array following C4Component schema:

   { "id": "...", "name": "...", "type": "Service", "description": "...", "featureTitle": "Layer Name", "systems": ["sap"] }

2. Build diagram function returning a Mermaid graph TB string with subgraphs per architectural layer. Add click directives for every clickable node.

3. Wire routing in buildC2Diagram():

   if (domainId === 'your-domain') return buildYourDomainC2Diagram();

4. Map node IDs to routes in a helper function, used by handleNodeClick in C2View.

See buildBankruptcyC2Diagram() and getBkNodeRoutes() in ProgramArchitecturePage.tsx as the reference implementation.

Adding Click to C1 Mindmap Boundary Labels

Boundary labels (like "Bankruptcy") in the C1 mindmap auto-navigate to domains. The handleLabelClick in C1View already matches labels against both externalSystems and domains arrays. No click directive needed - mindmaps use DOM label matching.