igoralekseev-dev/rag-vector-chat

1. This repository is a self-hosted RAG chat application built as a FastAPI backend with server-rendered HTML. The UI is not a SPA: it uses Jinja2 templates plus HTMX-style partial updates to refresh chat, document, and message fragments from the server.

2. The codebase is split into two main application domains: chat and documents. chat owns chat lifecycle, message history, and response generation. documents owns PDF upload, parsing, chunking, embedding, and indexing into the vector store.

3. src/main.py is the application bootstrap point. It likely assembles the FastAPI app, registers routers from both domains, and wires startup configuration and shared dependencies such as database and vector/LLM clients.

4. src/config.py centralizes runtime settings from environment variables, including the SQLite database URL, Qdrant endpoint, and OpenAI-compatible LLM credentials/model name. This makes the app portable across local and Docker Compose deployments.

5. src/database.py is the relational persistence boundary. The README indicates SQLite is used to store chat history, messages, and uploaded file metadata. This relational layer keeps the app lightweight and acts as the source of truth for chat/session state.

6. The vector-search boundary is Qdrant. Documents are split into chunks, embedded with Sentence Transformers, and stored in Qdrant with metadata tied to chat_id. That chat_id filter is the key isolation mechanism that prevents retrieval from mixing content across chats.

7. The documents subsystem likely follows a pipeline: receive PDF upload through documents/router.py, parse and normalize file content in documents/utils.py, then persist document records and upsert vectors via documents/service.py. The relational DB records the file, while Qdrant stores the semantic index.

8. The chat subsystem exposes routes for creating/opening chats and sending messages. chat/models.py and chat/schemas.py define the data shape for persisted chat entities and API/request-response payloads, while chat/service.py handles the business logic for message persistence, retrieval of relevant chunks, prompt assembly, and calling the language model.

9. LLM generation is externalized behind an OpenAI-compatible API. The repository does not appear to hardcode a specific provider; instead, the model endpoint, API key, and model name are configurable, which is an important architectural boundary for swapping providers without changing the UI or domain logic.

10. The rendered UI is composed of reusable partials under src/templates/partials/. These fragments correspond to distinct functional areas such as the sidebar chat list, the active chat workspace, message pairs, document cards, and “new chat” responses. That indicates a page layout driven by incremental server-side updates rather than client-side state management.

11. The end-to-end data flow is: user creates/selects a chat, uploads one or more PDFs, documents are chunked and indexed, then the user asks a question. On message submit, the backend searches Qdrant only within that chat, injects the relevant context into the prompt, sends it to the LLM, stores the answer in SQLite, and returns updated HTML fragments to the browser.

12. Deployment is designed around local or containerized execution. docker-compose.yml runs the app alongside Qdrant, and the README notes that the project can be run entirely self-hosted. The dependency set in pyproject.toml supports async Python web execution, PDF parsing, vector search, and templated HTML rendering.

13. From an architecture-diagram perspective, the important boundaries are: browser/UI, FastAPI server, SQLite relational store, Qdrant vector store, and external LLM API. The chat and documents modules sit inside the FastAPI boundary as separate vertical slices that share config and database infrastructure but have distinct responsibilities.