paulh
/
recipe-manager
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
recipe-manager/docs/recipe-manager-mvp-plan.md

6.8 KiB
Raw Blame History

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.