# harun8/askpdf architecture

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

- Interactive diagram: https://gitdiagram.com/harun8/askpdf
- Repository: https://github.com/harun8/askpdf

## Overview

##### Project type and purpose
- AskPDF is a full-stack, server-rendered Next.js web application that lets users upload PDF documents, processes them via embeddings (using OpenAI’s embedding API and LangChain), stores and queries the resulting vectors in Supabase’s vector-enabled Postgres, and supports real-time chat interactions. It also integrates payment (Stripe), email notifications (SendGrid), authentication & user metadata (Supabase Auth), and end-to-end testing (Cypress).

##### File structure
- Top-level “app” directory: Next.js 13+ App Router pages and API routes (`app/api/.../route.js`), localized UIs (`app/[locale]/…`), global layout (`app/layout.js`), providers (`app/providers.tsx`).
- “components” & “components/ui”: Reusable React components and UI primitives.
- “lib” and “util”: Client/server helper modules (Supabase client, OpenAI wrappers, utilities for streaming, chunking, embedding).
- “services”: Business-logic modules (e.g., locale management).
- “supabase”: Supabase project config, seeds, migrations, and vector DB configuration.
- “public/styles” and Tailwind/PostCSS configs: Styling infrastructure.
- Cypress config: End-to-end testing harness.
- Dockerfile and GitHub Actions workflow: CI/CD pipelines for containerization and deployment.

##### Readme insights
- The author migrated from naive chat-completion looping to an embedding-based retrieval approach using LangChain.
- Supabase is used for Auth, Realtime broadcasting (to stream LLM tokens to clients), and as the hosting vector database.
- Stripe for payments, SendGrid for emails, and lscache for client-side rate limiting on the free tier.
- Key flows: PDF upload → chunking → embedding → store vectors → question query → similarity search → LLM streaming → client.

##### Main components and interactions
a. Frontend (Next.js / React)
- Localized pages, routing, UI components, real-time subscription to chat messages.
- Communicates with Next.js API routes via fetch.
b. Backend (Next.js API Routes)
- Endpoint layers: `/api/chat` (handling question submissions and streaming back tokens), `/api/llm/preview` & `/api/llm/enhance` (document processing), `/api/checkout` (Stripe), `/api/auth` (OAuth callback), `/api/settings`, `/api/stripe`.
- Each route orchestrates calls to utility libraries (OpenAI, Supabase).
c. Supabase (BaaS)
- Auth (user sessions), Postgres with pgvector extension for storing embeddings, Realtime (broadcast channel for streaming responses), Storage (for PDF files if used).
d. OpenAI + LangChain
- Embedding API: vectorizes PDF chunks.
- Chat completion / streaming API: answers user queries from retrieved chunks.
e. External services
- Stripe: payment flows, webhooks via Next.js API.
- SendGrid: transactional emails (sign-up, receipts).
f. Testing & DevOps
- Cypress E2E tests, Docker containerization, GitHub Actions for CI/CD, Vercel or custom deployments.

##### Architectural patterns & principles
- Separation of concerns: UI vs. API vs. data services.
- “Retrieval-Augmented Generation” (RAG) pattern: store embeddings in vector DB, retrieve relevant context, then call LLM.
- API-first micro-service style within Next.js (each API route as a modular handler).
- Real-time event propagation through Supabase Realtime channels (similar to WebSockets).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer" 
        direction TB
        Browser["User's Browser"]:::frontend
        LocalizedUI["Localized Pages"]:::frontend
        ChatUI["Chat UI Components"]:::frontend
        UploadUI["PDF Upload & Processing UI"]:::frontend
    end

    %% Application Layer
    subgraph "Application Layer"
        direction TB
        NextApp["Next.js App Router"]:::backend
        subgraph "API Routes"
            direction TB
            ChatAPI["/api/chat"]:::backend
            PreviewAPI["/api/llm/preview"]:::backend
            EnhanceAPI["/api/llm/enhance"]:::backend
            CheckoutAPI["/api/checkout"]:::backend
            CheckoutIdAPI["/api/checkout/[id]"]:::backend
            StripeAPI["/api/stripe"]:::backend
            AuthAPI["/api/auth/callback"]:::backend
            SettingsAPI["/api/settings"]:::backend
        end
        LocaleService["Locale Management Service"]:::backend
        subgraph "Helpers & Libs"
            direction TB
            SupaClient["Supabase Client Init"]:::backend
            OpenAIHelpers["OpenAI & LangChain Helpers"]:::backend
            StreamingUtil["Streaming Utilities"]:::backend
            FileLimits["File/Upload Utilities"]:::backend
        end
        GlobalLayout["Global Layout & Providers"]:::backend
    end

    %% Data & External Services
    subgraph "Data & External Services"
        direction TB
        SupaAuth["Supabase Auth"]:::data
        VectorDB["Postgres + pgvector"]:::data
        Realtime["Supabase Realtime"]:::data
        Storage["Supabase Storage"]:::data
        OpenAIEmbed["OpenAI Embedding API"]:::external
        OpenAIChat["OpenAI Chat API"]:::external
        StripeSvc["Stripe"]:::external
        SendGridSvc["SendGrid"]:::external
    end

    %% Flows
    Browser -->|view pages| LocalizedUI
    Browser -->|load layout/providers| GlobalLayout
    LocalizedUI -->|fetch| NextApp
    ChatUI -->|calls| ChatAPI
    UploadUI -->|calls| PreviewAPI
    UploadUI -->|calls| EnhanceAPI

    NextApp -->|uses| GlobalLayout
    NextApp -->|routes to| ChatAPI
    NextApp -->|routes to| PreviewAPI
    NextApp -->|routes to| EnhanceAPI

    ChatAPI -->|uses| StreamingUtil
    ChatAPI -->|queries| VectorDB
    ChatAPI -->|calls| OpenAIChat
    ChatAPI -->|publishes tokens| Realtime
    StreamingUtil -->|init| SupaClient

    PreviewAPI -->|uses| FileLimits
    PreviewAPI -->|uses| OpenAIHelpers
    PreviewAPI -->|stores vectors| VectorDB
    PreviewAPI -->|via| SupaClient

    EnhanceAPI -->|uses| OpenAIHelpers
    EnhanceAPI -->|stores vectors| VectorDB

    CheckoutAPI -->|calls| StripeSvc
    CheckoutIdAPI -->|webhook| StripeSvc
    StripeAPI -->|manages| StripeSvc

    AuthAPI -->|uses| SupaAuth
    SettingsAPI -->|reads/writes| SupaClient

    VectorDB -->|auth| SupaAuth
    VectorDB -->|storage| Storage

    OpenAIHelpers -->|select model| OpenAIEmbed
    OpenAIHelpers -->|chunk docs| OpenAIEmbed

    LocaleService -->|supports| LocalizedUI

    %% Click Events
    click Browser "https://github.com/harun8/askpdf/tree/main/app/"
    click LocalizedUI "https://github.com/harun8/askpdf/tree/main/app/[locale]/"
    click GlobalLayout "https://github.com/harun8/askpdf/blob/main/app/layout.js"
    click GlobalLayout "https://github.com/harun8/askpdf/blob/main/app/providers.tsx"
    click ChatUI "https://github.com/harun8/askpdf/blob/main/components/ChatNav.jsx"
    click ChatUI "https://github.com/harun8/askpdf/blob/main/components/ConversationDisplay.jsx"
    click UploadUI "https://github.com/harun8/askpdf/blob/main/components/PDF-upload.jsx"
    click UploadUI "https://github.com/harun8/askpdf/blob/main/components/processingPDF.jsx"
    click UploadUI "https://github.com/harun8/askpdf/blob/main/components/loadingPDF.jsx"
    click SupaClient "https://github.com/harun8/askpdf/blob/main/lib/supabase.js"
    click SupaClient "https://github.com/harun8/askpdf/blob/main/lib/supabase-server.js"
    click OpenAIHelpers "https://github.com/harun8/askpdf/blob/main/util/openai/modelChooser.js"
    click OpenAIHelpers "https://github.com/harun8/askpdf/blob/main/util/combineDocuments.js"
    click StreamingUtil "https://github.com/harun8/askpdf/blob/main/util/streaming/chat-util.ts"
    click FileLimits "https://github.com/harun8/askpdf/blob/main/util/fileSizeLimit.js"
    click FileLimits "https://github.com/harun8/askpdf/blob/main/util/uploadLimit.js"
    click ChatAPI "https://github.com/harun8/askpdf/blob/main/app/api/chat/route.js"
    click PreviewAPI "https://github.com/harun8/askpdf/blob/main/app/api/llm/preview/route.js"
    click EnhanceAPI "https://github.com/harun8/askpdf/blob/main/app/api/llm/enhance/route.js"
    click CheckoutAPI "https://github.com/harun8/askpdf/blob/main/app/api/checkout/route.js"
    click CheckoutIdAPI "https://github.com/harun8/askpdf/blob/main/app/api/checkout/[id]/route.js"
    click StripeAPI "https://github.com/harun8/askpdf/blob/main/app/api/stripe/route.js"
    click AuthAPI "https://github.com/harun8/askpdf/blob/main/app/api/auth/callback/route.js"
    click SettingsAPI "https://github.com/harun8/askpdf/blob/main/app/api/settings/route.js"
    click LocaleService "https://github.com/harun8/askpdf/blob/main/services/locale.js"
    click SupaAuth "https://github.com/harun8/askpdf/blob/main/supabase/config.toml"
    click VectorDB "https://github.com/harun8/askpdf/blob/main/supabase/seed.sql"
    click Realtime "https://github.com/harun8/askpdf/tree/main/supabase/.branches/"
    click Storage "https://github.com/harun8/askpdf/blob/main/supabase/config.toml"
    click Browser "https://github.com/harun8/askpdf/tree/main/public/styles/"
    click Browser "https://github.com/harun8/askpdf/blob/main/tailwind.config.js"
    click Browser "https://github.com/harun8/askpdf/blob/main/postcss.config.js"
    click Realtime "https://github.com/harun8/askpdf/tree/main/cypress/"
    click Realtime "https://github.com/harun8/askpdf/blob/main/cypress.config.js"
    click Browser "https://github.com/harun8/askpdf/tree/main/Dockerfile"
    click Browser "https://github.com/harun8/askpdf/blob/main/.github/workflows/main.yml"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366d6
    classDef backend fill:#D5F5E3,stroke:#27ae60
    classDef data fill:#FCF3CF,stroke:#D68910
    classDef external fill:#FADBD8,stroke:#c0392b
```
