Sage/.planning/REQUIREMENTS.md

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