# adt-kmr/coderag architecture

> Architecture diagram of the GitHub repository adt-kmr/coderag, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/adt-kmr/coderag
- Repository: https://github.com/adt-kmr/coderag

## Overview

This repository appears to be a small, experiment-oriented CodeRAG project rather than a single packaged application. The top-level structure suggests three parallel implementation tracks: a hybrid RAG approach, a knowledge-graph/“other” approach, and a vector-database-based code RAG approach.

The README is minimal, so the architectural signal comes mostly from the directory names. The core domain is clearly code retrieval and code question answering, with the repository organizing different retrieval strategies around the same task.

The first major subsystem is the vector-based code RAG path under `vector db code rag`. This likely represents the baseline pipeline: source code is ingested, split into retrievable units, embedded, and indexed in a vector database for similarity search during query time.

The second subsystem is the knowledge-graph-oriented path under `kg and others`. This suggests a graph-centric representation of code, such as symbols, dependencies, or relationships between files/functions/classes, plus any auxiliary retrieval or reasoning methods that do not fit the vector store model.

The third subsystem is `hybrid rag`, which likely combines the two retrieval modes. Architecturally, this is the most important boundary: vector search provides semantic matching, while the graph side supplies structural or relational context, and the system merges both before generation.

A likely end-to-end data flow is: code corpus in the repository or an external source is processed into indexed representations; retrieval occurs from either the vector index, the knowledge graph, or both; the selected context is assembled; and an LLM generates the final answer or explanation.

The main architectural separation is therefore between indexing/storage and retrieval/generation. Storage is split across vector indexes and graph-like structures, while generation is downstream and depends on whatever context each approach surfaces.

Because the repo tree is shallow, it does not show a production service layer, API layer, or deployment layer. That implies the repository is probably a set of prototypes, notebooks, or scripts used to compare retrieval strategies rather than a full production system.

For an architecture diagram, the clearest structure is to show one shared “code corpus” input feeding three independent lanes: vector RAG, KG-based retrieval, and hybrid retrieval. Each lane likely has its own preprocessing and retrieval logic, but all converge on a common LLM answering stage.

The important external technologies are the ones implied by the names: embeddings/vector storage for semantic search, a graph model for code relationships, and an LLM for answer synthesis. No specific vendor or framework is visible from the tree alone, so those should be treated as implementation details, not core architecture.

Overall, this repo should be diagrammed as a comparative RAG lab for code intelligence: multiple retrieval backends, a shared code-understanding goal, and a hybrid path that bridges semantic and structural retrieval.

Main entry points: [`hybrid rag`](https://github.com/adt-kmr/coderag/tree/HEAD/hybrid%20rag) (Hybrid retriever), [`vector db code rag`](https://github.com/adt-kmr/coderag/tree/HEAD/vector%20db%20code%20rag) (Vector store), [`kg and others`](https://github.com/adt-kmr/coderag/tree/HEAD/kg%20and%20others) (Graph store)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_shared["Shared flow"]
  node_code_corpus[("Code corpus<br/>source")]
  node_prep["Prep<br/>ingest/chunk"]
  node_llm_answer["LLM answer<br/>generation"]
end

subgraph group_vector["Vector RAG"]
  node_embeddings(("Embeddings<br/>semantic indexer"))
  node_vector_store[("Vector store<br/>ANN index")]
  node_vector_query["Vector query<br/>retriever"]
  node_vector_track{{"Vector RAG<br/>track"}}
end

subgraph group_kg["Knowledge graph"]
  node_kg_extract["KG extract<br/>graph builder"]
  node_kg_store[("Graph store<br/>code graph")]
  node_kg_query["Graph query<br/>graph retriever"]
  node_kg_track{{"KG track"}}
end

subgraph group_hybrid["Hybrid RAG"]
  node_hybrid_retriever["Hybrid retriever<br/>fusion layer"]
  node_context_merge["Context merge<br/>rank/fuse"]
  node_hybrid_track{{"Hybrid track"}}
end

node_code_corpus -->|"ingest"| node_prep
node_prep -->|"chunk/embed"| node_embeddings
node_embeddings -->|"index"| node_vector_store
node_prep -->|"analyze"| node_kg_extract
node_kg_extract -->|"build graph"| node_kg_store
node_vector_store -->|"search"| node_vector_query
node_kg_store -->|"traverse"| node_kg_query
node_vector_query -->|"signal"| node_hybrid_retriever
node_kg_query -->|"signal"| node_hybrid_retriever
node_hybrid_retriever -->|"fuse"| node_context_merge
node_vector_query -.->|"context"| node_llm_answer
node_kg_query -.->|"context"| node_llm_answer
node_context_merge -->|"prompt"| node_llm_answer
node_vector_track -.->|"implements"| node_vector_store
node_kg_track -.->|"implements"| node_kg_store
node_hybrid_track -.->|"implements"| node_hybrid_retriever

click node_vector_store "https://github.com/adt-kmr/coderag/tree/main/vector db code rag"
click node_kg_store "https://github.com/adt-kmr/coderag/tree/main/kg and others"
click node_hybrid_retriever "https://github.com/adt-kmr/coderag/tree/main/hybrid rag"
click node_vector_track "https://github.com/adt-kmr/coderag/tree/main/vector db code rag"
click node_kg_track "https://github.com/adt-kmr/coderag/tree/main/kg and others"
click node_hybrid_track "https://github.com/adt-kmr/coderag/tree/main/hybrid rag"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_code_corpus,node_prep,node_llm_answer toneBlue
class node_embeddings,node_vector_store,node_vector_query,node_vector_track toneAmber
class node_kg_extract,node_kg_store,node_kg_query,node_kg_track toneMint
class node_hybrid_retriever,node_context_merge,node_hybrid_track toneRose
```

## Components

### Shared flow

Common code intelligence flow shared across the repository's prototype tracks.

- **Code corpus**: source · Repository code or an external codebase used as the retrieval target.
- **Prep**: ingest/chunk · Transforms source code into retrievable units and metadata.
- **LLM answer**: generation · Produces the final code explanation or question answer.

### Vector RAG

Embedding-based code retrieval path.

- **Embeddings**: semantic indexer · Converts code chunks into vectors for similarity search.
- [Vector store](https://github.com/adt-kmr/coderag/tree/HEAD/vector%20db%20code%20rag): ANN index · Stores embedded code chunks for nearest-neighbor retrieval. · `vector db code rag`
- **Vector query**: retriever · Finds semantically similar code using the vector index.
- [Vector RAG](https://github.com/adt-kmr/coderag/tree/HEAD/vector%20db%20code%20rag): track · Baseline retrieval path centered on embeddings and vector search. · `vector db code rag`

### Knowledge graph

Graph-oriented code representation and retrieval path.

- **KG extract**: graph builder · Extracts symbols, relations, or dependencies from code.
- [Graph store](https://github.com/adt-kmr/coderag/tree/HEAD/kg%20and%20others): code graph · Persists the code relationship graph for traversal and lookup. · `kg and others`
- **Graph query**: graph retriever · Retrieves structurally related code context from the graph.
- [KG track](https://github.com/adt-kmr/coderag/tree/HEAD/kg%20and%20others): track · Alternative retrieval path centered on code relationships and graph reasoning. · `kg and others`

### Hybrid RAG

Combined semantic and structural retrieval path.

- [Hybrid retriever](https://github.com/adt-kmr/coderag/tree/HEAD/hybrid%20rag): fusion layer · Combines vector and graph retrieval signals. · `hybrid rag`
- **Context merge**: rank/fuse · Merges retrieved snippets and graph facts into one prompt context.
- [Hybrid track](https://github.com/adt-kmr/coderag/tree/HEAD/hybrid%20rag): track · Combined retrieval path that uses both semantic and structural context. · `hybrid rag`

## Connections

- Code corpus → Prep: ingest · Prepare source code for indexing and retrieval.
- Prep → Embeddings: chunk/embed · Create vector representations of code chunks.
- Embeddings → Vector store: index · Store embeddings for semantic search.
- Prep → KG extract: analyze · Derive code entities and relationships.
- KG extract → Graph store: build graph · Persist the code graph.
- Vector store → Vector query: search · Support similarity-based retrieval.
- Graph store → Graph query: traverse · Support relationship-based retrieval.
- Vector query → Hybrid retriever: signal · Provide semantic matches to the hybrid layer.
- Graph query → Hybrid retriever: signal · Provide structural context to the hybrid layer.
- Hybrid retriever → Context merge: fuse · Combine retrieval results into prompt-ready context.
- Vector query → LLM answer: context · Vector-based context can feed generation directly.
- Graph query → LLM answer: context · Graph-derived context can feed generation directly.
- Context merge → LLM answer: prompt · Merged context drives the final answer.
- Vector RAG → Vector store: implements · The vector track contains the baseline retrieval path.
- KG track → Graph store: implements · The KG track contains the graph-based retrieval path.
- Hybrid track → Hybrid retriever: implements · The hybrid track contains the combined retrieval path.