OpenNoodl/dev-docs/tasks/phase-4-canvas-visualisation-views/VIEW-001-topology-map/SHELVED.md

Topology Map Panel - SHELVED

Date Shelved: April 1, 2026
Status: ⏸️ Disabled / Shelved for Future Development
Reason: Visual quality issues and complex layout problems

---

Why This Feature Was Shelved

The Topology Map Panel was an ambitious attempt to visualize project structure at the folder/component level with automatic layout, color-coded grouping, and interactive features. After multiple iterations attempting to fix visual bugs, the feature was shelved due to:

Primary Issues

1. SVG Text Layout Complexity

   • SVG doesn't support automatic text wrapping or flow layout like HTML
   • Attempts to use <foreignObject> for text wrapping created more problems than it solved
   • Dynamic card heights based on content proved difficult to coordinate across multiple elements
   • Text positioning calculations were fragile and broke easily

2. Visual Quality Problems

   • Text overlapping despite multiple fix attempts
   • Inconsistent spacing and padding across cards
   • Poor readability of folder/component information
   • Layout looked "worse than before" after attempted improvements

3. Fundamental Design Challenges

   • Mixing SVG rendering with HTML-like text layout expectations
   • Complex coordinate calculations for dynamic content
   • Difficulty achieving consistent visual polish

---

What Was Implemented

Despite being shelved, significant work was completed:

Working Features

• ✅ Component-level dependency graph analysis (utils/graphAnalysis/)
• ✅ Folder aggregation logic to group components by directory
• ✅ Semantic tier assignment (pages → features → integrations → UI → utilities)
• ✅ Folder type detection with color-coded styling
• ✅ Component X-Ray integration for detailed component stats
• ✅ Pan/zoom canvas with mouse wheel and drag controls
• ✅ Folder drilldown (double-click to see components inside)
• ✅ Trigger Chain Debugger integration

Partially Working

• ⚠️ Card rendering - Basic structure works, but visuals are poor
• ⚠️ Text layout - Titles wrap, but other text doesn't properly adjust
• ⚠️ Dynamic heights - Attempted but caused more issues

Not Implemented

• ❌ Draggable cards with position persistence (infrastructure exists, not integrated)
• ❌ Sticky notes for annotations
• ❌ Drilldown with back navigation (UI pattern not designed)
• ❌ Top-level component expansion (attempted but made things worse)

---

Code Location

The complete implementation exists in:

packages/noodl-editor/src/editor/src/views/panels/TopologyMapPanel/
├── TopologyMapPanel.tsx              # Main panel container
├── components/
│   ├── TopologyMapView.tsx           # SVG canvas with pan/zoom
│   ├── FolderNode.tsx                # Folder card rendering
│   ├── ComponentNode.tsx             # Component card rendering
│   ├── FolderEdge.tsx                # Connections between folders
│   └── *.module.scss                 # Styling (color-coded)
├── hooks/
│   ├── useFolderGraph.ts             # Builds folder graph from project
│   ├── useFolderLayout.ts            # Positions folders in tiers
│   ├── useTopologyGraph.ts           # Component-level graph (legacy)
│   └── useDraggable.ts               # Drag-and-drop (not integrated)
└── utils/
    ├── graphAnalysis/                # Dependency analysis (✅ solid)
    ├── folderAggregation.ts          # Group components into folders
    ├── folderTypeDetection.ts        # Classify folder types
    ├── tierAssignment.ts             # Semantic layout tiers
    ├── folderColors.ts               # Color schemes per type
    ├── componentStats.ts             # Extract component metadata
    ├── folderCardHeight.ts           # Dynamic height calculation
    ├── topologyPersistence.ts        # Save custom positions
    └── snapToGrid.ts                 # Grid snapping utility

Registration: Commented out in router.setup.ts (line ~85)

---

Lessons Learned

What Worked Well

1. Graph analysis utilities - The dependency analysis code is solid and reusable
2. Semantic tier system - Automatically categorizing folders by purpose works well
3. Color-coded folder types - Visual distinction by folder purpose is effective
4. Component X-Ray - Detailed component stats were valuable

What Didn't Work

1. SVG for complex UI - SVG is great for diagrams, poor for rich text and layout
2. Attempting HTML-like layout in SVG - Fighting against SVG's strengths
3. Dynamic card heights - Too many interdependent calculations, too fragile
4. Scope creep - Feature kept growing in complexity

Better Approaches for Future Attempts

1. Use HTML/CSS for cards - Render cards as HTML <div>s absolutely positioned on a canvas
2. Canvas API for connections - Use Canvas 2D API for drawing edges between cards
3. React Flow or similar library - Don't reinvent node graph visualization
4. Start with minimal viable version - Fixed-size cards, no fancy features
5. Focus on clarity over features - One clear view mode, not multiple view modes

---

Related Successful Features

These features from the same phase ARE working and enabled:

• ✅ Component X-Ray Panel (VIEW-002) - Shows detailed component information
• ✅ Trigger Chain Debugger (VIEW-003) - Visualizes event chains

Both use simpler rendering approaches (HTML/CSS) and focused scopes.

---

If You Want to Revive This Feature

Recommended Approach

1. Start from scratch with React Flow

   • Use reactflow library (or similar) for node graph visualization
   • Let the library handle layout, pan/zoom, connections
   • Focus on data preparation, not rendering

2. Simplify the UI

   • Fixed-height cards with consistent layout
   • Simple text labels (no fancy wrapping)
   • Clear, minimal styling

3. One view mode only

   • Either folder-level OR component-level, not both
   • No drilldown - just switch between two separate panels

4. Incremental delivery

   • Phase 1: Basic graph visualization (read-only)
   • Phase 2: Interaction (click to navigate)
   • Phase 3: Customization (drag, notes, etc.)

Alternative: Enhance Existing Tools

Instead of building a new visualization, enhance existing panels:

• Components Panel - Add folder tree view with stats
• Component X-Ray - Add visual dependency graph
• Search Panel - Add "show all uses" graph view

---

Status Summary

Disabled: April 1, 2026
Reason: Visual quality issues after multiple fix attempts
Decision: Shelve feature, code remains in codebase but not accessible in UI
Next Steps: Consider alternative approaches or simpler enhancements to existing panels

---

See Also:

• REMAINING-WORK-INDEX.md - What was planned but not completed
• CRITICAL-BUGS.md - The visual bugs that led to shelving
• BUGFIX-CHANGELOG.md - Fix attempts that didn't resolve the issues