# pixelcraftlab/custom-rag architecture

> Architecture diagram of the GitHub repository pixelcraftlab/custom-rag, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pixelcraftlab/custom-rag
- Repository: https://github.com/pixelcraftlab/custom-rag

## Overview

Custom RAG is a full-stack document-question-answering application. Users upload PDFs, which the backend loads, semantically chunks, embeds, and stores; questions travel from the React chat UI through FastAPI to hybrid retrieval and reranking, then to a grounded LLM response with sources. The README describes persistent vector storage and hybrid retrieval; sampled storage code currently uses PostgreSQL/pgvector rather than ChromaDB. Edges reflect shown calls, imports listed in the source index, or README-documented behavior; unsampled details are not inferred.

Main entry points: [`frontend/src/pages/Home.jsx`](https://github.com/pixelcraftlab/custom-rag/blob/main/frontend/src/pages/Home.jsx) (Home workflow), [`backend/app/ingestion.py`](https://github.com/pixelcraftlab/custom-rag/blob/main/backend/app/ingestion.py) (Ingestion pipeline), [`backend/app/chat.py`](https://github.com/pixelcraftlab/custom-rag/blob/main/backend/app/chat.py) (RAG orchestration), [`frontend/src/api/ragApi.js`](https://github.com/pixelcraftlab/custom-rag/blob/main/frontend/src/api/ragApi.js) (RAG API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["React interface"]
  node_home["Home workflow<br/>[Home.jsx]"]
  node_sidebar["Document sidebar<br/>[Sidebar.jsx]"]
  node_chatbox["Chat display<br/>[ChatBox.jsx]"]
  node_messages["Message list<br/>[MessageList.jsx]"]
  node_message["Message view<br/>[Message.jsx]"]
  node_input["Message input<br/>[MessageInput.jsx]"]
  node_webapi["RAG API client<br/>[ragApi.js]"]
end

subgraph group_api["FastAPI routes"]
  node_uploadapi["Upload route<br/>[upload.py]"]
  node_chatapi["Chat route<br/>[chat.py]"]
  node_documentsapi["Documents route<br/>[documents.py]"]
end

subgraph group_ingest["Document ingestion"]
  node_ingestion["Ingestion pipeline<br/>[ingestion.py]"]
  node_loader["PDF loading<br/>[loader.py]"]
  node_splitter["Semantic chunking<br/>[splitter.py]"]
end

subgraph group_retrieve["Retrieval"]
  node_retriever["Retrieval orchestration<br/>[retriever.py]"]
  node_hybrid["Hybrid retrieval"]
  node_vectorsearch["Vector search<br/>[vector_search.py]"]
  node_bm25loader["BM25 index loader<br/>[bm25_loader.py]"]
  node_bm25["BM25 search<br/>[bm25.py]"]
  node_rrf["Rank fusion<br/>[rrf.py]"]
  node_reranker["Result reranking<br/>[reranker.py]"]
end

subgraph group_answer["Answer and storage"]
  node_embeddings["Embedding model<br/>[embeddings.py]"]
  node_chat["RAG orchestration<br/>[chat.py]"]
  node_prompt["Grounding prompt<br/>[prompt.py]"]
  node_llm["LLM client<br/>[llm.py]"]
  node_memory["Conversation memory<br/>[memory.py]"]
  node_store["Document storage<br/>[vectorstore.py]"]
end

node_user(("Document user"))
node_database[("PostgreSQL pgvector")]

node_user -->|"uses"| node_home
node_home -->|"renders"| node_sidebar
node_home -->|"renders"| node_chatbox
node_home -->|"renders"| node_input
node_chatbox -->|"renders"| node_messages
node_messages -->|"renders"| node_message
node_home -->|"requests"| node_webapi
node_webapi -->|"uploads PDFs"| node_uploadapi
node_webapi -->|"sends questions"| node_chatapi
node_webapi -->|"lists and deletes"| node_documentsapi
node_uploadapi -->|"ingests files"| node_ingestion
node_ingestion -->|"loads PDFs"| node_loader
node_ingestion -->|"splits documents"| node_splitter
node_ingestion -->|"gets embeddings"| node_embeddings
node_ingestion -->|"stores chunks"| node_store
node_chatapi -->|"handles questions"| node_chat
node_chat -->|"retrieves context"| node_retriever
node_retriever -->|"searches candidates"| node_hybrid
node_retriever -->|"reranks results"| node_reranker
node_hybrid -->|"runs semantic search"| node_vectorsearch
node_hybrid -->|"loads keyword index"| node_bm25loader
node_hybrid -->|"fuses rankings"| node_rrf
node_vectorsearch -->|"queries vectors"| node_store
node_bm25loader -->|"loads index"| node_bm25
node_bm25loader -->|"loads stored chunks"| node_store
node_chat -->|"builds prompt"| node_prompt
node_chat -->|"generates answer"| node_llm
node_chat -->|"uses conversation state"| node_memory
node_store -->|"reads and writes"| node_database
node_llm -.->|"uses provider"| node_database

click node_home "https://github.com/pixelcraftlab/custom-rag/blob/main/frontend/src/pages/Home.jsx"
click node_sidebar "https://github.com/pixelcraftlab/custom-rag/blob/main/frontend/src/components/Sidebar.jsx"
click node_chatbox "https://github.com/pixelcraftlab/custom-rag/blob/main/frontend/src/components/ChatBox.jsx"
click node_messages "https://github.com/pixelcraftlab/custom-rag/blob/main/frontend/src/components/MessageList.jsx"
click node_message "https://github.com/pixelcraftlab/custom-rag/blob/main/frontend/src/components/Message.jsx"
click node_input "https://github.com/pixelcraftlab/custom-rag/blob/main/frontend/src/components/MessageInput.jsx"
click node_webapi "https://github.com/pixelcraftlab/custom-rag/blob/main/frontend/src/api/ragApi.js"
click node_uploadapi "https://github.com/pixelcraftlab/custom-rag/blob/main/backend/app/api/upload.py"
click node_chatapi "https://github.com/pixelcraftlab/custom-rag/blob/main/backend/app/api/chat.py"
click node_documentsapi "https://github.com/pixelcraftlab/custom-rag/blob/main/backend/app/api/documents.py"
click node_ingestion "https://github.com/pixelcraftlab/custom-rag/blob/main/backend/app/ingestion.py"
click node_loader "https://github.com/pixelcraftlab/custom-rag/blob/main/backend/app/loader.py"
click node_splitter "https://github.com/pixelcraftlab/custom-rag/blob/main/backend/app/splitter.py"
click node_embeddings "https://github.com/pixelcraftlab/custom-rag/blob/main/backend/app/embeddings.py"
click node_chat "https://github.com/pixelcraftlab/custom-rag/blob/main/backend/app/chat.py"
click node_retriever "https://github.com/pixelcraftlab/custom-rag/blob/main/backend/app/retriever.py"
click node_hybrid "https://github.com/pixelcraftlab/custom-rag/blob/main/backend/app/hybrid_retriever.py"
click node_vectorsearch "https://github.com/pixelcraftlab/custom-rag/blob/main/backend/app/vector_search.py"
click node_bm25loader "https://github.com/pixelcraftlab/custom-rag/blob/main/backend/app/bm25_loader.py"
click node_bm25 "https://github.com/pixelcraftlab/custom-rag/blob/main/backend/app/bm25.py"
click node_rrf "https://github.com/pixelcraftlab/custom-rag/blob/main/backend/app/rrf.py"
click node_reranker "https://github.com/pixelcraftlab/custom-rag/blob/main/backend/app/reranker.py"
click node_prompt "https://github.com/pixelcraftlab/custom-rag/blob/main/backend/app/prompt.py"
click node_llm "https://github.com/pixelcraftlab/custom-rag/blob/main/backend/app/llm.py"
click node_memory "https://github.com/pixelcraftlab/custom-rag/blob/main/backend/app/memory.py"
click node_store "https://github.com/pixelcraftlab/custom-rag/blob/main/backend/app/vectorstore.py"

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_home,node_sidebar,node_chatbox,node_messages,node_message,node_input,node_webapi,node_user toneBlue
class node_uploadapi,node_chatapi,node_documentsapi,node_database toneAmber
class node_ingestion,node_loader,node_splitter toneMint
class node_retriever,node_hybrid,node_vectorsearch,node_bm25loader,node_bm25,node_rrf,node_reranker toneRose
class node_embeddings,node_chat,node_prompt,node_llm,node_memory,node_store toneIndigo
```

## Components

### React interface

- [Home workflow](https://github.com/pixelcraftlab/custom-rag/blob/main/frontend/src/pages/Home.jsx): `frontend/src/pages/Home.jsx`
- [Document sidebar](https://github.com/pixelcraftlab/custom-rag/blob/main/frontend/src/components/Sidebar.jsx): `frontend/src/components/Sidebar.jsx`
- [Chat display](https://github.com/pixelcraftlab/custom-rag/blob/main/frontend/src/components/ChatBox.jsx): `frontend/src/components/ChatBox.jsx`
- [Message list](https://github.com/pixelcraftlab/custom-rag/blob/main/frontend/src/components/MessageList.jsx): `frontend/src/components/MessageList.jsx`
- [Message view](https://github.com/pixelcraftlab/custom-rag/blob/main/frontend/src/components/Message.jsx): `frontend/src/components/Message.jsx`
- [Message input](https://github.com/pixelcraftlab/custom-rag/blob/main/frontend/src/components/MessageInput.jsx): `frontend/src/components/MessageInput.jsx`
- [RAG API client](https://github.com/pixelcraftlab/custom-rag/blob/main/frontend/src/api/ragApi.js): `frontend/src/api/ragApi.js`

### FastAPI routes

- [Upload route](https://github.com/pixelcraftlab/custom-rag/blob/main/backend/app/api/upload.py): `backend/app/api/upload.py`
- [Chat route](https://github.com/pixelcraftlab/custom-rag/blob/main/backend/app/api/chat.py): `backend/app/api/chat.py`
- [Documents route](https://github.com/pixelcraftlab/custom-rag/blob/main/backend/app/api/documents.py): `backend/app/api/documents.py`

### Document ingestion

- [Ingestion pipeline](https://github.com/pixelcraftlab/custom-rag/blob/main/backend/app/ingestion.py): `backend/app/ingestion.py`
- [PDF loading](https://github.com/pixelcraftlab/custom-rag/blob/main/backend/app/loader.py): `backend/app/loader.py`
- [Semantic chunking](https://github.com/pixelcraftlab/custom-rag/blob/main/backend/app/splitter.py): `backend/app/splitter.py`

### Retrieval

- [Retrieval orchestration](https://github.com/pixelcraftlab/custom-rag/blob/main/backend/app/retriever.py): `backend/app/retriever.py`
- [Hybrid retrieval](https://github.com/pixelcraftlab/custom-rag/blob/main/backend/app/hybrid_retriever.py): `backend/app/hybrid_retriever.py`
- [Vector search](https://github.com/pixelcraftlab/custom-rag/blob/main/backend/app/vector_search.py): `backend/app/vector_search.py`
- [BM25 index loader](https://github.com/pixelcraftlab/custom-rag/blob/main/backend/app/bm25_loader.py): `backend/app/bm25_loader.py`
- [BM25 search](https://github.com/pixelcraftlab/custom-rag/blob/main/backend/app/bm25.py): `backend/app/bm25.py`
- [Rank fusion](https://github.com/pixelcraftlab/custom-rag/blob/main/backend/app/rrf.py): `backend/app/rrf.py`
- [Result reranking](https://github.com/pixelcraftlab/custom-rag/blob/main/backend/app/reranker.py): `backend/app/reranker.py`

### Answer and storage

- [Embedding model](https://github.com/pixelcraftlab/custom-rag/blob/main/backend/app/embeddings.py): `backend/app/embeddings.py`
- [RAG orchestration](https://github.com/pixelcraftlab/custom-rag/blob/main/backend/app/chat.py): `backend/app/chat.py`
- [Grounding prompt](https://github.com/pixelcraftlab/custom-rag/blob/main/backend/app/prompt.py): `backend/app/prompt.py`
- [LLM client](https://github.com/pixelcraftlab/custom-rag/blob/main/backend/app/llm.py): `backend/app/llm.py`
- [Conversation memory](https://github.com/pixelcraftlab/custom-rag/blob/main/backend/app/memory.py): `backend/app/memory.py`
- [Document storage](https://github.com/pixelcraftlab/custom-rag/blob/main/backend/app/vectorstore.py): `backend/app/vectorstore.py`

### Other components

- **Document user**
- **PostgreSQL pgvector**

## Connections

- Document user → Home workflow: uses (evidence: `README.md`)
- Home workflow → Document sidebar: renders (evidence: `frontend/src/pages/Home.jsx`)
- Home workflow → Chat display: renders (evidence: `frontend/src/pages/Home.jsx`)
- Home workflow → Message input: renders (evidence: `frontend/src/pages/Home.jsx`)
- Chat display → Message list: renders (evidence: `frontend/src/components/ChatBox.jsx`)
- Message list → Message view: renders (evidence: `frontend/src/components/MessageList.jsx`)
- Home workflow → RAG API client: requests (evidence: `frontend/src/pages/Home.jsx`)
- RAG API client → Upload route: uploads PDFs (evidence: `frontend/src/api/ragApi.js`)
- RAG API client → Chat route: sends questions (evidence: `frontend/src/api/ragApi.js`)
- RAG API client → Documents route: lists and deletes (evidence: `frontend/src/api/ragApi.js`)
- Upload route → Ingestion pipeline: ingests files (evidence: `backend/app/api/upload.py`)
- Ingestion pipeline → PDF loading: loads PDFs (evidence: `backend/app/ingestion.py`)
- Ingestion pipeline → Semantic chunking: splits documents (evidence: `backend/app/ingestion.py`)
- Ingestion pipeline → Embedding model: gets embeddings (evidence: `backend/app/ingestion.py`)
- Ingestion pipeline → Document storage: stores chunks (evidence: `backend/app/ingestion.py`)
- Chat route → RAG orchestration: handles questions (evidence: `backend/app/api/chat.py`)
- RAG orchestration → Retrieval orchestration: retrieves context (evidence: `backend/app/chat.py`)
- Retrieval orchestration → Hybrid retrieval: searches candidates (evidence: `backend/app/retriever.py`)
- Retrieval orchestration → Result reranking: reranks results (evidence: `backend/app/retriever.py`)
- Hybrid retrieval → Vector search: runs semantic search (evidence: `backend/app/hybrid_retriever.py`)
- Hybrid retrieval → BM25 index loader: loads keyword index (evidence: `backend/app/hybrid_retriever.py`)
- Hybrid retrieval → Rank fusion: fuses rankings (evidence: `backend/app/hybrid_retriever.py`)
- Vector search → Document storage: queries vectors (evidence: `backend/app/vector_search.py`)
- BM25 index loader → BM25 search: loads index (evidence: `backend/app/bm25_loader.py`)
- BM25 index loader → Document storage: loads stored chunks (evidence: `backend/app/bm25_loader.py`)
- RAG orchestration → Grounding prompt: builds prompt (evidence: `backend/app/chat.py`)
- RAG orchestration → LLM client: generates answer (evidence: `backend/app/chat.py`)
- RAG orchestration → Conversation memory: uses conversation state (evidence: `backend/app/chat.py`)
- Document storage → PostgreSQL pgvector: reads and writes (evidence: `backend/app/vectorstore.py`)
- LLM client → PostgreSQL pgvector: uses provider
