Clarity Books

A quarterly bookkeeping assistant that turns receipt photos into a reviewable ledger, CSV export, and draft tax estimate — built for Philippine small businesses.

Upload receipt images, and the app automatically classifies each one as a Sale or Expense, extracts key fields (merchant, date, amount, VAT), and computes a quarterly tax worksheet you can print or export.

Features

• AI-powered receipt scanning — A chain of vision LLMs (Gemini → OpenAI → Groq) analyzes uploaded receipt images server-side. If all providers are unavailable, the app falls back to client-side OCR via tesseract.js.
• Auto-classification — Each receipt is automatically labeled as Sale or Expense based on document signals (e.g., "sales invoice" vs. "cash tendered"). Users can override the classification in the ledger.
• Editable ledger — Review and correct extracted data (date, merchant, type, gross amount, VAT) before using the numbers.
• Tax estimate worksheet — Choose between percentage tax, income tax, or VAT payable, and generate a draft government-style worksheet with computed totals.
• CSV export — Download the full receipt ledger as a CSV file for use in spreadsheets or accounting software.
• Built-in chat assistant — A floating chatbot answers tax-related questions using the same LLM provider chain, with FAQ quick-replies for common topics.
• Privacy-first — Images are processed server-side via API keys you control; nothing is stored or sent to third parties beyond the configured providers.

Tech Stack

Layer	Technology
Framework	Next.js 14 (App Router)
Language	TypeScript
Styling	Tailwind CSS (via globals.css)
OCR fallback	tesseract.js 4
AI providers	Google Gemini 2.5 Flash, OpenAI GPT-4o-mini, Groq Llama 4 Scout
Deployment	Vercel (recommended)

Project Structure

app/
├── page.tsx              # Main UI — upload, ledger, and tax estimate steps
├── layout.tsx            # Root layout with metadata and chat bubble
├── globals.css           # All application styles
└── api/
    ├── analyze/          # POST /api/analyze — receipt image analysis
    │   ├── route.ts
    │   ├── types.ts
    │   └── providers/    # Gemini, OpenAI, Groq vision implementations
    └── chat/
        └── route.ts      # POST /api/chat — tax Q&A chatbot
component/
├── chat-bubble.tsx       # Floating chat toggle button
└── chat-panel.tsx        # Chat conversation UI
lib/
├── ai-providers.ts       # LLM provider chain for chat responses
└── chatbot-responses.ts  # FAQ keyword matching and fallback answers

Prerequisites

• Node.js 18 or newer
• npm

Getting Started

1. Install dependencies

npm install

2. Configure environment variables

Copy the example file and add your API keys:

cp .env.local.example .env.local

Variable	Provider	Purpose
GEMINI_API_KEY	Google Gemini	Vision analysis and chat (primary)
OPENAI_API_KEY	OpenAI	Vision analysis and chat (fallback)
GROQ_API_KEY	Groq	Vision analysis and chat (final fallback)

At least one key is required for server-side receipt analysis. If none are configured, the app degrades gracefully to client-side tesseract.js OCR (slower, less accurate).

API keys are read only on the server and never reach the browser.

3. Run the development server

npm run dev

Open http://localhost:3000 in your browser.

Usage Workflow

1. Upload receipts — Drop or select receipt photos (JPG, PNG, WEBP). The app scans each image and extracts merchant, date, amount, and VAT.
2. Review the ledger — Verify extracted data in an editable table. Correct any highlighted fields (missing amounts show a "Required" placeholder). Mark rows as Verified when satisfied.
3. Tax estimate — Choose your tax basis (percentage tax at 3%, income tax, or VAT payable), review the computed totals on a government-style worksheet, and print or export.

Building for Production

npm run build
npm start

Deploying to Vercel

1. Push the repository to GitHub/GitLab.
2. Import the project into Vercel.
3. Add GEMINI_API_KEY, OPENAI_API_KEY, and/or GROQ_API_KEY under Settings → Environment Variables.
4. Deploy.

How Receipt Analysis Works

When a receipt image is uploaded:

1. The image is encoded as base64 and sent to POST /api/analyze.
2. The server tries each vision provider in order (Gemini → OpenAI → Groq) until one succeeds.
3. The provider returns structured data: kind (Sale/Expense), merchant, date, amount, and vat.
4. If all server providers fail, the client falls back to tesseract.js OCR with local text parsing.

The classification logic looks for document signals:

• Sale signals — "sales invoice", "official receipt", "sold to", "bill to"
• Expense signals — "thank you for your purchase", "cash tendered", "cashier", "POS"

Notes

• Currency is formatted in Philippine Peso (₱ PHP).
• The tax worksheet is clearly marked as a draft and is not valid for government filing.
• The chat assistant uses the same provider fallback chain as receipt analysis.
• All processing happens per-session; no data is persisted to a database.