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

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. 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/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 (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 (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 (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, 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 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.

// 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/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/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).

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/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.

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:

// 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:

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:

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:

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 (construction), tour-generator.ts (sequencing), and 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) 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 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.

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