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

- [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)