# Core Components of code-graph-rag: A Complete Architecture Guide

> Explore the core components of code-graph-rag: codebase_rag, services, providers, tools, and evals. Understand this complete architecture for advanced code analysis and LLM integration.

- Repository: [Vitali Avagyan/code-graph-rag](https://github.com/vitali87/code-graph-rag)
- Tags: architecture
- Published: 2026-08-14

---

**`code-graph-rag` consists of six interconnected layers: `codebase_rag` (graph engine), `services` (LLM orchestration and Memgraph integration), `providers` (multi-vendor LLM abstraction), `tools` (sandboxed LLM capabilities), `evals` (cross-language benchmarks), and support modules for configuration and logging.**

## What Is code-graph-rag?

`code-graph-rag` is an open-source Python package that combines **Retrieval-Augmented Generation (RAG)** with **language-agnostic code graph analysis**. Built by vitali87, it enables LLMs to answer natural-language questions about codebases by parsing multiple programming languages into a unified call-graph, persisting it to Memgraph, and exposing safe tools for file operations and semantic search.

## The Six Core Components

### codebase_rag: The Graph Engine

The **`codebase_rag`** package forms the heart of the system. It handles source-code parsing, graph construction, and the interactive RAG loop.

| File | Responsibility |
|------|----------------|
| [`codebase_rag/main.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/main.py) | Entry point, session management, and UI rendering |
| [`codebase_rag/graph_loader.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/graph_loader.py) | Loads persisted graphs from JSON |
| [`codebase_rag/graph_updater.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/graph_updater.py) | Incremental updates while watching the repository |
| [`codebase_rag/parser_fingerprint.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/parser_fingerprint.py) | Cache-friendly AST parsing with content hashing |

In [`codebase_rag/main.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/main.py), the `run_chat_loop()` function drives the interactive session, managing conversation history and delegating to the LLM orchestrator. The parser fingerprinting system in [`parser_fingerprint.py`](https://github.com/vitali87/code-graph-rag/blob/main/parser_fingerprint.py) ensures that only changed files trigger re-parsing, making large codebase updates efficient.

### services: LLM and Database Glue

The **`services`** layer bridges the graph engine with external systems—LLMs, vector stores, and cost trackers.

- **[`services/llm.py`](https://github.com/vitali87/code-graph-rag/blob/main/services/llm.py)** – Creates a `pydantic_ai`-based agent, handles streaming responses, and formats tool calls for the RAG pipeline
- **[`services/graph_service.py`](https://github.com/vitali87/code-graph-rag/blob/main/services/graph_service.py)** – Wraps Memgraph ingestion operations and graph export functionality
- **[`services/usage_cost.py`](https://github.com/vitali87/code-graph-rag/blob/main/services/usage_cost.py)** – Estimates token-based pricing across OpenAI, Anthropic, and other supported providers

The `create_rag_orchestrator()` function in [`services/llm.py`](https://github.com/vitali87/code-graph-rag/blob/main/services/llm.py) instantiates the agent that mediates between natural-language queries and Cypher graph queries.

### providers: Multi-Vendor LLM Abstraction

The **`providers`** package implements a strategy pattern for LLM backends, ensuring the same RAG pipeline works regardless of which model provider you choose.

- **[`providers/base.py`](https://github.com/vitali87/code-graph-rag/blob/main/providers/base.py)** – Defines the common interface all providers must implement
- **[`providers/openai.py`](https://github.com/vitali87/code-graph-rag/blob/main/providers/openai.py)** – OpenAI GPT-4, GPT-4o, and GPT-3.5 support
- **[`providers/anthropic.py`](https://github.com/vitali87/code-graph-rag/blob/main/providers/anthropic.py)** – Claude 3 Opus, Sonnet, and Haiku support
- Additional providers (Ollama, etc.) follow the same pattern

This abstraction allows `code-graph-rag` users to switch models via configuration without modifying the core RAG logic.

### tools: Sandboxed LLM Capabilities

The **`tools`** package exposes discrete, safe operations that the LLM can invoke. Each tool is a function with a well-defined schema, preventing arbitrary code execution.

| Tool Module | Function |
|-------------|----------|
| [`tools/file_reader.py`](https://github.com/vitali87/code-graph-rag/blob/main/tools/file_reader.py) | Read files as binary or text content |
| [`tools/file_writer.py`](https://github.com/vitali87/code-graph-rag/blob/main/tools/file_writer.py) | Write files with atomic replacement |
| [`tools/directory_lister.py`](https://github.com/vitali87/code-graph-rag/blob/main/tools/directory_lister.py) | Enumerate repository contents with filtering |
| [`tools/semantic_search.py`](https://github.com/vitali87/code-graph-rag/blob/main/tools/semantic_search.py) | Vector-store lookup for code similarity |
| [`tools/structural_editor.py`](https://github.com/vitali87/code-graph-rag/blob/main/tools/structural_editor.py) | AST-based code modifications (add/remove/replace nodes) |
| [`tools/web_search.py`](https://github.com/vitali87/code-graph-rag/blob/main/tools/web_search.py) | Safe web-search integration for external context |

These tools are instantiated via factory functions like `create_query_tool()` and `create_file_editor_tool()`, then passed to the LLM orchestrator in [`services/llm.py`](https://github.com/vitali87/code-graph-rag/blob/main/services/llm.py).

### evals: Cross-Language Benchmarking

The **`evals`** directory contains language-specific evaluation scripts that verify retrieval accuracy and graph completeness. This ensures the parser works correctly across the supported language set.

- **[`evals/ts_retrieval.py`](https://github.com/vitali87/code-graph-rag/blob/main/evals/ts_retrieval.py)** – TypeScript/TypeScript+React retrieval benchmarks
- **[`evals/python_l1.py`](https://github.com/vitali87/code-graph-rag/blob/main/evals/python_l1.py)** – Python L1 (function-level) evaluation
- **[`evals/structure_report.py`](https://github.com/vitali87/code-graph-rag/blob/main/evals/structure_report.py)** – Generates completeness metrics for the entire graph

Running these evaluations validates that the call-graph correctly captures imports, function calls, and inheritance relationships before deploying the RAG system.

### Support Modules: Configuration and Utilities

Supporting infrastructure includes:

- **[`config.py`](https://github.com/vitali87/code-graph-rag/blob/main/config.py)** – Loads `.cgrignore` patterns, CLI flags, and model settings from environment or config files
- **[`constants.py`](https://github.com/vitali87/code-graph-rag/blob/main/constants.py)** – UI strings, color codes, and token threshold defaults
- **[`exceptions.py`](https://github.com/vitali87/code-graph-rag/blob/main/exceptions.py)** – Domain-specific error types for parser failures, LLM errors, and graph inconsistencies
- **[`logs.py`](https://github.com/vitali87/code-graph-rag/blob/main/logs.py)** – Structured logging helpers for the interactive session
- **`utils/`** – Cross-cutting utilities for path handling, text processing, and validation

## How the Components Work Together

The `code-graph-rag` architecture follows this data flow:

1. **Parse** – `codebase_rag` walks the repository, using tree-sitter grammars to parse Python, Java, TypeScript, Rust, Go, C/C++, Lua, PHP, and others into a unified AST representation
2. **Graphify** – The AST transforms into a call-graph with nodes for functions, classes, and modules; edges capture calls, imports, and inheritance
3. **Persist** – `graph_service` serializes to JSON or streams directly into Memgraph for Cypher querying
4. **Query** – The LLM agent in `services/llm` receives natural language, optionally invokes `tools` for additional context, and generates Cypher or direct answers
5. **Iterate** – `graph_updater` watches for filesystem changes and incrementally updates the graph without full re-parsing

## Code Example: Running the RAG Loop

```python
from pathlib import Path
from codebase_rag.main import run_chat_loop, ConfirmationToolNames
from codebase_rag.services.llm import create_rag_orchestrator
from codebase_rag.tools import create_query_tool, create_file_editor_tool

repo_root = Path("/path/to/your/repo")

# Instantiate the LLM orchestrator with configured provider

rag_agent = create_rag_orchestrator()

# Build tool set available to the LLM

tools = [
    create_query_tool(),
    create_file_editor_tool(),
]

# Start interactive session

await run_chat_loop(rag_agent, tools, repo_root, ConfirmationToolNames())

```

## Code Example: Exporting the Graph

```python
from codebase_rag.graph_updater import MemgraphIngestor
from codebase_rag.main import export_graph_to_file

# Connect to local Memgraph instance

ingestor = MemgraphIngestor(host="localhost", port=7687, batch_size=500)

# Export serialized graph to JSON

export_graph_to_file(ingestor, "graph_export.json")

```

## Summary

- **`codebase_rag`** provides the parsing engine, graph construction, and interactive loop
- **`services`** connects LLMs, Memgraph, and cost estimation in a unified interface
- **`providers`** abstracts OpenAI, Anthropic, and other backends behind a common base class
- **`tools`** exposes safe, schema-validated operations for file I/O, search, and AST editing
- **`evals`** validates graph quality across multiple programming languages
- **Support modules** handle configuration, logging, and cross-cutting concerns

## Frequently Asked Questions

### What graph database does code-graph-rag use?

`code-graph-rag` uses **Memgraph** as its primary graph database. The [`services/graph_service.py`](https://github.com/vitali87/code-graph-rag/blob/main/services/graph_service.py) module handles all ingestion and export operations via the Bolt protocol (default port 7687). Graphs can also be serialized to JSON for offline analysis or transfer.

### Which programming languages does the parser support?

The parser supports **Python, Java, TypeScript/JavaScript, Rust, Go, C/C++, Lua, and PHP**. The `evals/` directory contains benchmarking scripts for most of these languages. Language support is extensible through tree-sitter grammar integration.

### How does code-graph-rag handle API costs?

The [`services/usage_cost.py`](https://github.com/vitali87/code-graph-rag/blob/main/services/usage_cost.py) module tracks token consumption and estimates pricing based on the active provider's rate card. Costs are logged per session and can be capped via configuration in [`config.py`](https://github.com/vitali87/code-graph-rag/blob/main/config.py).

### Can I use local LLMs instead of cloud APIs?

Yes. The `providers` package is designed for pluggable backends. While [`providers/openai.py`](https://github.com/vitali87/code-graph-rag/blob/main/providers/openai.py) and [`providers/anthropic.py`](https://github.com/vitali87/code-graph-rag/blob/main/providers/anthropic.py) ship by default, the [`providers/base.py`](https://github.com/vitali87/code-graph-rag/blob/main/providers/base.py) interface supports any OpenAI-compatible endpoint—including **Ollama**, vLLM, or llama.cpp servers running locally.