# prafullpatel-dev/collegeordinancechatbot-miniproject architecture

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

- Interactive diagram: https://gitdiagram.com/prafullpatel-dev/collegeordinancechatbot-miniproject
- Repository: https://github.com/prafullpatel-dev/collegeordinancechatbot-miniproject

## Overview

#### Purpose and entry points
This is a local Streamlit Retrieval-Augmented Generation (RAG) chatbot for querying uploaded DMPC ordinance PDFs. The runtime entry point is `app.py`, launched with `streamlit run app.py`. RAG orchestration is separated into `rag_backend.py`.

#### Presentation and session controller
`app.py` owns the browser-facing Streamlit interface: multi-PDF upload, explicit document processing, chat input/output, and controls to clear chat or reset the session. It maintains per-browser-session conversational state and the currently built retrieval pipeline rather than exposing an HTTP API or persistent multi-user service.

Paths: `app.py`

#### Document ingestion boundary
Uploaded PDF content enters through the UI and is handed to the backend for text extraction. The documented loader is LangChain `PyPDFLoader`; PDFs must contain extractable text, as no OCR service or preprocessing stage is present. This is the key boundary between untrusted user documents and the in-memory RAG corpus.

Paths: `app.py`, `rag_backend.py`

#### Chunking and embedding stage
The backend splits extracted ordinance text into overlapping chunks before indexing. Its architecture-level parameters are a chunk size of 1,000 characters and 200-character overlap. Each chunk is embedded with HuggingFace’s `sentence-transformers/all-MiniLM-L6-v2`, typically requiring model download/cache availability in the execution environment.

Paths: `rag_backend.py`, `requirements.txt`

#### Retrieval index
Embeddings are stored in a FAISS vector store created from the uploaded documents. At question time, the backend turns the store into a retriever configured to return the top three relevant chunks. The index is derived from the active upload/session rather than described as durable storage, so reprocessing or reset rebuilds/removes the available knowledge base.

Paths: `rag_backend.py`, `app.py`

#### Answer-generation chain
For each chat question, the application combines retrieved ordinance chunks with conversational history and submits the resulting context to a LangChain-managed LLM chain. The generation provider is Groq, using `llama-3.3-70b-versatile` (Llama 3.3 70B). The answer returns to `app.py` for rendering and addition to chat history.

Paths: `rag_backend.py`, `app.py`

#### Runtime dependencies and external services
The application is Python-based, with Streamlit, LangChain, FAISS, PDF loading, and HuggingFace embedding dependencies declared in `requirements.txt`. Groq is the material external inference service; its credential is supplied via `GROQ_API_KEY` in a root `.env` file. Local container development support exists in `.devcontainer/devcontainer.json`, but no deployment, database, object store, or server-side persistence is represented.

Paths: `requirements.txt`, `.devcontainer/devcontainer.json`, `app.py`

Main entry points: [`app.py`](https://github.com/prafullpatel-dev/collegeordinancechatbot-miniproject/blob/main/app.py) (Streamlit UI), [`rag_backend.py`](https://github.com/prafullpatel-dev/collegeordinancechatbot-miniproject/blob/main/rag_backend.py) (RAG orchestrator), [`requirements.txt`](https://github.com/prafullpatel-dev/collegeordinancechatbot-miniproject/blob/main/requirements.txt) (Python dependencies), [`.devcontainer/devcontainer.json`](https://github.com/prafullpatel-dev/collegeordinancechatbot-miniproject/blob/main/.devcontainer/devcontainer.json) (Dev container)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Streamlit session"]
  node_app["Streamlit UI<br/>Python entry point<br/>[app.py]"]
  node_session[("Session state<br/>in-memory state<br/>[app.py]")]
  node_uploads["Uploaded ordinance PDFs<br/>untrusted documents<br/>[app.py]"]
end

subgraph group_rag["RAG pipeline"]
  node_backend["RAG orchestrator<br/>Python backend<br/>[rag_backend.py]"]
  node_pdf_loader["PyPDFLoader<br/>PDF extraction<br/>[rag_backend.py]"]
  node_chunker["Text chunker<br/>chunking stage<br/>[rag_backend.py]"]
  node_embeddings["MiniLM embeddings<br/>HuggingFace model<br/>[rag_backend.py]"]
  node_faiss[("FAISS vector store<br/>session index<br/>[rag_backend.py]")]
  node_retriever["Top-3 retriever<br/>retrieval stage<br/>[rag_backend.py]"]
  node_answer_chain["Answer chain<br/>LangChain generation<br/>[rag_backend.py]"]
end

subgraph group_external["Runtime services"]
  node_groq{{"Groq Llama 3.3 70B<br/>external inference"}}
  node_dependencies["Python dependencies<br/>runtime dependencies<br/>[requirements.txt]"]
  node_devcontainer["Dev container<br/>local development<br/>[devcontainer.json]"]
end

node_user(("Local user<br/>actor"))

node_user -->|"uses"| node_app
node_app -->|"accepts"| node_uploads
node_app -->|"maintains"| node_session
node_app -->|"processes and queries"| node_backend
node_uploads -->|"submitted for indexing"| node_backend
node_backend -->|"extracts text"| node_pdf_loader
node_pdf_loader -->|"text"| node_chunker
node_chunker -->|"chunks"| node_embeddings
node_embeddings -->|"indexes vectors"| node_faiss
node_faiss -->|"searches"| node_retriever
node_retriever -->|"relevant chunks"| node_answer_chain
node_session -->|"chat history"| node_answer_chain
node_answer_chain -->|"generates answer"| node_groq
node_answer_chain -->|"answer"| node_app
node_backend -->|"active pipeline"| node_session
node_dependencies -.->|"supports runtime"| node_app
node_devcontainer -.->|"local development"| node_app

click node_app "https://github.com/prafullpatel-dev/collegeordinancechatbot-miniproject/blob/main/app.py"
click node_session "https://github.com/prafullpatel-dev/collegeordinancechatbot-miniproject/blob/main/app.py"
click node_uploads "https://github.com/prafullpatel-dev/collegeordinancechatbot-miniproject/blob/main/app.py"
click node_backend "https://github.com/prafullpatel-dev/collegeordinancechatbot-miniproject/blob/main/rag_backend.py"
click node_pdf_loader "https://github.com/prafullpatel-dev/collegeordinancechatbot-miniproject/blob/main/rag_backend.py"
click node_chunker "https://github.com/prafullpatel-dev/collegeordinancechatbot-miniproject/blob/main/rag_backend.py"
click node_embeddings "https://github.com/prafullpatel-dev/collegeordinancechatbot-miniproject/blob/main/rag_backend.py"
click node_faiss "https://github.com/prafullpatel-dev/collegeordinancechatbot-miniproject/blob/main/rag_backend.py"
click node_retriever "https://github.com/prafullpatel-dev/collegeordinancechatbot-miniproject/blob/main/rag_backend.py"
click node_answer_chain "https://github.com/prafullpatel-dev/collegeordinancechatbot-miniproject/blob/main/rag_backend.py"
click node_dependencies "https://github.com/prafullpatel-dev/collegeordinancechatbot-miniproject/blob/main/requirements.txt"
click node_devcontainer "https://github.com/prafullpatel-dev/collegeordinancechatbot-miniproject/blob/main/.devcontainer/devcontainer.json"

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,node_session,node_uploads toneBlue
class node_backend,node_pdf_loader,node_chunker,node_embeddings,node_faiss,node_retriever,node_answer_chain toneAmber
class node_groq,node_dependencies,node_devcontainer toneMint
class node_user toneNeutral
```

## Components

### Streamlit session

Browser-facing local application state.

- [Streamlit UI](https://github.com/prafullpatel-dev/collegeordinancechatbot-miniproject/blob/main/app.py): Python entry point · Handles uploads, processing controls, chat, and reset actions. · `app.py`
- [Session state](https://github.com/prafullpatel-dev/collegeordinancechatbot-miniproject/blob/main/app.py): in-memory state · Stores chat history and the active retrieval pipeline per browser session. · `app.py`
- [Uploaded ordinance PDFs](https://github.com/prafullpatel-dev/collegeordinancechatbot-miniproject/blob/main/app.py): untrusted documents · PDFs require extractable text because OCR is absent. · `app.py`

### RAG pipeline

In-memory document processing and question answering.

- [RAG orchestrator](https://github.com/prafullpatel-dev/collegeordinancechatbot-miniproject/blob/main/rag_backend.py): Python backend · `rag_backend.py`
- [PyPDFLoader](https://github.com/prafullpatel-dev/collegeordinancechatbot-miniproject/blob/main/rag_backend.py): PDF extraction · `rag_backend.py`
- [Text chunker](https://github.com/prafullpatel-dev/collegeordinancechatbot-miniproject/blob/main/rag_backend.py): chunking stage · Creates 1,000-character chunks with 200-character overlap. · `rag_backend.py`
- [MiniLM embeddings](https://github.com/prafullpatel-dev/collegeordinancechatbot-miniproject/blob/main/rag_backend.py): HuggingFace model · Uses sentence-transformers/all-MiniLM-L6-v2. · `rag_backend.py`
- [FAISS vector store](https://github.com/prafullpatel-dev/collegeordinancechatbot-miniproject/blob/main/rag_backend.py): session index · Derived from the active upload and rebuilt or removed on reset. · `rag_backend.py`
- [Top-3 retriever](https://github.com/prafullpatel-dev/collegeordinancechatbot-miniproject/blob/main/rag_backend.py): retrieval stage · `rag_backend.py`
- [Answer chain](https://github.com/prafullpatel-dev/collegeordinancechatbot-miniproject/blob/main/rag_backend.py): LangChain generation · Combines retrieved chunks and conversational history. · `rag_backend.py`

### Runtime services

Model and local runtime dependencies.

- **Groq Llama 3.3 70B**: external inference · llama-3.3-70b-versatile, authenticated with GROQ_API_KEY.
- [Python dependencies](https://github.com/prafullpatel-dev/collegeordinancechatbot-miniproject/blob/main/requirements.txt): runtime dependencies · Declares Streamlit, LangChain, FAISS, PDF, and embedding packages. · `requirements.txt`
- [Dev container](https://github.com/prafullpatel-dev/collegeordinancechatbot-miniproject/blob/main/.devcontainer/devcontainer.json): local development · `.devcontainer/devcontainer.json`

### Other components

- **Local user**: actor

## Connections

- Local user → Streamlit UI: uses
- Streamlit UI → Uploaded ordinance PDFs: accepts
- Streamlit UI → Session state: maintains
- Streamlit UI → RAG orchestrator: processes and queries
- Uploaded ordinance PDFs → RAG orchestrator: submitted for indexing
- RAG orchestrator → PyPDFLoader: extracts text
- PyPDFLoader → Text chunker: text
- Text chunker → MiniLM embeddings: chunks
- MiniLM embeddings → FAISS vector store: indexes vectors
- FAISS vector store → Top-3 retriever: searches
- Top-3 retriever → Answer chain: relevant chunks
- Session state → Answer chain: chat history
- Answer chain → Groq Llama 3.3 70B: generates answer
- Answer chain → Streamlit UI: answer
- RAG orchestrator → Session state: active pipeline
- Python dependencies → Streamlit UI: supports runtime
- Dev container → Streamlit UI: local development