How harun8/askpdf works
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).