Understand Anything Knowledge Graph Schema: Complete Guide to Node and Edge Types

The Understand Anything knowledge graph schema defines 21 distinct node types and 35 edge types organized into 9 functional categories, all enforced through Zod schemas in packages/core/src/schema.ts.

The Egonex-AI/Understand-Anything repository implements a strict, type-safe knowledge graph schema that powers its AI-driven code understanding engine. This schema standardizes how software artifacts, infrastructure components, and business concepts interconnect within a unified graph structure. All type definitions reside in the core package and are validated using Zod to ensure data integrity across the entire platform.

Node Types in the Understand Anything Schema

The GraphNodeSchema.type field (lines 69–76 of packages/core/src/schema.ts) enumerates the canonical node categories. These nodes represent entities ranging from source code files to abstract business concepts.

Core Software Artifacts

These node types model traditional codebases and programming constructs:

• file – A source-code file within the repository
• function – A function or method definition
• class – A class or interface declaration
• module – A package or module boundary

Infrastructure and Data Components

These nodes capture deployment artifacts, data stores, and configuration:

• service – Deployable units such as containers or pods
• table – Database tables and persistent storage structures
• endpoint – API routes, GraphQL queries, or mutations
• pipeline – CI/CD workflows or data processing jobs
• schema – Data schemas including Protobuf, JSON Schema, or OpenAPI definitions
• resource – Cloud infrastructure resources managed by Terraform or similar tools
• config – Configuration values and environment settings

Business and Knowledge Concepts

These types bridge technical implementation with domain knowledge:

• concept – Abstract ideas or patterns
• domain – Business domain boundaries
• flow – Business process flows
• step – Individual steps within a business flow
• article – Knowledge base articles and documentation
• entity – Real-world entities such as persons or organizations
• topic – Subject tags or categorical labels
• claim – Assertions, decisions, or hypotheses
• source – External references to papers, links, or citations
• document – Documentation files such as READMEs

Edge Types and Relationship Categories

The EdgeTypeSchema (lines 4–14 of packages/core/src/schema.ts) defines 35 edge verbs that describe relationships between nodes. The engine groups these into functional categories to distinguish structural, behavioral, and semantic connections.

Structural Relationships

These edges define code hierarchy and composition:

• contains – Parent-child containment (e.g., a file contains functions)
• imports and exports – Module dependency relationships
• inherits – Class inheritance hierarchies
• implements – Interface implementation

Behavioral and Data Flow Connections

These edges capture runtime interactions and data movement:

• calls – Function-to-function invocation
• subscribes and publishes – Event-driven relationships
• middleware – Middleware chain connections
• reads_from and writes_to – Data access patterns
• transforms and validates – Data processing pipelines

Infrastructure and Domain Mapping

These edges connect technical implementation to deployment and business context:

• depends_on, tested_by, configures – Dependency and testing relationships
• deploys, serves, provisions, triggers – Infrastructure lifecycle events
• migrates, documents, routes, defines_schema – Schema evolution and documentation
• contains_flow, flow_step, cross_domain – Business process modeling
• related, similar_to – Semantic similarity links
• cites, contradicts, builds_on, exemplifies, categorized_under, authored_by – Knowledge graph citations and authorship

Working with the Schema in Code

The @understand-anything/core package exports GraphNodeSchema and GraphEdgeSchema for runtime validation and TypeScript type inference.

import { GraphNodeSchema, GraphEdgeSchema } from '@understand-anything/core';

// Create a validated function node
const fnNode = GraphNodeSchema.parse({
  id: 'node-123',
  type: 'function',
  name: 'calculateSum',
  filePath: 'src/math.ts',
  summary: 'Adds two numbers',
  tags: ['math', 'utility'],
  complexity: 'simple',
});

// Create an edge representing a function call
const callEdge = GraphEdgeSchema.parse({
  source: 'node-123',
  target: 'node-456',
  type: 'calls',
  direction: 'forward',
  weight: 0.8,
});

The engine automatically normalizes common aliases to canonical values. For example, type: 'func' normalizes to 'function', and type: 'invoke' normalizes to 'calls'.

import { normalizeGraph, validateGraph } from '@understand-anything/core';

const raw = {
  nodes: [{ id: 'n1', type: 'func', name: 'doWork', summary: '', tags: [], complexity: 'easy' }],
  edges: [{ source: 'n1', target: 'n2', type: 'invoke', direction: 'to', weight: 1 }],
};

const { data, issues } = validateGraph(normalizeGraph(raw));
// Normalized: type becomes 'function', edge type becomes 'calls', direction becomes 'forward'

Validation and Normalization

The schema enforcement layer resides in packages/core/src/schema.ts alongside packages/core/src/types.ts, which exports TypeScript interfaces derived from the Zod schemas. The normalizeGraph function sanitizes input data by mapping legacy or shorthand aliases to the strict enum values defined in the schema. This ensures that all graph data conforms to the 21 node types and 35 edge types before the validation engine processes relationships.

Summary

• The Understand Anything knowledge graph schema strictly defines 21 node types spanning code, infrastructure, and business domains in packages/core/src/schema.ts.
• 35 edge types categorize relationships into structural, behavioral, data flow, and semantic groups.
• The Zod-based validation system enforces schema compliance and automatically normalizes aliases like func to function or invoke to calls.
• Type definitions are exported from packages/core/src/types.ts for consumption across the plugin ecosystem.

Frequently Asked Questions

What file contains the knowledge graph schema definitions?

The canonical schema definitions reside in packages/core/src/schema.ts within the understand-anything-plugin package. This file exports GraphNodeSchema, EdgeTypeSchema, and related Zod validators that enforce the 21 node types and 35 edge types.

How many node and edge types does the schema support?

The schema defines 21 distinct node types ranging from file and function to concept and claim, plus 35 edge types organized into 9 functional categories including structural, behavioral, and knowledge relationships.

Can I use custom node types beyond the defined enums?

No, the schema uses strict Zod enums that reject unknown types during validation. However, the normalization layer in normalizeGraph maps common aliases (like func to function) to the canonical enums, allowing flexibility in input while maintaining strict type safety in the graph.

How does the schema handle edge directionality?

The GraphEdgeSchema includes a direction field that accepts 'forward' or 'backward' values. During normalization, directional aliases like 'to' are automatically mapped to 'forward', ensuring consistent traversal semantics across the knowledge graph.

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