pantry-app/pantry
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
feature/local-dev-setup
pantry/docs/PROJECT_PLAN.md
Claw 41537fa84c docs: Initial project documentation 
- README: Project overview, quick start, tech stack
- PROJECT_PLAN: Vision, roadmap, 6-week MVP timeline
- ARCHITECTURE: System design, data model, tech decisions

Establishes foundation for Pantry - self-hosted kitchen
inventory PWA with barcode scanning.
2026-02-08 18:47:48 +00:00

7.2 KiB
Raw Permalink Blame History

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

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

Reference in New Issue View Git Blame Copy Permalink