turash/bugulma/GRAPH_VISUALIZATION_POC.md

# Graph Visualization Proof of Concept

## Overview

Interactive network graph visualization integrated into the Organization detail pages, demonstrating how organizations connect to sites, resources, and other organizations through the Neo4j graph database.

## Implementation

### Backend API Endpoints

**Base URL:** `/api/graph`

1. **GET /organizations/:organizationId/network**
   - Returns graph data for an organization's network
   - Query params: `depth` (1-3, default: 2)
   - Response format:

   ```json
   {
     "nodes": [
       {
         "id": "uuid",
         "label": "Organization Name",
         "type": "organization|site|resource_flow",
         "properties": {}
       }
     ],
     "edges": [
       {
         "id": "uuid",
         "source": "node_id",
         "target": "node_id",
         "type": "OWNS|PROVIDES|CONSUMES|CONNECTED_TO",
         "properties": {}
       }
     ]
   }
   ```

2. **GET /shortest-path**
   - Find shortest path between two entities
   - Query params: `from`, `to`

3. **GET /matching-opportunities**
   - Find resource matching opportunities
   - Query params: `organizationId`

4. **GET /spatial-proximity**
   - Find spatially nearby entities
   - Query params: `organizationId`, `maxDistance`

5. **GET /statistics**
   - Graph-wide statistics and metrics

### Frontend Component

**Location:** `components/organization/NetworkGraph.tsx`

**Features:**

- Interactive graph visualization using vis-network
- 3-level depth control (1, 2, or 3 degrees of separation)
- Click nodes to navigate to organization/site pages
- Physics-based layout with automatic positioning
- Color-coded nodes by type:
  - Organizations: Blue (circle)
  - Sites: Green (box)
  - Resource Flows: Orange (diamond)
- Interactive controls: zoom, pan, drag nodes
- Hover tooltips showing entity details

**Integration:**
Added to `OrganizationContent.tsx` between the organization details grid and resource flow list.

### Dependencies Added

```bash
npm install vis-network vis-data
```

## Usage

### View Organization Network

1. Navigate to any organization detail page: `/organizations/:id`
2. Scroll to the "Network Graph" section
3. Use depth buttons (1, 2, 3) to expand/contract the network
4. Click nodes to navigate to that entity's page
5. Use mouse to pan/zoom and drag nodes

### API Testing

```bash
# Get organization network
curl http://localhost:8080/api/graph/organizations/{id}/network?depth=2

# Find shortest path
curl http://localhost:8080/api/graph/shortest-path?from={id1}&to={id2}

# Get matching opportunities
curl http://localhost:8080/api/graph/matching-opportunities?organizationId={id}
```

## Technical Details

### Graph Data Conversion

The `PathToGraphData()` function in `internal/handler/graph_types.go` converts Neo4j path results into visualization-friendly JSON format:

1. Extracts nodes and relationships from Neo4j paths
2. Deduplicates nodes by ID
3. Converts to standardized format with:
   - Node IDs, labels, types, properties
   - Edge IDs, source/target, relationship types
   - Type-based styling information

### Visualization Options

The vis-network is configured with:

- **Physics Engine:** Barnes-Hut simulation for natural positioning
- **Stabilization:** 100 iterations for initial layout
- **Interaction:** Hover tooltips, click handlers, navigation buttons
- **Styling:** Custom colors/shapes by entity type
- **Smooth Edges:** Continuous curves with 0.5 roundness

## Future Enhancements

### Filtering & Controls

- Filter by relationship type
- Filter by entity type
- Search/highlight specific nodes
- Save/load custom layouts

### Export Options

- Export as PNG/SVG
- Export raw JSON data
- Share graph views

### Advanced Features

- Time-based animation of resource flows
- Highlight critical paths
- Show impact metrics on edges
- Clustering of similar entities
- 3D visualization mode

### Performance

- Implement pagination for large networks (>1000 nodes)
- Add caching for frequently accessed graphs
- Lazy loading of node details
- WebGL rendering for very large graphs

## Validation Checklist

- [x] Backend graph endpoints implemented
- [x] Graph handler returns standardized JSON format
- [x] Endpoints registered in main.go
- [x] NetworkGraph component created
- [x] vis-network dependency installed
- [x] Component integrated into OrganizationPage
- [x] Click handlers for navigation
- [x] Depth control (1, 2, 3 levels)
- [x] Error handling and loading states
- [x] Type-safe TypeScript implementation
- [ ] End-to-end testing with real Neo4j data
- [ ] Performance testing with large graphs
- [ ] Mobile responsiveness

## Next Steps

1. **Test with Real Data:** Populate Neo4j with actual organization/site relationships and verify graph rendering
2. **Backend Server Running:** Ensure Go server is running on port 8080
3. **Frontend Dev Server:** Run `npm run dev` in bugulma/frontend
4. **Navigate:** Go to <http://localhost:5173/organizations/{id}> to see the graph
5. **Verify API:** Check browser DevTools Network tab for `/api/graph/` calls

## Related Files

**Backend:**

- `internal/handler/graph_handler.go` - HTTP handlers
- `internal/handler/graph_types.go` - Type definitions and conversion
- `internal/service/graph_service.go` - Neo4j queries
- `cmd/server/main.go` - Route registration

**Frontend:**

- `components/organization/NetworkGraph.tsx` - Graph component
- `components/organization/OrganizationContent.tsx` - Integration point
- `package.json` - Dependencies

**Documentation:**

- `concept/23_example_query_in_cypher_neo4j.md` - Neo4j query examples
- `concept/09_graph_database_design.md` - Graph schema