# gaurav9508/pdfintellect architecture

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

- Interactive diagram: https://gitdiagram.com/gaurav9508/pdfintellect
- Repository: https://github.com/gaurav9508/pdfintellect

## Overview

##### Project type and purpose
- PDFIntellect is a full-stack, AI-powered PDF note-taking web app.
- Frontend: Next.js (App Router) + TailwindCSS + ShadCN UI
- Backend: Convex (hosted database + serverless functions)
- Auth: Clerk
- AI: Google Gemini Pro API
- Payments: PayPal
- Purpose: Upload PDFs, extract/summarize content via AI, create/save notes, manage user plans.

##### File structure
- app/ – Next.js routes (auth, dashboard, workspace, global layout & providers)
- app/(auth)/sign-in – Clerk sign-in integration
- app/api/pdf-loader/route.js – Next.js serverless API to parse PDF
- app/dashboard/* – user dashboard pages/components (upload dialog, header, sidebar)
- app/workspace/[fileId]/* – per-PDF workspace with PdfViewer, TextEditor, Header
- convex/ – Convex backend:
- schema.js – data models
- fileStorage.js – upload URL generation & metadata mutations
- langchain/ – DB helpers for AI ingestion
- myAction.js (ingest) – calls Gemini, writes summary to DB
- user.js, notes.js – user & note management mutations/queries
- _generated/ – Convex-generated type definitions & API bindings
- configs/AIModel.js – AI model configuration
- lib/utils.js, middleware.js – shared utilities & Next.js middleware
- components/ui – reusable UI primitives (Button, Dialog, Input, etc.)
- next.config.mjs, postcss.config.mjs, jsconfig.json – build/deployment configs

##### Extract insights from README
- Key workflows: PDF upload → metadata stored via Convex → text extraction via /api/pdf-loader → summary via Convex+Gemini → notes stored in Convex DB
- Auth via Clerk with auto user creation in Convex
- Plan upgrade via PayPalButtons → Convex mutation

a. Main components:
- Client (Browser/Next.js React app)
- Next.js serverless layer (SSR pages + /api/pdf-loader route)
- Convex backend (DB + serverless functions)
- Clerk (Auth service)
- Google Gemini Pro API (AI service)
- PayPal (Payment service)
- File storage (Convex fileStorage or underlying S3)
b. Relationships & data flow:
1. User → Next.js pages (protected by Clerk middleware)
2. Next.js ↔ Clerk for auth tokens & session
3. Upload PDF:
- Frontend calls Convex fileStorage.generateUploadUrl
- Convex returns presigned URL → frontend uploads PDF to storage
- Convex mutation fileStorage.AddFileEntryToDb stores metadata
4. Extract & Summarize:
- Frontend calls GET /api/pdf-loader?pdfUrl=… → Next.js parses PDF client or server-side
- Next.js returns raw text → frontend invokes Convex action myAction.ingest(text, fileId)
- Convex function fetches Gemini API → stores summary & notes in DB
5. Read data: workspace pages query Convex for summary & note records
6. Plan upgrade: frontend embeds PayPalButtons → on success calls Convex user.userUpgradePlan
c. Architectural patterns & principles:
- Serverless functions for both frontend (Next.js API routes) and backend (Convex actions)
- Clear separation: UI (React components) vs. business logic (Convex functions) vs. data storage
- Event-driven (Convex actions trigger on client requests)
- Secure API keys via Convex env or .env files, no hardcoding
d. Key technologies:
- Next.js App Router (React, SSR/SSG, API routes)
- Convex SDK (db, actions, fileStorage)
- Clerk SDK (React auth hooks, middleware)
- Google Gemini Pro (fetch in Convex actions)
- PayPal JS SDK

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend (Next.js App)" 
        direction TB
        Layout["app/layout.jsx \n& app/provider.jsx"]:::frontend
        Middleware["middleware.js"]:::config
        Utils["lib/utils.js"]:::config
        subgraph "Auth Routes"
            SignIn["app/(auth)/sign-in/[[...sign-in]]/page.jsx"]:::frontend
        end
        subgraph "Dashboard"
            DashLayout["app/dashboard/layout.js"]:::frontend
            DashPage["app/dashboard/page.js"]:::frontend
            Header["app/dashboard/_components/Header.js"]:::frontend
            Sidebar["app/dashboard/_components/SideBar.js"]:::frontend
            UploadDialog["app/dashboard/_components/UploadPdfDialog.js"]:::frontend
            Upgrade["app/dashboard/upgrade/page.js"]:::frontend
        end
        subgraph "Workspace [fileId]"
            WSPage["app/workspace/[fileId]/page.js"]:::frontend
            PdfViewer["app/workspace/_components/PdfViewer.js"]:::frontend
            TextEditor["app/workspace/_components/TextEditor.js"]:::frontend
            EditorExt["app/workspace/_components/EditorExtension.js"]:::frontend
            WSHeader["app/workspace/_components/WorkspaceHeader.js"]:::frontend
        end
        subgraph "UI Primitives"
            Button["components/ui/button.jsx"]:::ui
            Dialog["components/ui/dialog.jsx"]:::ui
            Input["components/ui/input.jsx"]:::ui
            Progress["components/ui/progress.jsx"]:::ui
            Sonner["components/ui/sonner.jsx"]:::ui
        end
    end

    %% API Layer
    subgraph "Next.js API Layer"
        direction TB
        PDFLoader["app/api/pdf-loader/route.js"]:::api
    end

    %% Backend Layer
    subgraph "Convex Backend"
        direction TB
        Schema["convex/schema.js"]:::backend
        UserMut["convex/user.js"]:::backend
        NotesMut["convex/notes.js"]:::backend
        FileStorage["convex/fileStorage.js"]:::backend
        Langchain["convex/langchain/db.js"]:::backend
        AIAction["convex/myAction.js"]:::backend
        GeneratedAPI["convex/_generated/api.js"]:::backend
        GeneratedServer["convex/_generated/server.js"]:::backend
    end

    %% External Services
    subgraph "External Services"
        direction TB
        Clerk["Clerk Auth"]:::external
        Gemini["Google Gemini Pro API"]:::external
        PayPal["PayPal JS SDK"]:::external
        Storage["Convex File Storage\n(S3)"]:::external
    end

    %% AI Config
    AIConfig["configs/AIModel.js"]:::config

    %% Connections
    Layout -->|uses| Middleware
    Layout -->|uses| Utils
    Layout -->|provides| SignIn
    Layout -->|provides| DashLayout
    Middleware -->|protects| DashPage
    Middleware -->|protects| WSPage

    DashPage -->|renders| Header
    DashPage -->|renders| Sidebar
    DashPage -->|renders| UploadDialog
    DashPage -->|renders| Upgrade

    WSPage -->|renders| WSHeader
    WSPage -->|renders| PdfViewer
    WSPage -->|renders| TextEditor
    WSPage -->|enhanced by| EditorExt

    DashPage -->|calls| FileStorage
    UploadDialog -->|upload URL| FileStorage
    FileStorage -->|returns URL| UploadDialog
    UploadDialog -->|stores metadata| Schema

    PdfViewer -->|requests parse| PDFLoader
    PDFLoader -->|returns text| TextEditor

    TextEditor -->|invokes| AIAction
    AIAction -->|calls| Gemini
    AIAction -->|writes summary| Schema
    AIAction -->|writes notes| NotesMut

    WSPage -->|queries| Schema
    WSPage -->|queries| NotesMut

    DashPage -->|queries| UserMut
    Upgrade -->|calls| PayPal
    Upgrade -->|on success| UserMut

    Layout -->|loads| AIConfig

    %% Auth Flow
    SignIn -->|auth tokens| Clerk
    Layout -->|validates| Clerk
    Clerk -->|creates user| UserMut

    %% External storage
    FileStorage -->|stores PDF| Storage

    %% Click Events
    click Layout "https://github.com/gaurav9508/pdfintellect/blob/main/app/layout.jsx"
    click Layout "https://github.com/gaurav9508/pdfintellect/blob/main/app/provider.jsx"
    click Middleware "https://github.com/gaurav9508/pdfintellect/blob/main/middleware.js"
    click Utils "https://github.com/gaurav9508/pdfintellect/blob/main/lib/utils.js"
    click SignIn "https://github.com/gaurav9508/pdfintellect/blob/main/app/(auth)/sign-in/[[...sign-in]]/page.jsx"
    click DashPage "https://github.com/gaurav9508/pdfintellect/blob/main/app/dashboard/page.js"
    click DashLayout "https://github.com/gaurav9508/pdfintellect/blob/main/app/dashboard/layout.js"
    click Header "https://github.com/gaurav9508/pdfintellect/blob/main/app/dashboard/_components/Header.js"
    click Sidebar "https://github.com/gaurav9508/pdfintellect/blob/main/app/dashboard/_components/SideBar.js"
    click UploadDialog "https://github.com/gaurav9508/pdfintellect/blob/main/app/dashboard/_components/UploadPdfDialog.js"
    click Upgrade "https://github.com/gaurav9508/pdfintellect/blob/main/app/dashboard/upgrade/page.js"
    click WSPage "https://github.com/gaurav9508/pdfintellect/blob/main/app/workspace/[fileId]/page.js"
    click PdfViewer "https://github.com/gaurav9508/pdfintellect/blob/main/app/workspace/_components/PdfViewer.js"
    click TextEditor "https://github.com/gaurav9508/pdfintellect/blob/main/app/workspace/_components/TextEditor.js"
    click EditorExt "https://github.com/gaurav9508/pdfintellect/blob/main/app/workspace/_components/EditorExtension.js"
    click WSHeader "https://github.com/gaurav9508/pdfintellect/blob/main/app/workspace/_components/WorkspaceHeader.js"
    click PDFLoader "https://github.com/gaurav9508/pdfintellect/blob/main/app/api/pdf-loader/route.js"
    click Schema "https://github.com/gaurav9508/pdfintellect/blob/main/convex/schema.js"
    click UserMut "https://github.com/gaurav9508/pdfintellect/blob/main/convex/user.js"
    click NotesMut "https://github.com/gaurav9508/pdfintellect/blob/main/convex/notes.js"
    click FileStorage "https://github.com/gaurav9508/pdfintellect/blob/main/convex/fileStorage.js"
    click Langchain "https://github.com/gaurav9508/pdfintellect/blob/main/convex/langchain/db.js"
    click AIAction "https://github.com/gaurav9508/pdfintellect/blob/main/convex/myAction.js"
    click GeneratedAPI "https://github.com/gaurav9508/pdfintellect/blob/main/convex/_generated/api.js"
    click GeneratedServer "https://github.com/gaurav9508/pdfintellect/blob/main/convex/_generated/server.js"
    click AIConfig "https://github.com/gaurav9508/pdfintellect/blob/main/configs/AIModel.js"
    click Button "https://github.com/gaurav9508/pdfintellect/blob/main/components/ui/button.jsx"
    click Dialog "https://github.com/gaurav9508/pdfintellect/blob/main/components/ui/dialog.jsx"
    click Input "https://github.com/gaurav9508/pdfintellect/blob/main/components/ui/input.jsx"
    click Progress "https://github.com/gaurav9508/pdfintellect/blob/main/components/ui/progress.jsx"
    click Sonner "https://github.com/gaurav9508/pdfintellect/blob/main/components/ui/sonner.jsx"

    %% Styles
    classDef frontend fill:#e0f7fa,stroke:#006064,color:#004d40
    classDef api fill:#e3f2fd,stroke:#1565c0,color:#0d47a1
    classDef backend fill:#f3e5f5,stroke:#6a1b9a,color:#4a148c
    classDef external fill:#fff3e0,stroke:#ef6c00,color:#e65100
    classDef config fill:#eceff1,stroke:#607d8b,color:#37474f
    classDef ui fill:#f1f8e9,stroke:#558b2f,color:#33691e
```
