Knowledge Graph Types

All types are exported from @understand-anything/core (main entry) and from the @understand-anything/core/types subpath export (browser-safe).

import type { KnowledgeGraph, GraphNode, GraphEdge, EdgeType } from '@understand-anything/core/types';

KnowledgeGraph

The root structure produced by the analysis pipeline and stored in .understand-anything/knowledge-graph.json.

export interface KnowledgeGraph {
  version: string;
  project: ProjectMeta;
  nodes: GraphNode[];
  edges: GraphEdge[];
  layers: Layer[];
  tour: TourStep[];
}

version

string

required

Schema version string (e.g. "1.0.0"). Used for forward-compatibility checks.

project

ProjectMeta

required

Metadata about the analyzed project.

Show ProjectMeta fields

name

string

required

Display name of the project.

languages

string[]

required

Sorted list of detected programming languages (e.g. ["javascript", "typescript"]).

frameworks

string[]

required

Detected frameworks. May be empty when auto-detection is not available.

description

string

required

Human-readable project description generated by the LLM.

analyzedAt

string

required

ISO 8601 timestamp of when the analysis was run.

gitCommitHash

string

required

Git commit SHA at the time of analysis. Used for staleness checks.

nodes

GraphNode[]

required

All nodes in the graph. See GraphNode below.

edges

GraphEdge[]

required

All directed edges between nodes. See GraphEdge below.

layers

Layer[]

required

Logical groupings of nodes (e.g. “API Layer”, “Data Layer”). May be empty.

tour

TourStep[]

required

Ordered steps for the guided learning tour. May be empty.

GraphNode

Represents a single entity in the codebase — a file, function, class, module, or abstract concept.

export interface GraphNode {
  id: string;
  type: "file" | "function" | "class" | "module" | "concept";
  name: string;
  filePath?: string;
  lineRange?: [number, number];
  summary: string;
  tags: string[];
  complexity: "simple" | "moderate" | "complex";
  languageNotes?: string;
}

string

required

Stable unique identifier. Follows a namespaced convention:

file:<path> — e.g. file:src/index.ts
func:<path>:<name> — e.g. func:src/auth.ts:validateToken
class:<path>:<name> — e.g. class:src/server.ts:HttpServer

type

"file" | "function" | "class" | "module" | "concept"

required

The kind of entity this node represents.

name

string

required

Short display name. For file nodes this is the filename; for functions and classes it is the symbol name.

filePath

string

Relative path to the source file. Present on file, function, and class nodes. Omitted for module and concept nodes.

lineRange

[number, number]

Inclusive start/end line numbers within filePath. Only present on function and class nodes.

summary

string

required

LLM-generated plain-English description of what this entity does.

GraphEdge

A directed relationship between two nodes.

export interface GraphEdge {
  source: string;
  target: string;
  type: EdgeType;
  direction: "forward" | "backward" | "bidirectional";
  description?: string;
  weight: number; // 0–1
}

source

string

required

id of the originating node.

target

string

required

id of the destination node.

type

EdgeType

required

The semantic relationship type. See EdgeType for all 18 values.

direction

"forward" | "backward" | "bidirectional"

required

Directionality of the relationship relative to source → target.

description

string

Optional human-readable annotation for the edge.

weight

number

required

Strength of the relationship in the range 0–1. Used by graph layout algorithms. Default weights assigned by GraphBuilder:

imports edges: 0.7
calls edges: 0.8
contains edges: 1.0

EdgeType

Union of all 18 possible edge relationship types, organized into 5 semantic categories.

export type EdgeType =
  | "imports" | "exports" | "contains" | "inherits" | "implements"  // Structural
  | "calls" | "subscribes" | "publishes" | "middleware"              // Behavioral
  | "reads_from" | "writes_to" | "transforms" | "validates"         // Data flow
  | "depends_on" | "tested_by" | "configures"                       // Dependencies
  | "related" | "similar_to";                                        // Semantic

Structural — static code structure relationships:

Value	Meaning
`imports`	Source file imports the target
`exports`	Source exposes the target as a public API
`contains`	Source structurally contains the target (e.g. file → function)
`inherits`	Source class extends the target class
`implements`	Source class implements the target interface

Behavioral — runtime interaction relationships:

Value	Meaning
`calls`	Source function invokes the target function
`subscribes`	Source subscribes to events or messages from the target
`publishes`	Source emits events or messages consumed by the target
`middleware`	Source is a middleware layer that wraps the target

Data flow — data transformation relationships:

Value	Meaning
`reads_from`	Source reads data produced by the target
`writes_to`	Source writes data consumed by the target
`transforms`	Source transforms the output of the target
`validates`	Source validates the schema or output of the target

Dependencies — build and test relationships:

Value	Meaning
`depends_on`	Source requires the target to function
`tested_by`	Source is tested by the target
`configures`	Source configures or initializes the target

Semantic — loose conceptual relationships:

Value	Meaning
`related`	Source and target are conceptually related
`similar_to`	Source and target serve a similar purpose

Layer

A logical grouping of nodes used to represent architectural layers in the dashboard.

export interface Layer {
  id: string;
  name: string;
  description: string;
  nodeIds: string[];
}

string

required

Stable unique identifier for the layer.

name

string

required

Display name (e.g. "API Layer", "Data Access Layer").

description

string

required

LLM-generated description of the layer’s responsibility.

nodeIds

string[]

required

Array of GraphNode.id values belonging to this layer.

TourStep

One step in the guided onboarding tour, used by the Learn persona in the dashboard.

export interface TourStep {
  order: number;
  title: string;
  description: string;
  nodeIds: string[];
  languageLesson?: string;
}

order

number

required

1-based position of this step in the tour sequence.

title

string

required

Short title displayed in the learn panel.

description

string

required

Explanation of what the user should understand at this step.

nodeIds

string[]

required

Nodes highlighted in the graph when this step is active.

languageLesson

string

Optional language-specific lesson content (Markdown). Present when the step focuses on a language idiom.

ProjectMeta

export interface ProjectMeta {
  name: string;
  languages: string[];
  frameworks: string[];
  description: string;
  analyzedAt: string;
  gitCommitHash: string;
}

See field descriptions under KnowledgeGraph.project above.

AnalysisMeta

Persistence metadata written alongside the graph. Not part of KnowledgeGraph itself.

export interface AnalysisMeta {
  lastAnalyzedAt: string;
  gitCommitHash: string;
  version: string;
  analyzedFiles: number;
}

lastAnalyzedAt

string

required

ISO 8601 timestamp of the most recent analysis.

gitCommitHash

string

required

Git commit SHA from the most recent analysis run.

version

string

required

Core package version used to produce the stored graph.

analyzedFiles

number

required

Number of files included in the analysis.

Core Package

Skill Package

Plugin System

KnowledgeGraph

GraphNode

GraphEdge

EdgeType

Layer

TourStep

ProjectMeta

AnalysisMeta

Build docs developers (and LLMs) love

Core Package

Skill Package

Plugin System

​KnowledgeGraph

​GraphNode

​GraphEdge

​EdgeType

​Layer

​TourStep

​ProjectMeta

​AnalysisMeta

Build docs developers (and LLMs) love

KnowledgeGraph

GraphNode

GraphEdge

EdgeType

Layer

TourStep

ProjectMeta

AnalysisMeta