# veneel77/rag-based-knowledge-assistant architecture

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

- Interactive diagram: https://gitdiagram.com/veneel77/rag-based-knowledge-assistant
- Repository: https://github.com/veneel77/rag-based-knowledge-assistant

## Overview

#### Purpose and Entry Points
This repository is a document-scoped RAG knowledge assistant: authenticated users upload PDF/TXT/DOCX files and ask questions grounded in retrieved document chunks. The service entry point is FastAPI in `backend/app/main.py`; the Streamlit client entry is root-level `app.py` (despite the README’s older `frontend/app.py` layout). Local prebuilt/indexing artifacts also exist in `faiss.index`, `meta.pkl`, and `ingest_index.py`.

#### Client/API Boundary
The Streamlit UI provides registration/login, document upload, chat, citations, and history views, then calls the FastAPI REST service. API routing is separated by resource:
- Authentication: `backend/app/api/auth_api.py`
- Document ingestion and management: `backend/app/api/upload.py`
- Question answering: `backend/app/api/query.py`
- Conversation history: `backend/app/api/history.py`

JWT authentication is the boundary enforcing user identity and document isolation across these routes.

#### Identity and Persistent Metadata
Authentication hashes passwords and issues/verifies JWTs through `backend/app/auth/auth.py` and `backend/app/auth/jwt.py`. SQLAlchemy-backed persistence in `backend/app/models/database.py` stores user, document/chunk metadata, and query history. SQLite is the intended current datastore, creating a single-node persistence boundary rather than a distributed database service.

#### Ingestion Pipeline
Upload processing coordinates the RAG write path:
1. Receive and validate the uploaded file in `backend/app/api/upload.py`.
2. Extract text from supported file formats in `backend/app/rag/loader.py`.
3. Split text into overlapping chunks in `backend/app/rag/chunker.py`.
4. Produce MiniLM embeddings in `backend/app/rag/embedder.py`.
5. Persist/search vectors via FAISS in `backend/app/rag/vector_store.py`, while document/chunk metadata is recorded in the database.

The upload endpoint is therefore the transaction-like integration point between filesystem upload data, SQL metadata, and vector-index state.

#### Retrieval and Generation Pipeline
A query enters `backend/app/api/query.py`, where retrieval orchestration in `backend/app/rag/retriever.py` embeds the user question and performs top-K similarity search against FAISS. Retrieved chunks and associated metadata become grounded context for `backend/app/rag/generator.py`, which calls Google Gemini and returns an answer plus source citations/similarity information. Query/answer records flow to `backend/app/api/history.py` and the database for later display.

#### Configuration, Runtimes, and External Dependencies
Runtime configuration, including Gemini credentials, JWT secret, chunk parameters, retrieval count, and limits, is centralized in `backend/app/config.py`, with `env.example` as the environment contract. Material dependencies are Python 3.10+, FastAPI/Uvicorn, Streamlit, SQLAlchemy/SQLite, sentence-transformers (`all-MiniLM-L6-v2`), FAISS, and Google Gemini API. Gemini is the only required remote inference service; embedding and vector search are intended to run locally.

#### Deployment Shape
The repository supports a two-container deployment: backend image definition in `backend/Dockerfile`, frontend image definition in `frontend/Dockerfile`, and composition/networking through `docker-compose.yml`. The API is expected on port 8000 and Streamlit on 8501. This is a single-host architecture with local SQLite and FAISS state, so stateful volumes and coordinated index/database updates are operationally important.

Main entry points: [`backend/app/main.py`](https://github.com/veneel77/rag-based-knowledge-assistant/blob/main/backend/app/main.py) (FastAPI entry), [`backend/app/rag/retriever.py`](https://github.com/veneel77/rag-based-knowledge-assistant/blob/main/backend/app/rag/retriever.py) (Retrieval orchestration), [`backend/app/api/upload.py`](https://github.com/veneel77/rag-based-knowledge-assistant/blob/main/backend/app/api/upload.py) (Upload routes), [`backend/app/api/query.py`](https://github.com/veneel77/rag-based-knowledge-assistant/blob/main/backend/app/api/query.py) (Query routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client"]
  node_streamlit["Streamlit UI<br/>client<br/>[app.py]"]
end

subgraph group_api["FastAPI service"]
  node_fastapi["FastAPI entry<br/>[main.py]"]
  node_auth_api["Auth routes<br/>API routes<br/>[auth_api.py]"]
  node_upload_api["Upload routes<br/>API routes<br/>[upload.py]"]
  node_query_api["Query routes<br/>API routes<br/>[query.py]"]
  node_history_api["History routes<br/>API routes<br/>[history.py]"]
  node_identity["Password + JWT<br/>identity<br/>[auth.py]"]
  node_jwt["JWT implementation<br/>security<br/>[jwt.py]"]
  node_config["Runtime configuration<br/>[config.py]"]
end

subgraph group_ingestion["Ingestion pipeline"]
  node_loader["Text extraction<br/>ingestion stage<br/>[loader.py]"]
  node_chunker["Chunking<br/>ingestion stage<br/>[chunker.py]"]
end

subgraph group_rag["Retrieval and generation"]
  node_embedder["MiniLM embeddings<br/>local model<br/>[embedder.py]"]
  node_retriever["Retrieval orchestration<br/>RAG stage<br/>[retriever.py]"]
  node_generator["Grounded generator<br/>RAG stage<br/>[generator.py]"]
end

subgraph group_state["Local state"]
  node_vector_store[("FAISS vector store<br/>vector index<br/>[vector_store.py]")]
  node_database[("SQLite metadata DB<br/>SQLAlchemy persistence<br/>[database.py]")]
end

subgraph group_external["External inference"]
  node_gemini{{"Google Gemini<br/>remote LLM API"}}
end

node_streamlit -->|"REST + JWT"| node_fastapi
node_fastapi -->|"routes"| node_auth_api
node_fastapi -->|"routes"| node_upload_api
node_fastapi -->|"routes"| node_query_api
node_fastapi -->|"routes"| node_history_api
node_auth_api -->|"authenticate"| node_identity
node_identity -->|"issue / verify"| node_jwt
node_upload_api -->|"extract text"| node_loader
node_loader -->|"text"| node_chunker
node_chunker -->|"chunks"| node_embedder
node_embedder -->|"chunk vectors"| node_vector_store
node_upload_api -->|"document + chunk metadata"| node_database
node_query_api -->|"question"| node_retriever
node_retriever -->|"embed question"| node_embedder
node_retriever -->|"top-K search"| node_vector_store
node_retriever -->|"chunk metadata"| node_database
node_retriever -->|"grounded chunks"| node_generator
node_generator -->|"generate answer"| node_gemini
node_query_api -->|"query / answer record"| node_history_api
node_history_api -->|"history"| node_database
node_config -.->|"JWT settings"| node_identity
node_config -.->|"Gemini credentials"| node_generator

click node_streamlit "https://github.com/veneel77/rag-based-knowledge-assistant/blob/main/app.py"
click node_fastapi "https://github.com/veneel77/rag-based-knowledge-assistant/blob/main/backend/app/main.py"
click node_auth_api "https://github.com/veneel77/rag-based-knowledge-assistant/blob/main/backend/app/api/auth_api.py"
click node_upload_api "https://github.com/veneel77/rag-based-knowledge-assistant/blob/main/backend/app/api/upload.py"
click node_query_api "https://github.com/veneel77/rag-based-knowledge-assistant/blob/main/backend/app/api/query.py"
click node_history_api "https://github.com/veneel77/rag-based-knowledge-assistant/blob/main/backend/app/api/history.py"
click node_identity "https://github.com/veneel77/rag-based-knowledge-assistant/blob/main/backend/app/auth/auth.py"
click node_jwt "https://github.com/veneel77/rag-based-knowledge-assistant/blob/main/backend/app/auth/jwt.py"
click node_loader "https://github.com/veneel77/rag-based-knowledge-assistant/blob/main/backend/app/rag/loader.py"
click node_chunker "https://github.com/veneel77/rag-based-knowledge-assistant/blob/main/backend/app/rag/chunker.py"
click node_embedder "https://github.com/veneel77/rag-based-knowledge-assistant/blob/main/backend/app/rag/embedder.py"
click node_vector_store "https://github.com/veneel77/rag-based-knowledge-assistant/blob/main/backend/app/rag/vector_store.py"
click node_retriever "https://github.com/veneel77/rag-based-knowledge-assistant/blob/main/backend/app/rag/retriever.py"
click node_generator "https://github.com/veneel77/rag-based-knowledge-assistant/blob/main/backend/app/rag/generator.py"
click node_database "https://github.com/veneel77/rag-based-knowledge-assistant/blob/main/backend/app/models/database.py"
click node_config "https://github.com/veneel77/rag-based-knowledge-assistant/blob/main/backend/app/config.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_streamlit toneBlue
class node_fastapi,node_auth_api,node_upload_api,node_query_api,node_history_api,node_identity,node_jwt,node_config toneAmber
class node_loader,node_chunker toneMint
class node_embedder,node_retriever,node_generator toneRose
class node_vector_store,node_database toneIndigo
class node_gemini toneTeal
```

## Components

### Client

- [Streamlit UI](https://github.com/veneel77/rag-based-knowledge-assistant/blob/main/app.py): client · Registration, uploads, chat, citations, and history. · `app.py`

### FastAPI service

- [FastAPI entry](https://github.com/veneel77/rag-based-knowledge-assistant/blob/main/backend/app/main.py): service · Authenticated REST API on port 8000. · `backend/app/main.py`
- [Auth routes](https://github.com/veneel77/rag-based-knowledge-assistant/blob/main/backend/app/api/auth_api.py): API routes · `backend/app/api/auth_api.py`
- [Upload routes](https://github.com/veneel77/rag-based-knowledge-assistant/blob/main/backend/app/api/upload.py): API routes · Coordinates file validation, metadata, and indexing. · `backend/app/api/upload.py`
- [Query routes](https://github.com/veneel77/rag-based-knowledge-assistant/blob/main/backend/app/api/query.py): API routes · `backend/app/api/query.py`
- [History routes](https://github.com/veneel77/rag-based-knowledge-assistant/blob/main/backend/app/api/history.py): API routes · `backend/app/api/history.py`
- [Password + JWT](https://github.com/veneel77/rag-based-knowledge-assistant/blob/main/backend/app/auth/auth.py): identity · Hashes passwords and issues/verifies JWTs. · `backend/app/auth/auth.py`
- [JWT implementation](https://github.com/veneel77/rag-based-knowledge-assistant/blob/main/backend/app/auth/jwt.py): security · `backend/app/auth/jwt.py`
- [Runtime configuration](https://github.com/veneel77/rag-based-knowledge-assistant/blob/main/backend/app/config.py): configuration · Centralizes credentials, limits, chunking, and retrieval settings. · `backend/app/config.py`

### Ingestion pipeline

- [Text extraction](https://github.com/veneel77/rag-based-knowledge-assistant/blob/main/backend/app/rag/loader.py): ingestion stage · Extracts supported PDF, TXT, and DOCX content. · `backend/app/rag/loader.py`
- [Chunking](https://github.com/veneel77/rag-based-knowledge-assistant/blob/main/backend/app/rag/chunker.py): ingestion stage · Creates overlapping text chunks. · `backend/app/rag/chunker.py`

### Retrieval and generation

- [MiniLM embeddings](https://github.com/veneel77/rag-based-knowledge-assistant/blob/main/backend/app/rag/embedder.py): local model · Embeds chunks and user questions locally. · `backend/app/rag/embedder.py`
- [Retrieval orchestration](https://github.com/veneel77/rag-based-knowledge-assistant/blob/main/backend/app/rag/retriever.py): RAG stage · Embeds questions and retrieves top-K chunks. · `backend/app/rag/retriever.py`
- [Grounded generator](https://github.com/veneel77/rag-based-knowledge-assistant/blob/main/backend/app/rag/generator.py): RAG stage · Builds cited context and generates answers. · `backend/app/rag/generator.py`

### Local state

Single-host persistent metadata and vector index.

- [FAISS vector store](https://github.com/veneel77/rag-based-knowledge-assistant/blob/main/backend/app/rag/vector_store.py): vector index · Persists vectors and executes similarity search. · `backend/app/rag/vector_store.py`
- [SQLite metadata DB](https://github.com/veneel77/rag-based-knowledge-assistant/blob/main/backend/app/models/database.py): SQLAlchemy persistence · Stores users, documents, chunks, and query history. · `backend/app/models/database.py`

### External inference

- **Google Gemini**: remote LLM API · Required remote answer-generation service.

## Connections

- Streamlit UI → FastAPI entry: REST + JWT
- FastAPI entry → Auth routes: routes
- FastAPI entry → Upload routes: routes
- FastAPI entry → Query routes: routes
- FastAPI entry → History routes: routes
- Auth routes → Password + JWT: authenticate
- Password + JWT → JWT implementation: issue / verify
- Upload routes → Text extraction: extract text
- Text extraction → Chunking: text
- Chunking → MiniLM embeddings: chunks
- MiniLM embeddings → FAISS vector store: chunk vectors
- Upload routes → SQLite metadata DB: document + chunk metadata
- Query routes → Retrieval orchestration: question
- Retrieval orchestration → MiniLM embeddings: embed question
- Retrieval orchestration → FAISS vector store: top-K search
- Retrieval orchestration → SQLite metadata DB: chunk metadata
- Retrieval orchestration → Grounded generator: grounded chunks
- Grounded generator → Google Gemini: generate answer
- Query routes → History routes: query / answer record
- History routes → SQLite metadata DB: history
- Runtime configuration → Password + JWT: JWT settings
- Runtime configuration → Grounded generator: Gemini credentials
