Introduction

Glean - Cross-Platform Grocery Shopping Mobile Application

Glean is a complete, production-quality grocery delivery marketplace UI kit built with React Native and Expo. It ships with 61 routes, a full mock API layer, an offline AI demo, 10 languages and 20 currencies - no backend or API keys required to run.

The kit covers the entire shopping journey: onboarding, authentication, a rich home page, product browsing with filters, cart, a full checkout (address + map, delivery options, time slots, tips, voice-note instructions, payments), orders, invoices, two-way order tracking, returns & refunds, product requests, shopping lists, favorites, referrals, outlets, and an AI suite (assistant, guided find/gift flow, comparison, visual search).

Everything runs on bundled demo data. A typed API layer mirrors REST contracts for the flows that already use it; the rest of the app reads bundled data or Zustand stores directly, so connecting a real backend means implementing the endpoints and migrating the remaining screens (Backend Integration lists them).

Requirements

Before setting up the project, ensure your development environment meets these requirements:

Tech Stack At A Glance

Project Folder Structure

glean/
├── app.json                  # Expo config: name, icons, splash, plugins
├── eas.json                  # EAS build profiles (development / preview APK / production AAB)
├── metro.config.js           # Metro + NativeWind
├── scripts/
│   ├── verify-integrity.js   # routes + asset reference checks (npm run verify)
│   └── smoke-tests.ts        # dependency-free unit tests (npm test)
└── src/
    ├── app/                  # Expo Router routes (61 screens)
    │   ├── _layout.tsx       # Root layout: providers, offline handling, overlays
    │   ├── (auth)/           # login, signup, OTP, password reset, legal
    │   ├── (main)/           # orders, addresses, profile settings, returns, referrals...
    │   ├── (tabs)/           # home, categories, cart, offers, favorites, profile
    │   ├── ai-*.tsx          # assistant, comparison, shopping flow, visual search
    │   ├── product/[slug].tsx
    │   ├── search.tsx / search-results.tsx
    │   └── checkout.tsx / online-payment.tsx / order-success.tsx
    ├── screens/              # screen implementations used by the routes
    ├── components/           # ai, cards, modals, navigation, products, ui
    ├── store/                # 18 Zustand stores + storage adapter
    ├── services/
    │   ├── api/              # typed REST endpoint functions
    │   ├── mock/             # in-memory relational demo database + handlers
    │   ├── queries/          # TanStack Query hooks
    │   └── ai/               # AI provider boundary + mock provider
    ├── hooks/                # pagination, currency, network, debounce, refresh
    ├── lib/                  # types, i18n, data, validation, map config
    ├── providers/            # React Query provider
    ├── config/               # environment + home section mapping
    └── assets/
        ├── images/           # placeholder images (products, categories, brands, banners, backgrounds, offers, onboarding)
        └── icons/            # flags, payment methods, social icons

Images & icons: all bundled art lives under src/assets/images/ (products, categories, brands, banners, backgrounds, offers, onboarding, logos) and src/assets/icons/ (flags, payment methods, social icons). Each feature section below lists the exact files it uses.

Installation & Setup

No environment file is required to run: the app defaults to the bundled mock API, mock AI and OpenStreetMap tiles.

Demo Credentials

The login screen has a Demo Login button that signs you in instantly. If you prefer typing:

Guest and social logins work too - they start with an empty phone number, which demonstrates the "Complete profile" gate in checkout.

Running & Building

Development

npx expo start          # dev server (Expo Go)
npx expo start -c       # dev server with a cleared Metro cache

Clear the cache (-c) whenever you add/remove/rename assets or change global CSS.

Local release APK

npx expo prebuild --clean
cd android
.\gradlew assembleRelease

The APK is written to android/app/build/outputs/apk/release/app-release.apk. The generated Gradle project signs release builds with the debug keystore by default - use your own keystore for store releases.

Cloud builds (EAS)

npm install -g eas-cli                              # or use: npx eas-cli
eas login                                          # sign in - https://expo.dev/login
eas init                                           # create your own EAS project
eas build --platform android --profile preview      # installable APK (internal)
eas build --platform android --profile production   # AAB for the Play Store
eas build --platform ios --profile production       # iOS archive

EAS builds run prebuild in the cloud, so you never need a local android/ or ios/ folder. Before the first build: update the app identity in app.json, install the CLI (npm install -g eas-cli) and sign in with eas login - create a free Expo account at expo.dev/login. Full reference: docs.expo.dev.

App identity (do this first)

App Configuration

Everything that shapes the shipped app: environment variables, the Expo manifest, and the theme tokens.

Environment Configuration

Copy .env.example to .env (or .env.local) when you want to override the defaults. Everything is optional - the demo runs offline out of the box.

EXPO_PUBLIC_API_BASE_URL=http://localhost:3000/api/v1
EXPO_PUBLIC_USE_MOCK_AI=true
EXPO_PUBLIC_MAP_PROVIDER=osm
EXPO_PUBLIC_MAPTILER_KEY=

The mock API is on by default (USE_MOCK_API = true in src/config/env.ts), so every service-layer call is served by the bundled mock handlers and the demo runs fully offline. The browse-first screens additionally read the demo catalog in src/lib/data/* directly for instant, offline browsing. See Backend Integration for the exact switch procedure.

App JSON Configuration

app.json holds the Expo configuration. Key fields:

The template intentionally ships without a seller-owned owner or EAS projectId - run eas init after signing in to create your own project.

Theme & Styling

Styling is NativeWind v5 (Tailwind for React Native) with design tokens defined once in src/global.css:

Components use token classes (bg-background, text-foreground, bg-primary) so changing the tokens in src/global.css re-themes the whole app. The kit renders light-only by design (userInterfaceStyle: "light").

Tap feedback is centralized in src/components/ui/RipplePressable.tsx: it picks a circular ripple for square/round buttons and a masked ripple for wide items, plus a subtle pressed dim on every platform.

Architecture Overview

Navigation & Routing

Routing is Expo Router (file-based). Groups keep the URL structure clean:

src/app/
├── (auth)/      → /login /signup /verify-email /forgot-password /otp-verification
│                  /reset-password /reset-success /registration-success /terms /privacy
├── (tabs)/      → / (home) /categories /cart /offers /favorites /profile
├── (main)/      → /orders /orders/[id] /orders/invoice/[id] /addresses /add-address
│                  /edit-profile /change-password /referrals /returns /returns/new
│                  /track-order /track-order/[id] /income /faq /help-support
│                  /language /currency /offer-details /product-requests
├── ai-*.tsx     → /ai-assistant /ai-shopping-flow /ai-comparison /ai-visual-search
├── product/     → /product/[slug]
├── brands/      → /brands /brands/[id]
├── shopping-list/ → /shopping-list /shopping-list/[id]
├── categories/  → /categories/[slug]
└── root screens → /splash /onboarding /language-select /currency-select
                   /search /search-results /checkout /online-payment /order-success
                   /outlets /contact /refund-policy /no-internet /not-found

Typed routes are enabled (experiments.typedRoutes), so route names are checked at compile time. The tab bar is a custom component (src/components/navigation/TabBar.tsx) with a wave-shaped center cart button and a live cart badge.

State Management

18 Zustand stores handle all client state. Persisted stores use a shared AsyncStorage adapter (src/store/storage.ts), so state survives restarts:

Data Layer & Mock API

The demo needs no backend, and two data paths work together:

Flows that already run through the service layer: login and sign-up (authApi), product queries, category queries, delivery quotes and order-history reads. Everything else is local until you migrate it: cart and checkout/order placement (orderStore.createOrder), addresses, coupons and payment methods (Zustand stores), reviews (a local hook with hard-coded demo reviews), related products (bundled catalogue), password reset / OTP / email verification / change-password (setTimeout simulations), and offers, stories, outlets, wishlist, returns, shopping lists, notifications and referrals (no API module exists yet). Backend Integration lists exactly what to implement and which files to migrate.

Note: the demo still checks real connectivity (the no-internet screen appears when the device is offline) and map tiles stream from the provider.

Localization & Currency

Translation files live in src/lib/locales/*.ts. AI response copy is English-only in the demo; all other UI text is fully localized.

AI Layer

The AI features run through a provider boundary in src/services/ai/index.ts. The bundled mock provider simulates thinking latency (650ms) and answers from the demo catalog: it can search products, add to cart, compare items, and answer delivery/policy questions. Everything AI in the kit is an offline demo - no hosted AI service is called.

Visual search is demo mode: it uses the real camera/gallery picker but the matching is simulated against the bundled catalog (the screen shows a "Demo" badge and a note explaining this). Replace the provider to run real image recognition.

To run your own model, implement the provider in src/services/ai/index.ts and set EXPO_PUBLIC_USE_MOCK_AI=false. Note: the screens currently import the bundled mockAIService directly (guided flow, comparison, visual search, search interpretation, home recommendations, favorites insight and the product review/Q&A panels), while the assistant chat uses the provider boundary. Migrating those imports to the provider interface is part of the work. No API keys ship in the app.

Features & Screens

Every screen below runs on the bundled demo data and is fully interactive - including payments, orders, returns and the AI flows.

Authentication

All authentication is simulated against the mock API and persisted in authStore.

Resources: social button icons in src/assets/icons/social-icons/; brand logo on auth screens in src/assets/images/logo.png.

Home Screen

Top Bar

Delivery address (opens the address modal), search entry, notification bell with unread dot, and a menu button that opens the side drawer. The category drawer opens from the grid icon.

Hero Slider (Stories)

A looping, center-snapping banner slider with auto-play:

Banners live in src/lib/data/stories.ts (images in src/assets/images/banners, 700x300).

Resources: section backgrounds and promo art in src/assets/images/backgrounds/ (promo-1/2, background-1..7); offer popup poster in src/assets/images/offers/popup-offer.webp.

Home Sections

Offer Popup

A promo poster modal appears once after the home loads (2s delay). Dismissal is persisted - it does not show again on the next launch. The poster ratio is derived from the asset, so any export size works.

Floating Controls

Product Browsing

Categories

The categories tab shows a two-column grid with inline drill-down (root → sub → child) and a full category listing screen (/categories/[slug]) with a sidebar, sorting and pagination.

Search

Search Results & Filters

Product Detail

Favorites

Grid and list views (ProductListRow), a "You may also like" rail, and an AI wishlist insight card.

Brands & Outlets

Resources: product photos in src/assets/images/products/ (referenced from src/lib/data/products/*); category tiles in src/assets/images/categories/ (from src/lib/data/categories.ts); brand logos in src/assets/images/brands/ - 43 neutral placeholders, one per entry in src/lib/data/brands.ts (all logos ship local, no remote URLs).

Cart & Checkout

Cart

Checkout

A single scrolling checkout with three tabs: Delivery Options, Tip and Instructions.

Order Success

Animated success screen with the order number; the primary CTA jumps to Track order.

Resources: payment brand icons in src/assets/icons/payment-methods/ (numbered files pay-1.webp to pay-9.webp).

Orders & Tracking

Returns & Refunds

Product Requests

Customers can ask the store to source a product that is not in the catalog:

Shopping Lists

Profile & Settings

Resources: social icons in src/assets/icons/social-icons/; language flags in src/assets/icons/flags/; payment method icons in src/assets/icons/payment-methods/; profile photos are picked by the user (camera/gallery).

Notifications & Offline Handling

AI Suite (Offline Demo)

The assistant is also reachable from the floating button on every main screen. See AI Layer for wiring a real provider.

Customization Guide

Everything below is designed so you can rebrand the kit from central theme and configuration files.

App Identity

Edit app.json before publishing:

Images & Placeholders

Every image under src/assets/images/ is a neutral placeholder that shows its own dimensions and file name - so you always know the exact size to export. Replace a file with your art at the same size (keep the file name) and the layout stays untouched.

Colors & Theme

All colors flow from design tokens in src/global.css. Change them once and the whole app follows:

--color-primary: #00B64B;        /* brand green */
--color-background / --color-foreground
--color-card / --color-muted / --color-border

Gradient helpers (bg-gradient-green-top, bg-gradient-warm-bottom, bg-gradient-brand-deep) and the shared RipplePressable are also defined there / in src/components/ui. The app is intentionally light-only.

Demo Data

All catalog content lives in plain TypeScript files - no database:

After editing data, run npm run verify - it checks that every reference (product variants, category slugs, offer/story products, asset paths) still resolves.

Translations

Currency

Add or remove currencies in src/store/currencyStore.ts (code, symbol, locale). All prices format through useFormatCurrency, so a new currency applies everywhere at once.

Backend Integration

The demo runs on the bundled mock layer. To connect your own server:

The mock layer stays the default, so the demo keeps running offline. Flip the flag once your endpoints are live - the wired flows then use your server while the remaining screens keep running on bundled data until you migrate them. Auth headers are attached by the Axios client in src/services/apiClient.ts; the AI provider is swapped separately (see below).

Map Providers

Maps are Leaflet + raster tiles inside a WebView. Provider attribution is enabled on every map (required by the providers' terms). Pick a provider in .env:

Before going live, configure your own production providers. The defaults are public community services whose policies only cover light/demo traffic:

Provider config lives in src/lib/mapConfig.ts; the Leaflet HTML is built in src/components/maps/leafletMapHtml.ts and the address map in src/screens/addresses/components/addressMapHtml.ts. Google Maps would require the native react-native-maps/expo-maps module plus a billing-enabled API key - the map logic is isolated in a single component, so the swap stays contained.

Social Auth & AI Provider

Quality Checks

npm run lint      # ESLint (expo config)
npm test          # dependency-free smoke tests (18)
npm run verify    # data + navigation integrity checks
npx tsc --noEmit  # TypeScript
npx expo-doctor   # Expo SDK / dependency validation

npm test covers the search matcher, variant pricing, coupon math (percentage, fixed, caps, minimums) and order totals. npm run verify validates order seed items, home-section slugs, offer/story references, every asset require() target on disk, and every static navigation target against the route table.

Demo Data Reference

Troubleshooting

Source & Credits

Built with open-source software. Main libraries and their licenses:

Version Log

Support

Questions, bug reports or feature requests? Get in touch:

Thank you for choosing Glean.