HOME/PROJECTS/RepoBeacon: Codebase Indexing & RAG

RepoBeacon: Codebase Indexing & RAG

Designing an end-to-end repository ingestion and retrieval pipeline that grounds LLM responses using Spring Boot and PostgreSQL pgvector.

runtimeSpring Boot

pipelineIndex-Retrieve-Generate

vectorStorePostgreSQL (pgvector)

licenseOpen Source

Spring BootJavaNext.jsPostgreSQLpgvector

SECTION 01 // THE PROBLEM

Navigating Large Codebases

Providing developers with an AI assistant grounded in their actual repository context.

When onboarding to a new project or debugging complex issues, developers spend significant time searching through files to understand repository structure and logic.

General-purpose LLMs lack knowledge of private or recent codebase changes. To provide accurate, context-aware answers, the system needs to ingest the repository source code and retrieve relevant context based on user queries.

Standard LLMs

Relies on pre-training data. Hallucinates answers when asked about specific, unseen repository implementations.

RAG-Based Assistant

Indexes the actual repository code into semantic vectors, retrieving the most relevant files to ground the LLM's response in reality.

SECTION 02 // THE SOLUTION

Token-Based Chunking & Semantic Retrieval

Indexing repository content and grounding queries using vector similarity search.

RepoBeacon fetches repository files via the GitHub API, processes them using token-based chunking, and generates vector embeddings.

By storing these embeddings in PostgreSQL via pgvector, RepoBeacon can quickly retrieve the most semantically relevant code chunks to answer developer questions accurately.

Repository Ingestion Flow

// Standard RAG Pipeline
1. Fetch repository tree and files
2. Filter out binaries and irrelevant files
3. Split source code using token-based chunker
4. Generate embeddings for each chunk
5. Store embeddings and metadata in pgvector
6. Query: embed user question -> retrieve top-k chunks -> generate answer

SECTION 03 // DATA PIPELINE

Index-Retrieve-Generate Pipeline

Architecture flow from repository ingest to chat interface.

NODE 01

Repository Fetch

Downloading and filtering source files via the GitHub API.

GitHub API

NODE 02

Token Chunking

Splitting files into manageable token chunks for embedding.

Text Splitter

NODE 03

Embedding Generation

Transforming text chunks into semantic vector embeddings.

Embedding Model

NODE 04

Vector Storage

Storing chunks and embeddings for similarity search.

PostgreSQL / pgvector

NODE 05

Context-Aware Generation

Retrieving relevant chunks and streaming the LLM response.

Next.js / Spring Boot

SECTION 04 // DECISIONS

Architectural Choices

Practical choices for building a robust RAG application.

01 // BACKEND

Spring Boot for Pipeline Orchestration

Chosen Architecture:Spring Boot Ecosystem

Evaluated Alternative:Node.js / Python

Rationale:Leveraged Spring Boot to orchestrate the RAG pipeline, taking advantage of its robust enterprise capabilities, structured dependency injection, and data access integrations.

02 // DATABASE

PostgreSQL with pgvector

Chosen Architecture:PostgreSQL / pgvector

Evaluated Alternative:Dedicated Vector DB

Rationale:Using PostgreSQL for both standard relational data (users, chat history) and vector embeddings simplifies the architecture and eliminates the need for maintaining a separate database.

SECTION 05 // RETROSPECTIVE

Key Takeaways

Engineering lessons learned from building RepoBeacon.

Unified Storage

Keeping vector embeddings and relational metadata inside PostgreSQL greatly simplified operations and local development.

Chunking Strategies

Tuning the chunk size and overlap is critical to ensuring the LLM receives enough context without exceeding its context window.