Sage/PLAN.md

SAGE - KITCHEN MANAGEMENT APP

🎯 Project Plan & Current Status

Last Updated: October 3, 2025 Status: Planning Phase - Ready to Start Development! 🔥

---

📱 WHAT IS SAGE?

Sage is a smart kitchen management app that helps you:

• Track food inventory and expiration dates
• Never waste food or money again
• Manage recipes and generate shopping lists
• Share with family/household members
• Get Discord notifications for expiring items

Why "Sage"?

• The herb (kitchen theme!)
• Wisdom and smart decisions
• Simple, memorable, perfect! 💚

---

✅ COMPLETED

Planning & Design

• Core feature set defined
• Technical stack selected
• Database choices made
• UI/UX flow planned
• Project documentation created

---

🎯 CURRENT PHASE: PHASE 1 - FOUNDATION

What We're Building Now

Setting up the Flutter project and building the core inventory tracker with local database.

Phase 1 Checklist

• Install Flutter & Android Studio
• Create new Flutter project "sage"
• Set up project structure
• Install initial dependencies (sqflite/isar, riverpod)
• Create database schema
• Build basic UI framework (bottom navigation)
• Create home screen
• Build "Add Item" screen (manual entry)
• Implement local database (CRUD operations)
• Display inventory list
• Edit/delete items functionality
• Test everything works offline

Estimated Time: Week 1-2

---

🚀 UPCOMING PHASES

PHASE 2: BARCODE MAGIC (Week 2-3)

Goal: Scan barcodes and auto-populate items from Open Food Facts

Tasks:

• Install mobile_scanner package
• Implement barcode scanner UI
• Connect to Open Food Facts API
• Parse API response and auto-fill item details
• Cache product photos locally
• Handle "product not found" gracefully (fallback to manual)
• Test with various products

Key Decisions:

• Use Open Food Facts (free, 2M+ products!)
• Cache images using cached_network_image
• Manual entry always available as backup

---

PHASE 3: ALERTS & NOTIFICATIONS (Week 3-4)

Goal: Never let food expire without warning!

Tasks:

• Implement expiration tracking logic
• Set up flutter_local_notifications
• Create notification scheduler
• Build alert timeline:
  • 1 month before expiration
  • 2 weeks before expiration
  • 1 week before expiration
  • Shopping day alert (customizable)
• Add "Shopping Frequency" setting (weekly, bi-weekly, monthly, pay cycle)
• Calculate shopping day alerts based on frequency
• Discord webhook integration
• Settings screen for Discord webhook URL
• Test notification button
• Handle notification permissions

Alert Logic:

If item expires before next shopping day:
  → Send "Add to shopping list" alert
  → Send to Discord channel
  
If item expires within 1 week:
  → Send "Use soon!" alert
  → Suggest recipes using this item

---

PHASE 4: RECIPES (Week 4-5)

Goal: Store recipes and connect them to inventory

Tasks:

• Design recipe data model
• Create recipe database table
• Build "Add Recipe" screen
• Copy/paste from websites parser
• Manual recipe entry
• Ingredient list with quantities
• Instructions/notes field
• Optional photo upload
• Recipe categories/tags
• View recipe details
• Edit/delete recipes
• "What Can I Make?" logic (match recipes to inventory)
• Recipe sharing functionality

Data Structure:

Recipe:
  - id
  - name
  - ingredients[] (name, quantity, unit)
  - instructions
  - photo (optional)
  - tags[]
  - created_by (user_id for sharing)
  - is_public (shareable or private)

---

PHASE 5: SHOPPING LISTS (Week 5-6)

Goal: Never forget ingredients again!

Tasks:

• Shopping list data model
• Multiple lists support (Costco, Trader Joe's, etc.)
• Create/rename/delete lists
• Add items manually
• Add items from recipes (one-click)
• Check off items while shopping
• Quick-add to inventory after shopping
• List sharing with others
• Sort by store section (optional feature)
• Shopping history (what you usually buy)

User Flow:

1. Pick recipe → See missing ingredients → Add to shopping list
2. At store → Check off items as you shop
3. Home from store → Quick-add checked items to inventory
4. BOOM → Everything tracked!

---

PHASE 6: MULTI-USER & CLOUD SYNC (Week 6-7)

Goal: Share with household, sync across devices

Sync Options (User Choice):

Option 1: Cloud Sync (Supabase)

• Free tier: 500MB database, 2GB bandwidth
• Real-time sync
• User authentication
• Shared households

Option 2: Completely Free (Self-Hosted)

• Export/Import JSON files
• Local WiFi sync (peer-to-peer)
• Optional: Self-host simple backend (we provide Docker setup)
• No external dependencies!

Option 3: Local Only

• Everything on device
• Export for backup
• Import to share with others
• Zero cloud dependency

Tasks:

• Set up Supabase project
• User authentication (email/password)
• Cloud database schema
• Sync logic (offline-first!)
• Conflict resolution (last-write-wins)
• Household/family groups
• Invite system (QR code or link)
• Share permissions (view/edit)
• Export to JSON feature
• Import from JSON feature
• Local WiFi sync option
• Self-hosted backend docs (Docker Compose)

Offline-First Strategy:

1. All changes save locally FIRST
2. Queue changes for sync
3. Sync when online
4. Handle conflicts gracefully
5. App works PERFECTLY offline

---

PHASE 7: SMART FEATURES (Week 7-8)

Goal: Make Sage actually INTELLIGENT

Tasks:

• "What Can I Make?" recipe matcher
  • Match recipes to current inventory
  • Show % of ingredients you have
  • Sort by "most complete" recipes
• "Use It Up" suggestions
  • Find recipes using expiring items
  • Prioritize items expiring soonest
• Search functionality (inventory, recipes, shopping lists)
• Advanced filters (location, category, expiration date)
• Categories & organization
  • Auto-categorize from barcode
  • Manual category assignment
  • Custom categories
• Statistics dashboard
  • Money saved (estimated)
  • Food waste prevented
  • Most used recipes
• UI/UX polish
  • Smooth animations
  • Beautiful color scheme
  • Intuitive navigation
  • Accessibility features

---

💾 TECH STACK

Core Framework

• Flutter (Dart language)
• Cross-platform (Android & iOS from one codebase!)

Database

• Isar - Local database (super fast, Flutter-optimized)
• Supabase - Cloud sync (optional)
• SQLite fallback - If Isar has issues

State Management

• Riverpod - Modern, clean, powerful

Key Packages

dependencies:
  # State Management
  flutter_riverpod: ^2.4.0
  
  # Database
  isar: ^3.1.0
  isar_flutter_libs: ^3.1.0
  
  # Barcode Scanning
  mobile_scanner: ^3.5.0
  
  # API Calls
  http: ^1.1.0
  
  # Notifications
  flutter_local_notifications: ^16.0.0
  timezone: ^0.9.2
  
  # Images
  cached_network_image: ^3.3.0
  image_picker: ^1.0.0
  
  # Cloud (Optional)
  supabase_flutter: ^2.0.0
  
  # Utilities
  intl: ^0.18.0  # Date formatting
  path_provider: ^2.1.0  # File paths
  share_plus: ^7.2.0  # Sharing
  qr_flutter: ^4.1.0  # QR codes for sharing
  
dev_dependencies:
  # Code Generation
  isar_generator: ^3.1.0
  build_runner: ^2.4.0

---

📊 DATA MODELS

Food Item

@collection
class FoodItem {
  Id id = Isar.autoIncrement;
  
  late String name;
  String? barcode;
  late int quantity;
  String? unit;  // "bottles", "lbs", "oz", etc.
  
  late DateTime purchaseDate;
  late DateTime expirationDate;
  
  @enumerated
  late Location location;  // fridge, freezer, pantry, etc.
  
  String? category;  // dairy, produce, condiments, etc.
  String? photoUrl;
  String? notes;
  
  // For multi-user
  String? userId;
  String? householdId;
  
  // Sync tracking
  DateTime? lastModified;
  bool syncedToCloud = false;
}

enum Location {
  fridge,
  freezer,
  pantry,
  spiceRack,
  other
}

Recipe

@collection
class Recipe {
  Id id = Isar.autoIncrement;
  
  late String name;
  late List<Ingredient> ingredients;
  late String instructions;
  
  String? photoUrl;
  List<String> tags = [];
  
  int? prepTime;  // minutes
  int? servings;
  
  // Sharing
  String? createdBy;  // user_id
  bool isPublic = false;
  
  DateTime? created;
  DateTime? lastModified;
  bool syncedToCloud = false;
}

@embedded
class Ingredient {
  late String name;
  double? quantity;
  String? unit;
  bool? optional;
}

Shopping List

@collection
class ShoppingList {
  Id id = Isar.autoIncrement;
  
  late String name;  // "Costco", "Trader Joe's", etc.
  List<ShoppingItem> items = [];
  
  // Sharing
  String? householdId;
  List<String> sharedWith = [];
  
  DateTime? created;
  DateTime? lastModified;
  bool syncedToCloud = false;
}

@embedded
class ShoppingItem {
  late String name;
  double? quantity;
  String? unit;
  bool checked = false;
  int? priority;  // 1-5
  String? addedFrom;  // "recipe_id" or "manual"
}

User Settings

@collection
class UserSettings {
  Id id = Isar.autoIncrement;
  
  // Shopping frequency
  @enumerated
  ShoppingFrequency frequency = ShoppingFrequency.weekly;
  
  // If custom schedule
  List<int>? customDays;  // [1, 4] = Monday & Thursday
  
  // Next shopping day (calculated)
  DateTime? nextShoppingDay;
  
  // Notifications
  bool enableNotifications = true;
  bool enableDiscord = false;
  String? discordWebhookUrl;
  
  // Sync preferences
  @enumerated
  SyncMode syncMode = SyncMode.localOnly;
  
  // Display preferences
  bool showPhotos = true;
  @enumerated
  ThemeMode themeMode = ThemeMode.system;
}

enum ShoppingFrequency {
  weekly,
  biweekly,
  monthly,
  payCycle,  // Every 2 weeks on specific days
  custom
}

enum SyncMode {
  localOnly,
  cloudSync,
  wifiSync,
  selfHosted
}

---

🎨 UI/UX FLOW

Bottom Navigation

1. Home (🏠) - Dashboard with expiring items
2. Inventory (📦) - All food items
3. Recipes (📖) - Recipe book
4. Shopping (🛒) - Shopping lists
5. Settings (⚙️) - Preferences & sync

Home Screen Layout

┌─────────────────────────────┐
│  SAGE 🌿                    │
├─────────────────────────────┤
│  Expiring Soon              │
│  ┌───────┐ ┌───────┐       │
│  │ Ranch │ │ Milk  │  →→   │
│  │ 3 days│ │ 5 days│       │
│  └───────┘ └───────┘       │
├─────────────────────────────┤
│  Quick Stats                │
│  📦 24 items in inventory   │
│  🛒 7 items on shopping list│
│  📖 12 saved recipes        │
├─────────────────────────────┤
│        [+] Add Item         │
│     [📷] Scan Barcode       │
└─────────────────────────────┘

Add Item Flow

Scan Barcode
    ↓
Found in database?
    ├─ YES → Auto-fill name, photo, category
    │         User adds: quantity, expiration, location
    │         → Save to inventory
    │
    └─ NO → Manual entry form
             User adds: name, quantity, expiration, location
             → Save to inventory

Notification Flow

Background job runs daily:
  1. Check all items' expiration dates
  2. Calculate time until expiration
  3. Check user's next shopping day
  
  For each item:
    - 1 month away? → Send "FYI" notification
    - 2 weeks away? → Send "Getting close" notification
    - 1 week away? → Send "Use soon!" notification
    - Expires before next shopping day? → Send "Add to list!" + Discord alert

---

🔔 NOTIFICATION EXAMPLES

1 Month Alert:

🌿 Sage: FYI
Ranch dressing expires in 30 days

2 Week Alert:

🌿 Sage: Heads up!
Sour cream expires in 14 days

1 Week Alert:

🌿 Sage: Use soon!
Milk expires in 7 days
Tap to see recipes →

Shopping Day Alert:

🌿 Sage: Shopping tomorrow!
3 items expire before next week:
• Ranch dressing
• Croutons  
• Caesar salad kit

Add to shopping list?

Discord Alert Example:

🌿 **Sage Alert** 🌿
@everyone Shopping day is tomorrow!

**Expiring before next week:**
🔴 Ranch dressing (expires Oct 10)
🔴 Croutons (expires Oct 12)
🟡 Milk (expires Oct 15)

Don't forget to restock! 🛒

---

🎯 SUCCESS METRICS

How do we know Sage is WORKING?

1. User saves money

   • Less food waste
   • Fewer emergency takeout orders
   • Better grocery planning

2. User saves time

   • No more "what can I make?" confusion
   • Quick shopping trips (have a list!)
   • Organized kitchen

3. App is reliable

   • Works offline
   • Fast and responsive
   • Accurate notifications

4. Users love it

   • Easy to use
   • Beautiful design
   • Actually helps daily life

---

🚨 POTENTIAL CHALLENGES

Challenge 1: Barcode Database Coverage

Problem: Not all products in Open Food Facts
Solution:

• Manual entry always available
• Allow users to contribute photos/info
• Multiple API fallbacks (UPC Database, etc.)

Challenge 2: Expiration Date Entry

Problem: Users might not enter accurate dates
Solution:

• Default suggestions based on product type
• "Best by" vs "use by" education
• Calendar picker with smart defaults

Challenge 3: Notification Overload

Problem: Too many alerts = users ignore them
Solution:

• Smart batching (daily digest option)
• Priority levels
• Customizable alert preferences
• Only critical alerts to Discord

Challenge 4: Multi-User Sync Conflicts

Problem: Two people edit same item simultaneously
Solution:

• Last-write-wins with timestamp
• Conflict notification (rare)
• Clear "last updated by" info

Challenge 5: Free Hosting for Self-Hosted Option

Problem: Users need to host backend
Solution:

• Super simple Docker Compose setup
• Can run on Raspberry Pi at home!
• Full documentation
• Optional: Fly.io free tier

---

📱 PLATFORM SUPPORT

Phase 1-7: Android only (easier testing)
Phase 8: iOS support (Flutter makes this easy!)
Future: Web app? Desktop app?

---

🎉 VISION

Imagine this:

• You never waste food again
• Your grocery trips are EFFICIENT
• You always know what to make for dinner
• Your household is coordinated
• You save hundreds of dollars a year

That's what Sage makes possible! 💚

---

📝 NEXT STEPS (RIGHT NOW!)

1. Install Flutter & Android Studio
2. Create SAGE_PROJECT.md (full documentation)
3. Create PROJECT_STRUCTURE.md (file organization)
4. Initialize Flutter project
5. Set up Git repository
6. Start Phase 1! 🔥

---

LET'S BUILD SAGE! 💪✨

---

📚 RESOURCES

Learning Flutter (for beginners!)

• Flutter Docs: https://docs.flutter.dev/
• Flutter Codelabs: https://docs.flutter.dev/codelabs
• Riverpod Docs: https://riverpod.dev/
• Isar Docs: https://isar.dev/

APIs We're Using

• Open Food Facts: https://world.openfoodfacts.org/
• Discord Webhooks: https://discord.com/developers/docs/resources/webhook

Design Inspiration

• Material Design 3: https://m3.material.io/
• Flutter Gallery: https://gallery.flutter.dev/

---

Created with ✨ by CC and girlfriend! Last updated: October 3, 2025