Sage/.planning/research/README.md

# Research: Food Inventory & Multi-User Tracking Apps

## Overview

This research documents common pitfalls, patterns, and best practices for food inventory and household tracking applications. It forms the foundation for Sage's roadmap and architecture decisions.

**Research Scope:** Food & household inventory tracking apps with multi-user support and expiration tracking
**Researched:** January 2026
**Primary Focus:** What mistakes do these apps commonly make? What architectural patterns work? What should Sage avoid?

---

## Files in This Research

### 1. **RESEARCH_SUMMARY.md** (Start here)
Executive summary with roadmap implications. Covers:
- Why food tracking apps fail (4 critical cascades)
- Key findings organized by severity
- Technology landscape overview
- Phase-based roadmap implications
- Confidence assessment and gaps

**Read this first to understand the domain.**

### 2. **PITFALLS.md** (Implementation guidance)
Comprehensive catalog of 13 major pitfalls organized by severity:
- **Critical (v1 must fix):** Barcode mismatches, timezone bugs, sync conflicts, setup complexity
- **Moderate (v1.5 required):** Notification fatigue, offline sync, search UX, permissions
- **Minor (v2 deferred):** API costs, performance, predictions, community spam

Each pitfall includes:
- What goes wrong (with examples from real apps)
- Why it happens
- Consequences
- Prevention strategies (specific, actionable)
- Phase mapping (v1/v1.5/v2)
- Detection (warning signs to watch for)

**Read this before starting architecture work.**

### 3. **STACK.md** (Technology decisions)
Recommended technology stack with rationale:
- Free barcode & nutrition APIs (USDA FoodData Central, Open Food Facts)
- Multi-user sync approach (optimistic locking)
- Database tech (PostgreSQL/SQLite with UTC timestamps)
- Notification strategy (FCM/APNs with scheduling)

**Use this for technology selection and justification.**

### 4. **ARCHITECTURE.md** (System design patterns)
System structure, component boundaries, and patterns:
- Component responsibilities and communication
- Data flow diagrams
- Patterns to follow (optimistic locking, CRDTs for offline)
- Anti-patterns to avoid
- Scalability considerations

**Reference this during v1 architecture design.**

### 5. **FEATURES.md** (What to build)
Feature landscape organized by category:
- Table stakes (users expect these)
- Differentiators (valued but not expected)
- Anti-features (explicitly don't build)
- MVP recommendations
- Feature dependencies

**Use this to scope phases and prioritize work.**

### 6. **SUMMARY.md** (Quick reference)
Condensed summary of all research with key takeaways.

**Use as a checklist before starting development.**

---

## Key Takeaways for Roadmap

### v1 MVP (6-8 weeks) - Foundation Phase
**Must address these 5 pitfalls or app won't work for multi-user households:**

1. **Barcode Data Mismatches** → Fuzzy matching + deduplication
2. **Timezone Bugs** → UTC throughout (non-negotiable)
3. **Sync Conflicts** → Optimistic locking with version numbers
4. **Setup Complexity** → 3-field MVP onboarding only
5. **Notification Fatigue** → Snooze + configurable alerts

### v1.5 (4-6 weeks) - Stabilization Phase
**After MVP feedback, smooth out rough edges:**

- Offline sync with persistent queue
- Barcode scanner error handling
- Advanced search (FTS + fuzzy matching)
- Permission model with audit logging
- Performance optimization

### v2+ (3-6 months) - Growth Phase
**Only after v1 is stable and users are happy:**

- Community features (sales DB, crowdsourced corrections)
- ML predictions (with safeguards)
- Multi-location households
- Advanced insights

---

## Critical Success Factors

**For Sage to succeed where other apps failed:**

1. **Ship with UTC timezone handling from day one** - Not a refactor; foundational
2. **Make multi-user work in v1** - This is the core value prop; don't defer
3. **Ruthlessly simplify onboarding** - 3 fields maximum. Measure dropout rates.
4. **Don't over-predict purchases** - If you do AI, wait until v2 and start simple
5. **Expect barcode data quality issues** - Fuzzy matching and deduplication aren't optional

---

## Confidence Levels

| Area | Level | Why |
|------|-------|-----|
| Critical pitfalls (barcode, timezone, sync) | **HIGH** | Confirmed by multiple app reviews, technical docs, real-world examples |
| Secondary pitfalls (offline, search, notifications) | **MEDIUM-HIGH** | Ecosystem research + best practices; fewer direct app examples |
| Tech stack recommendations | **MEDIUM-HIGH** | APIs verified; alternative comparisons done |
| Feature landscape | **MEDIUM** | Inferred from app reviews and competitor analysis |
| Multi-user sync patterns | **MEDIUM** | General distributed systems knowledge; fewer food-app-specific examples |

---

## What This Research Covers

### Breadth
- 13 major pitfalls organized by severity and phase
- 4 technology categories (barcode APIs, sync, notifications, database)
- 5 app categories (permissions, search, offline, prediction, community)
- 10+ real-world app examples with specific user complaints

### What It Doesn't Cover (Phase-Specific Research Needed Later)

1. **USDA FoodData API specifics** - Rate limits, query patterns, coverage gaps
2. **SQLite multi-user locking details** - If you go self-hosted, deep dive needed
3. **Mobile barcode scanning accuracy** - Need lab testing of ML Kit vs AVFoundation
4. **Notification UX specifics** - iOS/Android snooze/scheduling implementation
5. **Household permission models** - Need to research 5-10 successful apps' UX

These should be addressed in Phase-specific research (not critical for roadmap, but needed before implementation).

---

## How to Use This Research

### For Roadmap Creation
1. Read **RESEARCH_SUMMARY.md** for domain overview
2. Review **PITFALLS.md** phase mapping to structure phases
3. Reference **FEATURES.md** to scope each phase
4. Use **STACK.md** for technology justification

### For Architecture Design
1. Read **ARCHITECTURE.md** for system patterns
2. Reference **PITFALLS.md** prevention strategies
3. Check **STACK.md** for tech choices
4. Review **FEATURES.md** for component boundaries

### For Phase Execution
1. Reference **PITFALLS.md** detection signs to watch for
2. Check **STACK.md** for implementation guidance
3. Use **FEATURES.md** to stay in scope
4. Review **ARCHITECTURE.md** for design patterns

### Before User Testing
1. Read **PITFALLS.md** to create test checklist
2. Check **FEATURES.md** table stakes (all should be testable in v1)
3. Verify **STACK.md** choices align with MVP scope

---

## Data Quality Notes

### What We Verified
- USDA FoodData Central API coverage and free access
- Open Food Facts barcode support and community data model
- Multiple app store reviews (My Pantry Tracker, NoWaste, FoodShiner, Pantry Check)
- Technical documentation on timezone handling, race conditions, sync patterns
- Real-world case studies (Sylius inventory, Atlassian Confluence, GitHub JWT)

### What We Didn't Lab Test
- Actual barcode scanning accuracy with real cameras
- USDA API performance with 10K+ item lookups
- SQLite locking behavior under concurrent load
- iOS/Android notification scheduling specifics

These should be tested during Phase 1 (Architecture) and Phase 2 (Implementation).

---

## Sources Summary

**Total sources reviewed:** 40+

**Source categories:**
- App store reviews (8 apps)
- Technical documentation (USDA, Open Food Facts, barcode APIs)
- Distributed systems papers and guides
- User research on feature adoption
- Case studies and post-mortems
- Official API documentation

**Confidence indicators:**
- Sources marked **HIGH** have 3+ independent verification
- Sources marked **MEDIUM-HIGH** have official doc + 2+ examples
- Sources marked **MEDIUM** have 2-3 convergent sources
- Sources marked **LOW** have 1 source; marked for validation

---

## Next Steps

**Before starting development:**
1. Validate UTC timestamp handling approach with your chosen database
2. Test USDA FoodData API coverage on real food products
3. Research 5-10 successful multi-user apps' permission models
4. Create test plan based on **PITFALLS.md** detection signs
5. Scope v1 features against **FEATURES.md** table stakes

**During development:**
- Reference **PITFALLS.md** for each major feature
- Track **PITFALLS.md** detection signs as early warning system
- Run timezone tests across device timezones weekly
- Monitor sync conflict rates in staging environment
- Measure onboarding dropout against target

---

## Questions or Gaps?

This research answers "What mistakes do food inventory apps commonly make?"

If you need different research later, consider:
- **Deeper API research:** How does USDA FoodData coverage compare to Open Food Facts?
- **Competitive analysis:** How do top apps (Out of Milk, Your Food, NoWaste) handle timezone/sync?
- **UX research:** What do users actually want from multi-user households?
- **Performance profiling:** How fast should search/sync be on average phones?

These are phase-specific questions; save them for when you have a v1 to test with.

---

## Document Structure Reference

### Each Pitfall in PITFALLS.md Follows This Format:

```
### Pitfall N: [Name]

**What goes wrong:** [Observable symptoms]

**Why it happens:** [Root causes]

**Consequences:** [Impact if not fixed]

**Real-world example:** [Specific app or case study]

**Prevention:** [Actionable strategies]

**Phase mapping:** [v1/v1.5/v2 placement]

**Detection:** [Warning signs to watch for]
```

### Each Feature in FEATURES.md Follows This Format:

```
| Feature | Why Expected/Valuable | Complexity | Notes |
| [name] | [reason] | Low/Med/High | [dependencies] |
```

---

**Research completed by:** Claude Code (GSD Researcher)
**Date:** January 27, 2026
**Status:** Complete and ready for roadmap creation