# Recipe Manager — MVP Execution Plan

**Date:** 2026-03-25  
**Owner:** Paul + Cleo  
**Goal:** Ship a tight, usable MVP with clear scope and a fast implementation path.

---

## 1) MVP Scope (Step 1 — locked)

### In Scope (MVP)
1. **Recipe CRUD**
   - Create recipe
   - Read/list recipes
   - View single recipe detail
   - Edit recipe
   - Delete recipe
2. **Tags**
   - Create/delete tags
   - Attach/remove tags on recipes
   - Filter list by tag
3. **Ingredients + Steps**
   - Ingredient list per recipe (qty/unit/item)
   - Ordered instruction steps
4. **Search**
   - Search by title
   - Search by ingredient text
   - Search by tag
5. **Backup portability**
   - JSON export
   - JSON import (merge strategy: skip duplicates by title+sourceUrl)

### Out of Scope (Post-MVP)
- AI substitutions
- Meal planner UX (calendar)
- Shopping list automation
- Nutrition calculations
- OCR/image import
- Multi-user auth/roles

### Definition of Done (MVP)
- User can create/edit/delete recipes with ingredients + steps
- User can tag and filter recipes
- User can search quickly by title/tag/ingredient
- User can export and import data JSON without data loss for core fields
- API + UI docs updated
- Docker compose run path works end-to-end

---

## 2) Architecture (existing stack + MVP alignment)

- **Backend:** Node/TypeScript REST API (SQLite)
- **Frontend:** React/TypeScript (Vite)
- **Storage:** SQLite file (`data/recipes.db`)
- **Deployment:** Docker + docker-compose

MVP will reuse existing architecture and avoid stack churn.

---

## 3) Data Model (Step 2 target)

### Tables
- `recipes`
  - `id` (PK)
  - `title` (TEXT, required)
  - `description` (TEXT)
  - `servings` (INTEGER)
  - `prep_time_minutes` (INTEGER)
  - `cook_time_minutes` (INTEGER)
  - `source_url` (TEXT)
  - `created_at`, `updated_at`

- `ingredients`
  - `id` (PK)
  - `recipe_id` (FK -> recipes.id)
  - `position` (INTEGER)
  - `quantity` (TEXT)
  - `unit` (TEXT)
  - `item` (TEXT, required)
  - `notes` (TEXT)

- `steps`
  - `id` (PK)
  - `recipe_id` (FK -> recipes.id)
  - `position` (INTEGER)
  - `instruction` (TEXT, required)

- `tags`
  - `id` (PK)
  - `name` (TEXT UNIQUE, required)

- `recipe_tags`
  - `recipe_id` (FK -> recipes.id)
  - `tag_id` (FK -> tags.id)
  - composite PK (`recipe_id`, `tag_id`)

### Suggested indexes
- `idx_recipes_title` on `recipes(title)`
- `idx_ingredients_item` on `ingredients(item)`
- `idx_recipe_tags_tag_id` on `recipe_tags(tag_id)`

---

## 4) API Surface (MVP)

### Recipes
- `GET /api/recipes?query=&tag=`
- `GET /api/recipes/:id`
- `POST /api/recipes`
- `PUT /api/recipes/:id`
- `DELETE /api/recipes/:id`

### Tags
- `GET /api/tags`
- `POST /api/tags`
- `DELETE /api/tags/:id`

### Backup
- `GET /api/export/json`
- `POST /api/import/json`

---

## 5) Frontend Surface (MVP)

- `RecipeListPage`
  - search box
  - tag filter
  - recipe cards/list
- `RecipeDetailPage`
  - metadata + ingredients + steps
- `RecipeFormPage`
  - create/edit form with dynamic ingredient + step rows
- `TagManager`
  - add/remove tags
- `ImportExportPanel`
  - export button
  - import file upload + summary

---

## 6) File-by-File Build Board

### Backend
1. DB schema/migrations (recipes, ingredients, steps, tags, recipe_tags)
2. Recipe repository/services with nested ingredient/step handling
3. Search query enhancements (title/ingredient/tag)
4. Tag endpoints + recipe-tag mapping logic
5. JSON export endpoint
6. JSON import endpoint + dedupe policy
7. API tests for CRUD + search + import/export

### Frontend
1. Recipe form supports ordered ingredients/steps
2. List page unified search + tag filter
3. Detail page renders normalized sections
4. Tag management wiring
5. Import/export UI panel
6. UI tests for key flows

### Docs
1. `docs/api.md` update
2. `docs/user-guide.md` update
3. README MVP usage + backup section

---

## 7) 6-Day Execution Plan

- **Day 1:** Scope freeze + schema lock + migration prep
- **Day 2:** CRUD hardening (nested ingredients/steps correctness)
- **Day 3:** Search + tag filter backend/frontend alignment
- **Day 4:** Import/export JSON endpoints + UI integration
- **Day 5:** Test pass, seed data, bug fixes
- **Day 6:** Docs + Docker validation + release tag

---

## 8) Immediate Next Actions (Starting now)

1. ✅ **Step 1 complete:** MVP scope locked in this document.
2. Next: verify existing TODO/roadmap lines up with locked scope.
3. Then start Step 2 (data model lock) by checking current schema vs target model and creating the migration delta list.

---

## 9) Risks / Decisions to keep an eye on

- Duplicate logic for import merge rules (title collisions)
- Tag naming normalization (case-insensitive unique)
- Ingredient parsing consistency for search quality
- Backward compatibility with existing recipe records

---

If scope changes are requested, update this file first and treat it as the source of truth for implementation sequencing.