252 lines
6.8 KiB
Markdown
252 lines
6.8 KiB
Markdown
# 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.
|