# Recipe Manager — Project Vision

**Project Name:** Recipe Manager  
**Owner:** Paul Huliganga  
**Created:** 2026-03-23  
**Status:** Planning → MVP Development

---

## Vision

Build a **self-hosted, privacy-first recipe management app** that Anne and Elizabeth can use to organize, import, and cook from their recipes—replacing CopyMeThat with full data ownership and extensibility.

### Why Build This?

1. **Data sovereignty** — We control our data, not a SaaS provider
2. **Agentic engineering practice** — Perfect scope for autonomous agent-driven development
3. **Extensibility** — Future AI features (meal planning, cost tracking via Fintrove integration)
4. **Learning** — Hands-on experience with modern web stack + agent collaboration

---

## Success Criteria

### MVP (v0.1) — "Anne and Elizabeth can use it"
- ✅ Manual recipe entry (title, ingredients, instructions, source URL, notes)
- ✅ Recipe viewing/editing/deletion
- ✅ Basic organization (tags/collections)
- ✅ Search (text-based)
- ✅ Cook mode (ingredient checkboxes, step tracking, wake lock)
- ✅ Self-hosted deployment (Docker Compose on paje.ca)

### v1.0 — "Feature parity with CopyMeThat"
- Recipe scraping (browser extension or bookmarklet)
- Multi-device sync
- Print styles
- Scaling (adjust serving sizes)
- Random recipe suggestion

### v2.0 — "AI-enhanced"
- Ingredient substitution suggestions
- Meal planning
- Shopping list generation
- Integration with Fintrove (recipe cost tracking)

---

## Constraints

### Technical
- **Stack:** Node.js + TypeScript + React + SQLite
- **Deployment:** Docker Compose, self-hosted on paje.ca
- **Storage:** Local-first (SQLite), cloud sync optional in v1
- **Browser support:** Modern evergreen browsers (Chrome, Firefox, Safari, Edge)

### Development
- **Agent-driven:** Sub-agents build, test, document autonomously
- **Version control:** Git with conventional commits
- **Testing:** Unit tests for core logic, E2E tests for critical flows
- **Documentation:** Auto-generated architecture decision records (ADRs)

### Timeline
- **MVP:** 48-72 hours of agent work (overnight runs)
- **v1.0:** 1-2 weeks (incremental agent iterations)
- **v2.0:** TBD (depends on AI integration complexity)

---

## Non-Goals (for MVP)

- ❌ Mobile apps (web-first, PWA later)
- ❌ User authentication (single household deployment)
- ❌ Recipe sharing/community features
- ❌ Video support
- ❌ Nutrition tracking (maybe v2)

---

## Key Decisions

### Why SQLite?
- Local-first, zero-config, portable
- Perfect for single-household deployment
- Can sync via file replication (Syncthing, Dropbox) if needed

### Why React?
- Agent familiarity (Codex knows React cold)
- Rich ecosystem for forms, UI components
- Can evolve to Next.js if SSR needed

### Why Docker Compose?
- Consistent deployment across machines
- Easy backup/restore (just copy SQLite file)
- Can add services incrementally (reverse proxy, backup cron, etc.)

---

## Agent Instructions Reference

See `AGENT_INSTRUCTIONS.md` for how agents should approach development, testing, and documentation.

---

## Decisions Made (2026-03-23)

1. **Domain/URL:** `recipes.paje.ca` ✓
2. **Initial users:** Whole family (Anne, Elizabeth, Paul, Joseph) ✓
3. **Data migration:** Export from CopyMeThat if possible (free tier may be limited now)
4. **First priority after MVP:** Recipe scraping extension (v1.0 milestone)

---

## AI Features Vision (v2.0+)

These are the "smart" features planned for future releases:

### Cooking Intelligence
- **Ingredient substitutions** — "Out of buttermilk? Use milk + vinegar"
- **Meal planning** — Generate weekly menus from your recipe collection
- **Shopping lists** — Aggregate ingredients, de-duplicate, organize by grocery aisle
- **Recipe recommendations** — "You haven't made this in 3 months, try it tonight!"

### Data & Integration
- **Nutrition estimates** — Calorie/macro breakdown via USDA database
- **Fintrove integration** — Track recipe costs, generate budget-aware meal plans
- **Recipe costing** — "This dinner costs $4.50/serving"

### Advanced Input
- **Voice input** — Add ingredients/steps via speech-to-text
- **OCR import** — Scan physical recipe cards or cookbooks
- **Smart parsing** — AI-enhanced recipe extraction from non-standard sites

**Why later?** Need MVP data (recipes + usage patterns) to tune AI features effectively. Scraping comes first so Anne & Elizabeth can import their existing collections.

---

_This is a living document. Agents should update it as the project evolves._
