# How Nodes, Edges, Layers, and Tours Work in Egonex-AI Understand-Anything

> Understand how nodes, edges, layers, and tours work together in Egonex-AI Understand Anything. Explore code entities, relationships, groupings, and guided navigation for deeper insights.

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

---

**In Egonex-AI Understand-Anything, nodes represent atomic code entities, edges define directed relationships between them, layers provide logical groupings of node IDs, and tours offer ordered sequences of node IDs to guide users through the codebase.**

The Egonex-AI Understand-Anything engine transforms complex codebases into navigable knowledge graphs using four fundamental abstractions defined in [`packages/core/src/types.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/packages/core/src/types.ts). These components work together to create a rich, queryable representation of your software architecture that powers both the CLI and dashboard experiences.

## Core Knowledge Graph Components

### GraphNode: The Atomic Entities

**GraphNode** instances are the discrete vertices of the knowledge graph. According to the source code in [[`packages/core/src/types.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/packages/core/src/types.ts)](https://github.com/Egonex-AI/Understand-Anything/blob/main/understand-anything-plugin/packages/core/src/types.ts#L38-L50), each node carries an `id`, `type`, `name`, optional `filePath`, `lineRange`, a summary, tags, complexity metrics, and optional metadata fields (`domainMeta`, `knowledgeMeta`).

Nodes represent concrete elements such as files, functions, classes, configurations, or knowledge artifacts. They serve as the foundation upon which all other relationships are built—edges always point **from a source node to a target node**, layers reference node IDs, and tour steps highlight specific node collections.

### GraphEdge: Directed Relationships

**GraphEdge** objects define typed, directed connections between nodes. As implemented in [`packages/core/src/types.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/packages/core/src/types.ts) (lines 53-60), each edge specifies a `source` node ID, `target` node ID, relationship `type`, and `direction` (`forward`, `backward`, or `bidirectional`).

Edge types include structural relationships (`imports`, `contains`), behavioral links (`calls`, `publishes`), and categories covering data-flow, dependencies, semantics, infrastructure, schema, domain, and knowledge classifications. The dashboard uses the direction field to render arrows correctly, while layers and tours do **not** embed edges directly—instead, the UI filters edges incident on nodes belonging to the current layer or active tour step.

### Layer: Logical Node Groupings

**Layer** objects provide static, named buckets for organizing nodes into logical views such as "frontend," "authentication," or "data-pipeline." The type definition in [`packages/core/src/types.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/packages/core/src/types.ts) (lines 63-68) establishes that each layer stores an `id`, `name`, description, and an array of `nodeIds: string[]`.

Layers function as filters rather than containers. When a user selects a layer in the dashboard, the UI highlights only the nodes listed in that layer's `nodeIds` array. The store logic automatically handles layer switching when a tour step crosses layer boundaries, ensuring the context remains visible as users navigate through different subsystems.

### TourStep: Guided Walkthrough Sequences

**TourStep** instances create ordered learning paths through the graph. Defined in [`packages/core/src/types.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/packages/core/src/types.ts) (lines 71-78), each step contains an `order` index, `title`, `description`, a list of `nodeIds` to highlight, and an optional language lesson.

Tours are sequences of steps that reference node IDs without embedding edges. When a step becomes active, the dashboard renders the step's nodes and their incident edges to provide context. The tour drives the **layer navigation** logic in [`packages/dashboard/src/store.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/packages/dashboard/src/store.ts), automatically switching the visible layer when the highlighted nodes belong to a different logical grouping.

## How the Components Connect in Code

### Graph Construction in graph-builder.ts

The [`graph-builder.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/graph-builder.ts) module coordinates the assembly of these four concepts. During analysis, the builder walks the project to create `GraphNode` instances for every discoverable entity, generates `GraphEdge` instances for imports and calls, groups nodes into `Layer` objects using directory structure heuristics, and optionally produces a `TourStep` array.

```typescript
// Simplified excerpt from packages/core/src/analyzer/graph-builder.ts
const nodes: GraphNode[] = [...];
const edges: GraphEdge[] = [...];
const layers: Layer[] = computeLayers(nodes);
const tour: TourStep[] = generateHeuristicTour({ nodes, edges, layers });
const graph: KnowledgeGraph = { version, project, nodes, edges, layers, tour };

```

See the full implementation at [[`packages/core/src/analyzer/graph-builder.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/packages/core/src/analyzer/graph-builder.ts)](https://github.com/Egonex-AI/Understand-Anything/blob/main/understand-anything-plugin/packages/core/src/analyzer/graph-builder.ts#L334).

### Tour Generation in tour-generator.ts

The [[`packages/core/src/analyzer/tour-generator.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/packages/core/src/analyzer/tour-generator.ts)](https://github.com/Egonex-AI/Understand-Anything/blob/main/understand-anything-plugin/packages/core/src/analyzer/tour-generator.ts) module produces the ordered sequence of steps using either LLM-based analysis or topological heuristics (e.g., central nodes, layer transitions).

```typescript
const tour = generateHeuristicTour(sampleGraph);

```

This generation process identifies important pathway nodes and creates `TourStep` objects that guide newcomers through the architecture in a logical order.

### UI State Management in store.ts

The dashboard store in [[`packages/dashboard/src/store.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/packages/dashboard/src/store.ts)](https://github.com/Egonex-AI/Understand-Anything/blob/main/understand-anything-plugin/packages/dashboard/src/store.ts) manages the runtime relationship between these concepts. It extracts the tour from the loaded graph, sorts steps by the `order` field, and maintains UI state including `tourActive`, `tourHighlightedNodeIds`, and `tourFitPending`.

```typescript
const tour = graph.tour ?? [];
const sorted = [...tour].sort((a, b) => a.order - b.order);
set({ tourActive: true, tourHighlightedNodeIds: sorted[0].nodeIds });

```

When a step activates, the store populates `tourHighlightedNodeIds` with the step's node IDs, causing the graph view to focus on those nodes and their incident edges.

## Practical Code Examples

Creating nodes and edges in Egonex-AI starts with the core types:

```typescript
// Defining a file node and a contained function
const nodeA: GraphNode = {
  id: "file:src/app.ts",
  type: "file",
  name: "app.ts",
  filePath: "src/app.ts",
  summary: "Entry point of the application",
  tags: ["entry"],
  complexity: "moderate",
};

const nodeB: GraphNode = {
  id: "function:main",
  type: "function",
  name: "main",
  filePath: "src/app.ts",
  lineRange: [10, 22],
  summary: "Bootstraps the server",
  tags: [],
  complexity: "simple",
};

// Creating a "contains" relationship
const edge: GraphEdge = {
  source: nodeA.id,
  target: nodeB.id,
  type: "contains",
  direction: "forward",
  weight: 0.9,
};

```

Group these nodes into a logical layer:

```typescript
const layer: Layer = {
  id: "layer:app",
  name: "Application Core",
  description: "Core entry files and functions",
  nodeIds: [nodeA.id, nodeB.id],
};

```

Define a guided tour step that highlights these nodes:

```typescript
const step: TourStep = {
  order: 1,
  title: "Start the app",
  description: "Understand the entry point and its main function",
  nodeIds: [nodeA.id, nodeB.id],
};

```

Assemble the complete knowledge graph:

```typescript
const graph: KnowledgeGraph = {
  version: "1.0",
  project: { 
    name: "Demo", 
    languages: ["ts"], 
    frameworks: [], 
    description: "", 
    analyzedAt: new Date().toISOString(), 
    gitCommitHash: "abc123" 
  },
  nodes: [nodeA, nodeB],
  edges: [edge],
  layers: [layer],
  tour: [step],
};

```

## Summary

- **Nodes** are the fundamental entities in the Egonex-AI graph, representing files, functions, classes, and other code elements with rich metadata.
- **Edges** connect nodes via typed, directional relationships and are filtered by the UI based on the currently active nodes, rather than being embedded within layers or tours.
- **Layers** provide static, named groupings of node IDs that function as view filters, allowing users to focus on specific subsystems like "frontend" or "authentication."
- **Tours** are ordered sequences of steps that reference node IDs, driving both the highlighting of specific nodes and automatic layer switching in the dashboard UI.
- The system coordinates these components through [`graph-builder.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/graph-builder.ts) (construction), [`tour-generator.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/tour-generator.ts) (sequencing), and [`store.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/store.ts) (runtime UI state).

## Frequently Asked Questions

### Can edges belong to multiple layers in Egonex-AI?

Edges do not belong to layers directly. Instead, the dashboard filters and displays edges that are **incident on** the nodes belonging to the currently selected layer or active tour step. This means an edge between two nodes will appear whenever either endpoint is visible, regardless of which layer is active.

### How does a tour step trigger layer switching in the dashboard?

When a tour step becomes active, the dashboard store ([`packages/dashboard/src/store.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/packages/dashboard/src/store.ts)) checks if the step's `nodeIds` belong to a different layer than the one currently visible. If the highlighted nodes reside in a layer defined in the graph's `layers` array, the UI automatically switches the visible layer to maintain context, ensuring users see the appropriate subsystem when following the guided walkthrough.

### What is the difference between the `direction` and `type` fields in GraphEdge?

The `type` field categorizes the semantic relationship (e.g., `imports`, `calls`, `contains`), while the `direction` field (`forward`, `backward`, or `bidirectional`) controls how the dashboard renders the visual arrow. The direction indicates the flow of the relationship—forward means from source to target—allowing the UI to draw directional graphs correctly even when traversing relationships programmatically.

### Where does the CLI output render the tour information?

The [`onboard-builder.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/onboard-builder.ts) module formats the textual onboarding guide by extracting the `tour` array from the `KnowledgeGraph` object. It iterates through the tour steps and emits a step-by-step list for CLI output, pulling titles and descriptions from each `TourStep` to create the guided learning experience in terminal environments.