pantry/docs/PROJECT_PLAN.md

Pantry - Project Plan

Version: 1.0
Last Updated: 2026-02-08
Status: Planning

---

🎯 Vision & Goals

Problem Statement

Kitchen inventory management is either:

• Too complex (Grocy) — intimidating for casual users
• Too simple (KitchenOwl) — missing critical features

Gap: No self-hosted solution that's both powerful AND easy enough for the whole family.

Solution

Pantry — A PWA that makes inventory management invisible:

• Barcode scanning reduces data entry to 3 taps
• Tag-based organization (no rigid categories)
• Unit conversions handled automatically
• Multi-user without household complexity

Success Criteria

• Non-technical family member can add items solo
• Adding via barcode takes <10 seconds
• Zero onboarding docs needed (self-explanatory UI)
• Deployed and used in production by v0.2

---

🎨 Core Principles

1. Family-Friendly First

Test: Can your parents use it without help?

• No technical jargon in UI
• Defaults for everything
• One primary action per screen
• Forgiving (easy undo)

2. Barcode-First Workflow

Most common action should be fastest:

Scan → Confirm → Done (3 taps)

Everything else is secondary.

3. Progressive Disclosure

Simple by default, powerful when needed:

• Quick add: just quantity
• Advanced: tags, expiry, custom units
• Settings: hidden until needed

4. Tag Everything

No rigid hierarchies:

• Position tags: fridge, freezer, pantry
• Type tags: dairy, meat, vegan
• Custom tags: meal-prep, groceries-to-buy
• Multi-tag items (dairy + fridge)

5. Self-Hosted Only

No SaaS plans, ever:

• One-click Docker Compose deploy
• All data stays local
• No phone-home analytics
• MIT licensed

---

🗺️ Roadmap

MVP (v0.1) — 6 weeks

Target: Usable for single household

Core features:

• ✅ Barcode scanning (PWA camera)
• ✅ Auto-fill from Open Food Facts
• ✅ Tag-based organization
• ✅ Unit conversions (metric defaults)
• ✅ Multi-user (email/password auth)
• ✅ PWA (installable, offline-ready)

Out of scope for v0.1:

• OIDC providers (added later)
• Shopping lists
• Recipe integration
• Expiry notifications
• Mobile app (PWA only)

v0.2 — Polish (4 weeks)

• Quick actions (consume, restock)
• Search & advanced filters
• Expiry date tracking
• Low-stock alerts
• OIDC auth (Authentik, Google)

v0.3 — Expansion (TBD)

• Shopping list generation
• Recipe integration
• Meal planning
• Barcode printer labels
• Import/export

v1.0 — Production-Ready (TBD)

• Full test coverage
• Performance optimization
• Mobile app (React Native/Capacitor)
• Admin dashboard
• Multi-language support

---

📅 MVP Timeline (6 Weeks)

Week 1: Foundation

Goal: Core infrastructure + auth

• Create organization + monorepo
• Nuxt 4 scaffold (Tailwind + Nuxt UI)
• Supabase local setup (Docker)
• Database schema (initial)
• Email/password auth
• Deploy to development environment

Deliverable: Authenticated empty app

Week 2: Core Inventory

Goal: Manual inventory management

• Database migrations (items, tags, units)
• Seed default tags & units
• Item CRUD UI
• Tag picker component
• Unit selector with conversions
• Inventory list view

Deliverable: Can add/edit items manually

Week 3: Barcode Scanning

Goal: Scan → Add workflow

• PWA camera permissions
• Barcode scanner component (html5-qrcode)
• Open Food Facts API integration
• Product lookup & cache
• Scan UI flow
• Quick-add from scan

Deliverable: Barcode scanning works end-to-end

Week 4: Tag System

Goal: Flexible organization

• Tag management UI
• Tag categories (position, type, custom)
• Multi-tag selection
• Filter by tags
• Tag-based search
• Tag statistics

Deliverable: Full tag system functional

Week 5: PWA & Offline

Goal: Mobile experience

• PWA manifest
• Service worker (offline cache)
• Install prompt
• Mobile UI polish
• Touch gestures
• Loading states

Deliverable: Installable PWA with offline support

Week 6: Deployment

Goal: Production-ready

• Docker Compose production config
• Environment variables
• Coolify deployment guide
• Backup strategy
• Monitoring setup
• User documentation

Deliverable: Running in production

---

🏗️ Architecture Decisions

Monorepo Structure

Decision: Single repo with /app and /supabase

Rationale:

• Simpler deployment (one repo clone)
• Easier version coordination
• Less overhead for solo/small team

Supabase Direct Access

Decision: Frontend talks to Supabase directly (no custom backend)

Rationale:

• Supabase handles auth, RLS, realtime
• Edge functions for complex logic only
• Faster development
• Less infrastructure

Tag-Based Organization

Decision: Unified tags (no separate locations/categories)

Rationale:

• More flexible (dairy + fridge + meal-prep)
• Easier to expand (just add tags)
• Simpler data model
• Better search/filter

Unit Conversions

Decision: Base units + conversion factors

Rationale:

• Handles metric conversions (kg ↔ g)
• Supports custom units (can, jar)
• User-friendly (pick any unit, we convert)
• Grocy-style but simpler

Multi-User Without Households

Decision: Shared inventory, no tenant isolation

Rationale:

• Simpler for single family use
• Trust model (users can edit anything)
• Avoid SaaS complexity
• Can add later if needed

---

🧪 Testing Strategy

Manual Testing (v0.1)

• Playwright E2E tests (critical paths)
• Mobile testing (real devices)
• Barcode scanning (various formats)

Automated Testing (v0.2+)

• Unit tests (conversion logic, etc.)
• Component tests (Vue Test Utils)
• API tests (Supabase functions)

User Testing (v0.3+)

• Family members (non-technical)
• Real inventory data
• Feedback loop

---

📊 Success Metrics

MVP Launch (v0.1)

• 100+ items scanned successfully
• <10s average scan-to-add time
• Zero crashes in 1 week of use
• Positive feedback from 3+ users

v1.0 Goals

• 10+ active deployments (GitHub issues as proxy)
• 100+ GitHub stars
• Positive user testimonials
• No major bugs >1 week old

---

🚧 Known Challenges

1. Barcode Quality

Problem: Low-light, damaged labels Mitigation: Fallback to manual barcode entry

2. Open Food Facts Coverage

Problem: Not all products in database Mitigation: Allow manual product creation

3. Unit Conversion Edge Cases

Problem: Custom units (e.g., "1 can") Mitigation: Store base quantity, let user define conversions

4. PWA Install Friction

Problem: iOS Safari limitations Mitigation: Clear install instructions, test on iOS

---

🔄 Review & Iteration

Weekly Review:

• What shipped?
• What blocked us?
• Adjust next week's scope

Post-MVP:

• User feedback sessions
• GitHub issues prioritization
• Feature roadmap votes

---

📚 References

• Architecture
• Database Schema
• API Reference
• Development Guide

---

Next Steps: Review this plan, then build ARCHITECTURE.md