# arhanansari/chat-to-pdf architecture

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

- Interactive diagram: https://gitdiagram.com/arhanansari/chat-to-pdf
- Repository: https://github.com/arhanansari/chat-to-pdf

## Overview

##### Project type and purpose
- This is a full-stack SaaS web application (“Chat to PDF”) built with Next.js and React, integrating AI (OpenAI & Langchain), vector DB (Pinecone), file storage (Firebase), authentication (Clerk), and payment (Stripe). Users sign up, upload PDFs, chat with their documents, and manage subscriptions.

##### File structure
- Top-level:
- app/ (Next.js 13+ App Router) with pages: landing (app/page.tsx), sign-in/up, dashboard, upload, files, upgrade, webhook
- actions/ (server actions for Stripe, Firestore, embeddings, document delete)
- components/ & components/ui/ (React UI components & design system)
- lib/ (wrappers for OpenAI/Langchain, Pinecone, Stripe, utils)
- hooks/ (client hooks: useUpload, useSubscription)
- firebase.ts & firebaseAdmin.ts (client & admin SDK init)
- middleware.ts (route protection via Clerk)
- next.config.mjs, tailwind.config.ts, etc.

##### README for additional insights
- Describes a 5-day challenge demo app: build landing, auth with Clerk, upload with React-Dropzone, Firebase storage & Firestore, PDF viewer, Pinecone + Langchain + OpenAI chat, Stripe checkout & webhooks, role-based access (free / pro), file delete/download, deployments to Vercel.

a. Main components
- Client (Browser/React UI)
- Next.js App (Server + Edge Functions)
- Authentication Service (Clerk)
- File Storage & Database (Firebase Storage & Firestore)
- Vector DB & Embedding Service (Pinecone + Langchain + OpenAI API)
- Payment Service (Stripe + Webhook)
- External CDN/Deployment (Vercel / Netlify badge)

b. Relationships & interactions
- User ←→ Next.js frontend (React on client, server-side rendering/page routing)
- Next.js ←→ Clerk for sign-in/up, JWT session
- Next.js Server Actions / API Routes:
- upload PDF → Firebase Storage & store metadata in Firestore
- generateEmbeddings → OpenAI embeddings → Pinecone upsert
- askQuestion → Query Pinecone → Langchain chain → OpenAI → return chat response
- createCheckoutSession / createStripePortal → Stripe API → return session URL
- Stripe Webhook endpoint (app/webhook/route.ts) → Listen for events → update Firestore subscription docs
- deleteDocument → remove from Firestore & Pinecone & Firebase Storage
- Client Hooks consume:
- useUpload (calls upload action)
- useSubscription (polls Firestore for subscription status)
- Components render PDF (PdfView), chat (Chat, ChatMessage), documents list, config form, upgrade flows.

c. Architectural patterns & design principles
- Jamstack / Serverless functions (Next.js App Router server actions)
- Separation of concerns: UI components, server actions, data layer (lib/ + hooks/)
- External managed services for heavy lifting (auth, AI, vector DB, payments, storage)
- Single-page app feel with SSR & ISR where needed

d. Key technologies & libraries
- Next.js 13 (App Router, React Server Components)
- React & Tailwind CSS (shadcn/ui primitives)
- Clerk (authentication & middleware)
- Firebase Storage & Firestore (file storage & metadata)
- Pinecone + Langchain + OpenAI (vector search & chat)
- Stripe (checkout, billing portal, webhooks)
- Vercel (deployment)

- Frontend: Next.js pages & React components communicate via fetch or server actions.
- Auth: Clerk middleware protects dashboard routes; tokens validated server-side.
- File upload: React-Dropzone → Next.js action → Firebase Storage → Firestore metadata.
- Embeddings: upon file upload, server action calls OpenAI embeddings → Pinecone client in lib/pinecone.ts.
- Chat: frontend sends question → askQuestion action → Pinecone query → Langchain chain → OpenAI → return answer.
- Billing: createCheckoutSession → Stripe checkout → webhook endpoint updates Firestore subscription status → UI hook reflects plan.
- Document management: list & delete documents via server actions that coordinate Firebase + Pinecone.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client (Browser)" 
        direction TB
        UI["React UI Components"]:::frontend
        Hooks["Client Hooks"]:::frontend
        UI -->|uses| Hooks
        Landing["Landing Page"]:::frontend
        SignIn["Sign-In Page"]:::frontend
        SignUp["Sign-Up Page"]:::frontend
        Dashboard["Dashboard Pages"]:::frontend
        UploadPage["Upload Page"]:::frontend
        FilesPage["File Listing & Detail"]:::frontend
        UpgradePage["Upgrade Page"]:::frontend
        UI -->|renders| Landing
        UI -->|renders| SignIn
        UI -->|renders| SignUp
        UI -->|renders| Dashboard
        Dashboard --> UploadPage
        Dashboard --> FilesPage
        Dashboard --> UpgradePage
    end

    %% Server Layer
    subgraph "Next.js App Server" 
        direction TB
        Middleware["Auth Middleware"]:::server
        UploadAction["upload PDF Action"]:::server
        EmbedAction["generateEmbeddings"]:::server
        ChatAction["askQuestion"]:::server
        CheckoutAction["createCheckoutSession"]:::server
        PortalAction["createStripePortal"]:::server
        DeleteAction["deleteDocument"]:::server
        Webhook["Stripe Webhook Endpoint"]:::server
        Middleware -->|protects| UploadAction
        Middleware -->|protects| EmbedAction
        Middleware -->|protects| ChatAction
        Middleware -->|protects| CheckoutAction
        Middleware -->|protects| PortalAction
        Middleware -->|protects| DeleteAction
    end

    %% Integration Layer
    subgraph "Lib Integrations" 
        direction TB
        Langchain["LangChain & OpenAI"]:::server
        PineconeClient["Pinecone Client"]:::server
        StripeLib["Stripe Integration"]:::server
        FirebaseAdmin["Firebase Admin SDK"]:::server
        Utils["Utility Helpers"]:::server
    end

    %% External Services
    subgraph "External Services"
        direction TB
        ClerkAPI["Clerk API"]:::external
        FirebaseStorage["Firebase Storage"]:::datastore
        FirestoreDB["Firestore"]:::datastore
        PineconeDB["Pinecone Vector DB"]:::datastore
        OpenAIAPI["OpenAI API"]:::external
        StripeAPI["Stripe API"]:::external
    end

    %% Data Flows
    UI -->|calls Server Actions| UploadAction
    UploadAction -->|stores file| FirebaseStorage
    UploadAction -->|writes metadata| FirestoreDB
    UploadAction -->|calls| EmbedAction
    EmbedAction -->|gets embeddings| OpenAIAPI
    EmbedAction -->|upserts vectors| PineconeDB
    UI -->|sends question| ChatAction
    ChatAction -->|queries| PineconeDB
    ChatAction -->|invokes| Langchain
    Langchain -->|calls| OpenAIAPI
    ChatAction -->|returns answer| UI
    UI -->|click upgrade| CheckoutAction
    CheckoutAction -->|creates session| StripeAPI
    UI -->|manage portal| PortalAction
    PortalAction -->|calls| StripeAPI
    StripeAPI -->|webhook event| Webhook
    Webhook -->|updates| FirestoreDB
    UI -->|delete doc| DeleteAction
    DeleteAction -->|removes metadata| FirestoreDB
    DeleteAction -->|deletes file| FirebaseStorage
    DeleteAction -->|removes vectors| PineconeDB
    UI -->|auth requests| ClerkAPI

    %% Click Events
    click UI "https://github.com/arhanansari/chat-to-pdf/tree/main/components/"
    click Landing "https://github.com/arhanansari/chat-to-pdf/blob/main/app/page.tsx"
    click SignIn "https://github.com/arhanansari/chat-to-pdf/blob/main/app/sign-in/[[...sign-in]]/page.tsx"
    click SignUp "https://github.com/arhanansari/chat-to-pdf/blob/main/app/sign-up/[[...sign-up]]/page.tsx"
    click Dashboard "https://github.com/arhanansari/chat-to-pdf/blob/main/app/dashboard/layout.tsx"
    click Dashboard "https://github.com/arhanansari/chat-to-pdf/blob/main/app/dashboard/page.tsx"
    click UploadPage "https://github.com/arhanansari/chat-to-pdf/blob/main/app/dashboard/upload/page.tsx"
    click FilesPage "https://github.com/arhanansari/chat-to-pdf/blob/main/app/dashboard/files/[id]/page.tsx"
    click UpgradePage "https://github.com/arhanansari/chat-to-pdf/blob/main/app/dashboard/upgrade/page.tsx"
    click Webhook "https://github.com/arhanansari/chat-to-pdf/blob/main/app/webhook/route.ts"
    click ChatAction "https://github.com/arhanansari/chat-to-pdf/blob/main/actions/askQuestion.ts"
    click EmbedAction "https://github.com/arhanansari/chat-to-pdf/blob/main/actions/generateEmbeddings.ts"
    click CheckoutAction "https://github.com/arhanansari/chat-to-pdf/blob/main/actions/createCheckoutSession.ts"
    click PortalAction "https://github.com/arhanansari/chat-to-pdf/blob/main/actions/createStripePortal.ts"
    click DeleteAction "https://github.com/arhanansari/chat-to-pdf/blob/main/actions/deleteDocument.ts"
    click Hooks "https://github.com/arhanansari/chat-to-pdf/blob/main/hooks/useUpload.ts"
    click Hooks "https://github.com/arhanansari/chat-to-pdf/blob/main/hooks/useSubscription.ts"
    click FirebaseAdmin "https://github.com/arhanansari/chat-to-pdf/blob/main/firebaseAdmin.ts"
    click Langchain "https://github.com/arhanansari/chat-to-pdf/blob/main/lib/langchain.ts"
    click PineconeClient "https://github.com/arhanansari/chat-to-pdf/blob/main/lib/pinecone.ts"
    click StripeLib "https://github.com/arhanansari/chat-to-pdf/blob/main/lib/stripe.ts"
    click Utils "https://github.com/arhanansari/chat-to-pdf/blob/main/lib/utils.ts"

    %% Styles
    classDef frontend fill:#AED6F1,stroke:#21618C,color:#000
    classDef server fill:#ABEBC6,stroke:#196F3D,color:#000
    classDef external fill:#F9E79F,stroke:#B9770E,color:#000
    classDef datastore fill:#F5B7B1,stroke:#C0392B,color:#000
```
