# arpanbasusachdeva/querydocs architecture

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

- Interactive diagram: https://gitdiagram.com/arpanbasusachdeva/querydocs
- Repository: https://github.com/arpanbasusachdeva/querydocs

## Overview

##### Project Type and Purpose
- Project Type: Full-stack web application with AI/ML components
- Purpose: Provide a user interface (Streamlit) for uploading documents, storing them, generating embeddings, and enabling context-aware AI chat.

##### File Structure
Top-Level:
- main.py            → FastAPI backend entry point
- streamlit_app.py   → Streamlit frontend entry point
- Router/            → Core business logic modules
- database.py       → Database connection setup
- table_creater.py  → ORM models (SQLAlchemy)
- relations.py      → Model relationships
- Chatbot_retriver.py → Chat logic (query embeddings, call AI)
- embedding.py      → Embedding generation pipeline
- exception_utils.py→ Error handling utilities
- embedding/        → Persisted FAISS indexes and pickles
- uploads/           → File storage for uploaded documents
- requirements.txt   → Python dependencies
- runtime.txt        → Deployment runtime

##### Extract Insights from the README
- Backend: FastAPI + Uvicorn + SQLAlchemy + Pydantic
- Frontend: Streamlit + Pandas + Requests
- DB: SQLite (default) / PostgreSQL
- AI: Document embedding + semantic search + external LLM API
- Key features: Document management, context-aware chat, session/chat history, exception logging

##### Main Components
a. User Interface Layer
- Streamlit Frontend
b. API Layer
- FastAPI application (main.py) hosted on Uvicorn
- Pydantic schemas, routers
c. Persistence Layer
- Relational DB (SQLite/PostgreSQL)
- ORM models (SQLAlchemy)
- File storage (uploads directory)
- FAISS embedding indexes on disk
d. AI/ML Layer
- Embedding generation module (Router/embedding.py)
- FAISS index lookup (Router/Chatbot_retriver.py)
- External LLM API calls (e.g., OpenAI)
e. Utility/Support
- Exception handling (Router/exception_utils.py)
- Background tasks (if any)

##### Relationships & Data Flows
1. User interacts via Streamlit UI
2. Frontend issues HTTP requests (upload, chat) → FastAPI endpoints
3. Upload flow:
- API saves file to uploads/
- API invokes embedding pipeline
- Documents are chunked & embeddings generated
- Embeddings persisted as FAISS indexes + metadata stored in DB
4. Chat flow:
- API retrieves relevant FAISS index → semantic search
- Combines retrieved context + user query → calls LLM
- Stores chat history in DB
- Returns AI response to frontend
5. Diagnostics & Exceptions:
- All errors funnel through exception_utils → logs in DB

##### Architectural Patterns & Design Principles
- Layered Architecture: UI → API → Persistence/AI
- Modularization: “Router” folder separates concerns
- Repository/ORM pattern for DB access
- FAISS as specialized datastore for vector search
- Stateless HTTP services + session-based chat tracking

##### Technologies & Frameworks to Annotate
- Frontend: Streamlit, Pandas, Requests
- API: FastAPI, Uvicorn, Pydantic
- ORM: SQLAlchemy
- DB: SQLite / PostgreSQL
- Embedding Store: FAISS indexes (.faiss, .pkl files)
- External AI: OpenAI (or other LLM provider)

## Diagram (Mermaid)

```mermaid
graph TB
    %% User Interface Layer
    subgraph "User Interface Layer"
        Streamlit_Frontend["Streamlit Frontend"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend Layer"
        subgraph "API Layer"
            API["FastAPI App (main.py)"]:::api
            Docs["/docs (Swagger UI)"]:::api
        end

        subgraph "Business Logic Modules"
            DocumentAPI["Document Management"]:::api
            ChatAPI["Chat Endpoints"]:::api
        end
    end

    %% Persistence Layer
    subgraph "Persistence Layer"
        DB["Relational DB (SQLite/PostgreSQL)"]:::persistence
        DBConn["Database Connection (database.py)"]:::persistence
        TableModels["ORM Models (table_creater.py)"]:::persistence
        Relations["Model Relationships (relations.py)"]:::persistence
        Uploads["Uploads Directory"]:::persistence
        FAISSStore["FAISS Indexes & Pickles"]:::persistence
    end

    %% AI/ML Layer
    subgraph "AI/ML Layer"
        EmbeddingPipeline["Embedding Pipeline (embedding.py)"]:::ai
        Retrieval["Chatbot Retriever (Chatbot_retriver.py)"]:::ai
        LLM["External LLM API"]:::ai
    end

    %% Utility / Support
    subgraph "Utility / Support"
        ExceptionUtils["Exception Utilities (exception_utils.py)"]:::support
    end

    %% Infrastructure
    subgraph "Infrastructure"
        Requirements["requirements.txt"]:::infra
        Runtime["runtime.txt"]:::infra
    end

    %% Data Flows
    Streamlit_Frontend -->|"POST /upload-document"| API
    Streamlit_Frontend -->|"POST /chat"| API
    API -->|calls| DocumentAPI
    API -->|calls| ChatAPI
    API -->|"fetches/updates"| DBConn
    API -->|uses| TableModels
    API -->|uses| Relations
    DocumentAPI -->|saves file| Uploads
    DocumentAPI -->|invokes| EmbeddingPipeline
    EmbeddingPipeline -->|stores embeddings| FAISSStore
    EmbeddingPipeline -->|stores metadata| TableModels
    ChatAPI -->|invokes| Retrieval
    Retrieval -->|semantic search| FAISSStore
    Retrieval -->|combines context + query| LLM
    Retrieval -->|stores history| TableModels
    Retrieval -->|logs sessions| DBConn
    %% Exceptions
    API -->|error handling| ExceptionUtils
    DocumentAPI -->|error handling| ExceptionUtils
    ChatAPI -->|error handling| ExceptionUtils
    EmbeddingPipeline -->|error handling| ExceptionUtils
    Retrieval -->|error handling| ExceptionUtils

    %% Click Events
    click Streamlit_Frontend "https://github.com/arpanbasusachdeva/querydocs/blob/main/streamlit_app.py"
    click API "https://github.com/arpanbasusachdeva/querydocs/blob/main/main.py"
    click DBConn "https://github.com/arpanbasusachdeva/querydocs/blob/main/Router/database.py"
    click TableModels "https://github.com/arpanbasusachdeva/querydocs/blob/main/Router/table_creater.py"
    click Relations "https://github.com/arpanbasusachdeva/querydocs/blob/main/Router/relations.py"
    click Retrieval "https://github.com/arpanbasusachdeva/querydocs/blob/main/Router/Chatbot_retriver.py"
    click EmbeddingPipeline "https://github.com/arpanbasusachdeva/querydocs/blob/main/Router/embedding.py"
    click FAISSStore "https://github.com/arpanbasusachdeva/querydocs/tree/main/Router/embedding/"
    click ExceptionUtils "https://github.com/arpanbasusachdeva/querydocs/blob/main/Router/exception_utils.py"
    click Uploads "https://github.com/arpanbasusachdeva/querydocs/tree/main/uploads/"
    click Requirements "https://github.com/arpanbasusachdeva/querydocs/blob/main/requirements.txt"
    click Runtime "https://github.com/arpanbasusachdeva/querydocs/blob/main/runtime.txt"

    %% Styles
    classDef frontend fill:#BBDEFB,stroke:#0D47A1,color:#0D47A1;
    classDef api fill:#C8E6C9,stroke:#1B5E20,color:#1B5E20;
    classDef persistence fill:#FFE0B2,stroke:#E65100,color:#E65100;
    classDef ai fill:#E1BEE7,stroke:#4A148C,color:#4A148C;
    classDef support fill:#CFD8DC,stroke:#37474F,color:#37474F;
    classDef infra fill:#F5F5F5,stroke:#9E9E9E,color:#9E9E9E;
```
