# harvard-hbs/rag-example architecture

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

- Interactive diagram: https://gitdiagram.com/harvard-hbs/rag-example
- Repository: https://github.com/harvard-hbs/rag-example

## Overview

This repository is a compact RAG example: it indexes PDF text into a persistent vector store, then offers both similarity-search demos and conversational retrieval with an LLM. The main workflow runs from indexing through retrieval and answer generation; separate CLI and Streamlit entry points expose those capabilities. The source shows Chroma, OpenSearch, and PGVector as environment-selected storage options, and Azure OpenAI or Bedrock as chat-model options. Edges are based on the README and excerpts; unsampled details are not inferred.

Main entry points: [`document_chatbot.py`](https://github.com/harvard-hbs/rag-example/blob/main/document_chatbot.py) (Chat example), [`document_chatbot_ui.py`](https://github.com/harvard-hbs/rag-example/blob/main/document_chatbot_ui.py) (Chat UI), [`index_documents.py`](https://github.com/harvard-hbs/rag-example/blob/main/index_documents.py) (Indexing script), [`search_index.py`](https://github.com/harvard-hbs/rag-example/blob/main/search_index.py) (Search example)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Document indexing"]
  node_pdf["Federalist PDF"]
  node_indexer["Indexing script<br/>[index_documents.py]"]
  node_pdfprep["PDF chunking<br/>[index_documents.py]"]
  node_embed["HuggingFace embeddings"]
end

subgraph group_retrieve["Vector retrieval"]
  node_vectorstore[("Persistent vector store")]
  node_searchcli["Search example<br/>[search_index.py]"]
end

subgraph group_chat["Conversational RAG"]
  node_retriever["Retriever"]
  node_memory["Chat memory"]
  node_chain["Retrieval chain"]
  node_llm["Chat model"]
  node_azure["Azure OpenAI"]
  node_bedrock["Amazon Bedrock"]
end

subgraph group_interfaces["User interfaces"]
  node_searchui["Search UI<br/>[search_index_ui.py]"]
  node_chatcli["Chat example"]
  node_chatui["Chat UI"]
end

node_operator(("Operator"))

node_operator -->|"runs indexing"| node_indexer
node_indexer -->|"ingests"| node_pdf
node_indexer -->|"chunks documents"| node_pdfprep
node_indexer -->|"creates embeddings"| node_embed
node_indexer -->|"persists chunks"| node_vectorstore
node_operator -->|"runs search"| node_searchcli
node_operator -->|"opens search UI"| node_searchui
node_searchcli -->|"loads embeddings"| node_embed
node_searchcli -->|"queries index"| node_vectorstore
node_searchui -->|"loads embeddings"| node_embed
node_searchui -->|"queries index"| node_vectorstore
node_operator -->|"runs chatbot"| node_chatcli
node_operator -->|"opens chatbot UI"| node_chatui
node_chatcli -->|"loads embeddings"| node_embed
node_chatcli -->|"opens index"| node_vectorstore
node_chatcli -->|"creates retriever"| node_retriever
node_chatcli -->|"creates memory"| node_memory
node_chatcli -->|"builds and invokes"| node_chain
node_chain -->|"retrieves chunks"| node_retriever
node_chain -->|"uses context"| node_memory
node_chain -->|"generates answer"| node_llm
node_llm -.->|"selects when configured"| node_azure
node_llm -.->|"selects when configured"| node_bedrock
node_chatui -->|"loads embeddings"| node_embed
node_chatui -->|"opens index"| node_vectorstore
node_chatui -->|"creates retriever"| node_retriever
node_chatui -->|"creates memory"| node_memory
node_chatui -->|"builds and invokes"| node_chain

click node_pdf "https://github.com/harvard-hbs/rag-example/blob/main/source_documents/5008_Federalist%20Papers.pdf"
click node_indexer "https://github.com/harvard-hbs/rag-example/blob/main/index_documents.py"
click node_pdfprep "https://github.com/harvard-hbs/rag-example/blob/main/index_documents.py"
click node_searchcli "https://github.com/harvard-hbs/rag-example/blob/main/search_index.py"
click node_searchui "https://github.com/harvard-hbs/rag-example/blob/main/search_index_ui.py"
click node_retriever "https://github.com/harvard-hbs/rag-example/blob/main/document_chatbot.py"
click node_memory "https://github.com/harvard-hbs/rag-example/blob/main/document_chatbot.py"
click node_chain "https://github.com/harvard-hbs/rag-example/blob/main/document_chatbot.py"
click node_chatcli "https://github.com/harvard-hbs/rag-example/blob/main/document_chatbot.py"
click node_chatui "https://github.com/harvard-hbs/rag-example/blob/main/document_chatbot_ui.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_pdf,node_indexer,node_pdfprep,node_embed toneBlue
class node_vectorstore,node_searchcli toneAmber
class node_retriever,node_memory,node_chain,node_llm,node_azure,node_bedrock toneMint
class node_searchui,node_chatcli,node_chatui toneRose
class node_operator toneIndigo
```

## Components

### Document indexing

- [Federalist PDF](https://github.com/harvard-hbs/rag-example/blob/main/source_documents/5008_Federalist%20Papers.pdf): `source_documents/5008_Federalist Papers.pdf`
- [Indexing script](https://github.com/harvard-hbs/rag-example/blob/main/index_documents.py): `index_documents.py`
- [PDF chunking](https://github.com/harvard-hbs/rag-example/blob/main/index_documents.py): `index_documents.py`
- **HuggingFace embeddings**

### Vector retrieval

- **Persistent vector store**
- [Search example](https://github.com/harvard-hbs/rag-example/blob/main/search_index.py): `search_index.py`

### Conversational RAG

- [Retriever](https://github.com/harvard-hbs/rag-example/blob/main/document_chatbot.py): `document_chatbot.py`
- [Chat memory](https://github.com/harvard-hbs/rag-example/blob/main/document_chatbot.py): `document_chatbot.py`
- [Retrieval chain](https://github.com/harvard-hbs/rag-example/blob/main/document_chatbot.py): `document_chatbot.py`
- **Chat model**
- **Azure OpenAI**
- **Amazon Bedrock**

### User interfaces

- [Search UI](https://github.com/harvard-hbs/rag-example/blob/main/search_index_ui.py): `search_index_ui.py`
- [Chat example](https://github.com/harvard-hbs/rag-example/blob/main/document_chatbot.py): `document_chatbot.py`
- [Chat UI](https://github.com/harvard-hbs/rag-example/blob/main/document_chatbot_ui.py): `document_chatbot_ui.py`

### Other components

- **Operator**

## Connections

- Operator → Indexing script: runs indexing (evidence: `README.md`)
- Indexing script → Federalist PDF: ingests (evidence: `index_documents.py`)
- Indexing script → PDF chunking: chunks documents (evidence: `index_documents.py`)
- Indexing script → HuggingFace embeddings: creates embeddings (evidence: `index_documents.py`)
- Indexing script → Persistent vector store: persists chunks (evidence: `index_documents.py`)
- Operator → Search example: runs search (evidence: `README.md`)
- Operator → Search UI: opens search UI (evidence: `README.md`)
- Search example → HuggingFace embeddings: loads embeddings (evidence: `search_index.py`)
- Search example → Persistent vector store: queries index (evidence: `search_index.py`)
- Search UI → HuggingFace embeddings: loads embeddings (evidence: `search_index_ui.py`)
- Search UI → Persistent vector store: queries index (evidence: `search_index_ui.py`)
- Operator → Chat example: runs chatbot (evidence: `README.md`)
- Operator → Chat UI: opens chatbot UI (evidence: `README.md`)
- Chat example → HuggingFace embeddings: loads embeddings (evidence: `document_chatbot.py`)
- Chat example → Persistent vector store: opens index (evidence: `document_chatbot.py`)
- Chat example → Retriever: creates retriever (evidence: `document_chatbot.py`)
- Chat example → Chat memory: creates memory (evidence: `document_chatbot.py`)
- Chat example → Retrieval chain: builds and invokes (evidence: `document_chatbot.py`)
- Retrieval chain → Retriever: retrieves chunks (evidence: `document_chatbot.py`)
- Retrieval chain → Chat memory: uses context (evidence: `document_chatbot.py`)
- Retrieval chain → Chat model: generates answer (evidence: `document_chatbot.py`)
- Chat model → Azure OpenAI: selects when configured
- Chat model → Amazon Bedrock: selects when configured
- Chat UI → HuggingFace embeddings: loads embeddings (evidence: `document_chatbot_ui.py`)
- Chat UI → Persistent vector store: opens index (evidence: `document_chatbot_ui.py`)
- Chat UI → Retriever: creates retriever (evidence: `document_chatbot_ui.py`)
- Chat UI → Chat memory: creates memory (evidence: `document_chatbot_ui.py`)
- Chat UI → Retrieval chain: builds and invokes (evidence: `document_chatbot_ui.py`)
