Meal Plan Builder

The meal plan builder is the core of MealStack. Create day-by-day nutrition plans with real-time calorie and macro tracking, visual progress indicators, and smart nutrient gap alerts.

Creating a plan

Client context panel

When a plan is linked to a client, a Client tab appears in the builder sidebar (open by default). This panel gives you constant access to the client's health profile without leaving the builder. A View Profile link at the top opens the full client profile in a new tab for quick edits.

Sections displayed:

• Profile snapshot — name, age, gender, height, weight, BMI
• Daily targets — calorie and macro progress bars showing actual vs target for the current day
• Restrictions — allergies (red), intolerances (amber), dietary preference (blue)
• Medical conditions — badges for diabetes, PCOS, thyroid, etc.
• Cuisine preferences — preferred cuisines for culturally appropriate meal planning
• Food likes & dislikes — green tags for likes, red tags for dislikes
• Women's health — pregnancy status with trimester indicator and calorie adjustment (+0/+340/+452 kcal), breastfeeding status with baby age and calorie guidance (+400/+500 kcal), menstrual cycle regularity, menopausal status
• Medications & supplements — current prescriptions and supplements (important for food-drug interactions)
• Lifestyle — cooking skill, meal prep time, eating out frequency, stress level
• Typical diet — what the client normally eats for each meal (helps you build plans they'll actually follow)

Plan score

The Score tab in the builder sidebar rates your plan across up to 7 metrics. The overall score is the average of all applicable metrics.

Clinical safety flags

When the client has medical conditions or special health status, the Clinical Safety metric checks for potential issues:

Nutrient tracking

The nutrient bar at the top provides real-time visual feedback:

• Calorie ring — circular progress indicator showing percentage of daily calorie target. Green when 80–110% (on track), amber when slightly off, red when significantly under or over.
• Calorie bar — stacked progress bar showing per-meal calorie contribution. Each meal gets its own colored segment with a compact legend below (e.g., "Breakfast 420 · Lunch 580 · Dinner 490"). Hover any segment to see the exact kcal. When no meals have items yet, falls back to a simple progress bar.
• Macro mini-bars — compact progress bars for Protein, Carbs, and Fat showing actual vs target (e.g., "P 58/165g")

Per-item nutrition

Every food and recipe item in the plan shows inline macro pills below its name:

• P (protein), C (carbs), F (fat), Fb (fiber) — color-coded and shown in grams
• Only non-zero values are displayed (no clutter from "P 0g")
• Hover over any item name to see a nutrition hover card with a macro ratio bar, kcal, and all macros in a compact grid

Click any food name to open the Food Detail Sheet (full nutrient breakdown, portions, micronutrients). Click any recipe name to open the Recipe Detail Sheet (nutrition per serving, ingredients list, instructions).

Meal timeline

A compact timeline above the meal slots shows your meal spacing visually:

• Dots represent each meal on a 5AM–11PM track
• Filled dots = meals with food items, empty dots = empty slots
• Shows eating window duration and fasting window (e.g., "15.5h eating · 8.5h fasting")

This is especially useful for intermittent fasting plans and ensuring proper meal spacing.

Day view

The default view shows one day at a time with meal slots:

Adding foods

Click Add food or recipe in any meal slot to open the search panel.

AI-powered suggestions

When there's a significant nutrient gap (>30% below target for any macro), an AI Suggestions section appears in the search panel. Click the "Suggest foods" button to get AI-powered recommendations based on the client's profile, dietary preference, and current nutrient gaps.

Suggestions are cached per meal type — switching between meals and back reuses previous results without another AI call. Click Refresh to get new suggestions.

Manual search

Search by English name — Type "brown rice" → results show Brown rice, cooked (USDA) at 123 kcal/100g.

Search by Hindi name — Type "dahi" → results show Curd / Dahi (IFCT) at 60 kcal/100g.

Prefix matching — Type "chick" → immediately shows Chicken, Chickpea, etc. without needing the full word.

Each search result shows:

• Food name with source badge (IFCT / INDB / USDA)
• Macro preview (calories, protein, carbs, fat) in consistent colors
• Hindi name (when available)
• Category name
• Calorie density badge — VL (very low, under 60 kcal/100g), L (low), M (medium), H (high, over 400 kcal/100g)

Recipe results appear in a separate section above foods, showing:

• Recipe name with a violet indicator
• Calories per serving — so you can compare recipes against individual foods before adding
• Servings count, cuisine type, and ingredient count
• "per serving" label for context

The first 15 results load instantly. If more results exist, a "Show more" button appears at the bottom with the total count (e.g., "Show more — 32 remaining"). Click to load the next page.

Can't find a food? A "Create custom food" link appears at the bottom of search results. Click it to open the Quick Food Creator pre-filled with your search query. After creating, the food is automatically added to the meal slot — no need to search again. See Food Database → Quick food creator for details.

After adding, adjust the quantity and portion size (grams, katori, roti, cup, tablespoon, etc.).

Organizing items

Reorder within a meal

Hover over any food item to reveal a drag handle (⠿) on the left. Drag items up or down to reorder them within the meal — useful for putting the main item first, sides second, and beverages last. An amber line shows above the row where the item will land.

Move between meals or days

Two ways to move an item:

• Via the ⋯ menu on the item: pick Move to → [meal name] for a quick relocate within the same day.
• Drag the item onto another meal slot to move it there (the target meal lights up amber with a "Move to" banner, and an amber line marks the drop position). Drag onto a day tab at the top to move the item to that day. The matching meal type carries over when present, otherwise the item lands on the first meal of the target day.

Add foods by dragging from the Food Library

Open the Food Library sidebar tab on the right. Search for any food or recipe, then drag the result onto a meal:

• Drop on empty space in the meal to append the item at the end.
• Drop on an existing item to slot the new food at that visual position — surrounding items shift down to make room. An emerald line indicates the drop position; the target meal slot lights up emerald with a "Drop to add" banner.
• Drops onto alternatives or side dishes inside a group append at the end (the group structure is preserved).

The search row's keyboard flow (↑↓ / ↵ / ⌘↵ / ⇧↵) is faster for bulk adds, but drag-from-library is the right tool when you're exploring or already have the sidebar open.

Clear and remove meals

The ⋯ menu on each meal header offers:

• Clear all items — empties the meal without removing the slot itself
• Remove meal — deletes the meal slot entirely (confirms if it has items)

Add a meal slot

Click + Add meal slot below the last meal to add a missing meal type (e.g., Pre-Workout, Post-Workout, Bedtime). The dropdown shows only meal types not already in the current day.

Nutrient gap alerts

When daily targets are set and a nutrient is significantly off, the builder shows smart alerts at the bottom of the day:

Food safety warnings

The builder automatically flags foods that may be unsafe or inappropriate based on the client's health profile. Warnings appear as colored badges on food items in the meal slots.

Pregnancy safety

When a client is marked as pregnant, the builder warns about:

Medical condition warnings

When a client has medical conditions in their profile, the builder flags condition-specific foods:

Medication interactions

When a client has medications listed in their profile, the builder warns about food-drug interactions:

Day tabs with calorie totals

The day sidebar shows each day's name and total calories, making it easy to spot which days need attention without clicking through each one.

For active plans, the day that corresponds to today's date shows a green "Today" badge — so you always know which day the client is currently on in their portal.

Week view

Switch to week view to see all days side by side. Each day shows:

• Total calories with a color-coded progress bar
• Macro breakdown (P/C/F) in consistent colors
• Food items per meal slot

Click any day to jump back to the day view for editing.

Copying meals and days

This is the biggest time-saver in the builder:

• Copy a meal — click the ⋯ menu on any meal → "Copy to other days"
• Duplicate a day — hover over a day tab → ⋯ → "Duplicate Day"

Food alternatives

For any food in a meal, you can add alternatives — "or" options the client can choose from if the primary item isn't available or preferred. This is the industry-standard approach used by platforms like Nutrium and Foodzilla.

How nutrient totals work

Only the primary food in each alternative group counts toward meal and day totals. The primary is always the first item in the group (topmost). Alternative items show their own calories inline but are excluded from all totals — nutrient bar, day calories, plan score, grocery list, and PDF summaries.

Adding alternatives

You can also click + Add option in the group footer to add more alternatives to an existing group.

Visual grouping

Items in the same alternative group are wrapped in a dashed border with "or" dividers between them:

• The primary item (first in the group) shows a green dot (●) next to its name — this is the one counting toward totals
• Alternative items show dimmed calorie values to indicate they're excluded from totals
• The group footer has two actions: + Add option (add another alternative) and Ungroup (dissolve the group)

Changing the primary

Drag-and-drop reordering within a group changes which item is primary. The topmost item after reordering becomes the new primary, and nutrient totals update accordingly.

Removing and moving items

• Removing an item from a 2-item group automatically dissolves the group — the remaining item becomes standalone
• Moving an item to a different meal detaches it from its group. If the source group is left with only 1 item, that group is dissolved automatically

Alternatives in PDF exports

Day list layout — Alternative items appear indented below the primary with an italic "or" prefix and dimmed calories. A footnote explains: "Items marked 'or' are alternatives. Nutrition totals reflect the primary option only."

Week grid layout — Only primary items are shown (space is limited). Items that have alternatives show an asterisk (*). A footnote explains the convention.

Grocery list — Only primary items are included in the grocery list. Alternative ingredients are excluded to avoid over-purchasing.

Alternatives in the client portal

Clients see the primary food normally. Below it, a small chip shows "X alternatives" — tapping it expands the alternative options with an "or" prefix and a left border accent.

Each alternative has a "Use this" button. When a client taps it, the selected food swaps to the top position and the meal's nutrient totals recalculate instantly to reflect the selected item. The day totals and calorie ring on the home screen update too. Selections persist across page refreshes — the client doesn't need to re-select each time.

Notes and instructions

Add notes at any level of the plan — per food item, per meal, per day, or for the entire plan. Each note has two fields:

Per-food notes

Click the 📝 icon on any food item to add notes. Common uses:

• "Boil for 10 minutes" (preparation instruction)
• "Can substitute with paneer" (alternative suggestion)
• "Use low-fat version" (client-facing tip)
• "Client mentioned bloating with this food" (internal clinical note)

Per-meal notes

Click the 📝 icon in the meal header (next to the kcal total). Use for timing instructions like "Eat within 30 minutes of waking up" or "Post-workout — consume within 45 min."

Per-day notes

Click the 📝 icon at the top of the day view. Use for special day instructions like "Fasting day — only liquids until noon" or "High-carb day (training day)."

Plan-level notes

Open Plan Settings (⚙️) to add plan-level notes:

• Client Notes — general instructions shown on the PDF and portal (e.g., "Drink 3L water daily")
• Internal Notes — private notes for your reference (e.g., "Client prefers South Indian cuisine, review in 2 weeks")

Plan actions

The builder header groups actions by purpose.

Status

The status pill next to the plan title is a menu. Click it to move the plan through its lifecycle. Only valid moves are shown, and each opens a short confirm.

A contextual primary button sits beside the pill for the most common move: Activate (draft), Resume (paused), Reopen (completed), or Restore (archived).

• Activate makes the plan live, publishes the first version, and emails the client.
• Back to draft clears the dates and removes the plan from the portal.
• Pause temporarily hides the plan without ending it (see Pausing a plan).

Publish (active plans)

Active plans show a single Publish control in place of a separate button and banner. It holds every publish action and shows the current state at a glance (see Editing an active plan).

Tools

The ⋯ menu holds utilities: Grocery List, Export PDF, Copy Portal Link, Plan Settings, Save as Template, Clone Plan, and Version History.

Help and tours

A ? button sits in the header between Grocery and Activate/Publish. Click it for a flat list of focused walkthroughs:

• Quick tour of the planner — the 5-step overview that auto-launches once for new users. Replayable any time.
• Build your first meal — the core add flow: pick a meal, open the search, pick a food, edit the portion, watch the macros update.
• Activate and publish — status lifecycle, activating a draft, publishing edits on active plans.
• Plan score and issues — the six dimensions of plan score and how to act on suggestions.
• AI features — only shown when AI is connected: AI suggestions in the search row, AI swap on items, fill a meal with AI, and the AI Assistant panel.
• Tools, templates, PDFs — what lives behind the Tools menu.

Each mini-tour is 3-5 steps. None of them auto-launch — open them when you want a refresher.

View and grocery

A day/week toggle switches the layout. The 🛒 button opens the auto-generated grocery list (on small screens it moves into the Tools menu).

Plan settings

Open Plan Settings from the ⋯ menu (or click the gear icon) to manage all plan metadata in one place.

Client assignment

The top section lets you assign, change, or remove the client linked to this plan.

• Assign a client — search by name and select. Nutrient targets auto-fill from the client's profile for any empty target fields.
• Change — switch to a different client. Empty targets are filled from the new client's profile.
• Remove — unlink the client (the plan keeps its content and targets).

Changes are saved when you click Save Settings — you can cancel to undo.

Duration

Use the +/− stepper to change the plan duration (1–28 days).

• Extending adds blank days with the same meal slot structure as existing days.
• Shrinking removes days from the end. If those days contain food items, a confirmation dialog warns you before deleting.

Schedule

• Start date — sets when the plan begins. Auto-detects the weekday and relabels days accordingly.
• End date — auto-calculated from start date + duration.
• Day labels — choose weekday labels (Mon→Sun) or generic labels (Day 1, Day 2...).

Daily targets

Edit calorie and macro targets. If a client is linked, click Sync from client to pull the latest targets from their profile.

Nutrient visibility

Control which nutrients the client sees in PDFs and the portal. By default, all five nutrients (calories, protein, carbs, fat, fiber) are visible. You can hide specific nutrients per plan — useful for clients where showing certain macros isn't clinically appropriate (e.g., hiding fat for clients with eating disorder history, or hiding all macros for clients who feel overwhelmed by numbers).

Click any nutrient pill to toggle it off. Hidden nutrients are still tracked internally — the practitioner always sees all data in the builder. Only the client-facing outputs (PDF exports and portal) are affected.

Notes

• Client notes — shown on PDF exports and the client portal.
• Internal notes — visible only to you and your team.

Grocery list

Click the 🛒 button to auto-generate a shopping list from all foods in the plan, grouped by category (grains, vegetables, fruits, dairy, etc.). Quantities are rounded to practical shopping amounts.

Share via copy, WhatsApp, or print.

PDF export

Click ⋯ → Export PDF to generate a branded PDF. Customize what appears:

• Cover page with practice logo and client name
• Client summary with health stats
• Day-by-day meal plan with portions and per-meal nutrients
• Per-item macros (optional) — show P/C/F below each food item. Enable with the "Show item macros" toggle in the export dialog. Off by default to keep PDFs clean.
• Daily nutrient totals
• Nutrient summary across all days
• Recipes (if included)
• Grocery list
• Recommendations (water intake, physical activity, foods to avoid)
• Custom message
• Visible nutrients picker — choose which macros appear in the PDF (calories, protein, carbs, fat, fiber)

Display preferences in exports

Your practice's display preferences (configured in Settings → Food Database → Visibility & Filters) automatically apply to PDF exports:

If the client's portal is enabled, a QR code linking to the portal is automatically added to the cover page. For PDFs without a cover page, the QR code appears at the end of the document.

Templates

Save any plan as a reusable template:

Plan statuses

Confirmation dialogs

All status transitions require explicit confirmation. Each dialog explains what will happen:

One active plan per client

MealStack enforces a single active plan per client. If you try to activate a plan for a client who already has one active, you'll see a dialog offering two choices:

• Cancel — keep the existing plan active
• Replace & Activate — the existing plan is automatically marked as "Completed" and the new plan becomes active

This prevents confusion about which plan is current. If you have legacy duplicate active plans (created before this guardrail), the plan list shows an amber ⚠ warning icon with a tooltip: "This client has multiple active plans."

Deactivating a plan (Back to Draft)

If you accidentally activated a plan or need to make significant edits, use Back to Draft from the ⋯ menu. This:

• Moves the plan back to Draft status
• Clears the start and end dates (they'll be re-set on next activation)
• Removes the plan from the client's portal immediately
• Does not send any email notification to the client

Reopening and restoring plans

• Completed → Reopen: Moves the plan back to Draft so you can edit it. Start and end dates are cleared — they'll be re-set when you activate again.
• Archived → Restore: Same as reopen — moves to Draft for editing.

This means no plan is ever a dead end. You can always go back and revise.

Editing an active plan

Active and paused plans stay fully editable, but your edits are staged until you publish them. The client keeps seeing the last published version in their portal, so they never catch a half-finished change mid-week.

How it works

• When you Activate a plan, MealStack publishes a snapshot of its content. That snapshot is what the client sees.
• As you edit an active plan, your draft builds up alongside the published version.
• The header's Publish control shows the state and holds every publish action in one place.

The Publish control

For an active plan, the header shows one split button whose primary segment reflects the state:

The chevron beside it opens a menu:

• Publish & email PDF: publishes and also emails the plan with a PDF (the delivery dialog).
• Preview changes: opens a diff of your draft against the last published version before you publish (see Version history).
• Discard changes: throws away your unpublished edits and reverts the plan to what the client is currently seeing. Your draft is saved as a version first, so a discard is reversible.

Pausing a plan

Use Pause (from the ⋯ menu on an active plan) to temporarily take a plan offline without ending it.

• The client stops seeing the plan in their portal and gets a "your plan is paused by your dietitian" message instead of a blank screen.
• Progress, history, and content are all kept.
• Click Resume to make it live again, or Complete to end it.

Approval workflow

Approval controls whether a plan needs a second pair of eyes before it can reach a client. An admin sets the policy under Settings → Approval Workflow:

A practitioner can never approve their own plan, so "Approval for everyone" needs at least two team members with reporting access.

Under the default mode, publishing is gated by the mealPlans.publish capability:

• Owner, Lead Dietitian, and Dietitian can publish freely (activate, publish updates, and deliver).
• Interns and trainees (and any custom role without the capability) must get a plan approved before it can reach a client.

For the author (submit for review)

When a gated member opens a plan, the header shows a Submit for review button instead of Activate/Send. After submitting:

• The plan's reviewers (members with reporting access, which Lead Dietitians and Owners have by default) are notified by email.
• The header shows the review state: Awaiting review, Approved, or Changes requested (with the reviewer's note on hover).
• If changes are requested, make them and click Resubmit for review.
• Once approved, the normal Activate / Publish / Send actions appear.

The gate applies to every path that reaches a client: activation, "replace existing active plan", publish update, and delivery. There's no way around it.

For the reviewer (approve or request changes)

Reviewers can act in two places:

• From the plan — open the submitted plan and use the inline Approve or Request changes buttons in the header.
• From the Team dashboard — the Team Oversight pending-review queue lists all plans awaiting review.

A badge on the Team sidebar item shows how many plans are waiting. Review decisions are logged to the client's activity timeline for audit.

Sending plans to clients

After activating a plan, open the Publish control and choose Publish & email PDF. The delivery dialog offers two channels side by side:

• Send Email — emails the plan to the client with an optional personal message and PDF attachment
• WhatsApp — opens WhatsApp with a pre-composed message containing the plan details and portal link (requires the client to have a phone number)

Both options support:

• A personal message field (optional)
• PDF attachment toggle (on by default)
• Portal link inclusion (if the client's portal is enabled)

If the client has only a phone number (no email), you can still deliver via WhatsApp. If they have only an email (no phone), the WhatsApp button won't appear.

You can also copy the portal link directly from the ⋯ menu → Copy Portal Link in the plan builder toolbar.

Cloning and next cycle

Instead of building every plan from scratch, clone an existing one:

• Clone Plan — creates an exact copy as a new Draft. Available from the ⋯ menu in the builder, the plan list, or the client's Plans tab.
• Create Next Cycle — clones a completed plan and shifts the dates forward. If the original plan ended on Friday, the new one starts Saturday. Available on completed plans in the client's Plans tab.

Cloned plans track their lineage — each clone increments the version number (v2, v3, etc.) and links back to the source plan via parentPlanId.

Version history

Every plan keeps an immutable history of its content. Open Version History from the ⋯ menu.

Snapshots are captured automatically when you:

• Activate a plan (the first published version)
• Publish update or Publish & email PDF (each becomes a published version)
• Restore or Discard (your current content is saved first, so both are reversible)

The history sheet

• A status timeline at the top shows lifecycle events (created, activated, paused, completed, delivered) with the date and who did it.
• Content versions are listed newest first. The version the client is currently seeing is marked Live now. When you have unpublished edits, a Current draft row appears at the top with Preview and Discard.
• Auto-saved snapshots (taken before a restore or discard) are hidden behind a Show auto-saves toggle to cut noise.

For each version you can:

• View: a read-only preview of that version's days, meals, and items.
• Compare: a diff of that version against your current draft.
• Restore: replace the current content with that version (disabled for the live version).

Comparing versions

Compare (on any version) and Preview changes (on the Publish control, draft vs last published) open the same diff view. It shows, per day and meal:

• Items added, removed, and changed, with the before and after portion.
• Changes to plan settings (targets, client notes, visible nutrients).
• A nutrition impact summary: the net change in calories and macros for the day.

Plan expiry

When an active plan passes its end date, MealStack shows visual indicators:

• Builder header — "Xd remaining" (amber when ≤3 days, red when overdue)
• Plan list — expiry badge next to the status
• Plan settings — status section with countdown
• Expired banner — a red banner appears in the builder with two actions: Complete or Next Cycle