# 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

---

## 10) Visual Overhaul Task List (UI/UX Execution — Added 2026-03-27)

This list is now the visual execution source-of-truth. Continue these tasks in order.

1. [ ] **UI Audit vs Plan**
   - Inventory current pages/components/styles in frontend.
   - Mark what is complete, partial, or missing.
   - Confirm why color/theme is not visible in current build.

2. [ ] **Design System Baseline**
   - Define color tokens (primary/secondary/accent/surface/text/muted/success/warning/error).
   - Define typography scale (H1-H6/body/caption), spacing scale, radius, shadow levels.
   - Add focus-ring + interactive states (hover/active/disabled).

3. [ ] **App Shell Polish**
   - Upgrade header/nav/sidebar layout and visual hierarchy.
   - Apply page background + card surface contrast.
   - Standardize container widths and vertical rhythm.

4. [ ] **Core Component Restyle**
   - Buttons, inputs, selects, textareas, chips/tags, badges.
   - Card/list row/table visual consistency.
   - Form field spacing, labels, helper/error message styling.

5. [ ] **Key Page Visual Pass**
   - Recipe list page (search/filter strip + cards/list state).
   - Recipe detail page (metadata, ingredients, steps sections).
   - Recipe create/edit page (clean form hierarchy).
   - Tag manager + import/export panels.

6. [ ] **Empty / Loading / Error States**
   - Branded empty states with clear CTAs.
   - Loading skeleton/spinner consistency.
   - Error states with recovery actions.

7. [ ] **Responsive Tuning**
   - Mobile-first checks for list, detail, form, and filters.
   - Tablet breakpoints and spacing adjustments.
   - Desktop density polish.

8. [ ] **Accessibility Pass**
   - Contrast checks for text/surfaces/buttons.
   - Keyboard navigation + visible focus.
   - Semantic labels/aria for core interactions.

9. [ ] **Visual QA + Release Prep**
   - Screenshot pass of all key views.
   - Fix visual regressions.
   - Update docs with theme/design decisions.
   - Commit + changelog note.

---

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