# alexzxu/local-rag architecture

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

- Interactive diagram: https://gitdiagram.com/alexzxu/local-rag
- Repository: https://github.com/alexzxu/local-rag

## Overview

This is a small document-ingestion and retrieval-augmented generation (RAG) application. Its ingestion workflow loads local files or webpages, filters already-known sources, splits new documents into chunks, and stores them in Chroma; its query workflow retrieves matching documents and prints their content and metadata. The README is empty, so the map reflects the sampled code. Web loading is explicit; embedding-provider calls during storage or retrieval are delegated to LangChain and are not shown in these excerpts.

Main entry points: [`main.py`](https://github.com/alexzxu/local-rag/blob/main/main.py) (Workflow orchestrator), [`rag_vector_store.py`](https://github.com/alexzxu/local-rag/blob/main/rag_vector_store.py) (Chroma setup), [`rag_loaders.py`](https://github.com/alexzxu/local-rag/blob/main/rag_loaders.py) (Source loaders), [`rag_document_tracker.py`](https://github.com/alexzxu/local-rag/blob/main/rag_document_tracker.py) (Source tracking)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Document ingestion"]
  node_main["Workflow orchestrator<br/>[main.py]"]
  node_loaders["Source loaders<br/>[rag_loaders.py]"]
  node_parser["Document chunking<br/>[rag_parsing.py]"]
end

subgraph group_storage["Index and storage"]
  node_tracker["Source tracking"]
  node_embeddings["Embedding setup<br/>[rag_embedding.py]"]
  node_store_setup["Chroma setup"]
  node_chroma[("Chroma database")]
end

subgraph group_query["Query runtime"]
  node_retriever["Query retrieval<br/>[main.py]"]
  node_results["Printed matches<br/>[main.py]"]
end

node_user(("User"))
node_sources["Documents and URLs"]
node_web(("Websites"))

node_user -->|"starts workflow"| node_main
node_sources -->|"provides sources"| node_loaders
node_main -->|"loads documents"| node_loaders
node_loaders -->|"fetches pages"| node_web
node_main -->|"filters sources"| node_tracker
node_main -->|"splits new documents"| node_parser
node_main -->|"creates embeddings"| node_embeddings
node_main -->|"creates store"| node_store_setup
node_main -->|"adds chunks"| node_tracker
node_tracker -->|"checks and writes"| node_store_setup
node_store_setup -->|"persists documents"| node_chroma
node_main -->|"invokes query"| node_retriever
node_retriever -->|"retrieves matches"| node_chroma
node_retriever -->|"prints matches"| node_results
node_user -->|"submits query"| node_retriever
node_embeddings -->|"configures embeddings"| node_store_setup

click node_main "https://github.com/alexzxu/local-rag/blob/main/main.py"
click node_loaders "https://github.com/alexzxu/local-rag/blob/main/rag_loaders.py"
click node_parser "https://github.com/alexzxu/local-rag/blob/main/rag_parsing.py"
click node_tracker "https://github.com/alexzxu/local-rag/blob/main/rag_document_tracker.py"
click node_embeddings "https://github.com/alexzxu/local-rag/blob/main/rag_embedding.py"
click node_store_setup "https://github.com/alexzxu/local-rag/blob/main/rag_vector_store.py"
click node_chroma "https://github.com/alexzxu/local-rag/blob/main/rag_vector_store.py"
click node_retriever "https://github.com/alexzxu/local-rag/blob/main/main.py"
click node_results "https://github.com/alexzxu/local-rag/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_main,node_loaders,node_parser,node_user toneBlue
class node_tracker,node_embeddings,node_store_setup,node_chroma toneAmber
class node_retriever,node_results toneMint
class node_sources,node_web toneIndigo
```

## Components

### Document ingestion

- [Workflow orchestrator](https://github.com/alexzxu/local-rag/blob/main/main.py): `main.py`
- [Source loaders](https://github.com/alexzxu/local-rag/blob/main/rag_loaders.py): `rag_loaders.py`
- [Document chunking](https://github.com/alexzxu/local-rag/blob/main/rag_parsing.py): `rag_parsing.py`

### Index and storage

- [Source tracking](https://github.com/alexzxu/local-rag/blob/main/rag_document_tracker.py): `rag_document_tracker.py`
- [Embedding setup](https://github.com/alexzxu/local-rag/blob/main/rag_embedding.py): `rag_embedding.py`
- [Chroma setup](https://github.com/alexzxu/local-rag/blob/main/rag_vector_store.py): `rag_vector_store.py`
- [Chroma database](https://github.com/alexzxu/local-rag/blob/main/rag_vector_store.py): `rag_vector_store.py`

### Query runtime

- [Query retrieval](https://github.com/alexzxu/local-rag/blob/main/main.py): `main.py`
- [Printed matches](https://github.com/alexzxu/local-rag/blob/main/main.py): `main.py`

### Other components

- **User**
- **Documents and URLs**
- **Websites**

## Connections

- User → Workflow orchestrator: starts workflow (evidence: `main.py`)
- Documents and URLs → Source loaders: provides sources (evidence: `rag_loaders.py`)
- Workflow orchestrator → Source loaders: loads documents (evidence: `main.py`)
- Source loaders → Websites: fetches pages (evidence: `rag_loaders.py`)
- Workflow orchestrator → Source tracking: filters sources (evidence: `main.py`)
- Workflow orchestrator → Document chunking: splits new documents (evidence: `main.py`)
- Workflow orchestrator → Embedding setup: creates embeddings (evidence: `main.py`)
- Workflow orchestrator → Chroma setup: creates store (evidence: `main.py`)
- Workflow orchestrator → Source tracking: adds chunks (evidence: `main.py`)
- Source tracking → Chroma setup: checks and writes (evidence: `rag_document_tracker.py`)
- Chroma setup → Chroma database: persists documents (evidence: `rag_vector_store.py`)
- Workflow orchestrator → Query retrieval: invokes query (evidence: `main.py`)
- Query retrieval → Chroma database: retrieves matches (evidence: `main.py`)
- Query retrieval → Printed matches: prints matches (evidence: `main.py`)
- User → Query retrieval: submits query (evidence: `main.py`)
- Embedding setup → Chroma setup: configures embeddings (evidence: `main.py`)
