# yousefahmednm8-png/rag-study-assistant architecture

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

- Interactive diagram: https://gitdiagram.com/yousefahmednm8-png/rag-study-assistant
- Repository: https://github.com/yousefahmednm8-png/rag-study-assistant

## Overview

RAG Study Assistant lets a learner upload PDF/TXT study materials, build a local searchable index, and ask questions answered with source citations. The documented flow is ingestion, chunking, embedding/indexing, dense retrieval, reranking, prompt construction, and Ollama generation; the Streamlit app handles upload and question interaction. The graph includes BM25 as a distinct evaluation capability and the FAISS-backed persistent store. Evidence for runtime links comes from excerpts and README; the deeper internals of generation and unexcerpted UI behavior were not inspected.

Main entry points: [`src/pipeline.py`](https://github.com/yousefahmednm8-png/rag-study-assistant/blob/main/src/pipeline.py) (RAG orchestrator), [`app.py`](https://github.com/yousefahmednm8-png/rag-study-assistant/blob/main/app.py) (Streamlit app), [`src/vector_store.py`](https://github.com/yousefahmednm8-png/rag-study-assistant/blob/main/src/vector_store.py) (FAISS vector store), [`evaluations/evaluate.py`](https://github.com/yousefahmednm8-png/rag-study-assistant/blob/main/evaluations/evaluate.py) (Retrieval evaluation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Study assistant UI"]
  node_app["Streamlit app<br/>[app.py]"]
end

subgraph group_ingest["Document preparation"]
  node_ingester["PDF/TXT loader<br/>[ingestion.py]"]
  node_chunker["Chunking and IDs<br/>[chunking.py]"]
end

subgraph group_search["Retrieval and ranking"]
  node_embed["E5 embeddings<br/>[embeddings.py]"]
  node_retriever["Dense retriever<br/>[retrieval.py]"]
  node_reranker["Cross-encoder reranker<br/>[reranker.py]"]
  node_bm25["BM25 retrieval<br/>[bm25_retrieval.py]"]
  node_eval["Retrieval evaluation<br/>[evaluate.py]"]
end

subgraph group_answer["Answer generation"]
  node_pipeline["RAG orchestrator<br/>[pipeline.py]"]
  node_generator["Ollama generator<br/>[generation.py]"]
end

subgraph group_storage["Index persistence"]
  node_store[("FAISS vector store<br/>[vector_store.py]")]
  node_faissdata[("Persisted index and documents")]
end

node_learner(("Learner"))
node_ollama{{"Ollama service"}}

node_learner -->|"uses"| node_app
node_app -->|"ingests uploads"| node_ingester
node_app -->|"chunks documents"| node_chunker
node_app -->|"builds and queries"| node_pipeline
node_pipeline -->|"embeds documents"| node_embed
node_pipeline -->|"indexes and saves"| node_store
node_app -->|"loads index"| node_store
node_store -->|"reads/writes"| node_faissdata
node_pipeline -->|"retrieves candidates"| node_retriever
node_retriever -->|"encodes query"| node_embed
node_retriever -->|"searches vectors"| node_store
node_pipeline -->|"reranks candidates"| node_reranker
node_pipeline -->|"generates answer"| node_generator
node_generator -->|"requests completion"| node_ollama
node_pipeline -->|"returns citations"| node_app
node_eval -->|"evaluates dense search"| node_retriever
node_eval -->|"evaluates lexical search"| node_bm25
node_eval -->|"tests reranking"| node_reranker
node_eval -->|"loads index"| node_store

click node_app "https://github.com/yousefahmednm8-png/rag-study-assistant/blob/main/app.py"
click node_ingester "https://github.com/yousefahmednm8-png/rag-study-assistant/blob/main/src/ingestion.py"
click node_chunker "https://github.com/yousefahmednm8-png/rag-study-assistant/blob/main/src/chunking.py"
click node_pipeline "https://github.com/yousefahmednm8-png/rag-study-assistant/blob/main/src/pipeline.py"
click node_embed "https://github.com/yousefahmednm8-png/rag-study-assistant/blob/main/src/embeddings.py"
click node_retriever "https://github.com/yousefahmednm8-png/rag-study-assistant/blob/main/src/retrieval.py"
click node_reranker "https://github.com/yousefahmednm8-png/rag-study-assistant/blob/main/src/reranker.py"
click node_bm25 "https://github.com/yousefahmednm8-png/rag-study-assistant/blob/main/src/bm25_retrieval.py"
click node_generator "https://github.com/yousefahmednm8-png/rag-study-assistant/blob/main/src/generation.py"
click node_store "https://github.com/yousefahmednm8-png/rag-study-assistant/blob/main/src/vector_store.py"
click node_faissdata "https://github.com/yousefahmednm8-png/rag-study-assistant/tree/main/data/vector_store"
click node_eval "https://github.com/yousefahmednm8-png/rag-study-assistant/blob/main/evaluations/evaluate.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_app toneBlue
class node_ingester,node_chunker toneAmber
class node_embed,node_retriever,node_reranker,node_bm25,node_eval toneMint
class node_pipeline,node_generator toneRose
class node_store,node_faissdata,node_learner,node_ollama toneIndigo
```

## Components

### Study assistant UI

- [Streamlit app](https://github.com/yousefahmednm8-png/rag-study-assistant/blob/main/app.py): `app.py`

### Document preparation

- [PDF/TXT loader](https://github.com/yousefahmednm8-png/rag-study-assistant/blob/main/src/ingestion.py): `src/ingestion.py`
- [Chunking and IDs](https://github.com/yousefahmednm8-png/rag-study-assistant/blob/main/src/chunking.py): `src/chunking.py`

### Retrieval and ranking

- [E5 embeddings](https://github.com/yousefahmednm8-png/rag-study-assistant/blob/main/src/embeddings.py): `src/embeddings.py`
- [Dense retriever](https://github.com/yousefahmednm8-png/rag-study-assistant/blob/main/src/retrieval.py): `src/retrieval.py`
- [Cross-encoder reranker](https://github.com/yousefahmednm8-png/rag-study-assistant/blob/main/src/reranker.py): `src/reranker.py`
- [BM25 retrieval](https://github.com/yousefahmednm8-png/rag-study-assistant/blob/main/src/bm25_retrieval.py): `src/bm25_retrieval.py`
- [Retrieval evaluation](https://github.com/yousefahmednm8-png/rag-study-assistant/blob/main/evaluations/evaluate.py): `evaluations/evaluate.py`

### Answer generation

- [RAG orchestrator](https://github.com/yousefahmednm8-png/rag-study-assistant/blob/main/src/pipeline.py): `src/pipeline.py`
- [Ollama generator](https://github.com/yousefahmednm8-png/rag-study-assistant/blob/main/src/generation.py): `src/generation.py`

### Index persistence

- [FAISS vector store](https://github.com/yousefahmednm8-png/rag-study-assistant/blob/main/src/vector_store.py): `src/vector_store.py`
- [Persisted index and documents](https://github.com/yousefahmednm8-png/rag-study-assistant/tree/main/data/vector_store): `data/vector_store`

### Other components

- **Learner**
- **Ollama service**

## Connections

- Learner → Streamlit app: uses (evidence: `README.md`)
- Streamlit app → PDF/TXT loader: ingests uploads (evidence: `app.py`)
- Streamlit app → Chunking and IDs: chunks documents (evidence: `app.py`)
- Streamlit app → RAG orchestrator: builds and queries (evidence: `app.py`)
- RAG orchestrator → E5 embeddings: embeds documents (evidence: `README.md`)
- RAG orchestrator → FAISS vector store: indexes and saves (evidence: `src/pipeline.py`)
- Streamlit app → FAISS vector store: loads index (evidence: `app.py`)
- FAISS vector store → Persisted index and documents: reads/writes (evidence: `README.md`)
- RAG orchestrator → Dense retriever: retrieves candidates (evidence: `src/pipeline.py`)
- Dense retriever → E5 embeddings: encodes query (evidence: `src/retrieval.py`)
- Dense retriever → FAISS vector store: searches vectors (evidence: `src/retrieval.py`)
- RAG orchestrator → Cross-encoder reranker: reranks candidates (evidence: `src/pipeline.py`)
- RAG orchestrator → Ollama generator: generates answer (evidence: `README.md`)
- Ollama generator → Ollama service: requests completion (evidence: `README.md`)
- RAG orchestrator → Streamlit app: returns citations (evidence: `app.py`)
- Retrieval evaluation → Dense retriever: evaluates dense search (evidence: `evaluations/evaluate.py`)
- Retrieval evaluation → BM25 retrieval: evaluates lexical search (evidence: `evaluations/evaluate.py`)
- Retrieval evaluation → Cross-encoder reranker: tests reranking (evidence: `evaluations/evaluate.py`)
- Retrieval evaluation → FAISS vector store: loads index (evidence: `evaluations/evaluate.py`)
