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.
This commit is contained in:
Claw
323
docs/PROJECT_PLAN.md
Normal file
323
docs/PROJECT_PLAN.md
Normal file
@@ -0,0 +1,323 @@
|
||||
# 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)
|
||||
Reference in New Issue
Block a user