FitGenie calorie tracker build plan

Goal

Build a trustworthy, low-friction calorie and nutrient tracker whose logging experience improves as the user builds history. The first release prioritizes nutrition accuracy, repeat logging, home-cooked food, honest uncertainty, and reliable synchronization over unrelated fitness breadth.

“Perfect” is treated as a measurable quality target, not an assertion that food estimation can be exact. Packaged-food values can be precise to their labels; home-cooked, voice, and photo logs must communicate uncertainty and remain easy to correct.

Authoritative tracker design

• Calorie tracker data model
• Calorie tracker user experience
• Free-text meal parsing
• docs/strategy.html remains broader product context and data-source guidance.

Changes to tracker behavior must update the relevant design document before implementation when they affect stored data, permissions, nutrition calculations, or a primary user flow.

Product outcomes

The tracker succeeds when users can:

1. Set a safe, understandable calorie and macro target.
2. Find and log packaged or whole food quickly.
3. Repeat a previous meal while changing only today’s quantities.
4. Save and reuse meals, foods, and household recipes.
5. Log home-cooked portions in familiar units such as katori and roti.
6. Use voice, text, or photos as editable assistance rather than automatic truth.
7. Understand daily and monthly trends without missing data being interpreted as zero intake.
8. Trust that edits to the food catalog will not rewrite historical totals.

Scope priority

Required for polished tracker beta

• Authentication, onboarding, profile, units, goals, and effective-dated targets.
• Food search, aliases, serving selection, barcode lookup, and manual food creation.
• Today screen, meal slots, calorie/macro totals, editing, deletion with undo, and history.
• Recent/most-used foods, repeat meal, saved meals, and favorites.
• Household recipes, ingredient/yield calculation, common portions, and estimate ranges.
• Deterministic free-text parsing into an editable draft, with trusted nutrition calculation.
• Goal-free tracking and neutral home/dashboard states.
• Offline-safe writes, idempotent retries, RLS, account export/deletion, and observability.

Beta candidates after the required flows meet quality gates

• Enhanced AI parsing for complex or mixed-language descriptions.
• Voice transcription into the same editable text draft.
• Photo meal estimation.
• Meal-pattern suggestions and carefully limited notifications.
• Monthly goal-aware insights.

Outside this tracker release

• Exercise library and workout coaching.
• General-purpose AI coach and diet planner.
• Creator marketplace, commerce, and social feeds.

Those features can consume tracker data later but must not delay or weaken core logging.

Architecture

Flutter client

Flutter owns presentation, local form state, a small offline queue, cached recent/saved items, and user-controlled correction flows. It uses the Supabase client for authentication and access permitted by RLS.

The client never contains service-role credentials or provider secrets. External responses and local input are validated before entering domain state.

Supabase

Supabase provides:

• Postgres and migrations.
• Authentication.
• RLS-protected user data.
• Read-only public nutrition catalog access.
• Private media buckets with signed URLs.
• Atomic RPCs for confirming drafts, repeating meals, logging templates, and publishing recipes.

Canonical catalog tables are never client-writable. Development, staging, and production use separate projects and migration histories.

Node service

A thin Node service provides operations that require secrets, provider calls, or protected computation:

• Nutrition-source imports and reconciliation jobs.
• Recipe yield and retention calculation orchestration.
• Deterministic free-text parsing plus optional provider-neutral enhanced parsing.
• Voice transcription into the same structured recipe/meal draft.
• Photo-food model calls.
• Common-dish matching where database search is insufficient.
• Push scheduling and derived pattern jobs if those beta candidates ship.

LLM reasoning is isolated to the recipe/meal parsing boundary and receives structured user state, not raw chat history. NLP identifies foods and portions; versioned nutrition data performs calorie calculations. Provider output becomes a validated draft and never directly creates a confirmed log. The standard parser and enhanced AI parser implement the same contract, so AI can be disabled or replaced without changing Flutter or confirmed logs.

Data sources

Start with USDA FoodData Central, Open Food Facts, NIN tables, and in-house household presets. Every imported row records source and release metadata. Validate licensing, redistribution, attribution, update cadence, nutrient units, and actual prepared-dish coverage before production ingestion.

Paid data sources are considered only after measured search/barcode gaps show that free sources are insufficient.

Decisions required before implementation

1. Initial launch country and catalog coverage.
2. Initial languages, transliteration needs, and unit defaults.
3. Exact beta cutoff: required flows only or selected AI candidates.
4. Supabase organization, region, environments, and billing owner.
5. Apple team, bundle identifier, and authentication methods.
6. Nutrition-target formula, safety limits, and disclaimer language.
7. Media/transcript retention and account-deletion policy.
8. AI provider budget and per-user usage limits if assisted logging ships.
9. Whether a nutrition professional will review calculation fixtures and user-facing guidance.

These decisions affect schema, permissions, ingestion, and UX; they are not end-of-project polish.

Delivery sequence

Durations are planning ranges for a focused team, not commitments before stories are estimated.

Phase 0 — Decisions, contracts, and environments

Target: Week 1

• Resolve the implementation decisions listed above.
• Create development and staging Supabase projects.
• Scaffold Flutter and Node projects with environment validation.
• Establish migrations, generated database types, CI, secret scanning, and error reporting.
• Convert the data-model document into an initial migration plan.
• Define analytics events without collecting unnecessary raw meal content.
• Write the RLS policy matrix and first cross-user denial tests.

Exit criteria: environments are reproducible; migrations run from zero; CI rejects formatting, analysis, test, and migration failures; no privileged secret can enter the client build.

Phase 1 — Catalog foundation and thin vertical slice

Target: Weeks 1–3

• Implement profiles, goals, effective-dated targets, nutrient dictionary, catalog versions, servings, logs, and nutrient snapshots.
• Ingest a small, licensed fixture catalog before attempting full source imports.
• Build one end-to-end flow: sign in → set units/target → search fixture food → select serving → confirm → see Today total.
• Add immutable-history, unit-conversion, timezone, idempotency, and RLS tests alongside implementation.
• Measure search and logging latency from the first vertical slice.

Exit criteria: a confirmed log survives catalog version changes; retries cannot duplicate it; another user cannot read it; totals match fixtures.

Phase 2 — Reliable manual tracker

Target: Weeks 3–6

• Production ingestion for approved USDA/Open Food Facts/NIN subsets.
• Search ranking, aliases, source quality, barcode lookup, and country-aware products.
• Today screen, meal sections, quantity editor, editing, undo deletion, history, and target comparison.
• Manual food creation and nutrition-label entry.
• Cached recent items and safe offline write queue.
• Empty, loading, permission, network, and provider failure states.
• Accessibility coverage for onboarding, search, quantity editing, and Today.

Exit criteria: manual search and barcode paths meet acceptance criteria; offline retry is idempotent; catalog provenance is visible; core flows work with screen readers and dynamic type.

Phase 3 — Reuse and home-cooked food

Target: Weeks 5–8

• Recent and most-used ranking.
• Repeat meal with per-item quantity changes.
• Saved meals and favorites.
• Household recipe creation, ingredient composition, cooked yield, katori/roti servings, and confidence ranges.
• Common-dish fallback after household items.
• Fixture-based recipe, retention, serving-range, and copy-meal tests.
• Nutrition professional review before retention/yield estimates are presented as production-ready.

Exit criteria: users can log a repeated meal materially faster than rebuilding it; original meals remain unchanged; estimated totals expose their ranges and assumptions.

Phase 4 — Assisted logging candidates

Target: Weeks 7–10; include only if core tracker gates remain green

• Rules-first free-text parsing into editable draft items.
• Optional enhanced parser selected by server entitlement/feature flags with deterministic fallback.
• Voice transcription into the same draft contract.
• Photo upload, processing, candidate matching, and editable draft items.
• Private signed media access, expiration, deletion, rate limits, and provider cost controls.
• Evaluation datasets covering launch foods, languages, portion descriptions, and mixed dishes.
• Explicit uncertainty and recovery when providers fail.

Exit criteria: no provider can directly confirm a log; correction and fallback are always available; accuracy, correction rate, latency, and cost are measured by input type.

Phase 5 — Personalization candidates

Target: Weeks 9–12; driven by real usage data

• Day-of-week and meal-slot patterns from confirmed logs.
• Goal-free observational dashboards that distinguish missing data from zero intake.
• Opt-in target suggestions only after sufficient confirmed history.
• Previous-meal suggestions with Log, Review, and Not Today actions.
• Notification permission in context, quiet hours, caps, and dismissal learning.
• Monthly trends that distinguish missing logs from zero intake.
• Explainable, non-medical goal-aware insights.

Exit criteria: suggestions have a minimum evidence threshold, never auto-log, stop after repeated dismissal, and can be disabled independently.

Phase 6 — Public beta hardening

Target: two focused weeks after selected scope is feature-complete

• Full regression, migration, restore, RLS, accessibility, device, timezone, and poor-network testing.
• Performance and catalog-search profiling.
• Privacy policy, terms/disclaimers, account export/deletion, camera/microphone usage copy, and App Store privacy answers.
• TestFlight rollout, support workflow, incident runbook, dashboards, and rollback plan.
• Fix observed beta blockers before adding features.

Exit criteria: all UX release gates pass; crash-free and duplicate-log targets are met; support can diagnose failures without accessing unnecessary private meal content.

Testing strategy

Testing is part of every phase rather than a final activity.

• Database: migrations from zero, constraints, transactions, RLS allow/deny matrix, and query plans.
• Nutrition logic: source normalization, unit conversion, serving scaling, recipe yield, retention ranges, and macro aggregation fixtures.
• Flutter: state and business logic tests, widget tests for stable core flows, golden tests where visual regression matters, and end-to-end critical paths.
• Node: boundary validation, provider adapters, retry/idempotency behavior, structured-output contracts, and timeout/failure handling.
• AI evaluation: representative fixed datasets, match/correction metrics, language slices, latency, and cost. Snapshotting a prompt is not an accuracy test.
• Security/privacy: cross-user access denial, signed URL expiration, log redaction, deletion, export, and secret scanning.

Quality measures

Set numerical targets after the first instrumented vertical slice establishes a baseline. At minimum, track:

• Time to first confirmed log.
• Time to repeat a prior meal.
• Search success and reformulation rate.
• Barcode coverage by launch market.
• Draft correction and confirmation rates.
• Duplicate and failed-sync rate.
• Percentage of logs using recent/repeat/saved flows over time.
• Day-7 and day-30 logging retention.
• Notification dismissal/disable rate.
• Crash-free sessions and accessible-flow completion.

A speed metric is never considered successful if it increases accidental, duplicate, or unreviewed logs.

Timeline interpretation

A focused four-person team may reach a private beta of the required manual, repeat, saved-meal, and home-cooked flows in roughly 10–14 weeks if design decisions and data licensing are resolved promptly. A two-person team should plan a longer range and reduce parallel work.

Voice, photo, personalization, broad localization, and production catalog depth are scope multipliers. They enter the same beta only when core quality gates remain green; otherwise they follow in measured releases. The timeline must be re-estimated from implementation stories before an external launch date is announced.

Input needed from the product owner

Definition of done

A feature is done only when its schema/migration, validation, RLS, errors, loading/empty states, accessibility, analytics, tests, documentation, and rollback behavior are complete. A screen connected to a happy-path API is not done.