From a324e62e0468b9c0583ab06366c150ae23f28b83 Mon Sep 17 00:00:00 2001 From: Dani B Date: Tue, 27 Jan 2026 23:32:03 -0500 Subject: [PATCH] docs: initialize Sage project Collaborative household food inventory tracker that prioritizes expiration alerts and reduces waste through smart tracking and usage prediction. - Core: expiration alerts + multi-user + AI predictor + notifications - Stack: Flutter (Android/web), Supabase + self-hosted Docker - v1 focus: tracking, alerting, multi-user sync - Recipes deferred to v2 Co-Authored-By: Claude Haiku 4.5 --- .planning/PROJECT.md | 80 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 80 insertions(+) create mode 100644 .planning/PROJECT.md diff --git a/.planning/PROJECT.md b/.planning/PROJECT.md new file mode 100644 index 0000000..61e9864 --- /dev/null +++ b/.planning/PROJECT.md @@ -0,0 +1,80 @@ +# Sage + +## What This Is + +Sage is a collaborative household food inventory tracker that helps families and roommates track what they have, where it's stored, when it expires, when they bought it, and when they'll run out. The app identifies expiring items and suggests recipes to use them up, while intelligently predicting when items need replenishing. It's completely free, open-source, self-hostable, supports multiple users and devices, and integrates with Discord, ntfy, Pushbullet, and Telegram for smart notifications. + +## Core Value + +Users get accurate expiration alerts and never waste food due to forgotten ingredients. + +## Requirements + +### Validated + +(None yet — ship to validate) + +### Active + +- [ ] User can create account with email or join existing household via invite code +- [ ] User can add items by barcode scan or manual entry +- [ ] Barcode API lookups are cached to minimize costs +- [ ] User can set expiration date, purchase date, quantity, storage location +- [ ] System generates expiration alerts before items expire +- [ ] User can mark items as shared/community or personal +- [ ] Multiple users can access the same household inventory +- [ ] User can view inventory across all devices +- [ ] AI predicts when items will run out based on usage patterns and shopping list re-adds +- [ ] User can enable/disable expiration alerts via dark mode interface +- [ ] User can configure notifications (in-app, Discord webhook, ntfy, Pushbullet, Telegram) +- [ ] User can add local stores to track and view local sales for tracked items +- [ ] Community can contribute sales data (zipcode + store + sale, UUID-based) +- [ ] System attempts to auto-fetch online store ads for tracked items +- [ ] Setup wizard guides new users through account creation, household setup, and notification preferences +- [ ] Invite code flow allows merging/keeping separate inventories when joining +- [ ] Items from merged inventories with same name but different expiration dates are tracked separately +- [ ] App works on Android with native Flutter experience +- [ ] Web app allows inventory access from other devices +- [ ] UI prioritizes dark mode as default with light mode option + +### Out of Scope + +- Recipes to use expiring items — deferred to v2 +- iOS native app — deferred pending developer account +- Social features beyond household sharing — v2+ +- Advanced analytics/reporting — v2+ +- Voice input for items — v2+ +- Automatic bill/receipt integration — v2+ + +## Context + +- **User base:** Households (families, roommates, small shared living groups) who want to reduce food waste +- **Core pain point:** Users forget what they have, when it expires, or how much is left — leading to waste and duplicate purchases +- **Success metric:** Users get expiration alerts before food spoils and reduce waste +- **Tech environment:** Flutter for cross-platform native experience, Supabase for managed DB + auth, self-hosted Docker option for privacy-conscious users +- **Barcode data:** Open Food Facts API or similar (needs caching layer to avoid costs) +- **Sales tracking:** Minimal data collection (zipcode, store name, sale item/price, user UUID) to build community sales DB + +## Constraints + +- **Free forever:** No paid tiers, no ads, no revenue model — must use free APIs and free database tiers +- **FOSS compliant:** All code must be open source, all dependencies must be compatible +- **Self-hostable:** Docker container + clear setup instructions for non-technical users, plus TrueNAS Scale/Unraid support +- **Single codebase:** One Flutter codebase for web + Android (iOS deferred) +- **API cost control:** Barcode lookups must be cached; sales tracking must not use expensive APIs +- **Zero vendor lock-in:** Self-hosted option must be viable without Supabase + +## Key Decisions + +| Decision | Rationale | Outcome | +|----------|-----------|---------| +| Flutter over React Native | Handles Android + web well, true native feel, single codebase; iOS deferred until developer license acquired | — Pending | +| Supabase + self-hosted Docker | Gives users choice: free managed tier or full privacy control; no vendor lock-in | — Pending | +| Expiration alerts as v1 priority | Core value lives here; solves immediate food waste problem; builds habit of checking app | — Pending | +| Multi-user in v1 | Enables collaboration (families/roommates) and multi-device sync from day one | — Pending | +| AI shopping predictor in v1 | Adds intelligent automation to core value; prevents stockouts without user friction | — Pending | +| Community sales DB (minimal data) | Builds value for users without privacy risks or heavy server requirements | — Pending | +| Recipes deferred to v2 | Important but not core to expiration problem; v1 focuses on not wasting what you have | — Pending | + +--- +*Last updated: 2026-01-27 after initialization*