Understanding the Key Relationships in the Code-Graph-RAG Graph Schema

The Code-Graph-RAG graph schema defines 17 distinct relationship types—from containment hierarchies to call graphs—that connect nodes representing projects, packages, modules, classes, and functions within a Protocol Buffers-based knowledge graph.

The vitali87/code-graph-rag repository transforms software codebases into navigable semantic graphs using a strictly typed Protocol Buffers schema. At the heart of this system lies the Relationship message defined in codec/schema.proto, which enumerates exactly how different code entities interconnect to enable sophisticated retrieval-augmented generation (RAG) over source code.

Containment Hierarchy Relationships

The schema models physical and logical nesting through four primary containment edges. These relationships form the hierarchical backbone of the graph, connecting high-level organizational units down to individual files and modules.

• CONTAINS_PACKAGE: Connects a Project node to a Package node, representing that a project logically contains one or more packages.
• CONTAINS_FOLDER: Links a Project to a Folder, modeling directory structures within the codebase.
• CONTAINS_FILE: Associates a Folder (or Project) with a File, representing file system containment.
• CONTAINS_MODULE: Connects a Folder or Package to a Module, indicating that a specific module lives within that organizational boundary.

Definition and Inheritance Relationships

These edges capture object-oriented semantics, type definitions, and polymorphic behavior. They enable the graph to represent not just structure, but meaning and inheritance chains.

• DEFINES: A versatile relationship connecting Module, Class, or Interface nodes to the entities they define, including Function, Method, Class, Enum, or Type nodes.
• DEFINES_METHOD: Specifically links a Class or Interface to a Method it declares, distinguishing it from other definition types.
• INHERITS: Creates edges between Class nodes to represent class inheritance hierarchies (source inherits from target).
• IMPLEMENTS: Connects a Class to an Interface that it implements.
• OVERRIDES: Links a Method to another Method in a parent class that it overrides, enabling analysis of polymorphic behavior.

Dependency and Interaction Relationships

These relationships model cross-module dependencies, external library usage, and runtime interactions. They are critical for understanding coupling and building accurate call graphs.

• IMPORTS: Connects a Module to another Module or ExternalModule that it imports or depends upon.
• CALLS: Represents function invocation by linking a Function or Method to another Function or Method it calls at runtime.
• DEPENDS_ON_EXTERNAL: Links a Project or Package to an ExternalPackage representing third-party dependencies.
• IMPLEMENTS_MODULE: Connects a ModuleImplementation to a ModuleInterface it fulfills, supporting module system semantics.

Resource Access and Export Relationships

The schema captures I/O operations and public API surfaces through relationships that model how code interacts with external resources and what it exposes to consumers.

• EXPORTS: Connects a Module or Package to a Resource (such as a symbol or public identifier) that it makes available to external code.
• EXPORTS_MODULE: Specifically links a Package to a Module it exports as part of its public API.
• READS_FROM: Indicates that a Function or Method reads data from a File or Resource.
• WRITES_TO: Indicates that a Function or Method writes data to a File or Resource.

Relationship Schema Implementation

All relationship types are formally declared in the RelationshipType enum within codec/schema.proto at lines 115–136:

enum RelationshipType {
  RELATIONSHIP_TYPE_UNSPECIFIED = 0;
  CONTAINS_PACKAGE = 1;
  CONTAINS_FOLDER = 2;
  CONTAINS_FILE = 3;
  CONTAINS_MODULE = 4;
  DEFINES = 5;
  DEFINES_METHOD = 6;
  IMPORTS = 7;
  INHERITS = 8;
  OVERRIDES = 9;
  CALLS = 10;
  DEPENDS_ON_EXTERNAL = 11;
  IMPLEMENTS_MODULE = 12;
  IMPLEMENTS = 13;
  EXPORTS = 14;
  EXPORTS_MODULE = 15;
  READS_FROM = 16;
  WRITES_TO = 17;
}

Each instantiated edge is represented by a Relationship message (lines 138–147) that records the type, source_id, target_id, optional properties, and the label strings of the participating nodes. This structure ensures type safety while allowing rich metadata attachment.

Creating Relationships in Python

The schema is compiled into Python bindings available in [codec/schema_pb2.py](https://github.com/vitali87/code-graph-rag/blob/main/codec/schema_pb2.py). Below is a minimal example demonstrating how to construct nodes and connect them using the CONTAINS_PACKAGE relationship:

import codec.schema_pb2 as pb

# Create a Project node

proj = pb.Node()
proj.project.name = "my-awesome-project"

# Create a Package node

pkg = pb.Node()
pkg.package.qualified_name = "my_pkg"
pkg.package.name = "my_pkg"
pkg.package.path = "src/my_pkg"

# Relationship: Project CONTAINS_PACKAGE Package

rel = pb.Relationship(
    type=pb.Relationship.CONTAINS_PACKAGE,
    source_id="project:my-awesome-project",
    target_id="package:my_pkg",
    source_label="Project",
    target_label="Package",
)

# Assemble the GraphCodeIndex

graph = pb.GraphCodeIndex()
graph.nodes.extend([proj, pkg])
graph.relationships.append(rel)

# Serialise to bytes (e.g., for storage or transmission)

data = graph.SerializeToString()

# Deserialise later

restored = pb.GraphCodeIndex()
restored.ParseFromString(data)

For a more comprehensive demonstration of multiple relationship types including imports, calls, and inheritance, refer to the test suite in [codebase_rag/tests/test_protobuf_service.py](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/tests/test_protobuf_service.py).

Key Files for Graph Schema Management

Three primary files work together to define, generate, and utilize the relationship schema:

File	Role
codec/schema.proto	Defines the complete graph schema, including all node payloads and the Relationship enum.
[codec/schema_pb2.py](https://github.com/vitali87/code-graph-rag/blob/main/codec/schema_pb2.py)	Auto-generated Python bindings used to construct and manipulate graph objects programmatically.
[codebase_rag/services/protobuf_service.py](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/services/protobuf_service.py)	Service layer that creates GraphCodeIndex instances from parsed code, populating nodes and relationships according to the schema.

Summary

• The Code-Graph-RAG schema defines 17 relationship types in the RelationshipType enum within codec/schema.proto.
• Containment relationships (CONTAINS_PACKAGE, CONTAINS_FOLDER, etc.) model the physical and logical organization of code.
• Definition and inheritance relationships (DEFINES, INHERITS, IMPLEMENTS, OVERRIDES) capture object-oriented semantics and type hierarchies.
• Dependency relationships (IMPORTS, CALLS, DEPENDS_ON_EXTERNAL) enable call graph analysis and dependency tracking.
• Resource relationships (EXPORTS, READS_FROM, WRITES_TO) model I/O operations and public API surfaces.
• Relationships are instantiated via the Relationship message, which stores source/target IDs, types, and metadata.
• The Python implementation uses auto-generated bindings in codec/schema_pb2.py to build and serialize graph structures.

Frequently Asked Questions

What is the source of truth for relationship definitions in Code-Graph-RAG?

The canonical definitions reside in codec/schema.proto within the RelationshipType enum (lines 115–136). This Protocol Buffers file serves as the single source of truth, ensuring consistent graph structure across all language implementations and tooling.

How does the schema distinguish between a method definition and a general definition?

The schema uses two separate relationship types: DEFINES is a general-purpose edge connecting modules, classes, or interfaces to any defined entity (functions, classes, enums, types), while DEFINES_METHOD specifically connects classes or interfaces to methods they declare. This distinction enables precise querying of method hierarchies versus general type definitions.

Can the graph represent external dependencies and I/O operations?

Yes. The DEPENDS_ON_EXTERNAL relationship links projects or packages to external dependencies, while READS_FROM and WRITES_TO capture file and resource I/O operations at the function or method level. These edges enable security analysis and understanding of external system interactions.

Where can I find examples of multiple relationship types used together?

The repository's test suite in [codebase_rag/tests/test_protobuf_service.py](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/tests/test_protobuf_service.py) contains realistic examples demonstrating import relationships, call graphs, and inheritance chains constructed using the Python protobuf bindings.

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