Hungry — Mobile Frontend

Hungry is a dish-first food discovery app for Singapore hawker centres and food courts. Built with Expo + React Native. Mock-first for local demos, with Supabase-backed integrations staged behind release gates.

---

Quick Reference

Need	Go to
Start here (agents)	AGENTS.md
Workflow rules	CLAUDE.md
Operating model	WORKFLOW.md
Low-token defaults	ops/low-token-cheatsheet.md
Active backlog	tasks/backlog.md
Verification evidence	tasks/verification.md
Session history	tasks/session-log.md
Tech stack + commands	tasks/environment.md
Design tokens + components	tasks/design-system.md
Screen inventory + navigation	tasks/screens.md
Domain types + mock data	tasks/data-contracts.md
Testing + feedback loops	tasks/test-harness.md
Accessibility source guide	docs/accessibility-style-guide.md
Product requirements (summarised)	tasks/product-context.md
Marketing launch kit	marketing/
Historical roadmap + audit trail	tasks/todo.md
Past lessons	tasks/lessons.md
Product requirements	Research/01_Product_Requirements_Document_Hungry.docx
App flow spec	Research/02_App_Flow_Document_Hungry.docx
Frontend guidelines	Research/03_Frontend_Guidelines_Hungry.docx
UI prototypes	design/figma-v2/ and design/stitch/

---

What This App Is

Key	Value
Product	Hungry — dish-first food discovery
Market	Singapore (hawker centres, food courts, restaurants)
Platform	iOS + Android (Expo SDK 55 / React Native 0.83.6)
Phase	Consumer mobile app, mock-first locally with Supabase-backed MVP integrations
Production posture	MVP production defaults keep DMs, comments, stories, collections, gamification, merchant centre, merchant claim CTA, prototype routes, and floorplans disabled until separate launch gates pass
Still production-disabled	OAuth providers, merchant centre, merchant claim CTA, direct messages, comments, stories, collections, gamification/passport, prototype routes, and indoor floorplans
Core idea	Find the dish you want, then see which stall serves it — not the other way around
Taste model	6-axis vector: sweet · spicy · sour · salty · rich · aromatic

---

Stack

Layer	Choice
Framework	Expo SDK 55 + React Native 0.83.6
Language	TypeScript (strict mode)
Navigation	React Navigation v7
State	Zustand
Forms	React Hook Form
Animation	Reanimated 3
Sheets	@gorhom/bottom-sheet
Map	@rnmapbox/maps (mock surface available)
Icons	lucide-react-native
Fonts	Nunito + DM Mono

---

Commands

Command	Purpose
npm install	Install deps
npm run typecheck	TypeScript check — primary gate
npm run start	Expo dev server
npm run ios	iOS simulator
npm run android	Android emulator
npx expo-doctor	Dependency health
npm run test	TSX/Node test suite
npm run data:supabase:stage:canonical	Generate staging-only SQL for the canonical Singapore food-business CSV
npm run data:supabase:stage:canonical:split	Generate chunked staging SQL files for linked Supabase imports

---

Feature Flags

The application uses feature flags to toggle functionality for development and release branches. These are configured in src/constants/featureFlags.ts.

Flag	Description	Default
HUNGRY_DATA_SOURCE	Toggle between mock and supabase data layers.	mock
FEATURE_FLAGS.directMessagesEnabled	Enable the Direct Messages tab and chat functionality.	true outside production, false in production
FEATURE_FLAGS.prototypeRoutesEnabled	Register V2/prototype routes outside production release builds.	true in development/staging, false in production
FEATURE_FLAGS.merchantCentreEnabled	Register merchant centre beta routes behind auth, role, and verification guards.	true outside production, false in production
FEATURE_FLAGS.merchantClaimCtaEnabled	Enable the consumer stall claim CTA.	true outside production, false in production
FEATURE_FLAGS.commentsEnabled	Enable community comments on posts and reviews.	true outside production, false in production
FEATURE_FLAGS.oauthProvidersEnabled	Enable Google/Apple OAuth provider buttons.	true in development/staging, false in production
FEATURE_FLAGS.floorplansEnabled	Register indoor floorplan routes and entry points.	false in all environments until launch gates pass
FEATURE_FLAGS.gamificationEnabled	Enable Passport and Missions surfaces.	true outside production, false in production
FEATURE_FLAGS.collectionsEnabled	Enable collection list/detail routes.	true outside production, false in production
FEATURE_FLAGS.storiesEnabled	Enable story viewer and story creation surfaces.	true outside production, false in production
FEATURE_FLAGS.craveEnabled

To override these locally, you can use .env.development or modify the constants directly during prototyping.

---

Project Status

Stitch screen iteration (23 October 2026): eight Search, Profile, Achievements, Settings, Reviews, Saved Dishes, Stall, and Dish design exports are saved in design/stitch/iterations-11940609752387078506/. The corresponding React Native screens are updated on codex/stitch-eight-screens; focused contracts pass 30/30. PR CI and native visual acceptance remain pending.

Area	Status
Expo scaffold	Done
Domain types + stores	Done
Mock repositories	Done
Navigation shell	Done
Home, Discover, Maps, Search	Done
Auth, Onboarding	Done
Developer launcher (dev-only)	Done
Profile, Favourites, Review History	Done
Review flow	Done
Reads (feature-flagged)	Done
Offline + NotFound states	Done
Marketing launch kit	Done
Excel Ingestion & ETL Migration	Done — reconciled workbook and rights-safe runtime catalog published
Singapore F&B source refresh	In progress — 38,584-record public-access Excel; 294 catalogue-linked websites reviewed with 507 menu and 2,682 image URL candidates in separate review-only tabs. 11 operator snapshots contribute 246 exact outlet joins, 461 brand menu items, and 553 operator/exact-venue image candidates. OSM contributes 132 strict plus 694 labelled tier-2 joins. Fresh outlet-level menus, ratings, image rights, and closure verification remain incomplete.
Typecheck	Passing
Expo Doctor	Passing (18/18)
Agent harness docs	Done
Unit tests	Passing (npm test)
Playwright E2E	Passing when run with localhost access; Codex sandbox TCP bind needs elevated/local shell

---

Notes

• Default LLM operating mode for this repo is low-token mode: use bounded task IDs or files, canonical docs first, and delta-only output unless a broad summary is explicitly requested.
• Mock data lives exclusively in src/lib/services/mock/data.ts
• Design tokens live exclusively in src/theme/tokens.ts — never hardcode values
• The app runs fully without network or backend
• Cold-start signed-out users land on Login. Public discovery/detail routes remain unprotected for explicit public links or dev flows.
• Protected actions route to auth and keep a return route: create post, review, save/favourite, messages/chat, profile-private pages, merchant tools, claim/order/cart
• V2/prototype routes are registered only when FEATURE_FLAGS.prototypeRoutesEnabled is true; production builds keep unfinished prototype/design routes off the root navigator
• MerchantTabs is registered only when FEATURE_FLAGS.merchantCentreEnabled is true
• Direct messages and chat entry points are hidden or disabled when FEATURE_FLAGS.directMessagesEnabled is false
• Indoor floorplan routes and layout entry points are registered only when FEATURE_FLAGS.floorplansEnabled is true
• Map mock mode: set FEATURE_FLAGS.mockMapboxEnabled = true for test environments
• Real map runtime: set EXPO_PUBLIC_MAPBOX_ACCESS_TOKEN locally to enable the live Mapbox surface; without it, the map falls back to a static coordinate preview so the repo screens stay inspectable.
• Maps now use a draggable bottom sheet (16% / 44% / 82%) and dynamic camera padding; the active pilot directory overlay is Koufu @ JEM (L2 + L3) with official floor-map image backplates, unit-aligned polygons, computed fit-to-viewport scaling, and explicit zoom controls.
• Map marker semantics are standardized across map surfaces: hawker centre = orange, food court = teal, restaurant = grey/text-muted.
• Core client state now persists across cold starts (session, profile, search filters/history, location, review draft) using Zustand persist + AsyncStorage.
• Root Expo scaffold, typed domain layer, Zustand stores, and mock repositories are in place
• Discover, Search, Details, Auth, Onboarding, Profile, Review, Reads, and recovery flows are implemented in the mobile app shell
• Review compose now supports real library photo attachments via expo-image-picker (dev client/native build required).
• The current runtime shell is Login-first for signed-out cold starts. Profile and protected actions redirect to auth; public discovery/detail route registrations remain available for explicit public entry points.

Commands

• npm install
• npm run start
• npm run ios
• npm run android
• npm run typecheck
• npm run data:enrich
• npm run data:supabase:stage:canonical
• npm run data:supabase:stage:canonical:split

Notes

• Source-of-truth product requirements currently live in the three Hungry docx files in the repo root.
• Added an interview question bank for multi-persona customer and stall-operator research at Research/agent_interview_question_bank.md.
• Reads stays behind a feature flag even though the tab contract exists now.
• The app is designed to demo end-to-end without backend availability.
• The data/ folder also contains the Singapore food-business workbook, a checked-in curated seed snapshot, and the refresh pipeline for rebuilding the database from public datasets plus supplementary hawker- and food-court-source discovery.
• The marketing/ workspace now contains repo-grounded launch materials plus the Next.js marketing site in marketing/web/ with the homepage, for-merchants, about, and privacy routes.

Delivery Governance

• Shared active task requirements live in tasks/backlog.md.
• Verification evidence lives in tasks/verification.md.
• Claude and Codex should both update the canonical task rows frequently during execution (at minimum once per focused work block and before ending a session).
• Planning-first execution is required: create/update scoped backlog rows before non-trivial implementation work, then record verification before checking tasks complete.
• tasks/todo.md remains the historical roadmap and audit trail, not the live status surface.

Future Roadmap

See tasks/todo.md for the historical/full roadmap and tasks/backlog.md for the currently active work. Key future features include:

• Digital Ordering & Payments — In-app ordering + PayNow/card checkout for hawker centres, food courts, and restaurants. Includes a vendor analytics dashboard (top dishes, peak hours, revenue), real-time crowd/busyness indicators per stall, and queue wait-time estimates. Crowd monitoring is derived from active order volume — no hardware sensors required for the MVP signal.
• Interactive Indoor Maps — SVG floor plans with polygon-level stall selection, open/closed colour coding, and pinch-to-zoom (see design/figma-v2/building-layout.html for mockups).
• "Decide for Me" AI — Personalised dish recommendation surfaced prominently in Discover.
• Group Wishlists — Shared save lists for planning meals with friends.