From a9ff5e860725496d128b94f81dc9ea6282cacc09 Mon Sep 17 00:00:00 2001 From: Dani B Date: Tue, 27 Jan 2026 23:44:43 -0500 Subject: [PATCH] docs: define v1 requirements 62 requirements across 9 categories: - Inventory core (7) - Sharing & multi-user (10) - Expiration management (7) - Authentication (5) - Notifications (7) - AI shopping prediction (7) - Local sales tracking (7) - Setup & onboarding (6) - UI & platform (7) - Data & performance (9) v2 deferred: recipes, iOS, advanced features All requirements ready for roadmap mapping. Co-Authored-By: Claude Haiku 4.5 --- .planning/REQUIREMENTS.md | 231 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 231 insertions(+) create mode 100644 .planning/REQUIREMENTS.md diff --git a/.planning/REQUIREMENTS.md b/.planning/REQUIREMENTS.md new file mode 100644 index 0000000..90576df --- /dev/null +++ b/.planning/REQUIREMENTS.md @@ -0,0 +1,231 @@ +# Requirements: Sage + +**Defined:** 2026-01-27 +**Core Value:** Users get accurate expiration alerts and never waste food due to forgotten ingredients + +## v1 Requirements + +### Inventory Core + +- [ ] **INV-01**: User can add items by barcode scan with product lookup +- [ ] **INV-02**: User can add items manually with name, quantity, location, optional expiration date +- [ ] **INV-03**: User can view full inventory organized by location/category +- [ ] **INV-04**: User can search and filter inventory by item name, location, or expiration status +- [ ] **INV-05**: User can edit item details (quantity, location, expiration date) +- [ ] **INV-06**: User can delete items from inventory +- [ ] **INV-07**: User can mark items as used or wasted + +### Sharing & Multi-User + +- [ ] **SHARE-01**: User can create a household and set household name +- [ ] **SHARE-02**: User can generate invite codes for household members to join +- [ ] **SHARE-03**: User can join existing household via invite code +- [ ] **SHARE-04**: User can choose to merge inventories, keep separate, or use invitee's inventory when joining +- [ ] **SHARE-05**: When inventories merge, items with same name but different expiration dates are tracked separately +- [ ] **SHARE-06**: All household members can view shared inventory +- [ ] **SHARE-07**: All household members can add/edit items in shared inventory +- [ ] **SHARE-08**: Items can be marked as personal or community/shared +- [ ] **SHARE-09**: Real-time sync updates all users' devices when inventory changes +- [ ] **SHARE-10**: User can access inventory from multiple devices simultaneously + +### Expiration Management + +- [ ] **EXP-01**: User can set expiration date when adding items +- [ ] **EXP-02**: System generates expiration alerts configurable days before expiration (default 3 days) +- [ ] **EXP-03**: User can view items sorted by expiration date (soonest first) +- [ ] **EXP-04**: User receives notification when items are approaching expiration +- [ ] **EXP-05**: User can snooze or customize expiration alert timing +- [ ] **EXP-06**: User can set purchase date when adding items +- [ ] **EXP-07**: System tracks when items were added/purchased for usage prediction + +### Authentication & Accounts + +- [ ] **AUTH-01**: User can create account with email and password +- [ ] **AUTH-02**: User can log in with email and password +- [ ] **AUTH-03**: User can reset password via email +- [ ] **AUTH-04**: User session persists across app restarts and device refresh +- [ ] **AUTH-05**: User can log out from any screen + +### Notifications + +- [ ] **NOTF-01**: In-app expiration alerts appear in notification center +- [ ] **NOTF-02**: User can enable/disable Discord webhook notifications +- [ ] **NOTF-03**: User can enable/disable ntfy notifications +- [ ] **NOTF-04**: User can enable/disable Pushbullet notifications +- [ ] **NOTF-05**: User can enable/disable Telegram notifications +- [ ] **NOTF-06**: Notifications include item name and days until expiration +- [ ] **NOTF-07**: User can configure notification preferences (frequency, quiet hours) + +### AI Shopping Prediction + +- [ ] **AI-01**: System tracks when items are marked as used +- [ ] **AI-02**: System analyzes purchase frequency and usage patterns +- [ ] **AI-03**: System detects when items re-appear on shopping list before expected expiration +- [ ] **AI-04**: System predicts when items will run out based on usage history +- [ ] **AI-05**: System automatically adds predicted items to shopping list with predicted date +- [ ] **AI-06**: User can accept or dismiss predicted items +- [ ] **AI-07**: System learns from user behavior and improves predictions over time + +### Local Sales Tracking + +- [ ] **SALES-01**: User can add local stores by name and zipcode +- [ ] **SALES-02**: User can track sales for items in their inventory +- [ ] **SALES-03**: User can manually enter sales information (store, item, price, sale dates) +- [ ] **SALES-04**: Community sales database collects sales data with zipcode, store, item, UUID (no user identification) +- [ ] **SALES-05**: User can view local sales for tracked items and stores +- [ ] **SALES-06**: System attempts to automatically fetch online store ads for tracked items +- [ ] **SALES-07**: User can see sales alerts for items when they're marked on sale nearby + +### Setup & Onboarding + +- [ ] **SETUP-01**: New users see guided setup wizard on first launch +- [ ] **SETUP-02**: Setup wizard requires 3 fields minimum: email, password, household name +- [ ] **SETUP-03**: Setup wizard offers to add basic notification preferences +- [ ] **SETUP-04**: Setup wizard shows option to create household or join via invite code +- [ ] **SETUP-05**: Advanced features progressively revealed as user explores app +- [ ] **SETUP-06**: User can access help/documentation from settings + +### UI & Platform + +- [ ] **UI-01**: App uses dark mode as default theme +- [ ] **UI-02**: User can switch to light mode in settings +- [ ] **UI-03**: All text is readable in both dark and light modes +- [ ] **UI-04**: App works on Android devices +- [ ] **UI-05**: Web app provides full inventory access from browser +- [ ] **UI-06**: Web app is responsive and usable on tablet/desktop +- [ ] **UI-07**: Barcode scanning works offline and queues when reconnected + +### Data & Performance + +- [ ] **DATA-01**: Barcode API lookups are cached to minimize API costs +- [ ] **DATA-02**: App stores data locally for offline access +- [ ] **DATA-03**: App syncs data to server when internet connection available +- [ ] **DATA-04**: All dates stored in UTC to prevent timezone bugs +- [ ] **DATA-05**: Concurrent edits to same item are handled without data loss +- [ ] **DATA-06**: App is completely free with no ads or paid features +- [ ] **DATA-07**: Code is open source and FOSS compliant +- [ ] **DATA-08**: Self-hosted Docker option available with clear setup instructions +- [ ] **DATA-09**: Self-hosted option supports TrueNAS Scale/Unraid deployment + +## v2 Requirements + +Deferred to future release. Tracked but not in current roadmap. + +### Recipes & Meal Planning + +- **RECIPE-01**: System suggests recipes based on expiring items +- **RECIPE-02**: User can view recipe ingredients and check inventory +- **RECIPE-03**: User can mark items as used for recipes +- **RECIPE-04**: User can save favorite recipes + +### Advanced Features + +- **ADVANCED-01**: iOS native app for Apple devices +- **ADVANCED-02**: Social features (share lists with friends outside household) +- **ADVANCED-03**: Detailed analytics on food waste by category +- **ADVANCED-04**: Barcode price history tracking +- **ADVANCED-05**: Voice input for adding items +- **ADVANCED-06**: Receipt photo capture and auto-parsing +- **ADVANCED-07**: Grocery store integrations (shopping cart sync) +- **ADVANCED-08**: Meal plan creation and shopping list generation + +## Out of Scope + +| Feature | Reason | +|---------|--------| +| Recipes to use expiring items | Deferred to v2; core value is tracking, not cooking | +| iOS native app | Pending developer account; web app + Android sufficient for v1 | +| Social features beyond household | Increases complexity; focus on household collaboration first | +| Temperature/humidity tracking | Nice-to-have; complexity vs. minimal user value | +| Auto-calculated expiration dates | Privacy concern; users know their products better | +| Barcode OCR from photos | ML complexity; physical barcode scan sufficient | +| Nutrition tracking | Out of scope; separate concern from food waste | +| Restaurant/dining out tracking | Scope creep; household inventory focus | + +## Traceability + +Which phases cover which requirements. Updated during roadmap creation. + +| Requirement | Phase | Status | +|-------------|-------|--------| +| INV-01 | — | Pending | +| INV-02 | — | Pending | +| INV-03 | — | Pending | +| INV-04 | — | Pending | +| INV-05 | — | Pending | +| INV-06 | — | Pending | +| INV-07 | — | Pending | +| SHARE-01 | — | Pending | +| SHARE-02 | — | Pending | +| SHARE-03 | — | Pending | +| SHARE-04 | — | Pending | +| SHARE-05 | — | Pending | +| SHARE-06 | — | Pending | +| SHARE-07 | — | Pending | +| SHARE-08 | — | Pending | +| SHARE-09 | — | Pending | +| SHARE-10 | — | Pending | +| EXP-01 | — | Pending | +| EXP-02 | — | Pending | +| EXP-03 | — | Pending | +| EXP-04 | — | Pending | +| EXP-05 | — | Pending | +| EXP-06 | — | Pending | +| EXP-07 | — | Pending | +| AUTH-01 | — | Pending | +| AUTH-02 | — | Pending | +| AUTH-03 | — | Pending | +| AUTH-04 | — | Pending | +| AUTH-05 | — | Pending | +| NOTF-01 | — | Pending | +| NOTF-02 | — | Pending | +| NOTF-03 | — | Pending | +| NOTF-04 | — | Pending | +| NOTF-05 | — | Pending | +| NOTF-06 | — | Pending | +| NOTF-07 | — | Pending | +| AI-01 | — | Pending | +| AI-02 | — | Pending | +| AI-03 | — | Pending | +| AI-04 | — | Pending | +| AI-05 | — | Pending | +| AI-06 | — | Pending | +| AI-07 | — | Pending | +| SALES-01 | — | Pending | +| SALES-02 | — | Pending | +| SALES-03 | — | Pending | +| SALES-04 | — | Pending | +| SALES-05 | — | Pending | +| SALES-06 | — | Pending | +| SALES-07 | — | Pending | +| SETUP-01 | — | Pending | +| SETUP-02 | — | Pending | +| SETUP-03 | — | Pending | +| SETUP-04 | — | Pending | +| SETUP-05 | — | Pending | +| SETUP-06 | — | Pending | +| UI-01 | — | Pending | +| UI-02 | — | Pending | +| UI-03 | — | Pending | +| UI-04 | — | Pending | +| UI-05 | — | Pending | +| UI-06 | — | Pending | +| UI-07 | — | Pending | +| DATA-01 | — | Pending | +| DATA-02 | — | Pending | +| DATA-03 | — | Pending | +| DATA-04 | — | Pending | +| DATA-05 | — | Pending | +| DATA-06 | — | Pending | +| DATA-07 | — | Pending | +| DATA-08 | — | Pending | +| DATA-09 | — | Pending | + +**Coverage:** +- v1 requirements: 62 total +- Mapped to phases: 0 +- Unmapped: 62 ⚠️ (will be filled by roadmap) + +--- +*Requirements defined: 2026-01-27* +*Last updated: 2026-01-27 after initial definition*