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

> Discover the Egonex layer visualization architecture. Learn how API, Service, Data, UI, and Utility layers collaborate to create interactive knowledge graphs from code analysis using React and Web Workers.

- Repository: [Egonex/Understand-Anything](https://github.com/Egonex-AI/Understand-Anything)
- Tags: architecture
- Published: 2026-06-21

---

**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`](https://github.com/Egonex-AI/Understand-Anything/blob/main/understand-anything-plugin/packages/core/src/types.ts), the `Layer` interface serves as the fundamental grouping mechanism:

```typescript
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`](https://github.com/Egonex-AI/Understand-Anything/blob/main/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`](https://github.com/Egonex-AI/Understand-Anything/blob/main/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`](https://github.com/Egonex-AI/Understand-Anything/blob/main/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`](https://github.com/Egonex-AI/Understand-Anything/blob/main/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`](https://github.com/Egonex-AI/Understand-Anything/blob/main/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`](https://github.com/Egonex-AI/Understand-Anything/blob/main/GraphView.tsx)**: Orchestrates the React Flow canvas, handling cluster creation and edge aggregation
- **[`LayerClusterNode.tsx`](https://github.com/Egonex-AI/Understand-Anything/blob/main/LayerClusterNode.tsx)**: Renders layers as visual clusters in overview mode
- **[`LayerLegend.tsx`](https://github.com/Egonex-AI/Understand-Anything/blob/main/LayerLegend.tsx)**: Displays the color palette and layer selection controls
- **[`PortalNode.tsx`](https://github.com/Egonex-AI/Understand-Anything/blob/main/PortalNode.tsx)**: Creates gateway nodes linking to external layers
- **[`FilterPanel.tsx`](https://github.com/Egonex-AI/Understand-Anything/blob/main/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`](https://github.com/Egonex-AI/Understand-Anything/blob/main/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`](https://github.com/Egonex-AI/Understand-Anything/blob/main/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`](https://github.com/Egonex-AI/Understand-Anything/blob/main/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`](https://github.com/Egonex-AI/Understand-Anything/blob/main/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`](https://github.com/Egonex-AI/Understand-Anything/blob/main/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`](https://github.com/Egonex-AI/Understand-Anything/blob/main/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`](https://github.com/Egonex-AI/Understand-Anything/blob/main/core/src/types.ts) defines the `Layer` interface and `KnowledgeGraph` schema that structures the entire visualization
- The **API layer** serves [`knowledge-graph.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/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`](https://github.com/Egonex-AI/Understand-Anything/blob/main/GraphView.tsx) to render three navigation levels
- The **Utility layer** optimizes performance through [`layerStats.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/layerStats.ts) (O(K) statistics) and [`layout.worker.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/layout.worker.ts) (async ELK layout), with [`louvain.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/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`](https://github.com/Egonex-AI/Understand-Anything/blob/main/layout.worker.ts), which runs the ELK layout algorithm asynchronously. Additionally, the utility layer uses optimized O(K) algorithms in [`layerStats.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/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`](https://github.com/Egonex-AI/Understand-Anything/blob/main/layerStats.ts), which uses the Louvain community detection algorithm implemented in [`louvain.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/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`](https://github.com/Egonex-AI/Understand-Anything/blob/main/core/src/types.ts). The UI accesses this data through a Zustand global store ([`store.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/store.ts)) that maintains `nodesById` and `layerIndexMap` derived indices, allowing components like [`LayerClusterNode.tsx`](https://github.com/Egonex-AI/Understand-Anything/blob/main/LayerClusterNode.tsx) and [`FilterPanel.tsx`](https://github.com/Egonex-AI/Understand-Anything/blob/main/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`](https://github.com/Egonex-AI/Understand-Anything/blob/main/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`](https://github.com/Egonex-AI/Understand-Anything/blob/main/GraphView.tsx) or other UI components, as long as the returned position format remains compatible.