Problem statement:
People collect recipes across chats, photos, and scraps; they need a fast, searchable, and
shareable app to save, scale, and use recipes (including images, categories, and shopping-lists)
— offline friendly and easy to demo at a hackathon.
Key features (MVP):
• Add / edit / delete recipes (title, ingredients, steps, image, prep time, servings,
tags/category)
• Browse recipes as cards (list & grid)
• Search (by title, ingredient, tag) + basic filter (category, duration)
• View recipe detail, scale ingredient quantities by servings
• Persist data (localStorage for MVP; API + DB for later phases)
• Responsive UI for demo on laptop / mobile
Expected outcome for Hackathon MVP (Phase 1 deliverable):
• Working single-page app (React + Tailwind) connected to a simple Express API (or local
mock) with documented endpoints, sample data, and run instructions.
• Clear wireframes and API spec to implement Phase 2 quickly.
2) Technology stack & environment setup
Recommended stack (fast to implement at hackathon):
• Frontend: React (Vite) + Tailwind CSS
• State: React Context + local reducer (or Redux if team prefers)
• Backend (optional MVP): [Link] + Express (simple REST API)
• Database (Phase 1 design): MongoDB (hosted: MongoDB Atlas) or SQLite for simple
server demo
• Image storage: base64 (MVP) or Cloudinary / Firebase Storage later
• Auth: none for MVP; optional Firebase Auth in Phase 3
• Dev tools: GitHub, VS Code, Postman, Docker (optional), Netlify/Vercel for frontend,
Render/Heroku for backend
Local dev setup (quick commands):
• Frontend (Vite):
• npm create vite@latest recipe-book -- --template react
• cd recipe-book
• npm install
• npm install -D tailwindcss postcss autoprefixer
• npx tailwindcss init -p
• npm run dev
• Backend (Express, optional):
• mkdir api && cd api
• npm init -y
• npm install express cors mongoose
• node [Link]
• Git workflow: feature branches + PR, name branch feat/<feature-name>
3) API Design & Data Model
I kept endpoints minimal and clear; use JSON over REST. These are ready-to-implement.
Data model (MongoDB-style documents)
Recipe
"_id": "ObjectId",
"title": "Masala Dosa",
"description": "Crispy rice and lentil crepe with potato filling",
"ingredients": [
{"name": "Rice", "quantity": 2, "unit": "cups"},
{"name": "Urad dal", "quantity": 0.5, "unit": "cups"}
],
"steps": [
"Soak rice and dal for 4 hours",
"Grind to a smooth batter",
"Ferment overnight",
"Cook dosa on tawa"
],
"servings": 4,
"prepTimeMin": 15,
"cookTimeMin": 30,
"tags": ["south indian", "breakfast"],
"category": "Vegetarian",
"imageUrl": "data:image/png;base64,....", // or cloud URL
"createdAt": "2025-10-13T10:00:00Z",
"updatedAt": "2025-10-13T10:00:00Z",
"favorites": 0 // optional
User (optional later)
"_id": "ObjectId",
"email": "user@[Link]",
"name": "Alex",
"favorites": ["recipeId1", "recipeId2"]
REST endpoints (MVP)
Base: /api
• GET /api/recipes
o Query params: q (search text), tag, category, limit, page
o Response: { items: [Recipe], total: 123 }
• GET /api/recipes/:id
o Response: Recipe object
• POST /api/recipes
o Body: Recipe (without _id)
o Response: created Recipe
• PUT /api/recipes/:id
o Body: partial or full Recipe updates
o Response: updated Recipe
• DELETE /api/recipes/:id
o Response: { success: true }
• POST /api/recipes/:id/favorite (optional)
o Toggle or increment favorites
• POST /api/recipes/import
o Accepts a JSON batch to seed sample recipes
Example request & response (create):
Request POST /api/recipes
"title": "Basic Pancakes",
"ingredients": [{"name":"Flour","quantity":1,"unit":"cup"}],
"steps": ["Mix", "Cook"],
"servings": 2
}
Response 201 Created
{ "_id":"...", "title":"Basic Pancakes", ... }
4) Front-End UI/UX Plan
Main screens & navigation
1. Home / Recipe List (default)
o Top nav with app name, search bar, "Add recipe" button, filters/tags icon.
o Grid of recipe cards (image, title, tags, prep time).
o Toggle: grid/list.
2. Recipe Detail (Modal or route /recipe/:id)
o Big image, title, tags, time, servings with a serving scaler control (+ / -).
o Ingredients (quantities update when servings change) and steps.
o Buttons: Edit, Favorite, Share, Export (PDF / text).
3. Add / Edit Recipe (form)
o Fields: title, description, tags (typeahead), category (dropdown), servings,
prep/cook time, ingredients (dynamic rows: name, qty, unit), steps (ordered list),
image upload (drag & drop).
o Save button (validates required fields).
4. My Recipes / Favorites (optional)
o Filtered list.
Wireframe (textual)
• Header: Left: logo | Center: search | Right: Add button + profile (if any)
• Left Sidebar (optional on wide screens): Filters (Category, Tags)
• Main: Grid of cards (3 columns desktop, 1 column mobile)
• Card: image (top), title, tags row, time + servings footer, overflow menu (edit/delete)
State management
• Top-level Context: RecipesProvider with reducer:
o Actions: LOAD_RECIPES, ADD_RECIPE, UPDATE_RECIPE, DELETE_RECIPE,
TOGGLE_FAVORITE, SET_FILTERS.
• Search input uses debounced query (300ms) — calls local filter or API.
• Use localStorage caching: save recipes to [Link] after change; on load,
hydrate from localStorage first, then optionally sync with server.
UX details & small delights (hackathon points)
• Live ingredient quantity scaling when user changes servings.
• Card animations (Tailwind + small transition).
• Drag-and-drop reorder for steps/ingredients (bonus if time).
• Quick-add ingredient by typing “2 cups sugar” auto-parsed (nice-to-have).
5) Development & Deployment Plan (Phase 1 scope)
Team roles (4-person example)
• Frontend lead (1): React + Tailwind, wireframes -> components.
• Backend lead (1): Express API, Mongo schema, seed data.
• Full-stack / QA (1): Integrate front & back, write basic tests, prepare demo.
• DevOps / Presentation (1): Deploy to Vercel/Render & build slides + demo script.
Milestones & timeline (hackathon-friendly)
• Hour 0–1: Project kickoff, repo init, basic wireframes, assign tasks.
• Hour 1–3: Implement frontend shell (list + card + search box) + local sample data.
• Hour 3–5: Add Add/Edit recipe form, recipe detail, ingredient scaling.
• Hour 5–7: Hook up Express API (CRUD), persist to Mongo/SQLite, seed sample recipes.
• Hour 7–8: Polish UI, add images, fix bugs, prepare demo script & slides.
(Adjust per your hackathon length.)
Git workflow
• Repo root: frontend/ and api/ folders.
• main protected; create branch feat/<name>. Merge via PR with 1 reviewer (fast).
Testing approach
• Frontend: manual QA flows + a couple of automated tests (Jest + React Testing Library)
for core components (Add recipe form validation, ingredient scaler).
• Backend: simple unit test for endpoints or Postman collection to run smoke tests.
Hosting / deployment
• Frontend: Vercel or Netlify (continuous deployment from GitHub).
• Backend: Render / Render deploy from GitHub or Heroku (if allowed).
• Database: MongoDB Atlas free tier (or a small Render Postgres).
• CI: GitHub Actions to run npm test on PRs (optional for hackathon).
Demo script (60–90 seconds)
1. Open Home -> show grid of sample recipes.
2. Search “egg” to show instant search.
3. Open a recipe -> change servings from 2 → 6 and show ingredients scale.
4. Click Add -> quickly create a new recipe (show form).
5. Show persistence (reload page -> recipe remains).
6. (If backend hooked) show POST/GET requests in Postman or console logs.
6) Sample seed data (3 recipes) — paste into api/[Link] or localStorage
"title": "Masala Dosa",
"description": "Crispy rice & dal crepe with spiced potato",
"ingredients":[{"name":"Rice","quantity":2,"unit":"cups"},{"name":"Urad
dal","quantity":0.5,"unit":"cups"}],
"steps":["Soak rice & dal","Grind","Ferment","Cook dosa"],
"servings":4,
"prepTimeMin":15,
"cookTimeMin":30,
"tags":["south indian","breakfast"],
"category":"Vegetarian"
},
"title":"Basic Pancakes",
"description":"Fluffy pancakes",
"ingredients":[{"name":"Flour","quantity":1,"unit":"cup"},{"name":"Milk","quantity":1,"unit":"c
up"}],
"steps":["Mix ingredients","Cook on skillet"],
"servings":2,
"prepTimeMin":5,
"cookTimeMin":10,
"tags":["breakfast","quick"],
"category":"Vegetarian"
},
"title":"Tomato Basil Soup",
"description":"Comforting soup",
"ingredients":[{"name":"Tomato","quantity":500,"unit":"g"},{"name":"Basil","quantity":5,"unit":
"leaves"}],
"steps":["Roast tomatoes","Blend","Simmer with basil"],
"servings":3,
"prepTimeMin":10,
"cookTimeMin":20,
"tags":["soup","comfort"],
"category":"Vegan"
7) Deliverables I produced (right now)
• Completed Phase 1 doc (this message) with:
o Problem statement & objectives
o Tech stack & setup instructions
o Full API spec + data model
o Frontend wireframes & state plan
o Development & deployment plan, timeline, demo script
o Seed data
If you want, I can immediately (choose one) and I’ll produce it now in the chat (no waiting):
• A full React + Tailwind single-file app (complete working code) wired to localStorage
(MVP).
• OR a combined React + Express starter repo scaffold (file tree + key files: [Link],
RecipesProvider, server/[Link], models/[Link]).
• OR a one-page slide deck (editable markdown) and 60s demo script formatted for
judges.