# How Egonex-AI Defines Nodes and Edges in Its Knowledge Graph Schema for Code Entities

> Discover how Egonex-AI defines nodes and edges in its knowledge graph for code entities. Understand typed code entities, UUIDs, metadata, and directed relationships in TypeScript.

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

---

**Egonex-AI's Understand-Anything project defines nodes as typed code entities with UUIDs and metadata, and edges as directed relationships between them, both declared in TypeScript interfaces in [`packages/core/src/types.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/packages/core/src/types.ts).**

The Egonex-AI Understand-Anything repository transforms raw source code into a queryable structure governed by a **knowledge graph schema for code entities**. This schema, defined in TypeScript within the [`packages/core/src/types.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/packages/core/src/types.ts) module, strictly types both nodes and edges to enable accurate cross-language code analysis. The following sections dissect the exact interface definitions and architectural patterns that convert software syntax into traversable graph relationships.

## Node Structure in the Knowledge Graph Schema

Nodes represent discrete code entities such as files, classes, functions, and variables. 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), each node implements a mandatory set of properties that ensure unique identification and traceability back to specific source locations.

### Core Node Properties

The `Node` interface requires the following fields:

- **`id`**: A globally unique UUID assigned to every entity
- **`type`**: The high-level category (e.g., `file`, `class`, `function`, `variable`, `test`)
- **`name`**: The human-readable identifier of the entity
- **`path`**: Relative filesystem path to the source file
- **`range`**: An object containing `start` and `end` line numbers locating the entity
- **`language`**: Programming language identifier (e.g., `typescript`, `python`, `go`)
- **`metadata`**: Optional JSON blob for language-specific details like signatures or docstrings
- **`tags`**: Optional array of strings for filtering (e.g., `public`, `private`, `test`)

```typescript
export interface Node {
  id: string;
  type: string;
  name: string;
  path: string;
  range: { start: number; end: number };
  language: string;
  metadata?: Record<string, unknown>;
  tags?: string[];
}

```

## Edge Structure and Relationship Types

Edges capture directional relationships between nodes, such as function calls, imports, inheritance, or containment. The `Edge` interface, defined alongside `Node` in [`packages/core/src/types.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/packages/core/src/types.ts), establishes the connection semantics using source and target UUID references.

### Edge Interface Definition

Each edge connects exactly two nodes through these properties:

- **`source`**: UUID of the origin node where the relationship originates
- **`target`**: UUID of the destination node where the relationship points
- **`type`**: Relationship category (e.g., `call`, `import`, `inheritance`, `containment`)
- **`label`**: Optional human-readable description for visualization
- **`metadata`**: Optional JSON object for additional context like call-site line numbers

```typescript
export interface Edge {
  source: string;
  target: string;
  type: string;
  label?: string;
  metadata?: Record<string, unknown>;
}

```

## How the Schema Powers Code Analysis

The static type definitions drive a multi-stage pipeline that converts abstract syntax tree (AST) fragments into a persistent, queryable knowledge graph.

### Entity Extraction via Tree-Sitter

The [`packages/core/src/plugins/tree-sitter-plugin.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/packages/core/src/plugins/tree-sitter-plugin.ts) implements language-specific AST walkers. These parsers traverse source files and instantiate `Node` objects for each discovered entity, populating the `range` and `language` fields based on concrete syntax tree positions.

### Graph Construction and Edge Resolution

After node collection, the [`packages/core/src/analyzer/graph-builder.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/packages/core/src/analyzer/graph-builder.ts) performs semantic analysis to create `Edge` instances. It identifies relationships through static analysis of imports, class inheritance chains, and function call graphs, mapping each relationship to the canonical `source` and `target` UUIDs defined in the schema.

### Persistence and Indexing

The assembled graph serializes to [`.understand-anything/knowledge-graph.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/.understand-anything/knowledge-graph.json). The [`packages/core/src/search.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/packages/core/src/search.ts) module indexes node metadata to enable full-text queries against the code graph, while [`packages/dashboard/src/utils/edgeAggregation.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/packages/dashboard/src/utils/edgeAggregation.ts) handles client-side merging of duplicate edges for visual clarity.

## Practical Code Examples

### Creating a Node Programmatically

```typescript
import { Node } from '@understand-anything/core';

const fnNode: Node = {
  id: 'node-12345',
  type: 'function',
  name: 'calculateTotal',
  path: 'src/utils/math.ts',
  range: { start: 42, end: 58 },
  language: 'typescript',
  metadata: { signature: '(prices: number[]) => number' },
  tags: ['public']
};

```

### Defining a Relationship Edge

```typescript
import { Edge } from '@understand-anything/core';

const callEdge: Edge = {
  source: 'node-12345',      // calculateTotal
  target: 'node-67890',      // sumArray
  type: 'call',
  label: 'calls',
  metadata: { line: 45 }     // line where call occurs
};

```

### Persisting the Knowledge Graph

```typescript
import { writeFile } from 'fs/promises';
import { Graph } from '@understand-anything/core';

const graph: Graph = {
  nodes: [fnNode, otherNode],
  edges: [callEdge, importEdge]
};

await writeFile('.understand-anything/knowledge-graph.json', JSON.stringify(graph, null, 2));

```

### Querying the Graph

```typescript
import { search } from '@understand-anything/core/search';

const results = await search('function:calculateTotal', { limit: 10 });
console.log(results); // Array of matching Node objects

```

## Key Implementation Files

These source files define and utilize the knowledge graph schema:

- **[`packages/core/src/types.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/packages/core/src/types.ts)**: Central TypeScript definitions for `Node` and `Edge` interfaces
- **[`packages/core/src/analyzer/graph-builder.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/packages/core/src/analyzer/graph-builder.ts)**: Logic that assembles nodes and derives edges from semantic analysis
- **[`packages/core/src/plugins/tree-sitter-plugin.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/packages/core/src/plugins/tree-sitter-plugin.ts)**: AST walker that extracts entities from source files and creates `Node` instances
- **[`packages/core/src/search.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/packages/core/src/search.ts)**: Full-text search engine that indexes node metadata for fast lookups
- **[`packages/dashboard/src/utils/edgeAggregation.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/packages/dashboard/src/utils/edgeAggregation.ts)**: Client-side utility for merging duplicate edges in visualizations

## Summary

- **Nodes** represent code entities with UUID-based identity, typed categorization, and source location tracking via the `Node` interface in [`packages/core/src/types.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/packages/core/src/types.ts)
- **Edges** model directed relationships using `source` and `target` UUID references, with optional labels and metadata for context
- The **Tree-Sitter plugin** handles initial node extraction from language-specific ASTs
- The **graph-builder** resolves semantic relationships to instantiate edges between related entities
- The **search module** indexes the graph for fast code navigation and querying
- Both nodes and edges support extensible **metadata** fields for language-specific details without breaking the core schema

## Frequently Asked Questions

### What identifier format does Egonex-AI use for knowledge graph nodes?

The system assigns each node a globally unique UUID stored in the required `id` field. This immutable identifier ensures stable references across the graph regardless of file renames or code refactoring operations.

### Can the schema handle relationships across different programming languages?

Yes. The `language` property on nodes tags entities by their source language, while edges connect nodes based on semantic relationships like `import` or `call`. The [`packages/core/src/analyzer/graph-builder.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/packages/core/src/analyzer/graph-builder.ts) handles cross-language resolution when analyzing polyglot repositories.

### How does the system distinguish between public and private code entities?

The optional `tags` array on nodes accepts string values like `public` or `private`. These tags filter query results and visualization views without requiring changes to the core TypeScript interfaces.

### Where does Understand-Anything store the constructed knowledge graph?

After analysis, the graph serializes to [`.understand-anything/knowledge-graph.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/.understand-anything/knowledge-graph.json) in the project root. The dashboard and search APIs read from this JSON file to serve the code exploration interface.