glam/UML_VIEWER_VS_MERMAID_ANALYSIS.md

UML Viewer vs. Mermaid Chart - Organization & UX Analysis

Date: November 23, 2025
Objective: Compare our UML Viewer with Mermaid Chart's interface to identify organizational improvements

---

🎯 Executive Summary

Our UML Viewer is functionally complete but can benefit from Mermaid's superior organization and workflow design. The key differences lie in layout clarity, code-first workflow, and panel management.

Key Finding: Mermaid Chart prioritizes the code editor with live preview, while our viewer prioritizes the visual diagram. Both approaches are valid but serve different use cases.

---

📊 Side-by-Side Comparison

Layout Architecture

Aspect	Mermaid Chart	Our UML Viewer	Winner
Primary Panel	Code Editor (left)	Diagram Viewer (center)	Depends on use case
Secondary Panel	Live Preview (right)	File List (left sidebar)	Mermaid (more flexible)
Tertiary Panel	None	Node Details (optional)	Viewer (more info)
Panel Resize	✅ Draggable splitters	❌ Fixed widths	Mermaid
Panel Collapse	✅ Full collapse	❌ No collapse	Mermaid
Layout Modes	Multiple (editor-focus, preview-focus, split)	Single fixed layout	Mermaid

Navigation & Organization

Aspect	Mermaid Chart	Our UML Viewer	Winner
File Navigation	Folder tree with search	Grouped flat list	Mermaid
Diagram Grouping	Folders, tags, categories	Static type groups (Mermaid/PlantUML/GraphViz)	Mermaid
Search	✅ Full-text search	❌ No search	Mermaid
Recently Viewed	✅ Quick access	❌ No history	Mermaid
Favorites	✅ Star diagrams	❌ No favorites	Mermaid
Diagram Count Badge	✅ Visible counts	❌ No counts	Mermaid

Toolbar & Controls

Aspect	Mermaid Chart	Our UML Viewer	Winner
Zoom Controls	✅ +/- buttons + slider	✅ +/- buttons	Tie
Fit to Screen	✅ One-click	✅ One-click	Tie
Export Options	✅ PNG, SVG, PDF, Source	✅ PNG, SVG, Source	Mermaid (PDF)
Theme Switcher	✅ Light/Dark mode	❌ Light only	Mermaid
Settings Panel	✅ Diagram config	❌ No settings	Mermaid
Share Button	✅ Copy link	❌ No sharing	Mermaid

Visual Design

Aspect	Mermaid Chart	Our UML Viewer	Winner
Color Scheme	Soft blue/white	NDE blue (#0a3dfa)	Viewer (brand consistency)
Typography	Inter/System fonts	System fonts	Tie
Spacing	Generous padding	Moderate padding	Mermaid
Visual Hierarchy	Clear depth (shadows)	Flat borders	Mermaid
Icons	Lucide icons	Lucide icons	Tie
Animation	Smooth transitions	Basic transitions	Mermaid

User Workflow

Aspect	Mermaid Chart	Our UML Viewer	Winner
Primary Use Case	Create/Edit diagrams	View existing diagrams	N/A (different goals)
Code Editing	✅ Full editor (Monaco)	❌ View-only (collapsed)	Mermaid
Live Preview	✅ Real-time updates	N/A	Mermaid
Syntax Validation	✅ Error highlighting	❌ Parse errors only	Mermaid
Auto-format	✅ Code formatting	❌ No formatting	Mermaid
Undo/Redo	✅ Full history	N/A	Mermaid

---

🔍 Detailed Feature Analysis

1. Code Editor vs. Visual-First Approach

Mermaid Chart:

• Code is primary: Left panel = Monaco editor (full IDE experience)
• Diagram is secondary: Right panel = live preview of code
• Workflow: Write code → See diagram instantly
• Target User: Developers creating diagrams from scratch

Our UML Viewer:

• Diagram is primary: Center panel = interactive D3.js visualization
• Code is secondary: Collapsed source viewer at bottom
• Workflow: Select file → View diagram → Export
• Target User: Stakeholders reviewing generated diagrams

Recommendation:

• Keep visual-first for our use case (viewing LinkML-generated diagrams)
• Add code panel toggle for power users who want to edit

---

2. Panel Resize & Layout Flexibility

Mermaid Chart:

┌─────────────┬────────────────┐
│             │                │
│   EDITOR    │    PREVIEW     │
│  (resize)   │   (resize)     │
│             │                │
└─────────────┴────────────────┘
   ^ Draggable splitter

Our UML Viewer:

┌────────┬─────────────────────┐
│        │                     │
│ FILES  │      DIAGRAM        │
│ (320px)│    (flex: 1)        │
│        │                     │
└────────┴─────────────────────┘
   ^ Fixed width (no resize)

Recommendation:

• Add draggable splitter between sidebar and main area
• Use react-resizable-panels or similar library
• Allow sidebar collapse (hamburger icon)

---

3. File Navigation & Organization

Mermaid Chart Structure:

📁 My Diagrams
  ├─ 📁 Architecture
  │   ├─ 📄 System Overview
  │   └─ 📄 Database Schema
  ├─ 📁 User Flows
  │   └─ 📄 Registration Flow
  └─ 📁 Recent (auto-generated)

Our UML Viewer Structure:

UML Diagrams
├─ Mermaid Class Diagrams
│   ├─ Custodian Multi-Aspect
│   └─ Custodian Name Modular
├─ ER Diagrams
│   ├─ Custodian ER Diagram
│   └─ Custodian Name Modular (ER)
└─ PlantUML / GraphViz

Recommendation:

• Add search bar above file list (fuzzy search)
• Group by schema version (20251121, 20251122, etc.)
• Add recently viewed section at top
• Show diagram metadata (date generated, node count, complexity)

---

4. Toolbar Organization

Mermaid Chart Toolbar:

┌────────────────────────────────────────────────┐
│ [≡] [Save] [Export ▾] [Share] ... [Theme] [?] │
└────────────────────────────────────────────────┘
     ^Left-aligned actions    ^Right-aligned settings

Our UML Viewer Toolbar:

┌────────────────────────────────────────────────┐
│ Custodian... [+] [-] [⊡] [↻]  [PNG] [SVG] [...] │
└────────────────────────────────────────────────┘
    ^Title      ^Zoom controls  ^Export buttons

Recommendation:

• Separate zoom and export with visual divider (vertical line)
• Add dropdown for export formats (cleaner than 3 buttons)
• Add settings icon for diagram config (layout algorithm, colors)

---

5. Visual Hierarchy & Depth

Mermaid Chart Design:

• Uses subtle shadows (box-shadow: 0 2px 8px rgba(0,0,0,0.1))
• Layered panels (editor over background)
• Rounded corners everywhere (8px border-radius)
• Hover states with color transitions

Our UML Viewer Design:

• Uses flat borders (border: 1px solid #e0e0e0)
• Minimal depth (no shadows)
• Rounded corners (6-8px)
• Hover states with background color

Recommendation:

• Add subtle shadows to sidebar and toolbar (depth perception)
• Use elevation system (sidebar = z-10, toolbar = z-20, modals = z-50)
• Add backdrop blur for modals/overlays

---

🎨 Specific UX Improvements

Priority 1: Layout Flexibility (High Impact, Medium Effort)

Implementation:

import { Panel, PanelGroup, PanelResizeHandle } from 'react-resizable-panels';

<PanelGroup direction="horizontal">
  {/* Sidebar */}
  <Panel defaultSize={20} minSize={15} maxSize={40}>
    <Sidebar />
  </Panel>
  
  {/* Resize handle */}
  <PanelResizeHandle className="resize-handle" />
  
  {/* Main diagram area */}
  <Panel defaultSize={80}>
    <DiagramViewer />
  </Panel>
</PanelGroup>

Benefits:

• Users can adjust sidebar width for long filenames
• Maximize diagram area for presentations
• More screen real estate on ultrawide monitors

---

Priority 2: Search & Filter (High Impact, Low Effort)

Implementation:

const [searchQuery, setSearchQuery] = useState('');

const filteredFiles = availableFiles.filter(file => 
  file.name.toLowerCase().includes(searchQuery.toLowerCase())
);

<div className="search-bar">
  <Search size={16} />
  <input 
    type="text"
    placeholder="Search diagrams..."
    value={searchQuery}
    onChange={(e) => setSearchQuery(e.target.value)}
  />
</div>

Benefits:

• Quick navigation in large diagram collections
• Filter by keyword (e.g., "custodian", "multi-aspect")
• Keyboard-first workflow (focus search with /)

---

Priority 3: Sidebar Collapse (Medium Impact, Low Effort)

Implementation:

const [sidebarOpen, setSidebarOpen] = useState(true);

<div className={`sidebar ${!sidebarOpen ? 'collapsed' : ''}`}>
  <button onClick={() => setSidebarOpen(!sidebarOpen)}>
    {sidebarOpen ? <ChevronLeft /> : <ChevronRight />}
  </button>
</div>

.sidebar.collapsed {
  width: 48px; /* Just show toggle button */
}

Benefits:

• Maximize diagram space for presentations
• Distraction-free viewing mode
• Better mobile experience

---

Priority 4: Export Dropdown (Low Impact, Low Effort)

Current: 3 separate buttons (PNG, SVG, Source)

Improved:

<DropdownMenu>
  <DropdownMenuTrigger>
    <Download size={16} />
    Export
  </DropdownMenuTrigger>
  <DropdownMenuContent>
    <DropdownMenuItem onClick={handleExportPNG}>
      <Image size={14} /> Export as PNG
    </DropdownMenuItem>
    <DropdownMenuItem onClick={handleExportSVG}>
      <FileCode size={14} /> Export as SVG
    </DropdownMenuItem>
    <DropdownMenuSeparator />
    <DropdownMenuItem onClick={handleDownloadSource}>
      <Code size={14} /> Download Source
    </DropdownMenuItem>
  </DropdownMenuContent>
</DropdownMenu>

Benefits:

• Cleaner toolbar (1 button instead of 3)
• Scalable (easy to add PDF export later)
• Better mobile UX (less button crowding)

---

Priority 5: Diagram Metadata (Medium Impact, Medium Effort)

Implementation:

interface DiagramMetadata {
  nodeCount: number;
  linkCount: number;
  generatedAt: string;
  schemaVersion: string;
  complexity: 'low' | 'medium' | 'high';
}

<div className="file-card">
  <h4>{file.name}</h4>
  <div className="metadata">
    <span><Boxes size={12} /> {metadata.nodeCount} nodes</span>
    <span><GitBranch size={12} /> {metadata.linkCount} links</span>
    <span><Calendar size={12} /> {metadata.generatedAt}</span>
  </div>
</div>

Benefits:

• Quick assessment of diagram size/complexity
• Version tracking (which schema generated this?)
• Better decision-making (choose right diagram for use case)

---

📈 Recommended Implementation Roadmap

Phase 1: Quick Wins (1-2 hours)

1. ✅ Add search bar to sidebar (fuzzy file search)
2. ✅ Add sidebar collapse toggle (hamburger icon)
3. ✅ Replace 3 export buttons with dropdown menu
4. ✅ Add subtle shadows to panels (depth perception)

Phase 2: Layout Improvements (3-4 hours)

1. ✅ Implement resizable panels (react-resizable-panels)
2. ✅ Add layout presets (sidebar-focus, diagram-focus, balanced)
3. ✅ Save layout preferences to localStorage
4. ✅ Add keyboard shortcuts (Cmd+F for search, Cmd+\ for sidebar)

Phase 3: Enhanced Navigation (2-3 hours)

1. ✅ Add diagram metadata badges (node count, complexity)
2. ✅ Implement recently viewed section
3. ✅ Add schema version grouping
4. ✅ Show diagram thumbnails on hover

Phase 4: Code Editor Mode (Optional, 4-6 hours)

1. ⏳ Add Monaco editor integration (for power users)
2. ⏳ Implement live preview (code → diagram sync)
3. ⏳ Add syntax highlighting for Mermaid/PlantUML/DOT
4. ⏳ Enable edit → save → regenerate workflow

---

🎯 Key Takeaways

What We're Doing Better Than Mermaid:

1. ✅ Multi-format support (Mermaid, PlantUML, GraphViz, ER)
2. ✅ D3.js force-directed layouts (more flexible than Mermaid's dagre)
3. ✅ Node details panel (Mermaid doesn't show class attributes inline)
4. ✅ Brand consistency (NDE logo, color scheme integration)

What We Can Learn From Mermaid:

1. 🎯 Panel flexibility (resize, collapse, rearrange)
2. 🎯 Search & filter (essential for large diagram collections)
3. 🎯 Visual hierarchy (shadows, depth, layering)
4. 🎯 Export workflow (dropdown menu vs. separate buttons)
5. 🎯 Diagram metadata (help users choose the right diagram)

What Doesn't Apply to Our Use Case:

1. ❌ Code-first editor (we're viewing generated diagrams, not authoring)
2. ❌ Collaboration features (not a multi-user tool)
3. ❌ Diagram versioning (handled by LinkML schema versioning)
4. ❌ Sharing/embedding (internal tool, not public sharing)

---

🚀 Next Steps

Immediate Action (Choose One):

1. Quick UX Polish (Phase 1) - 1-2 hours, high user satisfaction
2. Layout Overhaul (Phase 2) - 3-4 hours, transformative change
3. Continue to Performance Testing - Original Task 5 from roadmap

Recommendation: Implement Phase 1 (Quick Wins) now - it's low effort, high impact, and makes the viewer feel significantly more polished without major architectural changes.

After Phase 1, decide whether to:

• Continue with Phase 2 (Layout) if users demand more customization
• Move to Task 5 (Performance Testing) if diagram loading is slow
• Move to Task 6 (Mobile Responsiveness) if mobile users are frustrated

---

📚 References

• Mermaid Chart: https://www.mermaidchart.com/play
• Our UML Viewer: http://localhost:5173/uml-viewer
• React Resizable Panels: https://github.com/bvaughn/react-resizable-panels
• Radix UI (Dropdown Menu): https://www.radix-ui.com/primitives/docs/components/dropdown-menu
• D3 Force Simulation: https://d3js.org/d3-force

---

Analysis Date: November 23, 2025
Analyst: OpenCODE AI
Status: Ready for Implementation