# goldstygian/rag-from-scratch architecture

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

- Interactive diagram: https://gitdiagram.com/goldstygian/rag-from-scratch
- Repository: https://github.com/goldstygian/rag-from-scratch

## Overview

RAG from Scratch is an interactive, document-grounded question-answering program. It reads the knowledge base, chunks and embeds documents, caches per-document processing, builds a FAISS index, retrieves relevant chunks for each question, and sends the question with retrieved context to an LLM. The runtime is concentrated in main.py; README documents the intended end-to-end flow. Some internal call sites are in omitted excerpts, so those links rely on the README rather than implying additional implementation details.

Main entry points: [`main.py`](https://github.com/goldstygian/rag-from-scratch/blob/main/main.py) (Interactive CLI), [`knowledgebase`](https://github.com/goldstygian/rag-from-scratch/tree/main/knowledgebase) (Knowledge Documents)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Ingestion and Cache"]
  node_source_docs["Knowledge Documents"]
  node_load_chunk["Load and Chunk<br/>[main.py]"]
  node_embed_docs["Document Embeddings<br/>[main.py]"]
  node_cache[("Document Cache<br/>[main.py]")]
  node_embedding_model["Embedding Model"]
end

subgraph group_retrieve["Retrieval"]
  node_faiss[("FAISS Index<br/>[main.py]")]
  node_query_embed["Query Embedding<br/>[main.py]"]
  node_search["Similarity Search<br/>[main.py]"]
  node_context["Retrieved Chunks<br/>[main.py]"]
end

subgraph group_answer["Answer Generation"]
  node_cli["Interactive CLI<br/>[main.py]"]
  node_prompt["Context Prompt<br/>[main.py]"]
  node_ollama["Ollama LLM"]
  node_response["Grounded Answer<br/>[main.py]"]
end

node_user(("Questioner"))

node_user -->|"asks"| node_cli
node_source_docs -->|"loads and chunks"| node_load_chunk
node_load_chunk -->|"embeds chunks"| node_embed_docs
node_embedding_model -->|"creates vectors"| node_embed_docs
node_load_chunk -->|"caches chunks"| node_cache
node_embed_docs -->|"caches vectors"| node_cache
node_cache -->|"reuses valid data"| node_load_chunk
node_embed_docs -->|"stores vectors"| node_faiss
node_cli -->|"builds knowledge base"| node_load_chunk
node_cli -->|"builds index"| node_faiss
node_cli -->|"submits question"| node_query_embed
node_embedding_model -->|"embeds query"| node_query_embed
node_query_embed -->|"provides vector"| node_search
node_faiss -->|"searches vectors"| node_search
node_search -->|"returns matches"| node_context
node_cli -->|"provides question"| node_prompt
node_context -->|"adds context"| node_prompt
node_prompt -->|"sends prompt"| node_ollama
node_ollama -->|"generates answer"| node_response
node_response -->|"displays answer"| node_user

click node_cli "https://github.com/goldstygian/rag-from-scratch/blob/main/main.py"
click node_source_docs "https://github.com/goldstygian/rag-from-scratch/tree/main/knowledgebase"
click node_load_chunk "https://github.com/goldstygian/rag-from-scratch/blob/main/main.py"
click node_embed_docs "https://github.com/goldstygian/rag-from-scratch/blob/main/main.py"
click node_cache "https://github.com/goldstygian/rag-from-scratch/blob/main/main.py"
click node_faiss "https://github.com/goldstygian/rag-from-scratch/blob/main/main.py"
click node_query_embed "https://github.com/goldstygian/rag-from-scratch/blob/main/main.py"
click node_search "https://github.com/goldstygian/rag-from-scratch/blob/main/main.py"
click node_context "https://github.com/goldstygian/rag-from-scratch/blob/main/main.py"
click node_prompt "https://github.com/goldstygian/rag-from-scratch/blob/main/main.py"
click node_response "https://github.com/goldstygian/rag-from-scratch/blob/main/main.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_source_docs,node_load_chunk,node_embed_docs,node_cache,node_embedding_model toneBlue
class node_faiss,node_query_embed,node_search,node_context toneAmber
class node_cli,node_prompt,node_ollama,node_response toneMint
class node_user toneIndigo
```

## Components

### Ingestion and Cache

- [Knowledge Documents](https://github.com/goldstygian/rag-from-scratch/tree/main/knowledgebase): `knowledgebase`
- [Load and Chunk](https://github.com/goldstygian/rag-from-scratch/blob/main/main.py): `main.py`
- [Document Embeddings](https://github.com/goldstygian/rag-from-scratch/blob/main/main.py): `main.py`
- [Document Cache](https://github.com/goldstygian/rag-from-scratch/blob/main/main.py): `main.py`
- **Embedding Model**

### Retrieval

- [FAISS Index](https://github.com/goldstygian/rag-from-scratch/blob/main/main.py): `main.py`
- [Query Embedding](https://github.com/goldstygian/rag-from-scratch/blob/main/main.py): `main.py`
- [Similarity Search](https://github.com/goldstygian/rag-from-scratch/blob/main/main.py): `main.py`
- [Retrieved Chunks](https://github.com/goldstygian/rag-from-scratch/blob/main/main.py): `main.py`

### Answer Generation

- [Interactive CLI](https://github.com/goldstygian/rag-from-scratch/blob/main/main.py): `main.py`
- [Context Prompt](https://github.com/goldstygian/rag-from-scratch/blob/main/main.py): `main.py`
- **Ollama LLM**
- [Grounded Answer](https://github.com/goldstygian/rag-from-scratch/blob/main/main.py): `main.py`

### Other components

- **Questioner**

## Connections

- Questioner → Interactive CLI: asks (evidence: `main.py`)
- Knowledge Documents → Load and Chunk: loads and chunks (evidence: `README.md`)
- Load and Chunk → Document Embeddings: embeds chunks (evidence: `README.md`)
- Embedding Model → Document Embeddings: creates vectors (evidence: `main.py`)
- Load and Chunk → Document Cache: caches chunks (evidence: `README.md`)
- Document Embeddings → Document Cache: caches vectors (evidence: `README.md`)
- Document Cache → Load and Chunk: reuses valid data (evidence: `README.md`)
- Document Embeddings → FAISS Index: stores vectors (evidence: `README.md`)
- Interactive CLI → Load and Chunk: builds knowledge base (evidence: `main.py`)
- Interactive CLI → FAISS Index: builds index (evidence: `main.py`)
- Interactive CLI → Query Embedding: submits question (evidence: `README.md`)
- Embedding Model → Query Embedding: embeds query (evidence: `README.md`)
- Query Embedding → Similarity Search: provides vector (evidence: `README.md`)
- FAISS Index → Similarity Search: searches vectors (evidence: `main.py`)
- Similarity Search → Retrieved Chunks: returns matches (evidence: `README.md`)
- Interactive CLI → Context Prompt: provides question (evidence: `README.md`)
- Retrieved Chunks → Context Prompt: adds context (evidence: `README.md`)
- Context Prompt → Ollama LLM: sends prompt (evidence: `README.md`)
- Ollama LLM → Grounded Answer: generates answer (evidence: `README.md`)
- Grounded Answer → Questioner: displays answer (evidence: `README.md`)
