Scan what's in your fridge, get recipes that actually use what's there, and never guess how many calories are in a serving.
FRIDGe is a two-service app — an Express/Postgres API and an Expo/React Native client — built around one constraint: an LLM is a reasoning engine, not a ground truth engine. Everything below is about the code that enforces that line.
The one rule that matters more than any other: the model must never invent an
ingredient the household doesn't have, or use more of one than actually exists. That
isn't a prompt instruction the model is asked to honor — every recipe it returns is
checked in code before it's ever persisted or shown to anyone, in
api/src/ai/validate.ts and
api/src/ai/suggestions.ts.
1. Structured output, not free-text parsing. OpenAI is called with
response_format: { type: "json_schema", strict: true } and a hand-written schema —
every field required, additionalProperties: false, unit constrained to a 3-value
enum. Recipes are never regex'd or free-text-parsed out of prose.
2. Every recipe is validated against real inventory before anyone sees it:
// api/src/ai/validate.ts
export function validateRecipe(
recipe: ParsedRecipe,
availability: Map<string, AvailabilityEntry>,
): Violation[] {
const violations: Violation[] = [];
for (const use of recipe.uses) {
const key = normalizeKey(use.name);
const avail = availability.get(key);
if (!avail) {
violations.push({
recipeTitle: recipe.title,
rule: "invented_ingredient",
message: `"${recipe.title}" uses "${use.name}", which is not in your inventory.`,
});
continue;
}
if (use.unit === "piece") {
if (use.quantity <= avail.pieces) continue;
const catalogMatch = findCatalogItemByName(use.name);
if (catalogMatch?.gramsPerPiece && use.quantity * catalogMatch.gramsPerPiece <= avail.grams) {
continue;
}
violations.push({
recipeTitle: recipe.title,
rule: "quantity_exceeded",
message: `"${recipe.title}" uses ${use.quantity} piece ${use.name}; you don't have that much available.`,
});
continue;
}
if (use.quantity <= avail.grams) continue;
const unitLabel = use.unit === "ml" ? "ml" : "g";
violations.push({
recipeTitle: recipe.title,
rule: "quantity_exceeded",
message: `You used ${use.quantity}${unitLabel} ${use.name}; only ${avail.grams}${unitLabel} is available.`,
});
}
return violations;
}Every ingredient name is matched against real inventory by a normalized key (crude
de-pluralization — tomatoes → tomato — deliberately not a real lemmatizer, since it
only needs to be internally consistent, never shown to a user). Quantities are checked in
a common grams-equivalent unit, converting piece → grams via a real per-ingredient
catalog (tomato → 100g/piece, onion → 150g/piece, etc.) — the model can say "3 piece
tomato," but the check happens in grams either way.
3. On a violation: retry once, quoting the exact violation back — never repair or guess:
// api/src/ai/suggestions.ts
if (violations.length > 0 && callCount < MAX_CALLS) {
const violationSummary = violations.map((v) => v.message).join(" ");
messages = [
...messages,
{ role: "assistant", content: JSON.stringify(parsed) },
{ role: "user", content: buildRetryPrompt(violationSummary) },
];
parsed = await callModel(messages);
callCount += 1;
const revalidated = validateAll(parsed.recipes, availability);
validRecipes = revalidated.validRecipes;
violations = revalidated.violations;
}4. If it's still wrong after the retry, the recipe is dropped — not fixed, not faked.
FRIDGe never edits a uses[] quantity to make it "fit," and never substitutes a real
ingredient name to paper over an invented one. A dropped recipe is simply absent from the
response. If all recipes get dropped, the API returns 422 NO_VALID_RECIPES and the app
shows an honest "couldn't find a reliable recipe" message with a retry button — never
fabricated content. Hard cap: at most 2 OpenAI calls per request, regardless of how
many recipes still have violations after the retry.
Full write-up of every rule, including the caching strategy and why zodResponseFormat
is deliberately not used (it silently mis-converts zod v4 schemas — verified, not
assumed), is in README-notes.md.
A calorie count from an LLM is a plausible-sounding number with no ground truth behind
it. FRIDGe never asks the model for one. Instead, caloriesLow/caloriesHigh are
computed server-side from the same canonical data the validation layer already
trusts — the ingredient catalog's kcalPer100g and gramsPerPiece — in
api/src/lib/calories.ts:
const OIL_ALLOWANCE_KCAL_PER_SERVING = 80;
export function computeCalorieRange(uses: CalorieUseInput[], servings: number): CalorieRange {
let totalKcal = 0;
for (const use of uses) {
const catalogMatch = findCatalogItemByName(use.name);
if (!catalogMatch) continue; // no reliable source — skip rather than guess
let grams: number;
if (use.unit === "piece") {
if (!catalogMatch.gramsPerPiece) continue;
grams = use.quantity * catalogMatch.gramsPerPiece;
} else {
grams = use.quantity;
}
totalKcal += (grams / 100) * catalogMatch.kcalPer100g;
}
const safeServings = servings > 0 ? servings : 1;
const perServing = totalKcal / safeServings + OIL_ALLOWANCE_KCAL_PER_SERVING;
return {
low: roundDownTo25(perServing * 0.85), // floor to nearest 25
high: roundUpTo25(perServing * 1.15), // ceil to nearest 25
};
}An ingredient with no catalog match is skipped, not estimated — silently omitting a
minor ingredient's calories is preferable to inventing a number for it. A flat 80
kcal/serving allowance is added for cooking oil, which is never tracked as its own
inventory item; the app surfaces that exact assumption in an (i) tooltip next to the
pill, rather than burying it. The result is always shown as a range —
~350–450 cal/serving — never a single precise-looking number, because that precision
would be false: two different numbers computed the same honest way (0.85x/1.15x of the
same estimate) are the truth here, not one number pretending to be exact.
Two independent services, deliberately not an npm workspace/monorepo:
flowchart LR
subgraph client["app/ — Expo Router + TypeScript"]
UI["Kitchen, Scan, Cook,<br/>Recipe detail, Cook Mode"]
Store["zustand stores"]
UI --> Store
end
subgraph server["api/ — Express + TypeScript"]
Routes["/auth /items /catalog<br/>/scan /suggestions /recipes"]
Validate["ai/validate.ts<br/>the hallucination guard"]
Calories["lib/calories.ts<br/>computed calorie ranges"]
Deduct["lib/deduct.ts<br/>transactional inventory deduction"]
Routes --> Validate
Routes --> Calories
Routes --> Deduct
end
DB[("Postgres (Neon)")]
AI["OpenAI<br/>vision + chat, JSON Schema"]
Store <-->|"Bearer JWT, JSON"| Routes
Routes <-->|Prisma| DB
Validate -->|structured output| AI
Routes -.->|"resized JPEG in, JSON out"| AI
Why not a monorepo: an earlier attempt at this project used npm workspaces, and npm
hoisted react/expo-router out of app/'s own node_modules, which broke the Expo
CLI in ways that took a full session to diagnose. api/ and app/ now each have their
own package.json and their own node_modules, installed independently — no root
package.json, no workspaces field, no shared node_modules. The cost is some
duplicated code (formatQuantity, normalizeKey-style helpers exist in both places) —
a deliberate trade against a class of bug that already cost real time once. This is
documented as a hard rule in CLAUDE.md.
Why the OpenAI key only ever lives in api/: the client never talks to OpenAI
directly — every AI call (recipe suggestions, photo scanning) is a request to api/,
which holds the only copy of the key. There is no EXPO_PUBLIC_* variable for it and
nothing in app/ ever references it, so it can never end up bundled into a client build.
Stack:
| api/ | app/ | |
|---|---|---|
| Language | TypeScript (Node, CommonJS) | TypeScript (React Native) |
| Framework | Express 4 | Expo SDK 54, Expo Router 6 |
| Data | Prisma 7 + @prisma/adapter-pg, Postgres (Neon) |
zustand, expo-secure-store for the JWT |
| AI | OpenAI SDK v4, hand-written JSON Schema | — (never talks to OpenAI directly) |
| Validation | zod v4 | zod v4 (request shaping only) |
| Auth | JWT (jsonwebtoken) + bcryptjs |
Bearer token attached by a single apiFetch() |
| Native features | — | camera/library (expo-image-picker), haptics, keep-awake, audio |
You need: Node 20+, a Postgres database (this project uses Neon's free tier), an OpenAI API key with billing enabled (the free trial credit alone won't get you past the first real request), and either Expo Go on a phone or an iOS/Android simulator.
cd api
npm install
cp .env.example .envFill in .env:
DATABASE_URL="postgresql://USER:PASSWORD@HOST/DATABASE?sslmode=require" # Neon's DIRECT connection string, not "-pooler"
JWT_SECRET="any long random string"
OPENAI_API_KEY="sk-..."
OPENAI_MODEL="gpt-4o-mini"
PORT=4000npx prisma generate
npx prisma migrate deploy # or `migrate dev` if this is a fresh database
npm run devYou should see API listening on 0.0.0.0:4000 and a LAN: URL printed — that LAN URL is
what the app needs next, since a physical phone/simulator can't reach localhost on your
Mac.
cd app
npm install
cp .env.example .envSet EXPO_PUBLIC_API_URL in app/.env to the LAN URL the API printed (find it again
anytime with ipconfig getifaddr en0 on macOS). This drifts whenever your machine
changes networks — re-set it and restart expo start after editing, since
EXPO_PUBLIC_* variables are inlined into the bundle at build/start time, not read at
runtime.
npx expo startPress i for the iOS simulator, a for Android, or scan the QR code with Expo Go on a
physical phone on the same wifi network as your Mac.
- Register an account in the app (this creates a
User+Householdrow). - Add a few items on Kitchen, or use Scan to photograph some food.
- Cook tab → generates 3 suggestions from your real inventory (this is the OpenAI call — if it fails with a billing error, that's your OpenAI account, not the app).
- Open a recipe → Start Cooking → step through → Done cooking → confirm — check that Kitchen's quantities actually went down.
- Deployment — this runs locally only right now (a local Express process + Expo dev server). No hosting target, EAS project, or production build config exists yet.
- Web (Expo's
weboutput target exists in config but is untested).
See STATE.md for the full phase-by-phase build log, including exactly
what's verified against a live database vs. what's structurally complete but untested.