# Code-Review-Graph Knowledge Graph Nodes and Edges: A Complete Schema Guide

> Explore the code-review-graph knowledge graph schema. Understand nodes like File and Class and edges such as CALLS and IMPORTS_FROM for a complete view of program structure.

- Repository: [Tirth Kanani/code-review-graph](https://github.com/tirth8205/code-review-graph)
- Tags: api-reference
- Published: 2026-08-13

---

**The code-review-graph** stores program structure in a SQLite-backed knowledge graph where **nodes** represent concrete code entities (File, Class, Function, Type, Test) and **edges** capture relationships (CALLS, IMPORTS_FROM, INHERITS, IMPLEMENTS, CONTAINS, TESTED_BY, DEPENDS_ON, REFERENCES) between them.

The tirth8205/code-review-graph project parses source code into a persistent knowledge graph to enable impact analysis and intelligent code review. Understanding the precise schema of **code-review-graph knowledge graph nodes and edges** is essential for querying the database or extending the parser. The implementation uses SQLite as the backing store, with strict typing enforced through Python dataclasses.

## Understanding Node Types in the Code-Review-Graph

Nodes represent concrete code entities extracted during static analysis. According to the source code in [`code_review_graph/graph.py`](https://github.com/tirth8205/code-review-graph/blob/main/code_review_graph/graph.py), the nodes table is defined with a mandatory `kind` column and metadata fields.

### The Node Schema in graph.py

In [`code_review_graph/graph.py`](https://github.com/tirth8205/code-review-graph/blob/main/code_review_graph/graph.py) (lines 75-79), the SQLite schema defines nodes with the following columns:

- **kind**: The entity type (File, Class, Function, Type, or Test)
- **name**: The short identifier of the entity
- **qualified_name**: The fully qualified identifier used for cross-references
- **file_path**: Absolute or relative path to the source file
- **line_start** and **line_end**: The span of lines where the entity is defined
- **language**: Programming language identifier (e.g., "python", "javascript")
- **params** and **return_type**: Optional metadata for callable entities

Each node acts as a vertex in the graph, uniquely identified by its qualified name.

### The NodeInfo Dataclass

The concrete Python representation lives in [`code_review_graph/parser.py`](https://github.com/tirth8205/code-review-graph/blob/main/code_review_graph/parser.py) (lines 66-81). The **`NodeInfo`** dataclass mirrors the database schema:

```python
@dataclass
class NodeInfo:
    kind: str  # File, Class, Function, Type, Test

    name: str
    qualified_name: str
    file_path: str
    line_start: int
    line_end: int
    language: str
    is_test: bool
    parent_name: Optional[str] = None
    params: Optional[str] = None
    return_type: Optional[str] = None

```

### Concrete Node Kinds

The five mandatory node kinds cover the primary semantic constructs in modern codebases:

- **File**: Represents a source code file; acts as the root container for other entities
- **Class**: Object-oriented class definitions, including nested classes
- **Function**: Standalone functions and methods, storing parameter signatures and return types
- **Type**: Type aliases, interfaces, and abstract type definitions
- **Test**: Specialized nodes marking test functions or test classes (often cross-referenced via TESTED_BY edges)

## Understanding Edge Relationships in the Code-Review-Graph

Edges capture directed relationships between nodes, enabling graph traversal for impact analysis.

### The Edge Schema in graph.py

In [`code_review_graph/graph.py`](https://github.com/tirth8205/code-review-graph/blob/main/code_review_graph/graph.py) (lines 94-100), the edges table schema stores:

- **kind**: The relationship type (CALLS, IMPORTS_FROM, INHERITS, IMPLEMENTS, CONTAINS, TESTED_BY, DEPENDS_ON, REFERENCES, DEPENDS_ON_CONFIG)
- **source**: Qualified name of the originating node
- **target**: Qualified name of the destination node
- **file_path**: Location where the relationship is declared or inferred
- **line**: Specific line number where the relationship originates
- **confidence**: Float score indicating certainty (0.0-1.0)
- **extra_data**: JSON blob for additional metadata

### The EdgeInfo Dataclass

Defined in [`code_review_graph/parser.py`](https://github.com/tirth8205/code-review-graph/blob/main/code_review_graph/parser.py) (lines 93-98), the **`EdgeInfo`** dataclass provides the Python interface:

```python
@dataclass
class EdgeInfo:
    kind: str
    source: str  # qualified name of source node

    target: str  # qualified name of target node

    file_path: str
    line: int
    confidence: float = 1.0
    extra_data: Optional[Dict[str, Any]] = None

```

### Relationship Types and Semantics

The **`kind`** column enumerates nine distinct relationship types:

- **CALLS**: Function-to-function invocations, including method calls
- **IMPORTS_FROM**: Module or package import dependencies
- **INHERITS**: Class inheritance relationships (child to parent)
- **IMPLEMENTS**: Interface or protocol conformance
- **CONTAINS**: Parent-child containment (File contains Function, Class contains Method)
- **TESTED_BY**: Links production code to its corresponding test entities
- **DEPENDS_ON**: Generic dependency between components
- **DEPENDS_ON_CONFIG**: Special edge type for configuration-key dependencies (e.g., environment variables)
- **REFERENCES**: General symbol references not covered by CALLS or IMPORTS_FROM

## Working with Nodes and Edges in Python

The `GraphStore` class in [`code_review_graph/graph.py`](https://github.com/tirth8205/code-review-graph/blob/main/code_review_graph/graph.py) provides CRUD operations for both entities. Below is a practical example demonstrating node creation, edge insertion, and querying:

```python
from pathlib import Path
from code_review_graph.graph import GraphStore
from code_review_graph.parser import NodeInfo, EdgeInfo

# Open (or create) a graph database

store = GraphStore(Path("/tmp/crg.db"))

# Insert a file node

file_node = NodeInfo(
    kind="File",
    name="src/example.py",
    file_path="src/example.py",
    line_start=0,
    line_end=0,
    language="python",
    is_test=False,
)
store.upsert_node(file_node)

# Insert a function node

func_node = NodeInfo(
    kind="Function",
    name="greet",
    file_path="src/example.py",
    line_start=10,
    line_end=14,
    language="python",
    parent_name=None,
    params="name: str",
    return_type="str",
    is_test=False,
)
store.upsert_node(func_node)

# Record a CALLS edge (greet calls print)

call_edge = EdgeInfo(
    kind="CALLS",
    source="src/example.py::greet",
    target="builtins::print",
    file_path="src/example.py",
    line=12,
)
store.upsert_edge(call_edge)

# Query all function nodes

functions = [n for n in store.get_all_nodes() if n.kind == "Function"]
print(functions)

# Find outgoing CALLS edges from a function

outgoing_calls = store.get_edges_by_source("src/example.py::greet")
print(outgoing_calls)

store.close()

```

This snippet demonstrates the core workflow: initialize `GraphStore`, persist `NodeInfo` objects via `upsert_node()`, create `EdgeInfo` relationships via `upsert_edge()`, and retrieve entities using `get_all_nodes()` and `get_edges_by_source()`.

## Key Source Files and Architecture

Understanding the repository layout helps navigate the implementation of the knowledge graph schema:

- **[`code_review_graph/graph.py`](https://github.com/tirth8205/code-review-graph/blob/main/code_review_graph/graph.py)**: Core SQLite schema definitions, `GraphStore` class, and CRUD operations for nodes and edges
- **[`code_review_graph/parser.py`](https://github.com/tirth8205/code-review-graph/blob/main/code_review_graph/parser.py)**: `NodeInfo` and `EdgeInfo` dataclasses, plus utilities for path normalization and language detection
- **[`code_review_graph/constants.py`](https://github.com/tirth8205/code-review-graph/blob/main/code_review_graph/constants.py)**: Impact-analysis weights and directional defaults for edge kinds (particularly for `DEPENDS_ON` traversal)
- **[`code_review_graph/visualization.py`](https://github.com/tirth8205/code-review-graph/blob/main/code_review_graph/visualization.py)**: Rendering logic that styles different edge kinds with specific colors and dash patterns for graph visualization

## Summary

- **Nodes** represent five concrete code entity types: **File**, **Class**, **Function**, **Type**, and **Test**, storing location and metadata in [`code_review_graph/graph.py`](https://github.com/tirth8205/code-review-graph/blob/main/code_review_graph/graph.py)
- **Edges** model nine relationship types (**CALLS**, **IMPORTS_FROM**, **INHERITS**, **IMPLEMENTS**, **CONTAINS**, **TESTED_BY**, **DEPENDS_ON**, **REFERENCES**, **DEPENDS_ON_CONFIG**) with source/target qualified names and confidence scores
- **NodeInfo** and **EdgeInfo** dataclasses in [`code_review_graph/parser.py`](https://github.com/tirth8205/code-review-graph/blob/main/code_review_graph/parser.py) provide the typed Python interface to the SQLite schema
- **`GraphStore`** handles persistence, offering `upsert_node()`, `upsert_edge()`, and query methods like `get_edges_by_source()`

## Frequently Asked Questions

### What are the valid node kinds in the code-review-graph knowledge graph?

The valid node kinds are **File**, **Class**, **Function**, **Type**, and **Test**. These are stored in the mandatory `kind` column of the nodes table defined in [`code_review_graph/graph.py`](https://github.com/tirth8205/code-review-graph/blob/main/code_review_graph/graph.py) (lines 75-79). Each kind corresponds to a specific code construct that the parser extracts during static analysis, with **Test** nodes specifically identifying test functions and classes for coverage analysis.

### How are edges physically stored in the SQLite database?

Edges are stored in a dedicated table with columns for `kind`, `source` (qualified name), `target` (qualified name), `file_path`, `line`, `confidence`, and `extra_data`. The schema definition resides in [`code_review_graph/graph.py`](https://github.com/tirth8205/code-review-graph/blob/main/code_review_graph/graph.py) (lines 94-100). The `source` and `target` columns reference the `qualified_name` field of nodes, creating a foreign-key-like relationship without explicit SQLite foreign key constraints.

### What is the difference between CONTAINS and IMPORTS_FROM edges?

**CONTAINS** edges represent structural containment within the same file or scope, such as a File containing a Function or a Class containing a Method. **IMPORTS_FROM** edges represent cross-module dependencies where one file imports symbols from another module. While CONTAINS edges are hierarchical and intra-file, IMPORTS_FROM edges are inter-file dependencies that drive the import graph analysis.

### How do I query all outgoing edges from a specific function?

Use the `GraphStore.get_edges_by_source()` method, passing the qualified name of the function as the argument. For example, `store.get_edges_by_source("src/example.py::greet")` returns a list of `EdgeInfo` objects representing all relationships (calls, references, etc.) originating from that function. You can filter the results further by checking the `kind` attribute of each returned `EdgeInfo` instance.