# prongs394/harry-potter-langgraph-rag architecture

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

- Interactive diagram: https://gitdiagram.com/prongs394/harry-potter-langgraph-rag
- Repository: https://github.com/prongs394/harry-potter-langgraph-rag

## Overview

This is a Harry Potter question-answering RAG service. A client sends a question to the FastAPI `/chat` endpoint, which invokes a LangGraph workflow: retrieve and rank passages, generate an answer with Ollama, and—if the answer is “I don't know”—rewrite the question once and retry. Offline, the notebook processes book PDFs, chunks the text, and prepares the persistent ChromaDB collection used at runtime. The source excerpts show the runtime calls; indexing details and some workflow stages are documented in the README rather than sampled code.

Main entry points: [`retrieval.py`](https://github.com/prongs394/harry-potter-langgraph-rag/blob/main/retrieval.py) (Dense retrieval), [`agent.py`](https://github.com/prongs394/harry-potter-langgraph-rag/blob/main/agent.py) (LangGraph workflow), [`server.py`](https://github.com/prongs394/harry-potter-langgraph-rag/blob/main/server.py) (Chat endpoint), [`index_books.ipynb`](https://github.com/prongs394/harry-potter-langgraph-rag/blob/main/index_books.ipynb) (Text chunking)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API"]
  node_chat["Chat endpoint<br/>[server.py]"]
end

subgraph group_rag["Answer workflow"]
  node_workflow["LangGraph workflow<br/>[agent.py]"]
  node_retrieval_node["Retrieval step<br/>[agent.py]"]
  node_retrieval["Dense retrieval<br/>[retrieval.py]"]
  node_embedding["Query embedding<br/>[retrieval.py]"]
  node_chroma[("ChromaDB collection<br/>[retrieval.py]")]
  node_expansion["Context expansion<br/>[retrieval.py]"]
  node_reranking["Cross-encoder reranking<br/>[retrieval.py]"]
  node_generation["Answer generation<br/>[agent.py]"]
  node_rewrite_check["Answer check<br/>[agent.py]"]
  node_rewriting["Question rewriting<br/>[agent.py]"]
end

subgraph group_indexing["Book indexing"]
  node_pdf_processing["PDF processing<br/>[index_books.ipynb]"]
  node_chunking["Text chunking<br/>[index_books.ipynb]"]
  node_index_embeddings["Chunk embeddings<br/>[index_books.ipynb]"]
  node_vector_index[("Vector index<br/>[index_books.ipynb]")]
end

node_client(("API client"))
node_ollama["Local Ollama model"]

node_client -->|"submits question"| node_chat
node_chat -->|"invokes"| node_workflow
node_workflow -->|"starts at"| node_retrieval_node
node_retrieval_node -->|"calls"| node_retrieval
node_retrieval -->|"encodes query"| node_embedding
node_retrieval -->|"queries and reads"| node_chroma
node_retrieval -->|"assembles neighbors"| node_expansion
node_retrieval -->|"scores candidates"| node_reranking
node_workflow -->|"then generates"| node_generation
node_generation -->|"requests answer"| node_ollama
node_generation -->|"checks answer"| node_rewrite_check
node_rewrite_check -->|"may route to"| node_rewriting
node_rewriting -->|"requests rewrite"| node_ollama
node_rewriting -->|"retries retrieval"| node_retrieval_node
node_pdf_processing -->|"extracts and chunks"| node_chunking
node_chunking -->|"creates embeddings"| node_index_embeddings
node_index_embeddings -->|"prepares collection"| node_vector_index
node_vector_index -.->|"provides runtime collection"| node_chroma

click node_chat "https://github.com/prongs394/harry-potter-langgraph-rag/blob/main/server.py"
click node_workflow "https://github.com/prongs394/harry-potter-langgraph-rag/blob/main/agent.py"
click node_retrieval_node "https://github.com/prongs394/harry-potter-langgraph-rag/blob/main/agent.py"
click node_retrieval "https://github.com/prongs394/harry-potter-langgraph-rag/blob/main/retrieval.py"
click node_embedding "https://github.com/prongs394/harry-potter-langgraph-rag/blob/main/retrieval.py"
click node_chroma "https://github.com/prongs394/harry-potter-langgraph-rag/blob/main/retrieval.py"
click node_expansion "https://github.com/prongs394/harry-potter-langgraph-rag/blob/main/retrieval.py"
click node_reranking "https://github.com/prongs394/harry-potter-langgraph-rag/blob/main/retrieval.py"
click node_generation "https://github.com/prongs394/harry-potter-langgraph-rag/blob/main/agent.py"
click node_rewrite_check "https://github.com/prongs394/harry-potter-langgraph-rag/blob/main/agent.py"
click node_rewriting "https://github.com/prongs394/harry-potter-langgraph-rag/blob/main/agent.py"
click node_pdf_processing "https://github.com/prongs394/harry-potter-langgraph-rag/blob/main/index_books.ipynb"
click node_chunking "https://github.com/prongs394/harry-potter-langgraph-rag/blob/main/index_books.ipynb"
click node_index_embeddings "https://github.com/prongs394/harry-potter-langgraph-rag/blob/main/index_books.ipynb"
click node_vector_index "https://github.com/prongs394/harry-potter-langgraph-rag/blob/main/index_books.ipynb"

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_chat,node_client toneBlue
class node_workflow,node_retrieval_node,node_retrieval,node_embedding,node_chroma,node_expansion,node_reranking,node_generation,node_rewrite_check,node_rewriting toneAmber
class node_pdf_processing,node_chunking,node_index_embeddings,node_vector_index toneMint
class node_ollama toneIndigo
```

## Components

### API

- [Chat endpoint](https://github.com/prongs394/harry-potter-langgraph-rag/blob/main/server.py): `server.py`

### Answer workflow

- [LangGraph workflow](https://github.com/prongs394/harry-potter-langgraph-rag/blob/main/agent.py): `agent.py`
- [Retrieval step](https://github.com/prongs394/harry-potter-langgraph-rag/blob/main/agent.py): `agent.py`
- [Dense retrieval](https://github.com/prongs394/harry-potter-langgraph-rag/blob/main/retrieval.py): `retrieval.py`
- [Query embedding](https://github.com/prongs394/harry-potter-langgraph-rag/blob/main/retrieval.py): `retrieval.py`
- [ChromaDB collection](https://github.com/prongs394/harry-potter-langgraph-rag/blob/main/retrieval.py): `retrieval.py`
- [Context expansion](https://github.com/prongs394/harry-potter-langgraph-rag/blob/main/retrieval.py): `retrieval.py`
- [Cross-encoder reranking](https://github.com/prongs394/harry-potter-langgraph-rag/blob/main/retrieval.py): `retrieval.py`
- [Answer generation](https://github.com/prongs394/harry-potter-langgraph-rag/blob/main/agent.py): `agent.py`
- [Answer check](https://github.com/prongs394/harry-potter-langgraph-rag/blob/main/agent.py): `agent.py`
- [Question rewriting](https://github.com/prongs394/harry-potter-langgraph-rag/blob/main/agent.py): `agent.py`

### Book indexing

- [PDF processing](https://github.com/prongs394/harry-potter-langgraph-rag/blob/main/index_books.ipynb): `index_books.ipynb`
- [Text chunking](https://github.com/prongs394/harry-potter-langgraph-rag/blob/main/index_books.ipynb): `index_books.ipynb`
- [Chunk embeddings](https://github.com/prongs394/harry-potter-langgraph-rag/blob/main/index_books.ipynb): `index_books.ipynb`
- [Vector index](https://github.com/prongs394/harry-potter-langgraph-rag/blob/main/index_books.ipynb): `index_books.ipynb`

### Other components

- **API client**
- **Local Ollama model**

## Connections

- API client → Chat endpoint: submits question (evidence: `README.md`)
- Chat endpoint → LangGraph workflow: invokes (evidence: `server.py`)
- LangGraph workflow → Retrieval step: starts at (evidence: `agent.py`)
- Retrieval step → Dense retrieval: calls (evidence: `agent.py`)
- Dense retrieval → Query embedding: encodes query (evidence: `retrieval.py`)
- Dense retrieval → ChromaDB collection: queries and reads (evidence: `retrieval.py`)
- Dense retrieval → Context expansion: assembles neighbors (evidence: `retrieval.py`)
- Dense retrieval → Cross-encoder reranking: scores candidates (evidence: `retrieval.py`)
- LangGraph workflow → Answer generation: then generates (evidence: `agent.py`)
- Answer generation → Local Ollama model: requests answer (evidence: `agent.py`)
- Answer generation → Answer check: checks answer (evidence: `agent.py`)
- Answer check → Question rewriting: may route to (evidence: `agent.py`)
- Question rewriting → Local Ollama model: requests rewrite (evidence: `agent.py`)
- Question rewriting → Retrieval step: retries retrieval (evidence: `agent.py`)
- PDF processing → Text chunking: extracts and chunks (evidence: `README.md`)
- Text chunking → Chunk embeddings: creates embeddings (evidence: `README.md`)
- Chunk embeddings → Vector index: prepares collection (evidence: `README.md`)
- Vector index → ChromaDB collection: provides runtime collection (evidence: `README.md`)
