# aman554-eq/physics-rag-chatbot architecture

> Architecture diagram of the GitHub repository aman554-eq/physics-rag-chatbot, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aman554-eq/physics-rag-chatbot
- Repository: https://github.com/aman554-eq/physics-rag-chatbot

## Overview

This is a physics education chatbot: a user starts an isolated chat, submits a question, and receives a streamed, physics-grounded answer. The README documents the retrieval, reranking, prompt selection, memory, and local-model capabilities; sampled backend code confirms session registration, retrieval/reranking helpers, answer streaming, and history updates. Several stages are documented but their connecting implementation was not fully sampled, so those links follow the documented architecture rather than uninspected source.

Main entry points: [`server/rag-5.5.py`](https://github.com/aman554-eq/physics-rag-chatbot/blob/main/server/rag-5.5.py) (Stream endpoint), [`client/app/(root)/[id]/page.tsx`](https://github.com/aman554-eq/physics-rag-chatbot/blob/main/client/app/(root)/%5Bid%5D/page.tsx) (Chat page), [`client/app/(root)/page.tsx`](https://github.com/aman554-eq/physics-rag-chatbot/blob/main/client/app/(root)/page.tsx) (Landing page), [`server/vector/index.faiss`](https://github.com/aman554-eq/physics-rag-chatbot/tree/main/server/vector/index.faiss) (FAISS index)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Chat interface"]
  node_landing["Landing page<br/>[page.tsx]"]
  node_chat["Chat page<br/>[page.tsx]"]
  node_session_header["Session controls<br/>[Header.tsx]"]
end

subgraph group_api["API and sessions"]
  node_api_question["Question endpoint<br/>[rag-5.5.py]"]
  node_stream_endpoint["Stream endpoint<br/>[rag-5.5.py]"]
  node_session_store[("Session history<br/>[rag-5.5.py]")]
end

subgraph group_rag["Answer generation"]
  node_retrieval["Hybrid retrieval<br/>[rag-5.5.py]"]
  node_faiss["FAISS search<br/>[rag-5.5.py]"]
  node_dense["Dense search<br/>[rag-5.5.py]"]
  node_reranking["Cross-encoder reranking<br/>[rag-5.5.py]"]
  node_prompt_router["Prompt routing<br/>[rag-5.5.py]"]
  node_history_retriever["History-aware retrieval<br/>[rag-5.5.py]"]
  node_generation["Answer generation<br/>[rag-5.5.py]"]
end

subgraph group_knowledge["Knowledge base"]
  node_knowledge_source["Physics text<br/>[book.txt]"]
  node_chunking["Document splitting<br/>[rag-5.5.py]"]
  node_vector_index[("FAISS index<br/>[index.faiss]")]
end

node_user(("Physics learner"))
node_ollama["Ollama Gemma2"]
node_embedding_model["Embedding models"]

node_user -->|"opens app"| node_landing
node_landing -->|"starts session"| node_chat
node_user -->|"asks question"| node_chat
node_chat -->|"registers question"| node_api_question
node_api_question -->|"initializes session"| node_session_store
node_chat -->|"opens SSE stream"| node_stream_endpoint
node_stream_endpoint -->|"reads history"| node_session_store
node_stream_endpoint -->|"retrieves context"| node_retrieval
node_retrieval -->|"searches index"| node_faiss
node_retrieval -->|"searches embeddings"| node_dense
node_faiss -->|"searches"| node_vector_index
node_retrieval -->|"ranks candidates"| node_reranking
node_stream_endpoint -->|"selects prompt"| node_prompt_router
node_stream_endpoint -->|"reformulates with history"| node_history_retriever
node_stream_endpoint -->|"streams answer"| node_generation
node_generation -->|"requests completion"| node_ollama
node_stream_endpoint -->|"stores conversation"| node_session_store
node_stream_endpoint -->|"sends SSE tokens"| node_chat
node_chat -->|"renders answer"| node_user
node_session_header -->|"deletes session"| node_session_store
node_knowledge_source -->|"splits into chunks"| node_chunking
node_chunking -->|"builds index"| node_vector_index
node_embedding_model -->|"encodes documents"| node_dense

click node_landing "https://github.com/aman554-eq/physics-rag-chatbot/blob/main/client/app/(root)/page.tsx"
click node_chat "https://github.com/aman554-eq/physics-rag-chatbot/blob/main/client/app/(root)/%5Bid%5D/page.tsx"
click node_session_header "https://github.com/aman554-eq/physics-rag-chatbot/blob/main/client/app/components/Header.tsx"
click node_api_question "https://github.com/aman554-eq/physics-rag-chatbot/blob/main/server/rag-5.5.py"
click node_stream_endpoint "https://github.com/aman554-eq/physics-rag-chatbot/blob/main/server/rag-5.5.py"
click node_session_store "https://github.com/aman554-eq/physics-rag-chatbot/blob/main/server/rag-5.5.py"
click node_retrieval "https://github.com/aman554-eq/physics-rag-chatbot/blob/main/server/rag-5.5.py"
click node_faiss "https://github.com/aman554-eq/physics-rag-chatbot/blob/main/server/rag-5.5.py"
click node_dense "https://github.com/aman554-eq/physics-rag-chatbot/blob/main/server/rag-5.5.py"
click node_reranking "https://github.com/aman554-eq/physics-rag-chatbot/blob/main/server/rag-5.5.py"
click node_prompt_router "https://github.com/aman554-eq/physics-rag-chatbot/blob/main/server/rag-5.5.py"
click node_history_retriever "https://github.com/aman554-eq/physics-rag-chatbot/blob/main/server/rag-5.5.py"
click node_generation "https://github.com/aman554-eq/physics-rag-chatbot/blob/main/server/rag-5.5.py"
click node_knowledge_source "https://github.com/aman554-eq/physics-rag-chatbot/blob/main/server/data_extraction/book.txt"
click node_chunking "https://github.com/aman554-eq/physics-rag-chatbot/blob/main/server/rag-5.5.py"
click node_vector_index "https://github.com/aman554-eq/physics-rag-chatbot/tree/main/server/vector/index.faiss"

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_landing,node_chat,node_session_header toneBlue
class node_api_question,node_stream_endpoint,node_session_store toneAmber
class node_retrieval,node_faiss,node_dense,node_reranking,node_prompt_router,node_history_retriever,node_generation toneMint
class node_knowledge_source,node_chunking,node_vector_index toneRose
class node_user,node_ollama,node_embedding_model toneIndigo
```

## Components

### Chat interface

- [Landing page](https://github.com/aman554-eq/physics-rag-chatbot/blob/main/client/app/(root)/page.tsx): `client/app/(root)/page.tsx`
- [Chat page](https://github.com/aman554-eq/physics-rag-chatbot/blob/main/client/app/(root)/%5Bid%5D/page.tsx): `client/app/(root)/[id]/page.tsx`
- [Session controls](https://github.com/aman554-eq/physics-rag-chatbot/blob/main/client/app/components/Header.tsx): `client/app/components/Header.tsx`

### API and sessions

- [Question endpoint](https://github.com/aman554-eq/physics-rag-chatbot/blob/main/server/rag-5.5.py): `server/rag-5.5.py`
- [Stream endpoint](https://github.com/aman554-eq/physics-rag-chatbot/blob/main/server/rag-5.5.py): `server/rag-5.5.py`
- [Session history](https://github.com/aman554-eq/physics-rag-chatbot/blob/main/server/rag-5.5.py): `server/rag-5.5.py`

### Answer generation

- [Hybrid retrieval](https://github.com/aman554-eq/physics-rag-chatbot/blob/main/server/rag-5.5.py): `server/rag-5.5.py`
- [FAISS search](https://github.com/aman554-eq/physics-rag-chatbot/blob/main/server/rag-5.5.py): `server/rag-5.5.py`
- [Dense search](https://github.com/aman554-eq/physics-rag-chatbot/blob/main/server/rag-5.5.py): `server/rag-5.5.py`
- [Cross-encoder reranking](https://github.com/aman554-eq/physics-rag-chatbot/blob/main/server/rag-5.5.py): `server/rag-5.5.py`
- [Prompt routing](https://github.com/aman554-eq/physics-rag-chatbot/blob/main/server/rag-5.5.py): `server/rag-5.5.py`
- [History-aware retrieval](https://github.com/aman554-eq/physics-rag-chatbot/blob/main/server/rag-5.5.py): `server/rag-5.5.py`
- [Answer generation](https://github.com/aman554-eq/physics-rag-chatbot/blob/main/server/rag-5.5.py): `server/rag-5.5.py`

### Knowledge base

- [Physics text](https://github.com/aman554-eq/physics-rag-chatbot/blob/main/server/data_extraction/book.txt): `server/data_extraction/book.txt`
- [Document splitting](https://github.com/aman554-eq/physics-rag-chatbot/blob/main/server/rag-5.5.py): `server/rag-5.5.py`
- [FAISS index](https://github.com/aman554-eq/physics-rag-chatbot/tree/main/server/vector/index.faiss): `server/vector/index.faiss`

### Other components

- **Physics learner**
- **Ollama Gemma2**
- **Embedding models**

## Connections

- Physics learner → Landing page: opens app
- Landing page → Chat page: starts session
- Physics learner → Chat page: asks question
- Chat page → Question endpoint: registers question
- Question endpoint → Session history: initializes session
- Chat page → Stream endpoint: opens SSE stream
- Stream endpoint → Session history: reads history
- Stream endpoint → Hybrid retrieval: retrieves context
- Hybrid retrieval → FAISS search: searches index
- Hybrid retrieval → Dense search: searches embeddings
- FAISS search → FAISS index: searches
- Hybrid retrieval → Cross-encoder reranking: ranks candidates
- Stream endpoint → Prompt routing: selects prompt
- Stream endpoint → History-aware retrieval: reformulates with history
- Stream endpoint → Answer generation: streams answer
- Answer generation → Ollama Gemma2: requests completion
- Stream endpoint → Session history: stores conversation
- Stream endpoint → Chat page: sends SSE tokens
- Chat page → Physics learner: renders answer
- Session controls → Session history: deletes session
- Physics text → Document splitting: splits into chunks
- Document splitting → FAISS index: builds index
- Embedding models → Dense search: encodes documents