Use cases & flows

01 · Business model & value

emealia is an AI nutrition companion sold as a mobile-first PWA (no App Store) in Germany (primary) and the USA (simultaneous), all copy in EN + DE, GDPR-first. The base product is one version, one price per market — a free trial converting to a single paid subscription. There is no freemium tier and the core loop is never gated.

Pricing (Stripe price ids resolved server-side per market/interval via BillingCatalogs — never hardcoded in the frontend; no GET /config/prices endpoint exists, contrary to earlier drafts of this doc)

Annual is the checkout default with a secondary monthly toggle. Price is constant (founder decision 2026-07-03): one price per market, no retention/win-back discount, no lower price on the cancel screen. Trial-CTA subline is always "All features, one plan, forever."

Trial mechanics (corrected 2026-07-07 — supersedes the 168h clock model)

The trial is credit-based, not time-based: usage_accounts.trial_credits_granted defaults to 30 (admin-configurable, admin.toml [usage] trial_credits), decremented one-per-AI-estimate in trial_credits_used. Enforcement lives in the LogMeal use case via UsageMeter.check_entitlement()/check_and_reserve() before any AI call → EntitlementError → HTTP 402 once credits are exhausted and no subscription is active. Read access (history, stats, profile) stays open after exhaustion; only new AI estimation is blocked. A per-user daily cap (20/day) and a global daily cost cap (13,333/day) apply on top, both admin-configurable. Note: the boundary docstring (UsageMeter) and the CLAUDE.md root context still describe the earlier 168-hour clock-based trial (trial_started_at + 168h) — that model is superseded and not what the shipped SqlAlchemyUsageMeter implements; treat the credit model above as authoritative.

02 · The 6 non-negotiables

Every use case, flow and PR is checked against these. They are the product, not preferences.

03 · Actors & personas

Voice

A warm companion in du-form (German). Never judges, always forward-looking; honest about estimates ("roughly 550–650, close enough to place it", not "612 kcal"). The companion voice is set in Newsreader italic; ordinary UI labels stay in Hanken Grotesk.

04 · Use-case map

Who acts, what emealia does for them, and the external systems reached only through boundaries. The SDK/driver for each system lives solely inside its integration module — swapping a provider is a one-line change in wiring.py.

05 · Use-case catalog

The canonical list. Each row links a business goal to its primary actor, trigger, and the endpoints that serve it. Detailed flows follow in §06–§15.

06 · Core loop — log a meal UC-03 · UC-04

The signature interaction and the only primary input. It is async from day 1: the estimator never blocks the HTTP response. The contract is stable across the phase-1 in-process worker and the phase-2 SQS + Lambda worker — the frontend is never touched by that swap.

Main success flow

1. Free text in. The user types one sentence ("a big bowl of lentil soup and two slices of toast") and picks a meal_type (never AI-derived; defaults to other). POST /meals {text, meal_type, locale, log_date?}.
2. Pre-flight checks. LogMeal verifies body-health consent, validates the backdate window (≤7 days, no future), and calls UsageMeter.check_entitlement() — the trial/subscription gate.
3. Memory shortcut? If the text matches a confirmed dish (≥3 prior confirmations), the draft is created complete from memory: no AI call, no reservation, response {status:"completed", reused:true} — the client skips polling.
4. Reserve & queue. Otherwise check_and_reserve() meters one AI call, a draft meal + an ai_jobs row are written, and the API returns 202 {meal_id, status:"processing"} immediately.
5. Worker estimates. A background task (phase 1) or SQS worker (phase 2) claims the job and calls the AiEstimator boundary. See §07 for the full AI pipeline. Provider latency/failure becomes retry state, never user-facing red.
6. Poll the draft. The client polls GET /meals/{id}/draft until completed, failed, or needs_user_confirmation. The pre-save "meal log detail" screen shows the estimate with an explicit "nothing saved yet".
7. Save. POST /meals/{id}/save {meal_type} flips draft → logged, rebuilds daily_summaries, and records the confirmed dish for reuse. Only now does the meal count toward the day and appear in History.

States & alternates

• Offline. A meal logged offline queues locally and auto-commits to logged on reconnect (§15).
• Backdating. Any day within the last 7 (inclusive) is allowed; future dates are rejected by validate_log_date.
• Re-estimate cap. One re-estimate per meal in beta; reestimate_count is returned so the button disables (§09).
• No entitlement. Expired trial without subscription → EntitlementError → HTTP 402; reads stay open.

07 · AI communication the estimator seam

The product promise depends on free text staying natural and estimates staying honest. The AI estimates; the application validates, maps, formats and interprets. The meal text is always data, never instructions. Prompts are versioned data (a snippet library), not hardcoded strings — changing a prompt means editing a data file and bumping its version.

1 · Prompt assembly (versioned data)

The system prompt is composed per call from a snippet library, with constants (allowed units, portion descriptors, title/tag caps) injected at build time:

build_parse_meal_prompt(locale)  →  parse_meal.md
                                  +  voice_tone.{en|de}.md
                                  +  title_tag.{en|de}.md
                                  +  user_context.md
prompt_version = "meal-estimate-v1"

The user message carries prompt_version, locale, and the HTML-stripped, length-capped meal text inside an <meal_input>…</meal_input> wrapper the model is instructed to treat as data — the injection-defense seam.

2 · Forced tool use

Estimation is a single Anthropic Tool Use call through the AiEstimator boundary: temperature=0, max_tokens=1200, tool_choice pinned to the meal_estimate tool, and the SDK's own retries disabled (max_retries=0) because retries are our concern, not the transport's. The tool schema constrains the JSON:

3 · Validation layer 1 — structure & cosmetics

In ai_estimate_mapping.py, two field classes get two policies:

• Cosmetic (title, tag): wrong type or over cap → set to None, record a PII-free Violation, keep the meal. A retry would buy only a nicer label, so it is dropped, never re-sent. Violations are logged and counted for alerting.
• Amounts: portion and ingredient amounts are enum-constrained Amount objects at the schema level, so the model can't hand back a free-text unit; an amount the schema can't fit downgrades confidence_level to low rather than guessing.
• Nutrition / required: a Pydantic failure raises MealEstimateStructureError → the model is re-asked once, fed a compact reason derived from its own output (never the user's text).

4 · Validation layer 2 — meaning

The parsed estimate passes through validate_meal_plausibility and enforce_assumption_language — assumptions must read as natural German for de* and natural English for en*, regardless of the meal's input language. A language failure also triggers the single retry.

5 · Outcome

08 · Daily view & bands UC-07 · UC-08

The signature surface. A band gives a feel for the day, not a sum. Color says which nutrient, never good/bad; status is carried by the text label only. No numbers on Today (non-negotiable #2); numbers live one tap away in All-details.

How a band is computed

1. Aggregate. aggregate_daily_meals sums logged meals for the day. Drafts are excluded; pending / low-confidence meals contribute zero to the ranges and instead increment a calm "still estimating" count (non-negotiable #6).
2. Combine honestly. Per nutrient, midpoints sum linearly and half-width uncertainties combine as σ = √Σ(halfwidth²) (root-sum-square) — not naive addition.
3. Persist. The result is upserted into daily_summaries on every save and compared to the persisted user_targets ideal zone [min, max] (DGE/USDA reference; §10).
4. Measure geometry. BandFacts reduces the band to objective booleans: no_data, end_below_zone, start_above_line, after_pivot (before/after 15:00).
5. Classify. classify_band_state runs a versioned, ordered rule table (first match wins) over those facts and returns an opaque state key. The evaluator knows the rule shape, never what a key means.
6. Render. The key maps to localized copy in the frontend. Retuning a threshold or relabeling a state is a data edit — the classifier code never changes.

Band states

Category colors (which nutrient, not good/bad)

Default 5 bands (energy, protein, carbs, fat, fiber); the user can add up to 10 from the full nutrient/vitamin/mineral set — this is how non-weight goals (e.g. "watch iron") become visible, without new schema. The range boundary marker is drawn above the fill (z-index) so the ideal zone is never occluded when an estimate overshoots.

Day level (derived, never stored, never red)

A pure function of the day's energy-band position, used only for History calendar dots and statistics distribution — never as a fill-color judgment.

09 · Meal detail & refine UC-04 · UC-05

The glass box. A logged or draft meal shows exactly what the estimate depends on so the user can trust or adjust it. Bands describe a day; numbers describe a meal — the meal detail may show honest ranges, but never a day-budget band.

• Ingredients & assumptions are one concept. Top 5 / dominating assumptions are shown; the rest sit behind "all assumptions".
• Portion size comes from the user's own wording when present; otherwise the estimator assumes a natural single serving and records it as an assumption (never guessing small/medium/large).
• Refine / re-estimate (POST /meals/{id}/reestimate) replaces a draft's estimate once, spending one metered AI call and passing an expected_version for optimistic concurrency. reestimate_count disables the button after the single beta re-estimate.
• Read path GET /meals/{id} (logged) and GET /meals/{id}/draft (pre-save). The frontend ?demo=1 route uses fixture data for band-comprehension testing without any backend.

10 · Onboarding & monetization UC-01 · UC-02 · UC-13

Value before registration, then a low-friction path to goals, targets, a 30-estimate credit-based trial, and one paid plan.

Goals are a plain list, not flags

The profile carries goals: list[Goal] (+ optional free text). The canonical set: understand eating habits · improve nutrient intake · healthier lifestyle · more energy · build muscle · lose weight · gain weight · watch specific nutrients · medically motivated. No "maintain weight" (implicit when neither lose nor gain is chosen); lose × gain is the only mutual exclusion. The internal goal_focus / goal_energy_direction flags were explicitly rejected — no unnecessary backend complexity.

Targets are persisted, never computed on the fly

BuildTargets (pure) runs on every profile change: Mifflin-St Jeor TDEE, a selected-goals energy band (lose→deficit, gain→surplus, else maintenance), missing body params substituted from versioned regional averages, and activity from a movement×sport PAL grid (two onboarding radios). It upserts user_targets; the frontend renders ideal-zone bars only from the stored numbers.

Pre-signup demo

Hardcoded data, animated logo loader, pre-computed bands + one hardcoded tip. Zero AI call, zero cost, zero abuse surface. Demo data is a signed local session, purged after 30 days of inactivity, and is not migrated into a real account.

11 · History, favourites & memory UC-06 · UC-10

Meal history context & 0-AI reuse

Every confirmed dish is stored in the user's own words (meal_memory). A keyword match surfaces "From history" chips on the add-meal screen (GET /meals/suggestions). At ≥3 confirmations the dish re-logs instantly with zero AI cost — the draft lands complete and the client skips polling. Bounded recent history may inform coaching, but the product never promises the AI "learns over time".

12 · Coaching & suggestions UC-11

Bounded, consented, forward-looking. Silence is the default — emealia never sends "you haven't logged in X days" messages. Coaching sends only selected goals, cooking level, nutrition-knowledge level, preferences/free-text context, visible/starred band states, and bounded logged-meal history. Calls are schema-validated, idempotent, metered and capped.

Delivery piggybacks on natural app opens. The voice is the Newsreader-italic companion: observe, don't judge; always one small step that builds on what the user already does.

13 · Trial & payments UC-13

• Trial is emealia-side, not Stripe-side: enforced by UsageMeter against usage_accounts.trial_credits_granted/used (credit-based, default 30, admin-configurable) — not the clock-based trial_started_at + 168h model described elsewhere in older docs.
• Entitlement gate. check_entitlement() runs in LogMeal before any AI call. Expiry without a subscription → EntitlementError → HTTP 402. A separate per-user AI rate cap (check_and_reserve) protects cost.
• Subscription states (SubscriptionStatus): trialing · active · past_due · canceled. Payments own the transitions; the meter only interprets whether the next estimate is covered.
• Stripe handles paid subscriptions only (test → live), with tax and webhooks. One constant price per market from GET /config/prices. Soft paywall: reads stay open, only new logging is gated.
• Abuse prevention. ≤3 new trial/anonymous-session starts per IP per 24 h. Device fingerprinting is explicitly not used — trial-abuse cost (~€0.04) is far below its implementation cost.

14 · Statistics & reviews UC-12

Period summaries and a range-capable statistics chart — the honest ranges carry through to trends, so a period never collapses to a single fake-precise number. Distribution uses the derived day level, never red. The frontend statistics screen is currently a placeholder over recent backend groundwork.

15 · PWA & offline UC-14

Mobile-first PWA, no App Store. Installable via a hardened web app manifest (story 12.1), a service worker, an offline meal queue, and a performance budget. A meal logged offline queues locally and auto-commits to logged on reconnect — no error wall, ever.

16 · Compliance & quality (cross-cutting) launch blockers

17 · Endpoint reference

The current API surface (backend app/api/). Meal logging is async from day 1; the frontend consumes a typed client generated from the backend OpenAPI export.

18 · Data model reference

Macros and micros are stored as individual columns (not JSONB) with CHECK constraints, so statistics can aggregate any nutrient. One storage tier, columns only. daily_summaries is pre-computed. Meals follow a draft → logged lifecycle.

19 · Feature status matrix

Current implementation state (July 2026). See the developer onboarding for the live mock/real map and the app repo's implementation-plan/ for story-level acceptance criteria.