Files
Django_TasksApp/main/FOOD_DESIGN_SPEC.md
T

6.7 KiB

Food module — v1 design and implementation spec

Source: the supplied 00-overview.md and five food diary screenshots. The screenshots guide hierarchy and interactions; use original styling, icons, and product imagery. Do not copy the source app's assets or branding.

Project integration

food is a separate Django app in main/food/, registered in INSTALLED_APPS. Its URL namespace is food, mounted at /food/; food:diary is the entry point. The shared authenticated navigation contains a Food item. Food templates can extend planner/base.html and use the existing Vite/HTMX setup, but food models, views, forms, services, and tests belong to the food app. Every food record is owned by the authenticated user. The app scaffold and route exist; the diary features below are the implementation scope for v1.

Core flow

Open Food → choose a day → tap the plus beside a meal → pick a recent or favourite food, search local products, scan a barcode, or deliberately search Open Food Facts → review the product → choose a portion and quantity → save → see the meal list and daily totals update. A cached product must be reusable without another external request.

Screens and behavior

Diary (/food/)

  • Mobile: date switcher at top, then a calorie budget card, three macro summary cards, and Breakfast, Lunch, Dinner, Snacks groups. Each group shows its calories and an add button. Food rows show name, optional brand/image, calories, and chosen portion. A floating add action can open meal selection.
  • Keep a compact summary visible while scrolling if it does not obscure entries or controls. Desktop: meal list in the main column and a sticky summary sidebar.
  • The calorie card shows eaten, goal, and remaining. Macro cards show consumed/goal and progress for carbohydrates, protein, and fat. Empty and over-goal states need readable numbers in addition to color.
  • Date changes load that user's entries for the selected local day. Meal headings and totals derive from saved entries. A row opens its entry for editing or deletion; neither action affects another user's records.

Add food

  • Show Favourites, Recent, and All local products as distinct tabs. Search queries the local database while typing. Each row gives a product name, brand if known, calories for a clearly named reference portion, and optional thumbnail.
  • Provide explicit Search Open Food Facts and Scan barcode actions. Do not call the external catalogue on each keystroke. Preserve the selected day and meal throughout search and add flows.
  • Browser scanning uses native BarcodeDetector when supported and a ZXing browser fallback otherwise. Start the camera only after a user action; stop all tracks on success, cancel, navigation, and error. Offer text barcode entry when camera access fails.
  • On barcode entry or scan, look up the local cache first. Query Open Food Facts only for an uncached code or an explicit refresh. Show missing/incomplete data clearly and allow manual entry.

Product detail and log

  • Show product name, brand, optional image, and calories/carbohydrates/protein/fat for the selected amount. Quantity and portion controls update these values before saving. Let users define a named custom portion with its gram or millilitre amount.
  • Meal selection defaults to the meal used to launch the flow and remains editable. Show available nutrient data without turning missing values into invented zeros.
  • Saving creates a snapshot of name, amount, unit, nutrient values, meal, and date in the log entry. Later catalogue refreshes must not silently change historical entries. Favourites can be toggled here or from search.

Goals and export

  • Per-user daily calorie, carbohydrate, protein, and fat goals are editable. Choose sensible blank states instead of implying personalized recommendations.
  • Export the current week or current month as CSV using the user's local dates. Include date, meal, product, brand, quantity, portion, calories, carbohydrates, protein, and fat; restrict the export to the requesting user.

Data and service boundaries

  • FoodProduct: user-owned local catalogue entry or cached Open Food Facts item; store barcode/source identifier, display details, nutrients per 100 g or 100 ml, source/refresh timestamp, and optional image URL. Validate units and nullable nutrients. Barcode uniqueness should be scoped appropriately so users' local data stays isolated.
  • FoodPortion: product-linked label, amount, and unit; record which user created a custom portion. A standard 100 g/ml option must always be available when the source data supports it.
  • FoodLogEntry: user, local date, meal, product reference if available, chosen quantity/portion, and immutable display/nutrient snapshot. Calculate totals from snapshots with decimal arithmetic.
  • FoodGoal: one set of daily goals per user. FoodFavourite can be a user/product relation. Recents derive from log entries, ordered by latest use and deduplicated.
  • Put Open Food Facts HTTP calls in a server-side service with timeouts and explicit error handling. Map only validated catalogue values into local records. Include Open Food Facts attribution and a link to the source product where its data appears.

Visual system and accessibility

Use the screenshots' information hierarchy: high contrast background, restrained cards, color-coded nutrient accents, compact product rows, prominent add and scan controls. Respect the existing Tasknest appearance setting, including light mode. All actions must be reachable by keyboard and screen reader; icon-only buttons need accessible labels. Do not rely on ring color alone to convey a value. Preserve usable controls at iPhone widths, safe areas, and large text sizes.

Acceptance criteria

  1. A signed-in user can set goals, add a manual food to Breakfast, edit it, and delete it; the diary totals update correctly for that local day.
  2. Local search, favourites, and recents return only the user's available foods and never trigger an external request while typing.
  3. Barcode flow checks local records first; an uncached barcode fetches and caches an Open Food Facts product; scan cancellation releases the camera.
  4. Portion and quantity math uses the same nutrient basis in preview and saved entry; a custom portion can be reused.
  5. Week and month CSV files contain only the requesting user's entries and correct local dates.
  6. The mobile diary, add-food flow, and product detail remain usable without horizontal scrolling; desktop uses the available width.

Out of scope for v1

Weight-loss planning, automatic goal recommendations, exercise calorie adjustment, Apple Health, Home Assistant, recipes, meal templates, AI recognition, photo estimates, micronutrient goal dashboards, weekly nutrition reports, automatic grocery lists, diet scoring, and social features.