# 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 - [x] 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](./ARCHITECTURE.md) - [Database Schema](./DATABASE.md) - [API Reference](./API.md) - [Development Guide](./DEVELOPMENT.md) --- **Next Steps:** Review this plan, then build [ARCHITECTURE.md](./ARCHITECTURE.md)