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*