📑 InvoScope

InvoScope lets you upload, view, and analyze PDF invoices directly in the browser. With features like real-time PDF viewing, AI-powered invoice parsing, search, and invoice management, InvoScope is designed to simplify handling financial documents end-to-end.

---

✨ Features

• 📄 View PDFs in the browser using react-pdf with zoom, rotate, pagination
• ⬆️ Upload PDFs and persist metadata
• 🤖 Extract structured invoice data via Gemini with retry & fallback
• 🔍 Search and manage invoices (list, get, update, delete)

---

⚙️ Tech Stack

• Frontend: Next.js (App Router), TypeScript, Tailwind, react-pdf
• Backend: Node.js/Express, TypeScript, Mongoose/MongoDB, Google Gemini (for extraction)

---

🌱 Prerequisites

• Node.js 20+
• npm 10+
• MongoDB (local or remote)
• Google Gemini API key

---

🚀 Quick Start

1. Clone & Install

git clone https://github.com/AmanKrSahu/pdf-review-app.git
cd pdf-review-app

# install server deps
cd server && npm i

# install client deps
cd ../client && npm i

2. Configure Environment

• Server requires a .env file (see below).
• Client just needs the API base URL via NEXT_PUBLIC_API_BASE.

Create server/.env:

# Express
PORT=8000
NODE_ENV=development

# Mongo
MONGO_URI=mongodb://localhost:27017/pdf_review_app

# CORS
FRONTEND_ORIGIN=http://localhost:3000

# Google Gemini
GEMINI_API_KEY=YOUR_API_KEY

# Uploads
MAX_FILE_SIZE=26214400

3. Run Both Apps (two terminals)

# Terminal A
cd server
npm run build && npm start   # or: npm run dev

# Terminal B
cd client
npm run dev

Frontend ➝ http://localhost:3000 Backend ➝ http://localhost:8000 (base path /api)

---

💻 Client (Next.js)

• React 19, Next 15 (App Router).
• PDF viewing powered by react-pdf.

Worker setup (must match pdf.js version):

// client/src/components/pdf/PdfViewer.tsx
pdfjs.GlobalWorkerOptions.workerSrc = `https://unpkg.com/pdfjs-dist@${pdfjs.version}/build/pdf.worker.min.mjs`;

⚠️ Notes:

• If CDN use is disallowed, map the worker locally via Next config.
• Options passed to <Document /> are memoized to prevent reloads.

---

🛠 Server (Express API)

Base URL: http://localhost:8000/api

• GET / – health check
• POST /upload – upload a PDF
• GET /files/:fileId – fetch PDF file (or metadata)
• POST /extract – run Gemini extraction on uploaded PDF text
• GET /invoices – list invoices (?q=...&page=1&limit=10)
• GET /invoices/:id – get invoice by id OR fileId/fileName
• POST /invoices – create invoice
• PUT /invoices/:id – update by id OR fileId/fileName
• DELETE /invoices/:id – delete by id OR fileId/fileName

🤖 Gemini Resiliency

• Exponential backoff retries for transient errors (429, 503, overload, timeout).

• Fallback model sequence:

  1. gemini-2.5-flash-lite
  2. gemini-2.5-flash
  3. gemini-1.5-flash

🔐 Data Model (Invoice)

export interface LineItem {
  description: string;
  unitPrice: number;
  quantity: number;
  total: number;
}

export interface Invoice {
  _id?: string;
  fileId: string;
  fileName: string;
  vendor: {
    name: string;
    address?: string;
    taxId?: string;
  };
  invoice: {
    number: string;
    date: string;
    currency?: string;
    subtotal?: number;
    taxPercent?: number;
    total?: number;
    poNumber?: string;
    poDate?: string;
    lineItems: LineItem[];
  };
  createdAt: string;
  updatedAt?: string;
}

---

🔍 Features and Interfaces

1. Home Page

2. Invoice Page

3. Upload Invoice Dialog

4. PDF Reviewer Page

---

🧑‍💻 Development Tips

• CORS: set FRONTEND_ORIGIN to your client URL.
• ObjectId vs file identifiers: API accepts both.
• PDF worker mismatch: ensure pdfjs.version matches worker file.
• React hooks: keep them at the top of components.

---

📦 Build & Deploy

Deployment Notes

• Ensure MONGO_URI, GEMINI_API_KEY, FRONTEND_ORIGIN are configured.
• Serve client behind HTTPS if using react-pdf with credentials.

---

🐞 Troubleshooting

• Worker version mismatch → use pdfjs.version worker URL or pin pdfjs-dist.
• 503/overloaded from Gemini → server retries/fallback automatically (check logs).
• CastError for ObjectId → use filename or fileId; server resolves automatically.

---

🚀 Need Help??

Feel free to contact me on Linkedin