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:

   {
     "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

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

# 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

• Backend graph endpoints implemented
• Graph handler returns standardized JSON format
• Endpoints registered in main.go
• NetworkGraph component created
• vis-network dependency installed
• Component integrated into OrganizationPage
• Click handlers for navigation
• Depth control (1, 2, 3 levels)
• Error handling and loading states
• 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