# vitali87/code-graph-rag architecture

> Architecture diagram of the GitHub repository vitali87/code-graph-rag, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vitali87/code-graph-rag
- Repository: https://github.com/vitali87/code-graph-rag

## Overview

##### Project Type & Purpose
- This is an open-source, CLI-based Retrieval-Augmented Generation (RAG) system for multi-language codebases.
- It parses source code (via Tree-sitter), ingests a knowledge graph in Memgraph, and provides an interactive natural-language interface (and batch/export/optimization commands) to query and even surgically edit code.

##### High-Level File Structure
- Top-level files:
- Makefile, build_binary.py, pyproject.toml, docker-compose.yaml (build & deploy)
- main.py, realtime_updater.py (entry points)
- codebase_rag/ (core logic):
- config.py, main.py (orchestrator)
- parser_loader.py + parsers/ (language-specific AST processors)
- graph_loader.py, graph_updater.py + services/ (graph ingest/query layer)
- providers/ (LLM provider abstraction)
- tools/ (file I/O, code retrieval, directory lister, shell commands)
- tests/ (comprehensive multi-lang test suite)
- grammars/ (git-submodules for Tree-sitter grammars)
- examples/, optimize/ (usage examples & optimization scripts)

##### Architecture Overview (from README)
- Two main components:
A. **Multi-language Parser**: reads a code repo, feeds AST-derived nodes/edges to Memgraph.
B. **RAG CLI**: takes user NL queries, orchestrates LLM(s) → generates Cypher → queries Memgraph → returns results or applies edits.
- External dependencies: Memgraph database (Docker), LLM providers (OpenAI, Google Gemini, Ollama).

## Diagram (Mermaid)

```mermaid
graph TB
    %% CLI Layer
    subgraph "CLI Layer"
        CLI["User CLI\n(main.py)"]:::core
        RealTime["Real-time Updater\n(realtime_updater.py)"]:::core
        Orchestrator["Orchestrator\n(codebase_rag/main.py)"]:::core
    end

    %% Parsing Pipeline
    subgraph "Parsing Pipeline"
        ParserLoader["Parser Loader\n(codebase_rag/parser_loader.py)"]:::core
        Parsers["Language Parsers\n(codebase_rag/parsers/)"]:::core
    end

    %% Graph Service Layer
    subgraph "Graph Service Layer"
        GraphLoader["Graph Loader\n(codebase_rag/graph_loader.py)"]:::core
        GraphUpdater["Graph Updater\n(codebase_rag/graph_updater.py)"]:::core
        GraphService["Graph Service\n(codebase_rag/services/graph_service.py)"]:::core
    end

    %% LLM Pipeline
    subgraph "LLM Pipeline"
        LLMService["LLM Orchestrator\n(codebase_rag/services/llm.py)"]:::core
        Prompts["Prompts\n(codebase_rag/prompts.py)"]:::core
        Providers["Providers\n(codebase_rag/providers/)"]:::core
    end

    %% Tools Suite
    subgraph "Tools Suite"
        Tools["Tools Suite\n(codebase_rag/tools/)"]:::core
    end

    %% Configuration
    subgraph "Configuration"
        Config["Config\n(codebase_rag/config.py)"]:::core
        LangConfig["Language Config\n(codebase_rag/language_config.py)"]:::core
        Schemas["Schemas\n(codebase_rag/schemas.py)"]:::core
    end

    %% External Systems & DB
    DB["Memgraph Database"]:::datastore
    subgraph "External Systems"
        LLMExt["LLM Providers\n(OpenAI, Gemini, Ollama)"]:::external
        Docker["Docker Compose\n(docker-compose.yaml)"]:::deployment
    end

    %% File System
    FS["File System\n(Code Repo)"]:::filesystem

    %% Connections
    CLI --> Orchestrator
    RealTime --> Orchestrator
    Orchestrator --> ParserLoader
    ParserLoader --> Parsers
    Parsers --> FS
    ParserLoader --> GraphLoader
    Parsers --> GraphLoader
    GraphLoader --> GraphService
    GraphUpdater --> DB
    GraphService --> DB
    Orchestrator --> LLMService
    LLMService --> Providers
    Providers --> LLMExt
    LLMExt --> LLMService
    LLMService --> GraphService
    GraphService --> Orchestrator
    Orchestrator --> Tools
    Tools --> FS
    Orchestrator --> Docker

    %% Config dependencies
    Config --> ParserLoader
    Config --> GraphService
    Config --> LLMService
    LangConfig --> ParserLoader
    Schemas --> GraphService

    %% Click Events
    click CLI "https://github.com/vitali87/code-graph-rag/blob/main/main.py"
    click RealTime "https://github.com/vitali87/code-graph-rag/blob/main/realtime_updater.py"
    click Orchestrator "https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/main.py"
    click ParserLoader "https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/parser_loader.py"
    click Parsers "https://github.com/vitali87/code-graph-rag/tree/main/codebase_rag/parsers/"
    click GraphLoader "https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/graph_loader.py"
    click GraphUpdater "https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/graph_updater.py"
    click GraphService "https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/services/graph_service.py"
    click LLMService "https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/services/llm.py"
    click Prompts "https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/prompts.py"
    click Providers "https://github.com/vitali87/code-graph-rag/tree/main/codebase_rag/providers/"
    click Tools "https://github.com/vitali87/code-graph-rag/tree/main/codebase_rag/tools/"
    click Config "https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/config.py"
    click LangConfig "https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/language_config.py"
    click Schemas "https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/schemas.py"
    click Docker "https://github.com/vitali87/code-graph-rag/blob/main/docker-compose.yaml"

    %% Styles
    classDef core fill:#D6E9FF,stroke:#4A90E2,stroke-width:2px
    classDef external fill:#DFF2BF,stroke:#4F8A10,stroke-width:2px
    classDef datastore fill:#FFBABA,stroke:#D8000C,stroke-width:2px
    classDef filesystem fill:#FFF2CC,stroke:#9F6000,stroke-width:2px
    classDef deployment fill:#E2E2E2,stroke:#666666,stroke-width:2px
    class CLI,RealTime,Orchestrator,ParserLoader,Parsers,GraphLoader,GraphUpdater,GraphService,LLMService,Prompts,Providers,Tools,Config,LangConfig,Schemas core
    class LLMExt external
    class DB datastore
    class FS filesystem
    class Docker deployment
```
