Understand-Anything I³ Graph Schema: The 13 Node Types and 26 Edge Types Explained

The Understand-Anything engine structures codebase knowledge using an I³ graph comprising 13 distinct node types (encompassing code entities, infrastructure, and documentation) and 26 semantic edge types (spanning structural, behavioral, and data-flow relationships), formally defined in packages/core/src/types.ts and validated in packages/core/src/types.test.ts.

The I³ graph serves as the foundational knowledge representation in the Understand-Anything open-source project, mapping complex software systems into a queryable graph database. Every analyzed element becomes a node connected by typed edges that express precise relationships between components. This schema enables the file-analyzer, architecture-analyzer, and dashboard components to interoperate using a shared vocabulary, while packages/core/src/analyzer/graph-builder.ts maps raw analyzer output to these canonical types.

The 13 I³ Node Types

The I³ graph classifies every element into 13 core node types defined in packages/core/src/types.ts at lines 2–7. These divide into code entities and non-code infrastructure components.

Code Entity Nodes

Five node types represent source code structures:

• file: A source file in any programming language.
• function: A function or method definition.
• class: A class or prototype definition.
• module: A module or package grouping, such as a folder or namespace.
• concept: A higher-level abstraction that groups related code entities by domain concept.

Non-Code Entity Nodes

Eight node types capture configuration, infrastructure, and documentation:

• config: Configuration files including JSON, YAML, and environment files.
• document: Documentation files such as README and markdown content.
• service: Deployable services defined in Docker, Kubernetes, or similar platforms.
• table: Database table definitions and schema references.
• endpoint: API endpoint definitions covering REST, GraphQL, and other protocols.
• pipeline: CI/CD or data-pipeline scripts and workflows.
• schema: Data-schema files including SQL DDL, Protobuf, and OpenAPI specifications.
• resource: Cloud or infrastructure resources such as Terraform-managed assets.

The 26 I³ Edge Types

The 26 edge types express relationships between nodes, grouped into six semantic categories. The exhaustive list is asserted in the type test file packages/core/src/types.test.ts at lines 33–41.

Structural Relationships

These edges define code organization and inheritance:

• imports: File A imports symbols from File B.
• exports: File A exports symbols available for import elsewhere.
• contains: A container node (e.g., a class) includes a child node (e.g., a method).
• inherits: Class A inherits from Class B.
• implements: Class A implements Interface B.

Behavioral Relationships

These edges capture runtime interactions:

• calls: Function A invokes Function B.
• subscribes: Component A listens to an event or stream from Component B.
• publishes: Component A emits an event or stream to Component B.
• middleware: Middleware A processes requests between two pipeline steps.

Data-Flow Relationships

These edges track how data moves through the system:

• reads_from: Code A retrieves data from a table, file, or endpoint.
• writes_to: Code A persists data to a table, file, or endpoint.
• transforms: Data converts from one shape or format to another.
• validates: Code A validates data against a defined schema.

Dependency Relationships

These edges express reliance and testing connections:

• depends_on: One component relies on another (e.g., a service requires a database).
• tested_by: A test case validates the behavior of a target node.
• configures: A configuration file specifies settings for a target component.

Semantic Relationships

These edges capture loose associations:

• related: Nodes share the same domain or similar purpose without direct coupling.
• similar_to: Nodes exhibit structural or intent-based similarity.

Infrastructure and Schema Relationships

These eight edges connect deployment and data definitions:

• deploys: A CI job or pipeline deploys a service.
• serves: A service provides an endpoint to consumers.
• migrates: A migration script modifies a database schema.
• documents: A documentation node describes a target code or infrastructure node.
• provisions: Infrastructure-as-Code scripts create cloud resources.
• routes: A router maps incoming requests to specific handlers.
• defines_schema: Code establishes a data schema definition.
• triggers: An event source or scheduler initiates a job execution.

Working with the I³ Graph Schema

The packages/core/src/types.ts file exports TypeScript interfaces and type unions that enforce the I³ schema at compile time. Developers interact with these types when building graph nodes and edges, while packages/dashboard/src/store.ts mirrors the node-type list for UI filtering.

Creating Typed Nodes

The GraphNode interface (lines 38–48 in types.ts) requires specific fields for every node:

import type { GraphNode } from "./types.js";

const fileNode: GraphNode = {
  id: "file:src/index.ts",
  type: "file",
  name: "index.ts",
  filePath: "src/index.ts",
  summary: "Entry point of the application",
  tags: ["entry", "typescript"],
  complexity: "moderate",
};

Defining Typed Edges

The GraphEdge interface (lines 53–60 in types.ts) enforces directional relationships:

import type { GraphEdge } from "./types.js";

const edge: GraphEdge = {
  source: "file:src/utils.ts",
  target: "file:src/constants.ts",
  type: "imports",
  direction: "forward",
  weight: 0.9,
  description: "utils.ts imports constants.ts",
};

Validating Schema Compliance

The test suite in packages/core/src/types.test.ts (lines 19–44) maintains canonical arrays of allowed types. The following pattern verifies that your graph implementation conforms to the I³ specification:

import { expect } from "vitest";
import type { NodeType, EdgeType } from "./types.js";

const allowedNodeTypes: NodeType[] = [
  "file", "function", "class", "module", "concept",
  "config", "document", "service", "table", "endpoint",
  "pipeline", "schema", "resource",
];

expect(allowedNodeTypes).toHaveLength(13);

const allowedEdgeTypes: EdgeType[] = [
  "imports", "exports", "contains", "inherits", "implements",
  "calls", "subscribes", "publishes", "middleware",
  "reads_from", "writes_to", "transforms", "validates",
  "depends_on", "tested_by", "configures",
  "related", "similar_to",
  "deploys", "serves", "migrates", "documents",
  "provisions", "routes", "defines_schema", "triggers",
];

expect(allowedEdgeTypes).toHaveLength(26);

Summary

• The I³ graph in Understand-Anything uses 13 node types divided into code entities (file, function, class, module, concept) and non-code entities (config, document, service, table, endpoint, pipeline, schema, resource).
• 26 edge types express relationships across six categories: structural, behavioral, data-flow, dependencies, semantic, and infrastructure.
• Type definitions reside in packages/core/src/types.ts, with compile-time validation enforced through the GraphNode and GraphEdge interfaces.
• The test suite in packages/core/src/types.test.ts guarantees schema compliance by asserting the exact count and names of allowed types at lines 19–44.
• Agents in understand-anything-plugin/agents/ and the dashboard in packages/dashboard/src/store.ts rely on this shared vocabulary for analysis and visualization.

Frequently Asked Questions

What does I³ represent in the Understand-Anything graph?

I³ refers to the internal knowledge-graph model that serves as the core abstraction layer for representing codebases and infrastructure. It stands for the "Intelligent, Interconnected, Information" graph that classifies software elements into 13 node types and their relationships into 26 edge types, enabling cross-domain analysis from source code to cloud resources.

Where are the node and edge type definitions located in the source code?

The canonical definitions reside in packages/core/src/types.ts. The NodeType union type is exported at lines 2–7, while the EdgeType union covers the 26 relationship variants. The GraphNode interface (lines 38–48) and GraphEdge interface (lines 53–60) provide the complete schema for graph construction.

How does the system validate that only the 13 node types and 26 edge types are used?

Validation occurs through the unit test file packages/core/src/types.test.ts, which contains hardcoded arrays of the 13 node types and 26 edge types at lines 19–44. These arrays are tested for exact length and membership, ensuring that any change to the schema must update both the type definitions and the corresponding test assertions, preventing runtime type violations.

Can the I³ schema be extended with custom node or edge types for specialized domains?

While the core schema is fixed at 13 node types and 26 edge types in the current implementation, the TypeScript union types in packages/core/src/types.ts can be modified to include additional classifications. However, extending the schema requires updating the validation tests in packages/core/src/types.test.ts and ensuring that agents in understand-anything-plugin/agents/ and the dashboard logic in packages/dashboard/src/store.ts recognize the new types for proper rendering and analysis.

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