# shadab-sy/rag-based-college-assistance architecture

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

- Interactive diagram: https://gitdiagram.com/shadab-sy/rag-based-college-assistance
- Repository: https://github.com/shadab-sy/rag-based-college-assistance

## Overview

MHSSCE Knowledge Assistant lets users ask questions about the college’s official documents and receive evidence-grounded answers with citations. The main flow runs from the chat UI through the API and RAG pipeline, which retrieves and ranks document chunks before generating an answer. The repository also includes the corpus and a local vector store used for retrieval. The README documents OpenRouter generation and the frontend/backend connection; sampled source confirms key calls, but not every retrieval or generation detail.

Main entry points: [`backend/app/retrieval.py`](https://github.com/shadab-sy/rag-based-college-assistance/blob/main/backend/app/retrieval.py) (Hybrid retrieval), [`backend/app/main.py`](https://github.com/shadab-sy/rag-based-college-assistance/blob/main/backend/app/main.py) (FastAPI routes), [`backend/app/rag_pipeline.py`](https://github.com/shadab-sy/rag-based-college-assistance/blob/main/backend/app/rag_pipeline.py) (RAG pipeline), [`backend/app/vector_store.py`](https://github.com/shadab-sy/rag-based-college-assistance/blob/main/backend/app/vector_store.py) (Chroma vector store)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Chat client"]
  node_chat["Chat interface<br/>[App.jsx]"]
  node_webapi["API client<br/>[api.js]"]
end

subgraph group_service["Answer service"]
  node_api["FastAPI routes<br/>[main.py]"]
  node_pipeline["RAG pipeline<br/>[rag_pipeline.py]"]
  node_generator["Grounded generation<br/>[llm.py]"]
end

subgraph group_retrieval["Retrieval system"]
  node_retriever["Hybrid retrieval<br/>[retrieval.py]"]
  node_reranker["Cross-encoder reranker<br/>[reranker.py]"]
  node_embedder["Embedding manager<br/>[embeddings.py]"]
  node_metadata["Document metadata"]
  node_vectorstore[("Chroma vector store<br/>[vector_store.py]")]
end

subgraph group_corpus["Knowledge corpus"]
  node_chunks["Indexed chunks<br/>[chunks.json]"]
  node_approved["Approved source PDFs"]
  node_cleantext["Extracted document text"]
end

node_user(("Questioner"))
node_llmservice{{"OpenRouter"}}

node_user -->|"asks"| node_chat
node_chat -->|"submits question"| node_webapi
node_webapi -->|"posts question"| node_api
node_api -->|"invokes"| node_pipeline
node_pipeline -->|"retrieves evidence"| node_retriever
node_pipeline -->|"generates answer"| node_generator
node_generator -->|"requests completion"| node_llmservice
node_retriever -->|"embeds query"| node_embedder
node_retriever -->|"queries chunks"| node_vectorstore
node_retriever -->|"reranks candidates"| node_reranker
node_retriever -->|"normalizes years"| node_metadata
node_api -->|"counts chunks"| node_vectorstore
node_chunks -->|"provides index data"| node_vectorstore
node_approved -.->|"source for extraction"| node_cleantext
node_cleantext -.->|"source for chunking"| node_chunks

click node_chat "https://github.com/shadab-sy/rag-based-college-assistance/blob/main/frontend/src/App.jsx"
click node_webapi "https://github.com/shadab-sy/rag-based-college-assistance/blob/main/frontend/src/services/api.js"
click node_api "https://github.com/shadab-sy/rag-based-college-assistance/blob/main/backend/app/main.py"
click node_pipeline "https://github.com/shadab-sy/rag-based-college-assistance/blob/main/backend/app/rag_pipeline.py"
click node_generator "https://github.com/shadab-sy/rag-based-college-assistance/blob/main/backend/app/llm.py"
click node_retriever "https://github.com/shadab-sy/rag-based-college-assistance/blob/main/backend/app/retrieval.py"
click node_reranker "https://github.com/shadab-sy/rag-based-college-assistance/blob/main/backend/app/reranker.py"
click node_embedder "https://github.com/shadab-sy/rag-based-college-assistance/blob/main/backend/app/embeddings.py"
click node_metadata "https://github.com/shadab-sy/rag-based-college-assistance/blob/main/backend/app/document_metadata.py"
click node_vectorstore "https://github.com/shadab-sy/rag-based-college-assistance/blob/main/backend/app/vector_store.py"
click node_chunks "https://github.com/shadab-sy/rag-based-college-assistance/blob/main/MHSSCE_CHUNKS/chunks.json"
click node_approved "https://github.com/shadab-sy/rag-based-college-assistance/tree/main/MHSSCE_RAG_FINAL"
click node_cleantext "https://github.com/shadab-sy/rag-based-college-assistance/tree/main/MHSSCE_CLEAN_TEXT"

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_webapi toneBlue
class node_api,node_pipeline,node_generator toneAmber
class node_retriever,node_reranker,node_embedder,node_metadata,node_vectorstore,node_llmservice toneMint
class node_chunks,node_approved,node_cleantext toneRose
class node_user toneIndigo
```

## Components

### Chat client

- [Chat interface](https://github.com/shadab-sy/rag-based-college-assistance/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [API client](https://github.com/shadab-sy/rag-based-college-assistance/blob/main/frontend/src/services/api.js): `frontend/src/services/api.js`

### Answer service

- [FastAPI routes](https://github.com/shadab-sy/rag-based-college-assistance/blob/main/backend/app/main.py): `backend/app/main.py`
- [RAG pipeline](https://github.com/shadab-sy/rag-based-college-assistance/blob/main/backend/app/rag_pipeline.py): `backend/app/rag_pipeline.py`
- [Grounded generation](https://github.com/shadab-sy/rag-based-college-assistance/blob/main/backend/app/llm.py): `backend/app/llm.py`

### Retrieval system

- [Hybrid retrieval](https://github.com/shadab-sy/rag-based-college-assistance/blob/main/backend/app/retrieval.py): `backend/app/retrieval.py`
- [Cross-encoder reranker](https://github.com/shadab-sy/rag-based-college-assistance/blob/main/backend/app/reranker.py): `backend/app/reranker.py`
- [Embedding manager](https://github.com/shadab-sy/rag-based-college-assistance/blob/main/backend/app/embeddings.py): `backend/app/embeddings.py`
- [Document metadata](https://github.com/shadab-sy/rag-based-college-assistance/blob/main/backend/app/document_metadata.py): `backend/app/document_metadata.py`
- [Chroma vector store](https://github.com/shadab-sy/rag-based-college-assistance/blob/main/backend/app/vector_store.py): `backend/app/vector_store.py`

### Knowledge corpus

- [Indexed chunks](https://github.com/shadab-sy/rag-based-college-assistance/blob/main/MHSSCE_CHUNKS/chunks.json): `MHSSCE_CHUNKS/chunks.json`
- [Approved source PDFs](https://github.com/shadab-sy/rag-based-college-assistance/tree/main/MHSSCE_RAG_FINAL): `MHSSCE_RAG_FINAL`
- [Extracted document text](https://github.com/shadab-sy/rag-based-college-assistance/tree/main/MHSSCE_CLEAN_TEXT): `MHSSCE_CLEAN_TEXT`

### Other components

- **Questioner**
- **OpenRouter**

## Connections

- Questioner → Chat interface: asks (evidence: `README.md`)
- Chat interface → API client: submits question (evidence: `frontend/src/App.jsx`)
- API client → FastAPI routes: posts question (evidence: `frontend/src/services/api.js`)
- FastAPI routes → RAG pipeline: invokes (evidence: `backend/app/main.py`)
- RAG pipeline → Hybrid retrieval: retrieves evidence (evidence: `backend/app/rag_pipeline.py`)
- RAG pipeline → Grounded generation: generates answer (evidence: `backend/app/rag_pipeline.py`)
- Grounded generation → OpenRouter: requests completion (evidence: `README.md`)
- Hybrid retrieval → Embedding manager: embeds query (evidence: `backend/app/retrieval.py`)
- Hybrid retrieval → Chroma vector store: queries chunks (evidence: `backend/app/retrieval.py`)
- Hybrid retrieval → Cross-encoder reranker: reranks candidates (evidence: `backend/app/retrieval.py`)
- Hybrid retrieval → Document metadata: normalizes years (evidence: `backend/app/retrieval.py`)
- FastAPI routes → Chroma vector store: counts chunks (evidence: `backend/app/main.py`)
- Indexed chunks → Chroma vector store: provides index data (evidence: `README.md`)
- Approved source PDFs → Extracted document text: source for extraction
- Extracted document text → Indexed chunks: source for chunking
