# pnkvalavala/repochat architecture

> Architecture diagram of the GitHub repository pnkvalavala/repochat, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pnkvalavala/repochat
- Repository: https://github.com/pnkvalavala/repochat

## Overview

##### Project Type and Purpose
- Repochat is a self-hosted, LLM-powered chatbot that lets users query the contents of any GitHub repository.
- It runs entirely locally under the `main` branch: no external LLM APIs, only a local LlamaCpp model and a local vector database (ChromaDB).

##### File Structure
- Top level:
- app.py – Streamlit entrypoint and UI layer
- requirements.txt, LICENSE, README.md
- repochat/ – core application package
- Inside `repochat/`:
- git.py – clones and fetches files from GitHub
- utils.py – file-splitting, chunking, text processing helpers
- db.py – wraps ChromaDB vector store
- models.py – configures the LlamaCpp LLM instance (local model)
- chain.py – ties together Retriever + LLM + memory into a QA chain

##### Key Insights from README
- Workflow:
1. User inputs GitHub URL.
2. System clones repo into `cloned_repo/`.
3. Files are chunked & embedded via HuggingFace SentenceTransformer.
4. Embeddings are stored/retrieved in ChromaDB.
5. When the user queries, relevant chunks are fetched (vector retrieval) and passed, along with chat history, to LlamaCpp.
6. Streamlit UI renders responses.
- Local-only setup: llama-cpp-python, local HF models, local ChromaDB store.

##### Main Components & Their Relationships
a. User / Streamlit UI (app.py)
– Displays input form and chat pane.
– Sends “clone & ingest” commands or user questions to the backend.
b. Git Service (repochat/git.py)
– Clones the target repository → filesystem (`cloned_repo/`).
c. Chunking & Embedding Pipeline (repochat/utils.py + SentenceTransformer)
– Reads files from `cloned_repo/`.
– Splits into manageable text chunks.
– Calls HF embedding model to produce vector embeddings.
d. Vector Store (repochat/db.py → ChromaDB)
– Persists embeddings locally.
– Exposes a Retriever interface.
e. LLM Module (repochat/models.py → LlamaCpp)
– Loads a local GGUF model via llama-cpp-python.
– Exposes an LLM API for completion requests.
f. QA Chain (repochat/chain.py → LangChain-style chain)
– Combines Vector Retriever + LLM + optional memory.
– Orchestrates retrieval augmented generation.
g. Filesystem / Local Storage
– `cloned_repo/` for raw code files
– `models/` for downloaded GGUF model
– ChromaDB folder for vectors

User → Streamlit UI → Git Service → `cloned_repo` → Chunker → Embedding Model → ChromaDB
User Question → Streamlit UI → Retriever → LLM → Streamlit UI

##### Architectural Patterns & Design Principles
- Separation of concerns: UI, Git fetch, preprocessing, storage, LLM logic are in dedicated modules.
- Retrieval-Augmented Generation (RAG) pattern: vector store + LLM.
- Local-first design: no external APIs beyond GitHub cloning.
- Modular chain composition: easy to swap embedding models, vector stores, or LLM backends.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Entities
    User["User"]:::external
    GitHub["GitHub (HTTPS)"]:::external
    HF["SentenceTransformer"]:::external
    LlamaCPPLib["llama-cpp-python"]:::external

    %% UI Layer
    subgraph "UI Layer"
        UI["Streamlit UI (app.py)"]:::ui
    end

    %% Backend Components
    subgraph "Backend (repochat package)"
        Git["Git Clone Service"]:::preprocess
        Chunker["Chunker & Embedder"]:::preprocess
        Vector["ChromaDB Vector Store"]:::storage
        Chain["QA Chain Orchestrator"]:::inference
        LLM["LlamaCpp LLM Module"]:::inference
    end

    %% Local Storage
    subgraph "Local Storage"
        RepoFS["cloned_repo/"]:::storage
        ModelsFS["models/"]:::storage
        ChromaFS["ChromaDB Data"]:::storage
    end

    %% Data Flows - Ingestion
    User --> UI
    UI --> Git
    GitHub --> Git
    Git --> RepoFS
    RepoFS --> Chunker
    HF --> Chunker
    Chunker -->|"embeddings"| Vector
    Vector --> ChromaFS
    Vector --> Chain

    %% Data Flows - Query
    User -->|question| UI
    UI --> Chain
    Chain --> Vector
    Vector --> Chain
    Chain --> LLM
    LlamaCPPLib --> LLM
    LLM --> Chain
    Chain --> UI

    %% Click Events
    click UI "https://github.com/pnkvalavala/repochat/blob/main/app.py"
    click Git "https://github.com/pnkvalavala/repochat/blob/main/repochat/git.py"
    click Chunker "https://github.com/pnkvalavala/repochat/blob/main/repochat/utils.py"
    click Vector "https://github.com/pnkvalavala/repochat/blob/main/repochat/db.py"
    click LLM "https://github.com/pnkvalavala/repochat/blob/main/repochat/models.py"
    click Chain "https://github.com/pnkvalavala/repochat/blob/main/repochat/chain.py"

    %% Styles
    classDef ui fill:#E0F7FA,stroke:#006064,color:#006064
    classDef preprocess fill:#FFF9C4,stroke:#F57F17,color:#F57F17
    classDef storage fill:#E8F5E9,stroke:#2E7D32,color:#2E7D32
    classDef inference fill:#FFE0B2,stroke:#E65100,color:#E65100
    classDef external fill:#ECEFF1,stroke:#546E7A,color:#546E7A
```
