# VIEW-001: Project Topology Map

**View Type:** 🗺️ Meta View (replaces canvas with project-wide view)

## Overview

A high-level "Google Maps" view of the entire project's component structure. Shows how components relate to each other as a navigable graph, with a "You Are Here" indicator and the ability to jump to any component.

**Estimate:** 4-5 days  
**Priority:** HIGH  
**Complexity:** Medium  
**Dependencies:** VIEW-000 (Foundation)

---

## The Problem

When working in a complex Noodl project:

- You can't see how many components exist or how they relate
- You lose track of where you are when deep in nested components
- There's no way to get a "big picture" view of the project architecture
- Finding a component means hunting through the Components Panel tree

---

## The Solution

A visual map showing:

- Every component as a box/node
- Arrows showing which components use which others
- "You Are Here" highlight on the current component
- Click-to-navigate to any component
- Breadcrumb trail showing how you got to your current location

---

## User Stories

1. **As a new developer** joining a project, I want to see the overall structure so I can understand how the app is organized.

2. **As a developer debugging**, I want to see where the current component fits in the hierarchy so I understand the context.

3. **As a developer navigating**, I want to click on any component in the map to jump directly to it.

4. **As a developer planning**, I want to see which components are reused in multiple places.

---

## UI Design

### Main View

```
┌─────────────────────────────────────────────────────────────────┐
│ Project Topology                                    [Fit] [−][+]│
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│   ┌─────────┐     ┌─────────┐     ┌─────────┐                  │
│   │  Login  │     │  Home   │     │ Profile │   📄 PAGES       │
│   │  Page   │     │  Page   │     │  Page   │                  │
│   └────┬────┘     └────┬────┘     └────┬────┘                  │
│        │               │               │                        │
│        │    ┌──────────┼───────────────┤                       │
│        │    │          │               │                        │
│        ▼    ▼          ▼               ▼                        │
│   ┌─────────────┐ ┌─────────┐ ┌──────────────┐                 │
│   │   AuthFlow  │ │  NavBar │ │  UserCard    │  🧩 SHARED      │
│   │ ★ YOU ARE   │ │  (×3)   │ │   (×2)       │                 │
│   │    HERE     │ └─────────┘ └──────────────┘                 │
│   └──────┬──────┘                    │                          │
│          │                           │                          │
│          ▼                           ▼                          │
│   ┌─────────────┐            ┌──────────────┐                  │
│   │ LoginForm   │            │  AvatarIcon  │  🔧 NESTED       │
│   │ Component   │            │  Component   │                  │
│   └─────────────┘            └──────────────┘                  │
│                                                                 │
├─────────────────────────────────────────────────────────────────┤
│ 📍 Path: App Shell → Login Page → AuthFlow                      │
│ 📊 23 components total | 8 pages | 12 shared | 3 nested         │
└─────────────────────────────────────────────────────────────────┘
```

### Component Node Styling

| Component Type           | Visual Style                        |
| ------------------------ | ----------------------------------- |
| Page                     | Larger box, 📄 icon, distinct color |
| Shared (used 2+ times)   | Badge showing usage count (×3)      |
| Current ("You Are Here") | Highlighted border, ★ indicator     |
| Has subcomponents        | Subtle "expandable" indicator       |
| Orphan (unused)          | Dimmed, warning style               |

### Interactions

- **Click component** → Jump to that component in canvas
- **Hover component** → Show tooltip with summary (node count, I/O ports)
- **Double-click** → Expand to show internal structure (optional)
- **Drag to pan** → Navigate large maps
- **Scroll to zoom** → Zoom in/out
- **[Fit] button** → Fit entire map in view
- **Click breadcrumb** → Navigate to that ancestor component

---

## Technical Design

### Data Model

```typescript
interface TopologyNode {
  component: ComponentModel;
  name: string;
  fullName: string;
  type: 'page' | 'component';
  usageCount: number; // How many places use this component
  usedBy: string[]; // Which components use this one
  uses: string[]; // Which components this one uses
  depth: number; // Nesting depth from root
  isCurrentComponent: boolean;
}

interface TopologyEdge {
  from: string; // Component fullName
  to: string; // Component fullName
  count: number; // How many instances
}

interface TopologyGraph {
  nodes: TopologyNode[];
  edges: TopologyEdge[];
  currentPath: string[]; // Breadcrumb path
}
```

### Building the Graph

```typescript
function buildTopologyGraph(project: ProjectModel): TopologyGraph {
  const nodes: TopologyNode[] = [];
  const edges: TopologyEdge[] = [];

  // 1. Collect all components
  project.forEachComponent((component) => {
    nodes.push({
      component,
      name: component.name,
      fullName: component.fullName,
      type: isPageComponent(component) ? 'page' : 'component',
      usageCount: 0,
      usedBy: [],
      uses: [],
      depth: 0,
      isCurrentComponent: false
    });
  });

  // 2. Find all component usages (nodes of type that matches a component name)
  nodes.forEach((node) => {
    node.component.graph.forEachNode((graphNode) => {
      if (isComponentInstance(graphNode)) {
        const usedComponentName = graphNode.type.name;
        const usedNode = nodes.find((n) => n.fullName === usedComponentName);
        if (usedNode) {
          usedNode.usageCount++;
          usedNode.usedBy.push(node.fullName);
          node.uses.push(usedComponentName);

          edges.push({
            from: node.fullName,
            to: usedComponentName,
            count: 1 // Aggregate later
          });
        }
      }
    });
  });

  // 3. Calculate depths (BFS from pages)
  calculateDepths(nodes, edges);

  return { nodes, edges, currentPath: [] };
}
```

### Layout Algorithm

Use a hierarchical layout (like Dagre) to position nodes:

```typescript
import dagre from 'dagre';

function layoutTopology(graph: TopologyGraph): PositionedTopologyGraph {
  const g = new dagre.graphlib.Graph();
  g.setGraph({ rankdir: 'TB', ranksep: 80, nodesep: 50 });
  g.setDefaultEdgeLabel(() => ({}));

  // Add nodes with estimated sizes
  graph.nodes.forEach((node) => {
    const width = node.type === 'page' ? 140 : 120;
    const height = 60;
    g.setNode(node.fullName, { width, height });
  });

  // Add edges
  graph.edges.forEach((edge) => {
    g.setEdge(edge.from, edge.to);
  });

  dagre.layout(g);

  // Extract positions
  return graph.nodes.map((node) => ({
    ...node,
    x: g.node(node.fullName).x,
    y: g.node(node.fullName).y
  }));
}
```

### Rendering

Could use:

- **SVG** - Simple, good for moderate sizes
- **Canvas** - Better performance for large graphs
- **React Flow** - Library specifically for this (already used elsewhere?)

Recommend starting with SVG for simplicity, refactor to Canvas if performance issues.

---

## Implementation Phases

### Phase 1: Data Collection (1 day)

1. Implement `buildTopologyGraph()` using VIEW-000 utilities
2. Correctly identify component instances vs regular nodes
3. Calculate usage counts and relationships
4. Determine page vs component classification

**Verification:**

- [ ] All components in project appear in graph
- [ ] Component usage relationships are correct
- [ ] Pages correctly identified

### Phase 2: Layout Algorithm (1 day)

1. Integrate Dagre.js for hierarchical layout
2. Position pages at top, shared components in middle, nested at bottom
3. Handle edge cases (cycles, orphans)
4. Calculate viewport bounds

**Verification:**

- [ ] Layout produces non-overlapping nodes
- [ ] Hierarchy is visually clear
- [ ] Large graphs don't break

### Phase 3: Basic Rendering (1 day)

1. Create `TopologyMapView` React component
2. Render nodes as styled boxes
3. Render edges as lines/arrows
4. Implement pan and zoom
5. Add "Fit to View" button

**Verification:**

- [ ] Graph renders correctly
- [ ] Can pan and zoom
- [ ] Fit button works

### Phase 4: Interactivity (1 day)

1. Click node → Navigate to component
2. Hover → Show tooltip
3. Highlight current component
4. Show breadcrumb path
5. Add "You Are Here" indicator

**Verification:**

- [ ] Clicking navigates correctly
- [ ] Current component highlighted
- [ ] Breadcrumb shows path

### Phase 5: Polish (0.5-1 day)

1. Style refinement (colors, icons, badges)
2. Add usage count badges
3. Add orphan warnings
4. Performance optimization if needed
5. Add to Analysis Panel tabs

**Verification:**

- [ ] Visually polished
- [ ] Integrates with Analysis Panel
- [ ] Performance acceptable on large projects

---

## Files to Create

```
packages/noodl-editor/src/editor/src/views/AnalysisPanel/
└── TopologyMapView/
    ├── index.ts
    ├── TopologyMapView.tsx
    ├── TopologyMapView.module.scss
    ├── TopologyNode.tsx
    ├── TopologyEdge.tsx
    ├── TopologyTooltip.tsx
    ├── Breadcrumbs.tsx
    └── useTopologyGraph.ts
```

---

## Success Criteria

- [ ] Shows all components in the project
- [ ] Correctly displays which components use which
- [ ] "You Are Here" correctly highlights current component
- [ ] Click navigation works
- [ ] Breadcrumb trail is accurate
- [ ] Renders reasonably fast (< 1s) for projects with 50+ components
- [ ] Layout is readable (no major overlaps)

---

## Future Enhancements

- **Expand/collapse** - Click to expand a component and show its internal node summary
- **Filter** - Show only pages, only shared, only orphans
- **Search** - Find and highlight a component by name
- **Minimap** - Small overview when zoomed in
- **Export** - Export as PNG/SVG for documentation

---

## Risks & Mitigations

| Risk                                 | Mitigation                                |
| ------------------------------------ | ----------------------------------------- |
| Large projects (100+ components)     | Virtual rendering, progressive loading    |
| Complex nesting causes layout issues | Test with deeply nested projects early    |
| Dagre.js performance                 | Consider WebWorker for layout calculation |

---

## Dependencies

- VIEW-000 Foundation (for `buildComponentDependencyGraph`)
- Dagre.js (layout library)

## Blocks

- None (independent view)