# fangedvampire/white_nights_rag_qa architecture

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

- Interactive diagram: https://gitdiagram.com/fangedvampire/white_nights_rag_qa
- Repository: https://github.com/fangedvampire/white_nights_rag_qa

## Overview

This repository is a command-line retrieval-augmented question-answering tool for asking questions about PDFs, with the supplied corpus centered on *White Nights*. Its main workflow loads PDF pages, splits them into overlapping text chunks, builds a vector index, retrieves relevant passages for a question, and generates an answer with source-page citations. Chunk persistence and configuration evaluation are additional capabilities. The graph follows explicit calls in the sampled source; the README contains only an architecture-diagram link, so it provides no further capability or relationship evidence.

Main entry points: [`src/pipeline.py`](https://github.com/fangedvampire/white_nights_rag_qa/blob/main/src/pipeline.py) (RAG pipeline), [`src/evaluate.py`](https://github.com/fangedvampire/white_nights_rag_qa/blob/main/src/evaluate.py) (Configuration evaluation), [`app.py`](https://github.com/fangedvampire/white_nights_rag_qa/blob/main/app.py) (Interactive CLI), [`src/chunking.py`](https://github.com/fangedvampire/white_nights_rag_qa/blob/main/src/chunking.py) (Text chunking)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Question interface"]
  node_cli["Interactive CLI<br/>[app.py]"]
end

subgraph group_rag["RAG workflow"]
  node_pipeline["RAG pipeline<br/>[pipeline.py]"]
  node_ingest["PDF page extraction<br/>[ingest.py]"]
  node_chunking["Text chunking<br/>[chunking.py]"]
  node_vector["Vector index and retrieval<br/>[embed_index.py]"]
  node_generator["Answer generation<br/>[generate.py]"]
end

subgraph group_storage["Corpus and chunks"]
  node_pdfs["PDF corpus"]
  node_chunkfiles["Saved chunks"]
end

subgraph group_evaluation["Configuration evaluation"]
  node_evaluation["Configuration evaluation<br/>[evaluate.py]"]
  node_questions["Evaluation questions"]
  node_results["Evaluation results<br/>[results.csv]"]
end

node_user(("Questioner"))

node_user -->|"asks"| node_cli
node_cli -->|"creates and queries"| node_pipeline
node_pipeline -->|"loads pages"| node_ingest
node_pdfs -->|"supplies PDFs"| node_ingest
node_pipeline -->|"chunks pages"| node_chunking
node_pipeline -->|"builds and searches"| node_vector
node_pipeline -->|"generates answer"| node_generator
node_pipeline -->|"returns answer and sources"| node_cli
node_chunking -->|"writes and reads"| node_chunkfiles
node_evaluation -->|"evaluates configurations"| node_pipeline
node_evaluation -->|"reuses generator"| node_generator
node_questions -->|"provides test set"| node_evaluation
node_evaluation -->|"writes metrics"| node_results

click node_cli "https://github.com/fangedvampire/white_nights_rag_qa/blob/main/app.py"
click node_pipeline "https://github.com/fangedvampire/white_nights_rag_qa/blob/main/src/pipeline.py"
click node_pdfs "https://github.com/fangedvampire/white_nights_rag_qa/tree/main/data/pdfs"
click node_ingest "https://github.com/fangedvampire/white_nights_rag_qa/blob/main/src/ingest.py"
click node_chunking "https://github.com/fangedvampire/white_nights_rag_qa/blob/main/src/chunking.py"
click node_chunkfiles "https://github.com/fangedvampire/white_nights_rag_qa/tree/main/data/chunks"
click node_vector "https://github.com/fangedvampire/white_nights_rag_qa/blob/main/src/embed_index.py"
click node_generator "https://github.com/fangedvampire/white_nights_rag_qa/blob/main/src/generate.py"
click node_evaluation "https://github.com/fangedvampire/white_nights_rag_qa/blob/main/src/evaluate.py"
click node_questions "https://github.com/fangedvampire/white_nights_rag_qa/blob/main/eval/test_questions.json"
click node_results "https://github.com/fangedvampire/white_nights_rag_qa/blob/main/results/results.csv"

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_cli toneBlue
class node_pipeline,node_ingest,node_chunking,node_vector,node_generator toneAmber
class node_pdfs,node_chunkfiles toneMint
class node_evaluation,node_questions,node_results toneRose
class node_user toneIndigo
```

## Components

### Question interface

- [Interactive CLI](https://github.com/fangedvampire/white_nights_rag_qa/blob/main/app.py): `app.py`

### RAG workflow

- [RAG pipeline](https://github.com/fangedvampire/white_nights_rag_qa/blob/main/src/pipeline.py): `src/pipeline.py`
- [PDF page extraction](https://github.com/fangedvampire/white_nights_rag_qa/blob/main/src/ingest.py): `src/ingest.py`
- [Text chunking](https://github.com/fangedvampire/white_nights_rag_qa/blob/main/src/chunking.py): `src/chunking.py`
- [Vector index and retrieval](https://github.com/fangedvampire/white_nights_rag_qa/blob/main/src/embed_index.py): `src/embed_index.py`
- [Answer generation](https://github.com/fangedvampire/white_nights_rag_qa/blob/main/src/generate.py): `src/generate.py`

### Corpus and chunks

- [PDF corpus](https://github.com/fangedvampire/white_nights_rag_qa/tree/main/data/pdfs): `data/pdfs`
- [Saved chunks](https://github.com/fangedvampire/white_nights_rag_qa/tree/main/data/chunks): `data/chunks`

### Configuration evaluation

- [Configuration evaluation](https://github.com/fangedvampire/white_nights_rag_qa/blob/main/src/evaluate.py): `src/evaluate.py`
- [Evaluation questions](https://github.com/fangedvampire/white_nights_rag_qa/blob/main/eval/test_questions.json): `eval/test_questions.json`
- [Evaluation results](https://github.com/fangedvampire/white_nights_rag_qa/blob/main/results/results.csv): `results/results.csv`

### Other components

- **Questioner**

## Connections

- Questioner → Interactive CLI: asks (evidence: `app.py`)
- Interactive CLI → RAG pipeline: creates and queries (evidence: `app.py`)
- RAG pipeline → PDF page extraction: loads pages (evidence: `src/pipeline.py`)
- PDF corpus → PDF page extraction: supplies PDFs
- RAG pipeline → Text chunking: chunks pages (evidence: `src/pipeline.py`)
- RAG pipeline → Vector index and retrieval: builds and searches (evidence: `src/pipeline.py`)
- RAG pipeline → Answer generation: generates answer (evidence: `src/pipeline.py`)
- RAG pipeline → Interactive CLI: returns answer and sources (evidence: `app.py`)
- Text chunking → Saved chunks: writes and reads (evidence: `src/chunking.py`)
- Configuration evaluation → RAG pipeline: evaluates configurations (evidence: `src/evaluate.py`)
- Configuration evaluation → Answer generation: reuses generator (evidence: `src/evaluate.py`)
- Evaluation questions → Configuration evaluation: provides test set (evidence: `src/evaluate.py`)
- Configuration evaluation → Evaluation results: writes metrics (evidence: `src/evaluate.py`)
