Egonex Layer Visualization Architecture: How the API, Service, Data, UI, and Utility Layers Work Together

The Egonex layer visualization architecture consists of five specialized layers—API, Service, Data, UI, and Utility—that transform static code analysis into an interactive knowledge graph using React, Zustand, and Web Workers.

The Egonex-AI/Understand-Anything repository implements a modular visualization system that treats codebases as explorable knowledge graphs. This architecture separates concerns across five distinct layers, enabling the dashboard to render complex layer-by-layer navigation while maintaining performance through Web Workers and optimized data structures.

Data Layer: Core Types and the Knowledge Graph

The Data layer defines the canonical model for the entire visualization pipeline. In understand-anything-plugin/packages/core/src/types.ts, the Layer interface serves as the fundamental grouping mechanism:

export interface Layer {
  id: string;
  name: string;
  description: string;
  nodeIds: string[];
}

A Layer represents a logical grouping of node IDs (files, functions, classes), while the full KnowledgeGraph (containing nodes, edges, layers, and tour data) is constructed by the back-end analysis pipeline. This static data ultimately persists as knowledge-graph.json in the dashboard's public folder, creating a portable, schema-validated source of truth that the API layer serves to the frontend.

API Layer: Serving the Knowledge Graph

The API layer handles HTTP access control and data delivery. It serves the generated knowledge-graph.json over HTTP while enforcing security through a token-based allow-list mechanism. The API endpoint makes the graph available to the React application at runtime, validating the schema against the TypeScript definitions exported from the core package. This layer ensures that only authorized requests can access the serialized graph data, protecting the analyzed codebase structure.

Service Layer: Vite Dev Server and Bootstrap

The Service layer orchestrates the runtime environment through the Vite development server configured in understand-anything-plugin/packages/dashboard/vite.config.ts. This layer performs two critical functions:

1. Static Hosting: Serves the dashboard assets and the knowledge-graph.json file
2. Worker Initialization: Bootstraps the Web Worker that performs heavy layout calculations off the main thread

The service layer bridges the static build artifacts with the dynamic runtime requirements, ensuring the ELK layout engine and other compute-intensive utilities run without blocking the UI thread.

UI Layer: React, React Flow, and Zustand

The UI layer implements a three-level navigation system using React, TypeScript, React Flow, and Zustand for state management. The global store in understand-anything-plugin/packages/dashboard/src/store.ts maintains the graph state, derived indices (nodesById, layerIndexMap), and navigation level (overview, layer-detail, or node-detail).

Key components include:

• GraphView.tsx: Orchestrates the React Flow canvas, handling cluster creation and edge aggregation
• LayerClusterNode.tsx: Renders layers as visual clusters in overview mode
• LayerLegend.tsx: Displays the color palette and layer selection controls
• PortalNode.tsx: Creates gateway nodes linking to external layers
• FilterPanel.tsx: Manages layer visibility through the filters.layerIds store property

The UI consumes the graph from the Zustand store, applies user filters, and drives navigation through the global state, ensuring synchronized updates across all components.

Utility Layer: Statistics and Layout Computation

The Utility layer provides the computational heavy lifting for visualization logic. Located in understand-anything-plugin/packages/dashboard/src/utils/, this layer contains optimized algorithms for rendering performance.

Layer Statistics

The layerStats.ts module exports computeLayerStats(layer, nodesById), which iterates only the node IDs belonging to a specific layer (layer.nodeIds) to calculate:

• aggregateComplexity – Sum of node complexities
• fileCount, functionCount – Node type tallies
• getLayerColor – Deterministic color assignment for visual consistency

This O(K) per-layer algorithm replaces previous O(N) filtering approaches, dramatically improving performance on large codebases.

Layout Engines

The utility layer manages two layout strategies:

1. ELK Layout: layout.worker.ts runs the Eclipse Layout Kernel in a Web Worker to compute container layouts for clusters and portals, returning async positions after approximately 125ms for medium-sized layers
2. Louvain Community Detection: louvain.ts implements community detection algorithms to assign deterministic colors and group nodes for visual stability

End-to-End Data Flow

The complete data flow through the Egonex layer visualization architecture follows this sequence:

1. Static Analysis: The back-end pipeline scans the target repository and builds a KnowledgeGraph with populated Layer objects
2. Data Persistence: The graph serializes to knowledge-graph.json and copies into the dashboard's public/ folder
3. API Delivery: The service layer serves the JSON via HTTP, validated by the API token middleware
4. State Hydration: The UI fetches the graph and stores it in the Zustand store (store.ts), extracting layers, nodes, and edges
5. Statistical Computation: When a user selects a layer, the utility layer calculates statistics via computeLayerStats
6. Layout Calculation: The UI requests positions from layout.worker.ts, which runs ELK algorithms in a Web Worker
7. Rendering: React Flow receives the positioned nodes and renders either the overview (layers as clusters) or layer-detail view (expanded nodes with portal connections)

Summary

• The Data layer in core/src/types.ts defines the Layer interface and KnowledgeGraph schema that structures the entire visualization
• The API layer serves knowledge-graph.json with token-based access control from the dashboard's public folder
• The Service layer uses Vite to host the application and initialize the layout Web Worker
• The UI layer combines React Flow, Zustand, and specialized components like GraphView.tsx to render three navigation levels
• The Utility layer optimizes performance through layerStats.ts (O(K) statistics) and layout.worker.ts (async ELK layout), with louvain.ts providing community detection for stable coloring

Frequently Asked Questions

How does the Egonex layer visualization handle large codebases without blocking the UI?

The architecture offloads heavy computation to a Web Worker via layout.worker.ts, which runs the ELK layout algorithm asynchronously. Additionally, the utility layer uses optimized O(K) algorithms in layerStats.ts that iterate only relevant node IDs rather than the entire graph, ensuring the main thread remains responsive during interactions.

What determines the colors assigned to each layer in the visualization?

Layer colors are generated deterministically by the getLayerColor function in layerStats.ts, which uses the Louvain community detection algorithm implemented in louvain.ts. This ensures visual stability across sessions and consistent coloring for logical layer groupings.

Where is the layer data stored and how does the UI access it?

Layer definitions reside in the central KnowledgeGraph type defined in core/src/types.ts. The UI accesses this data through a Zustand global store (store.ts) that maintains nodesById and layerIndexMap derived indices, allowing components like LayerClusterNode.tsx and FilterPanel.tsx to read layer information without prop drilling.

Can the layout algorithm be replaced without modifying the UI components?

Yes, the architecture decouples layout logic from rendering. The layout.worker.ts module abstracts the ELK implementation, exposing a generic requestLayout interface. You could replace ELK with a different layout engine in the worker file without changing GraphView.tsx or other UI components, as long as the returned position format remains compatible.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}