🧺 Larder
Larder is an AI-powered inventory tracker that turns grocery receipts into a smart kitchen. Upload a photo of any receipt and Claude AI extracts every item — name, quantity, category, price, and estimated shelf life — into a pantry view that warns you before things expire. The average US household wastes ~$1,500 of food a year; Larder helps you fix that.
A production full-stack application built with Next.js 16 + React 19 on the frontend, FastAPI + Python on the backend, Supabase (Postgres + JWT auth) for data and identity, and Anthropic Claude for AI-powered receipt parsing. Deployed across Vercel and Render with GitHub Actions CI/CD.
📸 Screenshots
Screenshots are checked into docs/screenshots and captured from the local production builds with a seeded demo pantry session.
| Pantry dashboard | Expiring soon |
|---|
| |
🎯 What this project demonstrates
A complete end-to-end product built solo — frontend, backend, database, auth, AI integration, DevOps, and design.
| Area | Where it lives |
|---|
| Frontend engineering | 3 Next.js 16 App Router apps (web + marketing + docs), 11 routes, ~3,500 LOC of TypeScript/React |
| Backend engineering | FastAPI service with 10 endpoints, Pydantic v2 validation, dependency injection, lifespan hooks |
| Authentication & security | Supabase JWT (ES256) verification with JWKS, key-rotation fallback, type-email-to-confirm flows for destructive actions |
| Database design | Postgres schema with soft deletes, status state machine, re-purchase inference, indexed queries |
| AI / ML integration | Claude vision API for receipt parsing, structured JSON extraction, shelf-life estimation |
| DevOps & deployment | Three independent deploy targets (2× Vercel, 1× Render), explicit CORS allowlist via FRONTEND_URL, env-var-driven config |
| CI/CD | GitHub Actions: ruff lint, Next.js typecheck, auto-merge on green with retry loop |
| Product & UX design | Warm earthy design system, Notion-style sidebar, Headspace-inspired marketing site, animated mockups |
| Compliance | GDPR-friendly account deletion (cascades pantry + receipts + auth user), public privacy policy |
🔗 Live links
✨ Features
Core
- 📸 Receipt scanning — upload photo, PDF, Excel, Word, CSV, or TXT; Claude AI extracts every item with name, quantity, unit, category, price, and estimated shelf life
- 🥦 Smart pantry — items auto-grouped by category with color-coded freshness bars
- ⏰ Expiry tracking — three-tier urgency system (red / amber / green) + dedicated
/expiring page grouped into Expired / Today / Next 3 days
- 🔔 Live sidebar badge — fetches expiring count on every route change
- ➕ Manual add — for items without a receipt
- 🔍 Search & sort — real-time text search + Expiry / Name / Recent sort
- ✏️ Item details modal — click any item to see purchase date, days since added, shelf life, and full metadata
- 📉 Decrement & consume — track partial usage or mark fully used in one tap; uses Postgres atomic updates
Auth & account
- 🔑 Email/password sign up & sign in via Supabase (ES256 JWTs with HS256 dev fallback)
- 🔄 Password reset flow with secure email link +
PASSWORD_RECOVERY event handling
- ⚙️ Settings page — profile, change password, sign out
- 🗑️ Account deletion — type-email-to-confirm; cascades deletion of pantry, receipts, and auth user (GDPR-compliant)
- 📄 Public privacy policy page
Marketing site
- Animated hero with two product preview cards
- Scroll-triggered fade/slide animations (IntersectionObserver)
requestAnimationFrame-based count-up stats- CSS
@keyframes marquee ticker strip
- Tabbed feature showcase, FAQ accordion, auto-rotating testimonials
🤖 AI / LLM integration
Larder treats Claude as a first-class component, not a wrapper.
- Vision-based receipt parsing — Anthropic's Claude Sonnet (vision model) parses uploaded receipt images, PDFs, and structured documents (Word, Excel, CSV, TXT) into validated JSON items
- Structured output via JSON schema — the prompt instructs Claude to return strictly-typed items (
canonical_name, category, quantity, unit, price, shelf_life_days); responses are then parsed and validated through Pydantic v2 before insert
- Prompt engineering — single-shot prompt with category enum constraints, unit normalization rules, and shelf-life estimation grounded in food-type knowledge (milk ~7 days, canned goods ~365, produce ~3-14)
- Multi-modal input handling — images sent as base64; documents stripped to plain text before sending; the same prompt handles all input types via Claude's content blocks API
- Cost & latency aware — receipt parsing is the only LLM call in the hot path; everything else (search, sort, expiry checks) is pure Postgres
- Server-side only — Anthropic API key never leaves the FastAPI backend; the frontend never touches the LLM directly
Code: backend/app/services/vision.py and backend/app/api/receipts.py
🧱 Tech stack
| Layer | Tech |
|---|
| Frontend | Next.js 16 (App Router), React 19, TypeScript, Tailwind v4 |
| Backend | FastAPI, Pydantic v2, Uvicorn |
| Database & auth | Supabase (PostgreSQL, Row-Level Security, JWT) |
| AI | Anthropic Claude (claude-sonnet) — vision + structured extraction |
| File processing | Pillow (images), python-docx (Word), openpyxl (Excel), pdf parsing |
| Rate limiting | slowapi |
| Hosting | Vercel (frontend × 2), Render (Python backend) |
| CI/CD | GitHub Actions — ruff lint, Next.js typecheck, auto-merge on green |
🏗️ Architecture
┌────────────────────┐ ┌────────────────────┐
│ Marketing site │ │ Web app │
│ larder-website │ │ larder-theta │
│ (Next.js / SSG) │ │ (Next.js / CSR) │
└────────────────────┘ └─────────┬──────────┘
│ JWT (ES256)
▼
┌────────────────────┐
│ FastAPI backend │
│ larder.onrender │
│ │
│ ┌──────────────┐ │
│ │ /receipts │──┼──▶ Anthropic Claude
│ │ /pantry │ │
│ │ /account │ │
│ └──────┬───────┘ │
└─────────┼──────────┘
▼
┌────────────────────┐
│ Supabase │
│ • auth.users │
│ • pantry_items │
│ • receipts │
└────────────────────┘
Notable design decisions
- Two separate Next.js apps — marketing site (statically generated, SEO-friendly) is fully independent from the web app (client-rendered, auth-gated). They share no code but use the same warm-earthy design tokens.
- JWT verification with key rotation support — backend verifies Supabase JWTs using JWKS endpoint for ES256 keys, falls back to HS256 shared secret for older tokens. Handles Supabase's mid-2024 key format migration.
- Soft delete on pantry items — every item has a
status field (active, consumed_manual, consumed_inferred, expired, deleted) for full audit history. Re-purchase inference auto-marks duplicate active items as consumed_inferred when a new receipt adds the same canonical name.
- CORS with an explicit allowlist — the backend allows
localhost plus the exact origins listed in FRONTEND_URL (comma-separated). There is deliberately no wildcard *.vercel.app regex, so arbitrary preview origins can't call the API; add a new front-end origin by setting the env var.
- Atomic quantity decrement — the
/decrement endpoint reads and updates quantity in one round-trip, marking the item consumed if it drops below 1.
- Optimistic UI throughout — every action (mark used, decrement, edit, delete) updates local state immediately and only rolls back on API failure.
📁 Repository structure
pantry-poc/
├── backend/ # FastAPI backend
│ ├── app/
│ │ ├── api/ # Route handlers (receipts, pantry, account)
│ │ ├── services/ # Business logic (vision, pantry_state)
│ │ ├── auth.py # JWT verification (ES256 + HS256 fallback)
│ │ ├── db.py # Supabase client
│ │ ├── limiter.py # Rate limiter config
│ │ └── main.py # FastAPI app + CORS + lifespan
│ ├── scripts/
│ │ └── nightly_expiry.py
│ └── requirements.txt
│
├── web/ # Next.js consumer app (auth-gated)
│ ├── app/
│ │ ├── page.tsx # Pantry dashboard
│ │ ├── scan/ # Receipt upload page
│ │ ├── login/ signup/ forgot-password/ reset-password/
│ │ ├── settings/ # Profile, password, account deletion
│ │ ├── expiring/ # Items expiring within 3 days
│ │ └── AppShell.tsx # Sidebar + mobile nav wrapper
│ └── lib/supabase.ts
│
├── website/ # Next.js marketing site
│ ├── app/
│ │ ├── page.tsx # Landing page
│ │ ├── docs/
│ │ └── privacy/
│ └── components/ # Nav, Footer, animated sections, FAQ, etc.
│
├── render.yaml # Render deployment config
├── .github/workflows/ # CI: lint, build, auto-merge
└── README.md
🚀 Local development
Backend
cd backend
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -r requirements.txt
uvicorn app.main:app --reload --port 8000
Required env vars (backend/.env):
SUPABASE_URL=https://<project>.supabase.co
SUPABASE_SERVICE_KEY=<service role key>
ANTHROPIC_API_KEY=<key from console.anthropic.com>
FRONTEND_URL=http://localhost:3000
DEV_MODE=true
Web app
cd web && npm install && npm run dev
Required env vars (web/.env.local):
NEXT_PUBLIC_SUPABASE_URL=https://<project>.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=<anon key>
NEXT_PUBLIC_API_URL=http://localhost:8000
Marketing site
cd website && npm install && npm run dev
🔑 API reference
All authenticated endpoints expect Authorization: Bearer <Supabase JWT>.
| Method | Path | Purpose |
|---|
POST | /receipts | Upload a receipt; returns extracted items |
GET | /pantry | List all active items |
GET | /pantry/expiring?days=3 | Items expiring within N days |
POST | /pantry | Manually add an item |
PATCH | /pantry/{id} | Edit an item |
PATCH | /pantry/{id}/consumed | Mark fully used |
PATCH | /pantry/{id}/decrement | Atomic quantity −1 |
DELETE | /pantry/{id} | Soft delete |
DELETE | /account | Hard delete account + cascade |
GET | /health | Liveness probe |
🗄️ Database schema
pantry_items
| Column | Type | Notes |
|---|
id | uuid | PK |
user_id | uuid | FK → auth.users |
canonical_name | text | lowercased on insert |
category | text | enum-checked at API layer |
quantity | numeric | |
unit | text | |
price | numeric | nullable |
purchased_at | timestamptz | |
est_expiry | timestamptz | indexed |
consumed_at | timestamptz | nullable |
shelf_life_days | int | Claude estimate |
source_receipt_id | uuid | nullable, FK → receipts |
status | text | active, consumed_manual, consumed_inferred, expired, deleted |
receipts
| Column | Type |
|---|
id | uuid (PK) |
user_id | uuid (FK → auth.users) |
uploaded_at | timestamptz |
item_count | int |
🚢 Deployment
- Marketing site — Vercel project
larder-website, deploys from main
- Web app — Vercel project
larder-theta, deploys from main
- Backend — Render service
larder, deploys from main
A merge to main triggers all three deploys via webhook.
🩺 Uptime & keepalive
Two scheduled GitHub Actions keep the free-tier services warm:
keepalive.yml — pings the Render /health endpoint every ~14 min so the backend never cold-starts (Render sleeps after 15 min idle).nightly.yml — runs the expiry sweep daily, which doubles as Supabase traffic so the database never pauses (Supabase free tier pauses after ~7 days idle).
⚠️ Gotcha: GitHub auto-disables scheduled workflows after 60 days with no repo commits — which would silently stop the keepalive and pause Supabase. A commit to main resets that clock. Services last verified active: 2026-08-10.
📄 License
MIT — built by Chinmay Sawant.
