scan-receipts/PROJECT.md

Project: Receipt Scanner Web Application UI/UX Upgrade

Architecture

• Framework & Runtime: Next.js 15 App Router, React 19, TypeScript 5.7 (strict), Tailwind CSS 3.4
• Design System: Zenith Silver (#F6F9FF background, #FFFFFF surface cards, #E2E8F0 borders, #000000 accents, crisp 0px sharp corners, Hanken Grotesk / Inter / JetBrains Mono typography)
• Data & Storage: Local-first IndexedDB (idb) with PostgreSQL / Drizzle ORM schema compatibility
• Export Formats: Dual-sheet .xlsx (ExcelJS), DATEV-compliant .csv (UTF-8 BOM), structured .json

Feature Inventory

#	Feature	Description	Milestone	Source	Status
1	Full-page Drag & Drop Overlay	High-visibility global drag-and-drop backdrop overlay across dashboard	M1	ORIGINAL_REQUEST R1	DONE
2	Dedicated Dropzone Component	Visual upload card supporting PDF, PNG, JPEG, WebP with laser scanline	M1	ORIGINAL_REQUEST R1	DONE
3	Batch Upload Drawer & Queue	Multi-file batch queue with instant thumbnail previews, live progress bars	M1	ORIGINAL_REQUEST R1	DONE
4	Error Boundaries & File Retry	Isolated per-file failure handling, corrupt file rejection without halting queue, quick retry/remove	M1	ORIGINAL_REQUEST R1	DONE
5	Side-by-Side Dual Pane Modal	50/50 split review modal with document on LEFT and editable fields on RIGHT	M2	ORIGINAL_REQUEST R2	DONE
6	Interactive Document Viewer	CSS transform Zoom (0.25x–5x), Pan (grab/trackpad), Rotate, Fit-to-Page	M2	ORIGINAL_REQUEST R2	DONE
7	Bounding-Box Visual Cues	2-way highlight synchronization between image bounding boxes and extracted form fields	M2	ORIGINAL_REQUEST R2	DONE
8	Dynamic Line Items Editor	Inline-editable table for line items (description, quantity, price, total) with add/delete row controls	M2	ORIGINAL_REQUEST R2	DONE
9	Field Audit & Immediate Save	"AI Extracted" vs "Manually Edited" indicators, 1-click revert, debounced IndexedDB auto-save, Prev/Next navigation	M2	ORIGINAL_REQUEST R2	DONE
10	Payment Method & Schema Extension	Added payment method selection and extended receipt schema	M2	ORIGINAL_REQUEST R2	DONE
11	Editable Table Affordances	Clear dotted underlines, hover edit cues, human-edited flags in LiveTable	M3	ORIGINAL_REQUEST R3	DONE
12	3-Tier Status Badges	Standardized badges: Scanned (Emerald), Pending Review (Amber), Confirmed (Slate/Blue)	M3	ORIGINAL_REQUEST R3	DONE
13	Floating Batch Actions Toolbar	Multi-select toolbar for Bulk Export (Selected Only to XLSX/CSV/JSON), Bulk Categorize, Bulk Status Update, Bulk Delete	M3	ORIGINAL_REQUEST R3	DONE
14	Quick Search & Filter Chips Bar	Clickable chip filters for temporal ranges (Today/Week/Month/Year), status counters, categories, amount brackets	M3	ORIGINAL_REQUEST R3	DONE
15	Responsive Dashboard Navigation	Mobile-friendly sidebar drawer / bottom nav (hidden md:flex) eliminating horizontal clipping on <768px	M4	ORIGINAL_REQUEST R4	DONE
16	Interactive KPI Statistics Cards	Total Scanned, Monthly Spend, Pending Reviews, Average Accuracy cards with click-to-filter micro-interactions	M4	ORIGINAL_REQUEST R4	DONE
17	Accessible Information Hierarchy	WCAG AA contrast, crisp typography, clean header layout, zero horizontal overflow	M4	ORIGINAL_REQUEST R4	DONE
18	E2E & Unit Test Coverage	Comprehensive tests verifying R1–R4 features, build integrity, and typechecks	M5	ORIGINAL_REQUEST AC	DONE

Milestones

#	Name	Scope	Dependencies	Status
M1	Ingestion & Batch Upload (R1)	Global dropzone, batch queue drawer, thumbnails, progress, retry/remove	none	DONE
M2	Side-by-Side Inspector & Split Review (R2)	Dual-pane modal, DocumentViewer (zoom/pan), BBox sync, LineItemsEditor, audit badges	none	DONE
M3	Interactive Table & Batch Operations (R3)	Cell edit affordances, status badges, BatchActionBar, FilterChipsBar, selection hooks	none	DONE
M4	Accessible Hierarchy & Responsive Shell (R4)	Responsive Sidebar/TopNav, interactive KPI cards, mobile drawer, zero-overflow	M1, M2, M3	DONE
M5	E2E Test Suite & Final Verification	Test infra, Tier 1-5 tests, adversarial tests, npm run build, npx tsc --noEmit	M1, M2, M3, M4	DONE

Interface Contracts

M1 Ingestion ↔ Dashboard

• BatchUploadDrawer: Accepts onComplete: (receipts: ProcessedReceipt[]) => void, isOpen: boolean, onClose: () => void.
• BatchUploadDropzone: Accepts onFilesSelected: (files: File[]) => void.
• GlobalDropzoneOverlay: Listens to window drag events; triggers batch queue on file drop.

M2 Inspector ↔ Table & Storage

• ReceiptInspectorModal: Accepts receipt: ProcessedReceipt, isOpen: boolean, onClose: () => void, onSave: (updated: ProcessedReceipt) => void, onNavigate?: (direction: 'prev' | 'next') => void.
• ProcessedReceipt schema additions:
  • paymentMethod?: string
  • boundingBoxes?: Record<string, { x: number; y: number; width: number; height: number }>
  • editedFields?: Record<string, boolean>
  • originalExtraction?: Partial<ProcessedReceipt>

M3 LiveTable ↔ BatchActionBar & FilterChipsBar

• useReceiptFilters: returns { filteredReceipts, activePeriod, setPeriod, activeStatus, setStatus, activeCategory, setCategory, searchQuery, setSearchQuery, amountRange, setAmountRange, resetFilters }.
• useTableSelection: returns { selectedIds, isSelected, toggleSelect, toggleSelectAll, clearSelection, selectAll, count }.
• BatchActionBar: Accepts selectedIds: string[], receipts: ProcessedReceipt[], onBulkDelete, onBulkCategorize, onBulkStatusUpdate, onBulkExport, onClearSelection.

M4 Responsive Shell ↔ Dashboard Layout

• Sidebar: Desktop fixed sidebar (hidden md:flex) and mobile drawer (block md:hidden) triggered via TopNav hamburger button with smooth backdrop transition and zero horizontal overflow.
• TopNav: Header with breadcrumb/view indicator, quick search trigger, user/workspace menu, and mobile drawer toggle button.
• KPI Statistics Cards in page.tsx: Interactive cards for Total Scanned, Monthly Spend, Pending Reviews, and Average Accuracy (calculated dynamically from AI confidence/status with micro-interaction hover states and click-to-filter triggers).

Code Layout

src/
├── app/
│   ├── dashboard/
│   │   ├── layout.tsx                # Responsive shell (TopNav + mobile drawer + desktop Sidebar)
│   │   ├── page.tsx                  # Overview with KPI cards + Ingestion dropzone + LiveTable
│   │   ├── activity/page.tsx         # Activity archive with FilterChipsBar + LiveTable + BatchActionBar
│   │   ├── export/page.tsx           # Export hub with summary statistics & date filters
│   │   └── settings/page.tsx         # Settings & preferences
├── components/
│   ├── dashboard/
│   │   ├── BatchUploadDropzone.tsx   # [M1] Dedicated ingestion dropzone card (DONE)
│   │   ├── BatchUploadDrawer.tsx     # [M1] Multi-file upload queue & progress modal/drawer (DONE)
│   │   ├── GlobalDropzoneOverlay.tsx # [M1] Full-screen dragover overlay (DONE)
│   │   ├── ReceiptInspectorModal.tsx # [M2] 50/50 Dual-pane review modal (DONE)
│   │   ├── DocumentViewer.tsx        # [M2] Zoom, pan, rotate & bounding-box canvas (DONE)
│   │   ├── LineItemsEditor.tsx       # [M2] Line item table & editor (DONE)
│   │   ├── StatusBadge.tsx           # [M3] 3-tier status badges (DONE)
│   │   ├── BatchActionBar.tsx        # [M3] Multi-select batch operations floating bar (DONE)
│   │   ├── FilterChipsBar.tsx        # [M3] Responsive filter chips bar (DONE)
│   │   ├── LiveTable.tsx             # [M3] Spreadsheet table with cell edit indicators (DONE)
│   │   ├── Sidebar.tsx               # [M4] Responsive sidebar & mobile drawer (DONE)
│   │   ├── TopNav.tsx                # [M4] Header with search, mobile trigger, status (DONE)
│   │   └── KPICards.tsx              # [M4] Interactive KPI cards with micro-interactions (DONE)
└── lib/
    ├── hooks/
    │   ├── useReceiptFilters.ts      # [M3] Filtering hook (DONE)
    │   └── useTableSelection.ts      # [M3] Selection hook (DONE)
    ├── schema/
    │   └── receipt.ts                # [M2] Extended receipt schema (DONE)
    └── utils/
        └── boundingBoxes.ts          # [M2] Bounding box calculation & heuristics (DONE)

Appendix: Database Least Privilege

Why. The app must connect to PostgreSQL with only the rights it actually needs — not superuser. The docker-compose defaults make receipt_user the database superuser (POSTGRES_USER). If the application is compromised, an attacker holding the app's credentials would otherwise get full control of the database: read every user's receipts, drop or alter tables, or grant themselves rights. A restricted runtime role limits the blast radius to reading and modifying rows.

Two roles.

• receipt_user — owner / migration role. Keeps full rights (DDL) and is used for migrations and schema init (src/lib/db/init.ts). Never the runtime connection in production.
• receipt_app — runtime role (created by scripts/db-permissions.sql). LOGIN, no superuser, no CREATEDB/CREATEROLE. Granted exactly: CONNECT on the database, USAGE on schema public (no CREATE), SELECT/INSERT/UPDATE/DELETE on all tables, USAGE/SELECT on all sequences, and matching ALTER DEFAULT PRIVILEGES so future tables/sequences created by the owner during migrations are covered automatically. CREATE on public is additionally revoked from the PUBLIC pseudo-role.

How to apply.

• Fresh volume (docker compose up with no existing data): the postgres service mounts scripts/db-permissions.sql into /docker-entrypoint-initdb.d/10-db-permissions.sql; the image runs it once as POSTGRES_USER (superuser) before the app starts.
• Existing database (e.g. the local dev DB): node scripts/apply-db-permissions.mjs — connects with the owner URL from .env.local, executes the same SQL, safe to re-run. Set APP_DATABASE_PASSWORD to override the documented default password (also rotates it on an existing role).

How to verify. node scripts/verify-db-permissions.mjs connects both as the owner and as receipt_app and asserts: no superuser/CREATEDB/CREATEROLE, CONNECT

• schema USAGE, DML on all tables/sequences, no schema CREATE, no DDL (a real CREATE TABLE attempt is denied), default privileges are in place, and the owner can still run DDL. Prints PASS/FAIL and exits 1 on failure.

Limitation. The runtime role has no DDL, so migrations and schema init must use the owner URL. In production: run migrations with DATABASE_URL set to the owner URL, then run the app with DATABASE_URL (or APP_DATABASE_URL, plumbed through docker-compose) set to the restricted receipt_app URL.