Yammy Diet — Tandem Plate MVP

Make food work better together.

Live demo: https://yammy-diet-hackathon.vercel.app

Yammy Diet is a mobile-first, local-only meal companion. A user describes a meal, confirms locally recognised ingredients, and receives a small number of deterministic, evidence-cited food-pairing suggestions. The product avoids calorie scoring, medical interpretation, and runtime AI.

This repository makes no trademark, availability, registration, or clearance claim.

Hackathon snapshot

Experience	Mobile-first meal builder, pairing recommendations, meal history, and weekly review
Runtime	Runs entirely in the browser; no backend, account, API key, or environment variables
Data	Stored locally in the current browser using IndexedDB; each judge starts with a fresh profile
Recommendation model	Deterministic, versioned rules with visible evidence grades and safety exclusions
Current status	Hackathon MVP for adult general-wellbeing education; not a clinical product

Two-minute judge walkthrough

1. Select Set up my companion, confirm that you are 18+, and complete the short preference setup.
2. In Pair, enter Lentil curry and rice and select Recognise foods.
3. Confirm the recognised lentils and white rice, then select Find a pairing.
4. Open Evidence and rule details on the vitamin C suggestion, then select Add this.
5. Select Mark eaten, open Week, and see the pairing reflected in the local weekly summary.
6. Open You to inspect local-only privacy controls, export/import, and permanent deletion.

Intended purpose

“Tandem Plate provides general educational food-pairing suggestions for adults seeking to improve everyday meal variety and nutrient utilisation. It estimates nutrition coverage only from sufficiently complete food logs. It cannot determine how much of a nutrient an individual absorbs, diagnose a deficiency, interpret laboratory results, recommend supplements or diagnose, monitor, manage or treat disease.”

This v1 build is for adults aged 18+ seeking general wellbeing. It is not intended for diagnosis, treatment, supplement advice, medication changes, laboratory interpretation, pregnancy/child nutrition, or condition management.

Run locally

Prerequisites:

• Node.js >=22.12.0 (Node.js 24 LTS recommended)
• npm, which is included with Node.js

No account, API key, .env file, database server, or external service is required.

Windows PowerShell

Use the .cmd form so the commands also work when PowerShell script execution is restricted:

npm.cmd ci
npm.cmd run dev

macOS, Linux, or Windows Command Prompt

npm ci
npm run dev

Keep that terminal window open and visit exactly http://127.0.0.1:4173/. Press Ctrl+C in the terminal to stop the app. After the first install, subsequent launches only need the run dev command.

If the page appears blank

1. Confirm the terminal still says VITE ... ready and open exactly http://127.0.0.1:4173/.
2. Hard-refresh with Ctrl+Shift+R, or try a private/incognito browser window.
3. If this address previously served an older build, clear site data for 127.0.0.1 so an old service worker cannot serve cached files.

Deploy a public demo while keeping the code private

The simplest submission setup is a private personal GitHub repository connected to Vercel. The source repository remains private, while Vercel provides a public *.vercel.app demo URL. Each push to the repository's production branch can redeploy the demo automatically.

In Vercel, import the GitHub repository with these settings:

Setting	Value
Framework	Vite
Root directory	./
Build command	npm run build
Output directory	dist
Environment variables	None

After deployment, test the production URL in a private/incognito window before sharing it. The compiled browser assets are naturally visible to visitors even though the source repository is private.

Production build

Build and preview the production bundle:

npm run build
npm run preview

The preview uses the same local address. The static service worker/PWA shell is intended to keep the app usable offline after a successful first load. Offline behaviour is origin- and browser-dependent; clear site data when testing a fresh install.

Validation commands

npm run test
npm run typecheck
npm run build

For the mobile and desktop Playwright flows, install Chromium once and then run:

npx playwright install chromium
npm run test:e2e

Command	Purpose
npm run dev	Run Vite on 127.0.0.1:4173.
npm run test	Run the Vitest unit/component suite once.
npm run test:watch	Run Vitest interactively.
npm run typecheck	Check the TypeScript project without emitting app files.
npm run build	Type-check and create the production bundle.
npm run preview	Serve the production bundle locally.
npm run test:e2e	Run mobile and desktop Chromium end-to-end/accessibility coverage.

Architecture

• React, TypeScript, and Vite provide the responsive single-page interface.
• Pure TypeScript domain modules own schemas, local food recognition, reviewed pairing rules, safety decisions, stable ranking, and weekly recomputation. They do not depend on React.
• Versioned local data contains the qualitative food catalogue, evidence records, approved rule templates, and disabled reference-value layer. There is no runtime food API or nutrition-generating language model.
• Dexie/IndexedDB stores preferences, meals, recommendation feedback, day completion, and any future explicitly selected reference profile through explicit schema migrations.
• Zod validates domain records, database boundaries, and complete JSON imports/exports.
• Feature modules cover onboarding, Pair/meal building and history, recommendation cards, Week, and You/settings.
• Custom CSS variables, local SVG/CSS shapes, and accessible primitives create the ingredient-tandem visual system without a generic UI framework.
• Vitest, Testing Library, Playwright, and axe cover the domain, interaction, end-to-end, responsive, and accessibility boundaries.
• A static service worker and web manifest provide a small PWA shell without a backend.

The app follows this dependency direction:

React features → pure domain services → versioned local data
       │                  │
       └──── local repository / schema-validated import-export
                              │
                        Dexie / IndexedDB

See the product specification for the user journey, data model, recommendation pipeline, weekly gates, safety controls, and validation plan.

Evidence governance

Rules fail closed. A recommendation can appear only when its rule is active, uses supported evidence, has approved narrow copy, records an honest MVP evidence/content review and date, passes exclusions, and remains compatible with the user’s confirmed foods and preferences.

• A: explicit authoritative guidance or a strong applicable synthesis, followed by MVP content review.
• B: replicated human evidence with narrow wording, visible uncertainty, and MVP content review.
• C: preliminary, indirect, mechanistic, observational, or otherwise insufficient evidence; disabled by default.

Every recommendation exposes its type, action, meal trigger, concise mechanism, caveat, evidence strength and source, rule version, content-review date, compatibility, and feedback controls. It does not display a predicted absorption percentage. Missing, weakened, or unreviewed evidence moves a rule to needs-review or disabled; it does not trigger fallback health copy.

Full rule decisions, citations, activation gates, prohibited language, and review/change control are documented in docs/EVIDENCE_POLICY.md.

Initial source links include:

• NIH Office of Dietary Supplements: Vitamin C — Health Professional Fact Sheet
• NIH Office of Dietary Supplements: Iron — Health Professional Fact Sheet
• EASL–EASD–EASO MASLD clinical practice guideline — boundary-setting only, not an active v1 pairing source
• NICE NG49 NAFLD recommendations — boundary-setting only, not an active v1 pairing source

The included review is an internal MVP content review. It is not independent clinical review, clinical validation, regulatory approval, or evidence that the product improves health outcomes.

Food-data provenance and quantitative status

The bundled qualitative catalogue may provide canonical names, aliases, food groups, dietary/allergen metadata, and pairing tags. Those fields support recognition and rule matching; they are not nutrient measurements.

Quantitative weekly nutrition coverage is disabled. No official nutrient-data snapshot and no versioned reference-value dataset have been ingested into this MVP. Nutrient values remain null rather than fabricated or converted to zero, and synthetic numeric fixtures are permitted only in automated tests. The UI must show “Not enough complete data for a weekly nutrition estimate.”

The release gate stays closed until an official source is pinned, mapped, versioned, attributed, reviewed, and reconciled, and a separate cited reference-target dataset is ingested. The complete source-selection, licence, missing-value, ingestion, validation, and release process is in docs/DATA_PROVENANCE.md.

Candidate official sources:

• Preferred UK source after redistribution and record-level review: McCance and Widdowson’s CoFID
• Fallback or documented gap source: USDA FoodData Central API/licensing guide and downloadable releases

No food API is called by the browser and no API key belongs in browser code, source-generated catalogue files, or build output.

Even after the global data release gate opens, a week is eligible only with at least five explicitly complete days, recorded portions, at least 80% of logged food weight mapped to valid official nutrient data, and an explicitly selected compatible versioned reference profile. A future eligible result may compare logged intake with a general reference; it may not claim deficiency, infer absorption or disease, or recommend supplements.

Local-only privacy and security warning

Meal logs, preferences, and feedback remain in this browser profile’s IndexedDB. There is no account, backend, telemetry, third-party analytics, advertising, or automatic upload.

Browser storage is not encrypted against another person who can access this device or browser profile. JSON exports are also unencrypted and remain wherever the user saves or copies them. Use a trusted device/profile, protect exported files, and delete local data before sharing the device if that is a concern. Clearing browser/site data can permanently remove records; export first if a backup is wanted.

Security controls include:

• strict Zod schemas and explicit IndexedDB migrations;
• schema-versioned JSON export and complete import validation;
• .json file enforcement and a 2 MiB import limit;
• rejection of unsupported versions, unknown structures, malformed numbers, forbidden keys, excessive nesting, and script-bearing text;
• text rendering rather than raw HTML;
• no client secrets and no automatic runtime evidence/food requests;
• a restrictive Content Security Policy where the deployment supports it; and
• a one-tap permanent-delete action, protected by clear confirmation, for all local user data.

Opening a cited evidence link is a user-initiated visit to an external site and is outside the local app’s storage boundary.

Limitations

• General-wellbeing education for adults only; no medical, diagnostic, treatment, laboratory, medicine, supplement, pregnancy/child, or prescribed-diet support.
• The local catalogue is deliberately small. Unknown or ambiguous foods require user confirmation and may remain unsupported.
• A recognised food and an evidence-based mechanism do not establish what an individual absorbs or their nutrient status.
• Allergy filtering relies on reviewed catalogue metadata and stated preferences; it cannot determine cross-contact, recipe reformulation, or label accuracy. Users must check packaging and seek professional advice where needed.
• Pairing-only weekly summaries describe observed log events, not intake, adequacy, absorption, or deficiency.
• Quantitative coverage remains unavailable until official food nutrients and reference values pass the documented ingestion/review gates.
• Local data is tied to the browser profile and may be lost when site data is cleared, the profile is removed, or storage is evicted.
• Offline support applies only after the app shell has loaded and cached successfully; external evidence pages are not cached by the app.
• The working name is provisional and has not been cleared for public or commercial use.

Feature flags and condition-specific work

conditionRules.masld is hardcoded to false. It is an architectural placeholder only: v1 includes no MASLD rule pack, condition-mode interface, medical-input collection, disease inference, or treatment recommendation.

Turning it on would change the intended purpose and risk profile. Any future MASLD capability requires a separately versioned rule pack, specialist hepatology and dietetic review, documented clinical-risk management, independent usability and safety validation, privacy/data-protection review for any health data, and an appropriate regulatory assessment. It must not be enabled by configuration alone.

Clinical-review status

This application has not been clinically validated, independently clinically reviewed, medically approved, or assessed as suitable for condition management. Passing automated tests, accessibility checks, type checking, or a production build demonstrates engineering behaviour only.

Before public deployment, recommendation content and safety copy should receive documented independent review by an appropriately qualified registered dietitian or nutrition professional. Any condition-specific extension requires relevant specialist clinical review in addition to engineering, privacy, human-factors, and regulatory assessment.