# juaakash123/lesson-plan-creator-using-rag architecture

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

- Interactive diagram: https://gitdiagram.com/juaakash123/lesson-plan-creator-using-rag
- Repository: https://github.com/juaakash123/lesson-plan-creator-using-rag

## Overview

This is a temporary PDF question-answering chatbot that generates lesson plans from uploaded documents. A user uploads a PDF through the web/API layer; the server processes it into retrieval indexes and stores a conversational chain by session. Chat requests stream answers from that chain, while session listing and deletion provide basic lifecycle controls. The RAG implementation separates document preparation, hybrid retrieval and reranking, and answer generation. The source shows these stages in one module; relationships to external model services are based on configuration, not inspected service behavior.

Main entry points: [`app/main.py`](https://github.com/juaakash123/lesson-plan-creator-using-rag/blob/main/app/main.py) (FastAPI endpoints), [`app/rag_engine.py`](https://github.com/juaakash123/lesson-plan-creator-using-rag/blob/main/app/rag_engine.py) (BM25 and vector indexes), [`app/static/index.html`](https://github.com/juaakash123/lesson-plan-creator-using-rag/blob/main/app/static/index.html) (Web UI), [`app/dependencies.py`](https://github.com/juaakash123/lesson-plan-creator-using-rag/blob/main/app/dependencies.py) (Hugging Face embeddings)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Web and API"]
  node_web_ui["Web UI<br/>[index.html]"]
  node_api["FastAPI endpoints<br/>[main.py]"]
  node_schemas["Request and response schemas<br/>[model.py]"]
  node_pdf["Uploaded PDF"]
  node_answer["Streamed answer"]
end

subgraph group_rag["Document RAG"]
  node_pdf_ingest["PDF loading and chunking<br/>[rag_engine.py]"]
  node_retrieval_indexes["BM25 and vector indexes<br/>[rag_engine.py]"]
  node_hybrid_retrieval["Hybrid retrieval and reranking<br/>[rag_engine.py]"]
  node_lesson_prompt["Lesson-plan prompt and chain<br/>[rag_engine.py]"]
  node_conversation["Conversational RAG chain<br/>[rag_engine.py]"]
end

subgraph group_runtime["Models and sessions"]
  node_vector_store[("Chroma vector store<br/>[rag_engine.py]")]
  node_session_registry[("Active session registry<br/>[dependencies.py]")]
  node_chat_history[("Chat history store<br/>[rag_engine.py]")]
  node_embeddings["Hugging Face embeddings<br/>[dependencies.py]"]
  node_language_model["Gemini language model<br/>[dependencies.py]"]
  node_ranker["FlashRank reranker<br/>[rag_engine.py]"]
end

subgraph group_external["External services"]
  node_embedding_service{{"Embedding model service"}}
  node_llm_service{{"Google Gemini service"}}
end

node_user(("User"))

node_user -->|"uses"| node_web_ui
node_user -->|"requests"| node_api
node_web_ui -->|"serves through"| node_api
node_api -->|"validates with"| node_schemas
node_api -->|"receives"| node_pdf
node_api -->|"calls"| node_pdf_ingest
node_pdf_ingest -->|"splits into"| node_retrieval_indexes
node_retrieval_indexes -->|"embeds chunks"| node_embeddings
node_retrieval_indexes -->|"writes vectors"| node_vector_store
node_retrieval_indexes -->|"provides indexes"| node_hybrid_retrieval
node_hybrid_retrieval -->|"reranks results"| node_ranker
node_hybrid_retrieval -->|"supplies context"| node_lesson_prompt
node_lesson_prompt -->|"generates answer"| node_language_model
node_embeddings -.->|"calls"| node_embedding_service
node_language_model -.->|"calls"| node_llm_service
node_api -->|"checks and updates"| node_session_registry
node_api -->|"streams from"| node_conversation
node_conversation -->|"loads and saves"| node_chat_history
node_conversation -->|"yields"| node_answer
node_answer -->|"streams to"| node_user

click node_web_ui "https://github.com/juaakash123/lesson-plan-creator-using-rag/blob/main/app/static/index.html"
click node_api "https://github.com/juaakash123/lesson-plan-creator-using-rag/blob/main/app/main.py"
click node_schemas "https://github.com/juaakash123/lesson-plan-creator-using-rag/blob/main/app/model.py"
click node_pdf_ingest "https://github.com/juaakash123/lesson-plan-creator-using-rag/blob/main/app/rag_engine.py"
click node_retrieval_indexes "https://github.com/juaakash123/lesson-plan-creator-using-rag/blob/main/app/rag_engine.py"
click node_hybrid_retrieval "https://github.com/juaakash123/lesson-plan-creator-using-rag/blob/main/app/rag_engine.py"
click node_lesson_prompt "https://github.com/juaakash123/lesson-plan-creator-using-rag/blob/main/app/rag_engine.py"
click node_conversation "https://github.com/juaakash123/lesson-plan-creator-using-rag/blob/main/app/rag_engine.py"
click node_vector_store "https://github.com/juaakash123/lesson-plan-creator-using-rag/blob/main/app/rag_engine.py"
click node_session_registry "https://github.com/juaakash123/lesson-plan-creator-using-rag/blob/main/app/dependencies.py"
click node_chat_history "https://github.com/juaakash123/lesson-plan-creator-using-rag/blob/main/app/rag_engine.py"
click node_embeddings "https://github.com/juaakash123/lesson-plan-creator-using-rag/blob/main/app/dependencies.py"
click node_language_model "https://github.com/juaakash123/lesson-plan-creator-using-rag/blob/main/app/dependencies.py"
click node_ranker "https://github.com/juaakash123/lesson-plan-creator-using-rag/blob/main/app/rag_engine.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_web_ui,node_api,node_schemas,node_pdf,node_answer,node_user toneBlue
class node_pdf_ingest,node_retrieval_indexes,node_hybrid_retrieval,node_lesson_prompt,node_conversation toneAmber
class node_vector_store,node_session_registry,node_chat_history,node_embeddings,node_language_model,node_ranker toneMint
class node_embedding_service,node_llm_service toneRose
```

## Components

### Web and API

- [Web UI](https://github.com/juaakash123/lesson-plan-creator-using-rag/blob/main/app/static/index.html): `app/static/index.html`
- [FastAPI endpoints](https://github.com/juaakash123/lesson-plan-creator-using-rag/blob/main/app/main.py): `app/main.py`
- [Request and response schemas](https://github.com/juaakash123/lesson-plan-creator-using-rag/blob/main/app/model.py): `app/model.py`
- **Uploaded PDF**
- **Streamed answer**

### Document RAG

- [PDF loading and chunking](https://github.com/juaakash123/lesson-plan-creator-using-rag/blob/main/app/rag_engine.py): `app/rag_engine.py`
- [BM25 and vector indexes](https://github.com/juaakash123/lesson-plan-creator-using-rag/blob/main/app/rag_engine.py): `app/rag_engine.py`
- [Hybrid retrieval and reranking](https://github.com/juaakash123/lesson-plan-creator-using-rag/blob/main/app/rag_engine.py): `app/rag_engine.py`
- [Lesson-plan prompt and chain](https://github.com/juaakash123/lesson-plan-creator-using-rag/blob/main/app/rag_engine.py): `app/rag_engine.py`
- [Conversational RAG chain](https://github.com/juaakash123/lesson-plan-creator-using-rag/blob/main/app/rag_engine.py): `app/rag_engine.py`

### Models and sessions

- [Chroma vector store](https://github.com/juaakash123/lesson-plan-creator-using-rag/blob/main/app/rag_engine.py): `app/rag_engine.py`
- [Active session registry](https://github.com/juaakash123/lesson-plan-creator-using-rag/blob/main/app/dependencies.py): `app/dependencies.py`
- [Chat history store](https://github.com/juaakash123/lesson-plan-creator-using-rag/blob/main/app/rag_engine.py): `app/rag_engine.py`
- [Hugging Face embeddings](https://github.com/juaakash123/lesson-plan-creator-using-rag/blob/main/app/dependencies.py): `app/dependencies.py`
- [Gemini language model](https://github.com/juaakash123/lesson-plan-creator-using-rag/blob/main/app/dependencies.py): `app/dependencies.py`
- [FlashRank reranker](https://github.com/juaakash123/lesson-plan-creator-using-rag/blob/main/app/rag_engine.py): `app/rag_engine.py`

### External services

- **Embedding model service**
- **Google Gemini service**

### Other components

- **User**

## Connections

- User → Web UI: uses
- User → FastAPI endpoints: requests (evidence: `app/main.py`)
- Web UI → FastAPI endpoints: serves through (evidence: `app/main.py`)
- FastAPI endpoints → Request and response schemas: validates with (evidence: `app/main.py`)
- FastAPI endpoints → Uploaded PDF: receives (evidence: `app/main.py`)
- FastAPI endpoints → PDF loading and chunking: calls (evidence: `app/main.py`)
- PDF loading and chunking → BM25 and vector indexes: splits into (evidence: `app/rag_engine.py`)
- BM25 and vector indexes → Hugging Face embeddings: embeds chunks (evidence: `app/rag_engine.py`)
- BM25 and vector indexes → Chroma vector store: writes vectors (evidence: `app/rag_engine.py`)
- BM25 and vector indexes → Hybrid retrieval and reranking: provides indexes (evidence: `app/rag_engine.py`)
- Hybrid retrieval and reranking → FlashRank reranker: reranks results (evidence: `app/rag_engine.py`)
- Hybrid retrieval and reranking → Lesson-plan prompt and chain: supplies context (evidence: `app/rag_engine.py`)
- Lesson-plan prompt and chain → Gemini language model: generates answer (evidence: `app/rag_engine.py`)
- Hugging Face embeddings → Embedding model service: calls (evidence: `app/dependencies.py`)
- Gemini language model → Google Gemini service: calls (evidence: `app/dependencies.py`)
- FastAPI endpoints → Active session registry: checks and updates (evidence: `app/main.py`)
- FastAPI endpoints → Conversational RAG chain: streams from (evidence: `app/main.py`)
- Conversational RAG chain → Chat history store: loads and saves (evidence: `app/rag_engine.py`)
- Conversational RAG chain → Streamed answer: yields
- Streamed answer → User: streams to
