# jatin-mehra119/pdf-insight-beta architecture

> Architecture diagram of the GitHub repository jatin-mehra119/pdf-insight-beta, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jatin-mehra119/pdf-insight-beta
- Repository: https://github.com/jatin-mehra119/pdf-insight-beta

## Overview

##### Project Type and Purpose
- PDF Insight Pro is a full-stack document-analysis application.
- It provides a static JS/CSS/HTML frontend (served from `/static`), a FastAPI backend (`app.py` + `/api/…`), and an Android WebView client.
- Core purpose: upload a PDF, chunk & embed its text, run retrieval-augmented generation (RAG) with optional web-search, and return intelligent answers.

##### File Structure
- **Top-level**
- `app.py`, `gen_dataset.py`, `test_RAG.ipynb`, `requirements.txt`, `Dockerfile`, CI workflows.
- Folders: `api/`, `configs/`, `models/`, `services/`, `utils/`, `static/`, `development_scripts/`, `uploads/`, `Android App/`.
- **API Layer** (`api/`): chat, session, upload, utility route modules.
- **Config** (`configs/`): environment and key-management.
- **Models** (`models/`): Pydantic request/response schemas.
- **Business Logic** (`services/`):
- `rag_service.py` – RAG pipeline, agentic search.
- `llm_service.py` – LLM prompting/inference via Groq API.
- `session_service.py` – session persistence.
- **Utilities** (`utils/`):
- `text_processing.py` – PDF extraction & chunking.
- `faiss_utils.py` – FAISS index management.
- `session_utils.py` – serialize/deserialize sessions.
- **Frontend** (`static/`): HTML, CSS, JS, served as static assets.
- **Mobile** (`Android App/`): WebView-based wrapper.
- **Storage** (`uploads/`): incoming PDFs & pickled sessions.

##### README Insights
- Confirms modular architecture: PDF Processing, RAG Engine, API Layer, Frontend, Mobile.
- Details external dependencies: Groq API, Tavily API, FAISS, Sentence Transformers, PyMuPDF, Uvicorn.
- CI/CD: Docker + GitHub Actions + Hugging Face Spaces.

##### Detail
- Every service module (`rag_service`, `llm_service`, `session_service`).
- Flow of a single “Upload PDF → Ask a question” workflow from end to end.
- Persistent session storage and temporary indices.
- Don’t omit the Docker container boundary or the CI/CD workflow.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer"
        direction TB
        Browser["Web Browser UI"]:::frontend
        Android["Android WebView Client"]:::frontend
    end

    %% API and Container Boundary
    subgraph "Docker Container" 
        direction TB
        subgraph "API Layer"
            direction TB
            APIGateway["FastAPI Entrypoints"]:::api
            ChatRoutes["chat_routes.py"]:::api
            SessionRoutes["session_routes.py"]:::api
            UploadRoutes["upload_routes.py"]:::api
            UtilityRoutes["utility_routes.py"]:::api
            AppMain["app.py"]:::api
        end

        subgraph "Config & Models"
            direction TB
            ConfigLoader["config.py"]:::service
            DataModels["models.py"]:::service
        end

        subgraph "Service Layer"
            direction TB
            RAGService["rag_service.py"]:::service
            LLMService["llm_service.py"]:::service
            SessionService["session_service.py"]:::service
        end

        subgraph "Utility Layer"
            direction TB
            TextProc["text_processing.py"]:::util
            FaissUtil["faiss_utils.py"]:::util
            SessionUtil["session_utils.py"]:::util
        end

        subgraph "Storage"
            direction TB
            UploadStore["/uploads (PDFs & sessions)"]:::util
            FAISSIndex["FAISS Index (ephemeral/disk)"]:::util
        end
    end

    %% External Services and DevOps
    subgraph "External & DevOps"
        direction TB
        GroqAPI["Groq LLM API"]:::external
        TavilyAPI["Tavily Web Search API"]:::external
        CI["GitHub Actions CI/CD"]:::devops
        HFS["HuggingFace Spaces"]:::devops
        DockerfileNode["Dockerfile"]:::devops
    end

    %% Frontend Static Assets
    subgraph "Static Assets"
        direction TB
        StaticApp["Static Web App"]:::frontend
    end

    %% Connections
    Browser -->|HTTP JSON| StaticApp
    StaticApp -->|HTTP JSON| AppMain
    Android -->|HTTP JSON| AppMain

    AppMain -->|routes| ChatRoutes
    AppMain -->|routes| SessionRoutes
    AppMain -->|routes| UploadRoutes
    AppMain -->|routes| UtilityRoutes

    ChatRoutes -->|calls| RAGService
    SessionRoutes -->|calls| SessionService
    UploadRoutes -->|calls| TextProc
    UtilityRoutes -->|calls| SessionUtil

    RAGService -->|uses| LLMService
    RAGService -->|uses| FaissUtil
    RAGService -->|calls| GroqAPI
    RAGService -->|calls| TavilyAPI

    LLMService -->|uses| ConfigLoader
    SessionService -->|uses| SessionUtil
    TextProc -->|writes/reads| UploadStore
    SessionUtil -->|writes/reads| UploadStore
    FaissUtil -->|reads/writes| FAISSIndex

    CI -->|build & deploy| DockerfileNode
    DockerfileNode -->|deploy| HFS

    %% Click Events
    click StaticApp "https://github.com/jatin-mehra119/pdf-insight-beta/blob/main/static/index.html"
    click StaticApp "https://github.com/jatin-mehra119/pdf-insight-beta/blob/main/static/css/styles.css"
    click StaticApp "https://github.com/jatin-mehra119/pdf-insight-beta/blob/main/static/js/app.js"
    click Android "https://github.com/jatin-mehra119/pdf-insight-beta/blob/main/Android App/app/src/main/java/com/jatinmehra/pdfinsightpro/MainActivity.java"
    click Android "https://github.com/jatin-mehra119/pdf-insight-beta/blob/main/Android App/app/src/main/java/com/jatinmehra/pdfinsightpro/SplashActivity.java"
    click Android "https://github.com/jatin-mehra119/pdf-insight-beta/blob/main/Android App/app/src/main/res/layout/activity_main.xml"
    click Android "https://github.com/jatin-mehra119/pdf-insight-beta/blob/main/Android App/app/src/main/res/layout/activity_splash.xml"
    click AppMain "https://github.com/jatin-mehra119/pdf-insight-beta/blob/main/app.py"
    click ChatRoutes "https://github.com/jatin-mehra119/pdf-insight-beta/blob/main/api/chat_routes.py"
    click SessionRoutes "https://github.com/jatin-mehra119/pdf-insight-beta/blob/main/api/session_routes.py"
    click UploadRoutes "https://github.com/jatin-mehra119/pdf-insight-beta/blob/main/api/upload_routes.py"
    click UtilityRoutes "https://github.com/jatin-mehra119/pdf-insight-beta/blob/main/api/utility_routes.py"
    click ConfigLoader "https://github.com/jatin-mehra119/pdf-insight-beta/blob/main/configs/config.py"
    click DataModels "https://github.com/jatin-mehra119/pdf-insight-beta/blob/main/models/models.py"
    click RAGService "https://github.com/jatin-mehra119/pdf-insight-beta/blob/main/services/rag_service.py"
    click LLMService "https://github.com/jatin-mehra119/pdf-insight-beta/blob/main/services/llm_service.py"
    click SessionService "https://github.com/jatin-mehra119/pdf-insight-beta/blob/main/services/session_service.py"
    click TextProc "https://github.com/jatin-mehra119/pdf-insight-beta/blob/main/utils/text_processing.py"
    click FaissUtil "https://github.com/jatin-mehra119/pdf-insight-beta/blob/main/utils/faiss_utils.py"
    click SessionUtil "https://github.com/jatin-mehra119/pdf-insight-beta/blob/main/utils/session_utils.py"
    click DockerfileNode "https://github.com/jatin-mehra119/pdf-insight-beta/tree/main/Dockerfile"
    click CI "https://github.com/jatin-mehra119/pdf-insight-beta/blob/main/.github/workflows/sync_to_hf.yml"

    %% Styles
    classDef frontend fill:#CCE5FF,stroke:#333,stroke-width:1px
    classDef api fill:#DFFFD6,stroke:#333,stroke-width:1px
    classDef service fill:#FFE5B4,stroke:#333,stroke-width:1px
    classDef util fill:#E3E4FA,stroke:#333,stroke-width:1px
    classDef external fill:#E0E0E0,stroke:#333,stroke-width:1px
    classDef devops fill:#CCFFFF,stroke:#333,stroke-width:1px
```
