# rrpatil-1/qna_rag_doc_management architecture

> Architecture diagram of the GitHub repository rrpatil-1/qna_rag_doc_management, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rrpatil-1/qna_rag_doc_management
- Repository: https://github.com/rrpatil-1/qna_rag_doc_management

## Overview

##### Project Type & Purpose
- The project is a full-stack backend system built to support a QnA system with Retrieval-Augmented Generation (RAG). Its main purpose is to answer user questions by retrieving relevant document context (from a PostgreSQL vector database) and processing it using an LLM (via Ollama).
- Key functionalities include document ingestion, document processing, question answering, and listing available documents.

##### Major System Components
a. Backend Application:
- Contains the main business logic with the core modules organized under various directories:
- db_service – Manages database operations and connections, including SQL and vector database (pgvector) functionality.
- document_process – Handles processing and parsing of PDF documents.
- driver_services – Exposes API endpoints for ingestion, QA, and document listing.
- llm_service – Responsible for interfacing with the Ollama language model; includes a dedicated module for Ollama integration.
- utils – Contains logger, custom exceptions, parameter checks, etc.
b. Database Service:
- PostgreSQL with the pgvector extension is used, as indicated in the docker_compose.yaml.
c. Language Model Service:
- Uses Ollama as the LLM provider. There’s an Ollama-specific Dockerfile and startup script (pull-llama3.sh) to manage the model.
d. Containerization & Deployment:
- Dockerfiles for both backend and Ollama, along with a docker-compose file (in the deployment directory) that ties together the backend, the pgvector database, and the Ollama service on a defined network.
e. API Endpoints & External Interfaces:
- Endpoints include /ollamahealth, /qa_service, /ingest_documents, and /list_documents. These expose the system’s capabilities via REST.
f. Configuration & Environment Variables:
- The .env file provides necessary configurations for connecting to the database and the LLM service.

##### Interactions and Data Flows
- Incoming API requests (for QA, ingestion, document listing) are routed to the backend’s driver_services modules.
- For document ingestion, files are passed through the document_process modules for parsing (specifically handling PDFs).
- The database service (via db_service) manages storage and retrieval of document embeddings and metadata.
- When a query is received at the /qa_service endpoint, the query is processed by:
- Retrieving relevant document context using vector search against PostgreSQL (with pgvector).
- Sending the context to the llm_service (specifically the Ollama integration) for language model processing.
- Responses flow back from the database and the language model to the user via the backend API.

##### Architectural Patterns & Principles
- Modular and Layered Architecture: The code distinguishes separate services (db_service, document_process, driver_services, llm_service). Clearly defined modules ensure that components can be understood, tested, and maintained independently.
- Containerization: The services are containerized using Docker, promoting isolated and consistent deployments. Docker Compose orchestrates the multi-container deployment.
- Service Decoupling: Each service (backend API, database, and LLM) runs in its own container and communicates over a defined network (pg-network), which is a key design principle for scalability and maintenance.

## Diagram (Mermaid)

```mermaid
graph TD
  %% Client Node
  CR["Client Request"]:::client

  %% Configuration Node
  CFG["Configuration (.env)"]:::config

  %% Backend Application Subgraph
  subgraph "Backend Application"
    A["App Entry (app.py)"]:::backend
    subgraph "Modules"
      DS["Driver Services"]:::backend
      subgraph "Driver Endpoints"
        D1["Ingestion Endpoint (ingestion_service.py)"]:::backend
        D2["QA Endpoint (qa_service.py)"]:::backend
        D3["Document Listing Endpoint (list_available_doc.py)"]:::backend
      end
      DB["DB Service"]:::backend
      subgraph "DB Service Modules"
        DB1["Database Manager (database_manager.py)"]:::backend
        DB2["SQL Scripts"]:::backend
        DB3["Vector DB Logic"]:::backend
      end
      DP["Document Processing"]:::backend
      LS["LLM Service"]:::backend
      UT["Utils"]:::backend
    end
  end

  %% Containerized Services Subgraph
  subgraph "Containerized Services"
    PG["PostgreSQL Database (pgvector)"]:::container
    OL["Ollama LLM Service Container"]:::container
    DC["docker-compose Deployment"]:::container
  end

  %% Data flows from Client to Backend
  CR --> DS

  %% Data flows within Driver Endpoints
  D1 --> DP
  D1 --> DB
  D2 --> LS
  D3 --> DB

  %% Backend Modules interacting with external services
  DB --> PG
  LS --> OL

  %% Orchestration relationships
  DC --> PG
  DC --> OL

  %% Configuration link (used by Backend)
  A --> CFG

  %% Click events for Backend Application
  click A "https://github.com/rrpatil-1/qna_rag_doc_management/blob/main/backend/app.py"
  click DS "https://github.com/rrpatil-1/qna_rag_doc_management/tree/main/backend/driver_services"
  click D1 "https://github.com/rrpatil-1/qna_rag_doc_management/blob/main/backend/driver_services/ingestion_service.py"
  click D2 "https://github.com/rrpatil-1/qna_rag_doc_management/blob/main/backend/driver_services/qa_service.py"
  click D3 "https://github.com/rrpatil-1/qna_rag_doc_management/blob/main/backend/driver_services/list_available_doc.py"
  click DB "https://github.com/rrpatil-1/qna_rag_doc_management/tree/main/backend/db_service"
  click DB1 "https://github.com/rrpatil-1/qna_rag_doc_management/blob/main/backend/db_service/database_manager.py"
  click DB2 "https://github.com/rrpatil-1/qna_rag_doc_management/tree/main/backend/db_service/sql"
  click DB3 "https://github.com/rrpatil-1/qna_rag_doc_management/tree/main/backend/db_service/vectordb"
  click DP "https://github.com/rrpatil-1/qna_rag_doc_management/blob/main/backend/document_process/process_pdfdoc.py"
  click LS "https://github.com/rrpatil-1/qna_rag_doc_management/tree/main/backend/llm_service/Ollama"
  click UT "https://github.com/rrpatil-1/qna_rag_doc_management/tree/main/backend/utils"

  %% Click events for Containerization & Configuration
  click DC "https://github.com/rrpatil-1/qna_rag_doc_management/blob/main/deployment/docker_compose.yaml"
  click OL "https://github.com/rrpatil-1/qna_rag_doc_management/tree/main/ollama"
  click CFG "https://github.com/rrpatil-1/qna_rag_doc_management/blob/main/.env file"

  %% Styling classes
  classDef backend fill:#BBDEFB,stroke:#1E88E5,stroke-width:2px;
  classDef container fill:#C8E6C9,stroke:#2E7D32,stroke-width:2px;
  classDef client fill:#FFF9C4,stroke:#FBC02D,stroke-width:2px;
  classDef config fill:#D1C4E9,stroke:#512DA8,stroke-width:2px;
```
