Sage/.planning/ROADMAP.md

Sage Roadmap

Overview

Sage is built in 12 phases that move from authentication foundations through core inventory tracking, expiration management, notifications, usage tracking, AI predictions, and sales integration—ending with cross-platform polish and guided onboarding. This structure follows natural delivery boundaries: each phase enables a complete, verifiable user capability. Dependencies flow strictly upward (later phases depend on earlier ones), with horizontal separation (auth → multi-user → core tracking → alerts → notifications → intelligence).

Research validated three phases (MVP, expansion, differentiation); comprehensive depth expands these into 12 focused milestones that manage complexity and allow earlier user validation.

---

Phases

Phase 1: Authentication & Account Basics

Goal: Users can create accounts and authenticate securely across sessions.

Requirements: AUTH-01, AUTH-02, AUTH-03, AUTH-04, AUTH-05

Success Criteria:

1. User can sign up with email and password in <3 seconds
2. User can log in with valid credentials and session persists across app restarts
3. User can reset forgotten password and receive recovery email within 1 minute
4. User can log out from any screen and subsequent session requires re-authentication
5. Failed login attempts return clear error messages (invalid password vs account not found)

Dependencies: None (foundational)

---

Phase 2: Household Creation & Invites

Goal: Multiple users can collaborate in a shared household with invitation-based membership.

Requirements: SHARE-01, SHARE-02, SHARE-03, SHARE-04, SHARE-05

Success Criteria:

1. User can create a household with a name, and other users see it as joinable via invite code
2. User can generate unique invite codes that are valid for 30 days and expire explicitly
3. User can join a household via 8-character invite code and immediately access shared inventory
4. When joining, user can choose to merge inventories, keep separate, or use inviter's (option chosen in UI)
5. Items with same name but different expiration dates from merged inventories are tracked as separate entries

Dependencies: Phase 1 (AUTH required to create households)

---

Phase 3: Barcode Scanning & Product Lookup

Goal: Users can add items via barcode scan and product data is instantly recognized.

Requirements: INV-01, UI-07 (barcode offline queueing)

Success Criteria:

1. User can hold device to barcode and scan completes in <3 seconds with product name populated
2. Barcode scanning works offline and queues the request until connection restored
3. Barcode lookups for same product are cached (second scan instant; cache survives app restart)
4. User sees fallback to manual entry if scan fails (UI offers "Can't find it? Enter manually")
5. Cached barcode data reduces external API calls by 80%+ (server-side cache shared across household)

Dependencies: Phase 1 (AUTH required to save items to household)

---

Phase 4: Manual Entry, Search & Filtering

Goal: Users can add items manually and find what they're looking for instantly.

Requirements: INV-02, INV-03, INV-04, INV-05, INV-06

Success Criteria:

1. User can add item manually with name, quantity, location, optional expiration date in <15 seconds
2. User can view full inventory sorted by location and see items count per location
3. User can search inventory by name and get results in <500ms (fuzzy matching if typos)
4. User can filter inventory by location, expiration status (expiring soon, expired, valid)
5. User can edit item details (quantity, location, expiration) and changes sync to all household members in <10 seconds

Dependencies: Phase 1 (AUTH required)

---

Phase 5: Expiration Management & Alerts

Goal: System tracks expiration dates and alerts users before food spoils.

Requirements: EXP-01, EXP-02, EXP-03, EXP-04, EXP-05, EXP-06, EXP-07

Success Criteria:

1. User can set expiration date when adding item; system calculates "days until expiration" in real-time
2. User can view all items sorted by expiration date (soonest first) with visual age indicators (red = expired, yellow = <3 days, green = safe)
3. System sends expiration alert notification 3 days before expiration (configurable 1-7 days in settings)
4. User can snooze alert for 1 day or dismiss it permanently for that item
5. System tracks purchase date separately from expiration date to enable usage analytics later

Dependencies: Phase 4 (requires items in inventory to set expiration dates)

---

Phase 6: In-App Notification Center

Goal: Users see expiration alerts in a clean in-app notification center.

Requirements: NOTF-01

Success Criteria:

1. Notification center displays all alerts (expiring items) sorted by urgency
2. User can open item directly from notification and see current status
3. Notifications persist across app sessions until dismissed
4. Notification count badge on home screen shows unread count
5. User can clear all notifications in one action

Dependencies: Phase 5 (expiration alerts must exist to display)

---

Phase 7: External Notifications (Discord, ntfy, Pushbullet, Telegram)

Goal: Users can receive alerts via their preferred external platforms.

Requirements: NOTF-02, NOTF-03, NOTF-04, NOTF-05, NOTF-06, NOTF-07

Success Criteria:

1. User can enable Discord webhook by pasting webhook URL; test message sends within 10 seconds
2. User can enable ntfy notifications by entering topic name; alerts appear in ntfy app in <5 seconds
3. User can enable Pushbullet by authorizing account; alerts appear on all Pushbullet devices
4. User can enable Telegram by following bot link and entering received token; alerts arrive in Telegram chat
5. User can customize alert timing (days before expiration, quiet hours 10pm-7am), frequency (daily digest vs immediate)

Dependencies: Phase 5 (expiration alerts must exist to send externally)

---

Phase 8: Usage Tracking & Item History

Goal: System collects consumption data to enable later prediction and analytics.

Requirements: INV-06, INV-07, AI-01, AI-02, AI-03

Success Criteria:

1. User can mark item as "used" and it records timestamp; item removed from active inventory but tracked in history
2. User can mark item as "wasted" (expired, bad, etc.) and reason is recorded with timestamp
3. System builds usage history showing when items were purchased vs consumed (enables pattern detection)
4. System detects when items re-appear on shopping list before their last one expired (signals early replenishment pattern)
5. Historical data persists and is accessible for analytics dashboard

Dependencies: Phase 4 (requires items to track usage)

---

Phase 9: AI Shopping Prediction

Goal: System predicts when users will need items based on consumption history.

Requirements: AI-04, AI-05, AI-06, AI-07

Success Criteria:

1. After 2+ weeks of usage data, system predicts "You'll need milk in 3 days" based on historical frequency
2. System adds predicted items to shopping list automatically with predicted date
3. User can accept or dismiss prediction; system learns from choices (improves accuracy if dismissed)
4. Prediction accuracy improves over time (system trains on feedback; users see "Getting better at knowing your preferences")
5. Predictions cover 70%+ of re-purchased items (validated against actual user behavior)

Dependencies: Phase 8 (requires usage data to train predictions)

---

Phase 10: Local Sales Tracking

Goal: System tracks local store sales and alerts users to deals on items they use.

Requirements: SALES-01, SALES-02, SALES-03, SALES-04, SALES-05, SALES-06, SALES-07

Success Criteria:

1. User can add local store by name and zipcode; store appears in settings for sale tracking
2. User can manually enter sale (store, item name, price, sale dates) and sale is recorded with user UUID (anonymous)
3. Community sales database aggregates sales data; user can see sales for tracked items nearby (zipcode + store match)
4. System attempts to auto-fetch online store ads for tracked items (with fallback if services unavailable)
5. User receives alert when tracked item is on sale; predicted shopping needs are prioritized ("You need milk in 3 days, it's on sale this week at Kroger for $1.50 cheaper")

Dependencies: Phase 9 (optional but works best with predictions; Phase 8 for usage data)

---

Phase 11: Web App & Cross-Platform UI Polish

Goal: Users access inventory from any device with consistent experience.

Requirements: UI-01, UI-02, UI-03, UI-04, UI-05, UI-06, DATA-01, DATA-02, DATA-03, DATA-04, DATA-05

Success Criteria:

1. Web app accessible at shared URL; user logs in and sees same household inventory as mobile
2. All UI elements readable in both dark (default) and light modes; contrast ratios meet WCAG AA
3. Android app works smoothly on devices 7.0+ with offline-first local SQLite cache
4. Multi-device sync happens in <10 seconds; user edits item on phone, sees it updated on tablet in real-time
5. Data stored in UTC timestamps; no timezone-related expiration bugs when users cross timezones

Dependencies: Phase 4+ (UI elements must exist to polish; data structures set in earlier phases)

---

Phase 12: Setup Wizard & User Onboarding

Goal: New users complete setup in <5 minutes and understand core features.

Requirements: SETUP-01, SETUP-02, SETUP-03, SETUP-04, SETUP-05, SETUP-06, DATA-06, DATA-07, DATA-08, DATA-09

Success Criteria:

1. New user sees guided setup wizard requiring only email, password, household name (3 fields minimum)
2. Wizard asks about notification preferences (in-app, Discord, ntfy) as optional setup step
3. Wizard offers to generate invite code to share with household members or skip for solo use
4. Advanced features progressively revealed in settings as user explores (dark mode toggle, notification customization)
5. Help documentation accessible from settings; user can read about expiration alerts, barcode scanning, predictions

Dependencies: All phases (setup must reference all features; executes last after all are built)

Additional Requirements Mapped to Phase 12:

• 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

---

Requirement Mapping Summary

Requirement	Category	Phase	Status
INV-01	Inventory Core	3	Pending
INV-02	Inventory Core	4	Pending
INV-03	Inventory Core	4	Pending
INV-04	Inventory Core	4	Pending
INV-05	Inventory Core	4	Pending
INV-06	Inventory Core	8	Pending
INV-07	Inventory Core	8	Pending
SHARE-01	Sharing	2	Pending
SHARE-02	Sharing	2	Pending
SHARE-03	Sharing	2	Pending
SHARE-04	Sharing	2	Pending
SHARE-05	Sharing	2	Pending
SHARE-06	Sharing	4	Pending
SHARE-07	Sharing	4	Pending
SHARE-08	Sharing	4	Pending
SHARE-09	Sharing	4	Pending
SHARE-10	Sharing	11	Pending
EXP-01	Expiration	5	Pending
EXP-02	Expiration	5	Pending
EXP-03	Expiration	5	Pending
EXP-04	Expiration	5	Pending
EXP-05	Expiration	5	Pending
EXP-06	Expiration	5	Pending
EXP-07	Expiration	5	Pending
AUTH-01	Authentication	1	Pending
AUTH-02	Authentication	1	Pending
AUTH-03	Authentication	1	Pending
AUTH-04	Authentication	1	Pending
AUTH-05	Authentication	1	Pending
NOTF-01	Notifications	6	Pending
NOTF-02	Notifications	7	Pending
NOTF-03	Notifications	7	Pending
NOTF-04	Notifications	7	Pending
NOTF-05	Notifications	7	Pending
NOTF-06	Notifications	7	Pending
NOTF-07	Notifications	7	Pending
AI-01	AI Prediction	8	Pending
AI-02	AI Prediction	8	Pending
AI-03	AI Prediction	8	Pending
AI-04	AI Prediction	9	Pending
AI-05	AI Prediction	9	Pending
AI-06	AI Prediction	9	Pending
AI-07	AI Prediction	9	Pending
SALES-01	Sales Tracking	10	Pending
SALES-02	Sales Tracking	10	Pending
SALES-03	Sales Tracking	10	Pending
SALES-04	Sales Tracking	10	Pending
SALES-05	Sales Tracking	10	Pending
SALES-06	Sales Tracking	10	Pending
SALES-07	Sales Tracking	10	Pending
SETUP-01	Setup	12	Pending
SETUP-02	Setup	12	Pending
SETUP-03	Setup	12	Pending
SETUP-04	Setup	12	Pending
SETUP-05	Setup	12	Pending
SETUP-06	Setup	12	Pending
UI-01	UI	11	Pending
UI-02	UI	11	Pending
UI-03	UI	11	Pending
UI-04	UI	11	Pending
UI-05	UI	11	Pending
UI-06	UI	11	Pending
UI-07	UI	3	Pending
DATA-01	Data	3	Pending
DATA-02	Data	11	Pending
DATA-03	Data	11	Pending
DATA-04	Data	11	Pending
DATA-05	Data	11	Pending
DATA-06	Data	12	Pending
DATA-07	Data	12	Pending
DATA-08	Data	12	Pending
DATA-09	Data	12	Pending

Coverage Summary:

• Total v1 requirements: 62
• Mapped to phases: 62
• Unmapped: 0 ✓
• Coverage: 100%

---

Phase Dependencies

Phase 1 (Auth) ──┐
                  ├──→ Phase 2 (Households) ──→ Phase 3 (Barcode) ──→ Phase 4 (Manual + Search)
                  │
                  └──────────────────────────────────→ Phase 4
                                                             ↓
                                                      Phase 5 (Expiration)
                                                             ↓
                                                      Phase 6 (In-App Notifs)
                                                             ↓
                                                      Phase 7 (External Notifs)

Phase 4 ──→ Phase 8 (Usage Tracking) ──→ Phase 9 (AI Prediction) ──→ Phase 10 (Sales)

Phase 11 (Web App & Polish) ← depends on all core phases (3-10)
Phase 12 (Setup Wizard) ← depends on all phases (1-11, references all features)

Critical Path: 1 → 2 → 3 → 4 → 5 → 6 → 7 (auth foundations must complete before inventory features; expiration before notifications)

Parallel Opportunities:

• Phases 8-10 can start after Phase 4 completes (usage tracking independent of phases 5-7)
• Phase 11 can begin after Phase 5 completes (UI polish doesn't block feature delivery)

---

Phase Success Validation Strategy

For each phase completion:

1. All success criteria demonstrated in live app (not unit tests or architecture)
2. Cross-household sync verified (multiple users on different devices)
3. Offline functionality tested where applicable
4. No new bugs regression against previous phases

User validation milestones:

• After Phase 3: Users can add items (barcode)
• After Phase 5: Users can get expiration alerts (core value delivered)
• After Phase 8: Users generate consumption data (foundation for prediction)
• After Phase 9: Predictions show measurable accuracy (70%+ coverage)

---

Roadmap created: 2026-01-27 Total phases: 12 Depth calibration: Comprehensive (breaks down 3-phase research into focused milestones) Next step: Phase 1 planning via /gsd:plan-phase