# kartikeya2006/pdf_qa architecture

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

- Interactive diagram: https://gitdiagram.com/kartikeya2006/pdf_qa
- Repository: https://github.com/kartikeya2006/pdf_qa

## Overview

##### Project Type and Purpose
- This is a full-stack web application (“PDF Q&A App”) that lets users upload PDF documents and then ask natural-language questions about their contents.
- Frontend: Next.js + Tailwind CSS (deployed to Vercel)
- Backend: FastAPI + Uvicorn (deployed on AWS EC2)
- Core AI: LangChain/LlamaIndex for vector-based indexing and OpenAI LLM calls

##### High-Level File Structure
- frontend/qa_pdf
- Next.js app folder with React components, global styles, config (tsconfig, next.config.ts)
- UI components for upload and chat
- backend
- main.py (FastAPI entrypoint)
- pdf_processor.py (extracts text via PyMuPDF)
- qa_engine.py (builds/loads LlamaIndex vector stores and issues LLM queries)
- db.py + models.py + Alembic migrations (SQLite “pdfs.db” for metadata)
- uploads/ (raw PDFs)
- indices/ (per-PDF vector stores: docstore.json, graph_store.json, index_store.json, etc.)

##### Main Components
A. User’s Web Browser (Client)
B. Frontend App (Next.js server + static assets)
C. Backend API (FastAPI/Uvicorn)
D. PDF Storage (uploads/ on server disk)
E. PDF Processing Service (pdf_processor.py)
F. Indexing & QA Service (qa_engine.py with LlamaIndex/LangChain)
G. Persistent Metadata Store (SQLite via db.py + Alembic)
H. Vector Store Filesystem (indices/ per-PDF vector data)
I. External LLM Service (OpenAI API)

##### Relationships & Data Flow
1. User → Next.js Frontend: Upload PDF or ask a question
2. Next.js → FastAPI “/upload” endpoint: HTTP POST with file
3. FastAPI → Disk: save PDF to uploads/
4. FastAPI → pdf_processor.py: extract text from PDF
5. pdf_processor → qa_engine.py: ingest text into LlamaIndex → writes vector files under indices/
6. Backend → SQLite via db.py: record PDF metadata (filename, index path)
7. User → Frontend: renders upload success or file list
8. User → Frontend: enter question, Frontend → FastAPI “/query” endpoint with {pdf_id, question}
9. FastAPI → qa_engine.py: load vector store from indices/, call LlamaIndex QA chain which issues requests to OpenAI API
10. OpenAI API → qa_engine → FastAPI → Frontend → User: return contextual answer

##### Architectural Patterns & Design Principles
- Separation of Concerns:
- Frontend handles UI, routing, styling
- Backend handles ingestion pipeline, indexing, QA logic, persistence
- Layered Service:
- Storage layer (PDF files + vector files + SQLite)
- Processing layer (pdf_processor, qa_engine)
- API layer (FastAPI endpoints)
- Modular Indexing Pipeline: ingest → index → query
- CI/CD Targets: Vercel for frontend, EC2 for backend

- Frontend: React, Next.js, Tailwind CSS, TypeScript
- Backend: Python 3.9+, FastAPI, Uvicorn, PyMuPDF, LangChain/LlamaIndex, SQLite + Alembic
- External: OpenAI REST API

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client
    User["User's Browser"]:::client

    %% Frontend Layer
    subgraph "Frontend Layer"
        NextApp["Next.js Frontend\nReact, Tailwind CSS, TS\n(port 3000)"]:::frontend
        subgraph "Config & Styling"
            Config["next.config.ts,\ntsconfig.json,\npostcss.config.mjs,\nglobals.css"]:::frontend
        end
        subgraph "UI Components"
            UI["app/_components"]:::frontend
        end
        subgraph "Pages & Layout"
            Pages["page.tsx,\nlayout.tsx"]:::frontend
        end
    end

    %% Backend Layer
    subgraph "Backend Layer"
        API["FastAPI API Server\n(port 8000)"]:::backend
        subgraph "Processing & QA"
            PP["PDF Processor\n(pdf_processor.py)"]:::backend
            QA["Indexing & QA Service\n(qa_engine.py)"]:::backend
        end
        subgraph "Persistence & Storage"
            DBServ["SQLite Metadata Store\n(db.py, models.py)"]:::db
            Uploads["PDF Storage\nuploads/"]:::storage
            Indices["Vector Store FS\nindices/"]:::storage
            subgraph "Migrations"
                Mig["env.py,\nscript.py.mako"]:::db
            end
        end
        subgraph "Dependencies"
            Deps["requirements.txt,\nalembic.ini"]:::backend
        end
    end

    %% External Service
    OpenAI["OpenAI API"]:::external

    %% Data Flows
    User -->|"Upload PDF\nor Ask Question"| NextApp
    NextApp -->|"/upload (POST)"| API
    API -->|Save PDF File| Uploads
    API -->|"Extract Text"| PP
    PP -->|"Ingest Text"| QA
    QA -->|Write Vector Files| Indices
    API -->|"Record Metadata"| DBServ
    User -->|"Enter Question"| NextApp
    NextApp -->|"/query (POST)"| API
    API -->|"Load Vector Store"| QA
    QA -->|"Call LLM"| OpenAI
    OpenAI -->|"Return Response"| API
    API -->|"Return Answer"| NextApp
    NextApp -->|"Render Answer"| User

    %% Click Events - Frontend
    click NextApp "https://github.com/kartikeya2006/pdf_qa/tree/main/frontend/qa_pdf"
    click Config "https://github.com/kartikeya2006/pdf_qa/blob/main/frontend/qa_pdf/next.config.ts"
    click Config "https://github.com/kartikeya2006/pdf_qa/blob/main/frontend/qa_pdf/tsconfig.json"
    click Config "https://github.com/kartikeya2006/pdf_qa/blob/main/frontend/qa_pdf/postcss.config.mjs"
    click Config "https://github.com/kartikeya2006/pdf_qa/blob/main/frontend/qa_pdf/globals.css"
    click UI "https://github.com/kartikeya2006/pdf_qa/tree/main/frontend/qa_pdf/app/_components/"
    click Pages "https://github.com/kartikeya2006/pdf_qa/blob/main/frontend/qa_pdf/app/page.tsx"
    click Pages "https://github.com/kartikeya2006/pdf_qa/blob/main/frontend/qa_pdf/app/layout.tsx"

    %% Click Events - Backend
    click API "https://github.com/kartikeya2006/pdf_qa/blob/main/backend/main.py"
    click PP "https://github.com/kartikeya2006/pdf_qa/blob/main/backend/pdf_processor.py"
    click QA "https://github.com/kartikeya2006/pdf_qa/blob/main/backend/qa_engine.py"
    click DBServ "https://github.com/kartikeya2006/pdf_qa/blob/main/backend/db.py"
    click DBServ "https://github.com/kartikeya2006/pdf_qa/blob/main/backend/models.py"
    click Mig "https://github.com/kartikeya2006/pdf_qa/blob/main/backend/migrations/env.py"
    click Mig "https://github.com/kartikeya2006/pdf_qa/blob/main/backend/migrations/script.py.mako"
    click Uploads "https://github.com/kartikeya2006/pdf_qa/tree/main/backend/uploads/"
    click Indices "https://github.com/kartikeya2006/pdf_qa/tree/main/backend/indices/"
    click Deps "https://github.com/kartikeya2006/pdf_qa/blob/main/backend/requirements.txt"
    click Deps "https://github.com/kartikeya2006/pdf_qa/blob/main/backend/alembic.ini"

    %% Styles
    classDef client fill:#d3d3d3,stroke:#888,stroke-width:1px
    classDef frontend fill:#b3d9ff,stroke:#0366d6,stroke-width:1px
    classDef backend fill:#d2f8d2,stroke:#2e8b57,stroke-width:1px
    classDef storage fill:#ffe5b4,stroke:#cc8400,stroke-width:1px
    classDef db fill:#ffe5b4,stroke:#cc8400,stroke-width:1px
    classDef external fill:#e1c4f2,stroke:#800080,stroke-width:1px
```
