Overview & Vision Link to heading

A full-stack personal finance application that transforms the tedious task of manual expense tracking into a fast, intelligent workflow. Users capture receipts via camera, file upload, text paste, or manual entry, and an AI model automatically extracts the merchant, date, location, and every line item into a structured, editable database. Data can also be pulled directly from Costco’s purchase history API or imported via CSV. The result is a single, always-up-to-date ledger of personal spending — searchable, exportable, and visualised through charts — accessible from any device on the local network, including mobile phones.

Vision: Make expense tracking effortless enough that people actually do it, by eliminating the “I’ll log it later” gap between buying something and recording it.

Problem Statement Link to heading

Manual expense tracking is broken:

  • Paper receipts are lost, faded, or forgotten before they are ever logged
  • Spreadsheet entry is slow and error-prone, so people stop doing it
  • Bank statement exports are coarse — they show a merchant total but not individual items
  • Existing apps require subscriptions, cloud accounts, or third-party data sharing
  • Receipt photos pile up unsorted in camera rolls, never becoming usable data

Users need a private, self-hosted tool that turns any receipt — physical or digital — into structured, queryable spending data with minimal effort.

Target Audience Link to heading

Primary users:

  • Individuals and households who want itemised control over their spending without subscribing to a SaaS product
  • Small-business owners or freelancers tracking personal reimbursable expenses

Requirements & Features Link to heading

Receipt Capture

  • Upload image files (JPG, PNG, WEBP, HEIC, GIF) via drag-and-drop or file picker
  • Capture photo directly from device camera (mobile-friendly; requires HTTPS)
  • Paste raw receipt text for AI parsing
  • Manually enter a receipt with header fields (merchant, date, location) and an inline line-items table

AI-Powered Parsing

  • Send receipt image or text to a selectable AI model: Anthropic Claude, OpenRouter, DeepSeek, or Gemini (configured via environment variable)
  • Extract: merchant name, date, location, subtotal, tax, total, and all line items (description, quantity, unit price, total price, category)
  • Robust JSON extraction handles model responses wrapped in prose or markdown code fences
  • max_tokens set to 4096 to prevent truncation on large receipts

Transaction Management

  • View all line items in a searchable, filterable table
  • Toggle between read mode and edit mode per receipt or globally
  • In edit mode: modify any field inline (text, number, date/time, category dropdown)
  • Add new line items to an existing receipt
  • Delete individual line items (immediate) or bulk-delete selected rows (applied on Save)
  • Mass-update a column across all selected rows via a popover
  • Save changes to SQLite database; all changes are atomic per Save action
  • Export all transactions to CSV

Monthly View

  • Group and display spending by calendar month
  • Progress bars visualising spend vs. prior periods
  • Month selector to navigate history

Analytics

  • Bar charts: monthly spending totals
  • Pie chart: spending by category
  • Line chart: spending trend over time
  • Merchant breakdown table and daily spending breakdown

Costco Integration

  • Enter bearer token, client ID, and client identifier (captured from browser DevTools)
  • Token freshness badge: live countdown showing remaining validity (tokens expire after 15 minutes) with green / amber / red colour states
  • Fetch mode: last N days (7 / 14 / 30 / 60 / 90) or custom date range (From / To date pickers)
  • Discover step: connects to Costco GraphQL API, samples one receipt to catalogue all available fields with live sample values
  • Field mapping step: user maps each Costco item field to an app column (Description, Unit Price, Total Price, Quantity, Category, or Skip)
  • Preview step: list of receipts with already-imported flags (deduplication via source_id)
  • Import step: fetches full receipt detail per barcode, applies field mapping, saves to database

CSV Import

  • Upload any CSV file
  • Auto-detect column mapping from common header aliases (date, amount, merchant, etc.)
  • Manual mapping UI with live preview rows
  • Import creates one receipt per merchant-date group with all matching line items

Manual Receipt Entry

  • Fourth tab under “Add Receipt”: Manual Entry
  • Receipt header: merchant (required), date, location
  • Inline table: add / remove rows; columns match the Transaction table (date, description, qty, unit $, total $, category)
  • Running total auto-computed in table footer
  • Save creates a full receipt + line items record in the database

Infrastructure

  • HTTPS dev server (self-signed certificate) for camera access on the local network
  • SQLite database with receipts and line_items tables; source_id column with unique partial index for deduplication
  • All four AI providers lazily initialised to avoid dotenv load-order issues
  • Backend and frontend start together via a single ./start.sh command

User Stories & Acceptance Criteria Link to heading

Story 1 — Capture a receipt via camera As a user on my phone, I want to take a photo of a receipt so that it is automatically parsed into line items.

  • Camera tab activates the device rear camera over HTTPS
  • Captured image is sent to AI; parsed results appear in the transaction review panel within 10 seconds on a standard connection
  • All visible line items on the receipt appear as editable rows

Story 2 — Edit and save parsed line items As a user, I want to correct any AI parsing errors and save the result to the database.

  • Clicking Edit switches all fields to inline inputs
  • Changing a value and clicking Save persists it to SQLite and returns to read mode
  • No unsaved changes are lost on accidental navigation within the same receipt

Story 3 — Bulk delete transactions As a user, I want to select multiple rows and delete them in one action.

  • Selecting all rows and clicking Delete removes them from the UI immediately
  • Clicking Save removes them from the database; they do not reappear after save
  • Cancelling Edit after a bulk delete restores the original rows

Story 4 — Mass-update a column As a user, I want to set the same category for 20 selected rows at once.

  • Clicking a column header button opens a popover for that column
  • Entering a value and confirming updates all selected rows (or all visible rows if none selected)
  • Change is reflected in the table immediately and persisted on Save

Story 5 — Import from Costco As a Costco member, I want to import my warehouse purchase history automatically.

  • Entering credentials and clicking Connect fetches receipts and discovers available fields within 5 seconds
  • Token freshness badge shows remaining validity in real time; turns red after 15 minutes
  • Custom date range picker lets me choose any From–To window
  • Already-imported receipts are flagged; only new receipts are selectable
  • After import, all line items appear in the Transactions view

Story 6 — Manually enter a receipt As a user without a photo, I want to type in a receipt directly.

  • Manual Entry tab shows a merchant/date/location header form plus an editable line-items table
  • Clicking + Add Line appends a new editable row; clicking 🗑 removes a row
  • Clicking Save Receipt creates a database record and shows the receipt in Transactions

Story 7 — View spending analytics As a user, I want to see where my money goes by category and month.

  • Analytics tab shows bar, pie, and line charts populated from real database data
  • Switching months in Monthly View updates all charts and progress bars

Tech Stack Link to heading

Layer Technology
Frontend React 18 + TypeScript
Build tool Vite + @vitejs/plugin-basic-ssl (HTTPS)
Styling have AI figure this out
Charts Recharts (bar, pie, line)
HTTP client Axios
File upload react-dropzone
Backend Node.js + Express (ES Modules)
Database driver light for now, and pick whatever
File handling have AI figure this out
AI — Anthropic @anthropic-ai/sdk · Claude claude-opus-4-6 (vision)
AI — OpenRouter OpenAI-compatible · multi-model, vision supported
AI — DeepSeek OpenAI-compatible · text-only (no vision)
AI — Gemini OpenAI-compatible · vision supported
Database SQL or single json.
External API Costco ecom-api.costco.com · GraphQL

Database schema:

  • receipts: id, image_path, merchant, date, location, total, raw_response, source_id, created_at
  • line_items: id, receipt_id, description, quantity, unit_price, total_price, category, date, merchant, location

Success Criteria Link to heading

Functional

  • A receipt photo taken on a phone produces correctly categorised line items within 15 seconds, end to end
  • Editing and saving any field persists correctly to the database and survives a full page reload
  • Bulk deleting all rows and saving leaves the transaction table empty with no ghost data
  • Costco import correctly deduplicates previously imported receipts and imports only new ones
  • Analytics charts reflect the current database state without manual refresh

Reliability

  • AI response parsing succeeds even when the model wraps JSON in prose, code fences, or explanatory text (multi-stage extractJSON function)
  • Token expiry is surfaced proactively via the countdown badge — no surprise 401 errors mid-import
  • All API failures surface a visible error message; no silent error swallowing

Performance

  • App loads in under 2 seconds on a local network connection
  • SQLite queries return in under 100 ms for up to 10,000 line items

Self-hosted simplicity

  • Full stack starts with a single command (./start.sh)
  • No cloud account, no subscription, no external database required
  • Works on iOS and Android mobile browsers over HTTPS on the local Wi-Fi network
Summary by Claude Code Link to heading

The Personal Accounting App is a self-hosted, AI-powered receipt tracking system designed for individuals who want granular, item-level visibility into their spending — without cloud dependencies or subscription fees.

At its core, the app solves a gap that bank exports and budgeting apps leave open: they tell you that you spent $359 at Costco, but not that $87 of it was a case of olive oil. By combining AI vision parsing, direct Costco API integration, and a fully editable transaction ledger, the app turns every receipt — whether photographed, typed, pasted, or pulled from a retailer API — into structured, queryable data.

The system is deliberately pragmatic: it runs locally on a MacBook or home server, is accessible from any phone on the same Wi-Fi network, and stores everything in a single SQLite file that is easy to back up. The AI layer is swappable between four providers so users are never locked into one vendor. The Costco integration reflects real-world usage — many households make large, item-rich warehouse trips that are worth tracking at the item level, not just the receipt total.

Built with React, TypeScript, Node.js, Express, and SQLite, the stack is intentionally straightforward: well-documented, easy to understand, and simple to extend. The UI prioritises speed of entry and ease of correction — because the goal is to make recording expenses fast enough that people do it consistently.