Introduction

ZOVEN - Cross-Platform Fashion Shopping Mobile Application

ZOVEN is a fashion ecommerce UI kit built with React Native and Expo. It ships with 78 screens, a mock API layer, simulated AI demos, 10 curated palettes, 10 selectable locales with complete UI key coverage and 20 currencies - no backend or API keys required to run.

The kit covers the full fashion shopping journey: onboarding, authentication, product browsing, cart, checkout, order history and tracking, returns, product requests, shopping lists, favorites, comparison, referrals, outlets, gift cards, loyalty and demo AI experiences. Server-owned data uses shared API adapters; account feature state uses the customer-state adapter.

The app has one data integration path. Typed adapters and query hooks select HTTP or bundled mock handlers; persisted customer feature state uses the same mock/HTTP switch through a Zustand storage bridge. The demo runs offline, and buyers connect a server by implementing the documented resource endpoints and generic customer-state contract.

The 78 screens at a glance

Screens are file-based routes, so adding or removing one is a single file. Here is how the 78 break down:

Implementation lives in src/app/ (route screens) and src/screens/ (screen implementations), with shared UI in src/components/.

Requirements

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

Tech Stack At A Glance

Project Folder Structure

zoven/
├── app.json                  # Expo config: name, icons, splash, plugins
├── eas.json                  # EAS build profiles (development / preview APK / production AAB)
├── package.json              # dependencies, scripts, Node/npm engine range
├── .nvmrc                    # Node 24.22.2 for nvm users
├── 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)
│   └── check-theme-contrast.ts # WCAG AA palette gate (npm run theme:check)
└── src/
    ├── app/                  # Expo Router routes (80 routes / 78 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, sections, ui
    ├── store/                # 22 Zustand stores + storage adapters
    ├── 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, theme palettes, data, validation, map config
    ├── providers/            # React Query provider
    ├── utils/                # toast + navigation helpers
    ├── config/               # environment + home section mapping
    └── assets/
        ├── images/           # product, category, brand, banner, offer, background, onboarding art + logos
        └── 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 sign-ins are simulated local demo flows. Social sign-in creates a demo profile and token; no OAuth provider is contacted. These demo profiles start with an empty phone number to demonstrate 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 / link 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=

Mock mode is enabled by default through EXPO_PUBLIC_USE_MOCK_API. Typed adapters use bundled handlers, while persistent feature stores use the mock customer-state adapter; coupons and gift cards use their own resource adapters. Set EXPO_PUBLIC_API_BASE_URL and EXPO_PUBLIC_USE_MOCK_API=false to route those same boundaries to your server. Presentation-only size-chart reference tables and product editorial material/care copy remain bundled.

App JSON Configuration

app.json holds the Expo configuration. Key fields:

Theme & Styling

Styling is NativeWind v5 (Tailwind for React Native) with design tokens defined once in src/global.css and mirrored for every palette in src/lib/theme/themes.ts:

The palettes are Tailwind tokens, republished at runtime: the same compiled classes (bg-primary, text-foreground, border-border) resolve against whichever palette is active, written onto the root view by NativeWind's VariableContextProvider. Changing the tokens in src/global.css (or switching palette) re-themes the whole app instantly. 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

All 78 screens are Expo Router routes (file-based), so each screen is one file. 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
│                  /alerts /notifications /recently-viewed /lookbook /loyalty /gift-cards
│                  /payment-methods /size-guide
├── 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]
├── product-requests/ → /product-requests/new /product-requests
└── root screens → /splash /onboarding /language-select /currency-select /theme
                   /search /search-results /checkout /online-payment /order-success
                   /compare /outlets /contact /about /no-internet /not-found
                   /shipping-policy /payment-policy /gift-card-policy /warranty-policy
                   /cookie-policy /sustainability-policy /refund-policy

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.

Client State & Persistence

Zustand manages screen state. Business resources use typed API/query adapters; cart, alerts, fit profile, loyalty, notifications, product questions/requests, recently viewed, returns, shopping lists and product comparisons persist through customerStateApi using the same mock/HTTP switch. Coupon validation and gift-card validation/redemption use their own resource APIs. Account-specific data is read and written at /me/state/{resource}/{key} and must be authorized by the server. The auth session token is kept in the platform keychain/keystore through SecureStore; the user profile, theme, locale, currency, onboarding progress and temporary UI state remain on-device. Expo web has no OS keychain, so the web preview keeps the token in memory for the current session only and never persists it.

Address, payment method, favorite, review and order records use their typed resource adapters. The outlet directory is fetched via the content adapter; filter selections are transient screen state. src/services/mock/db.ts contains categories, brands and products for mock catalog responses.

Data Layer & Mock API

The demo needs no backend. Server-owned resources use typed API adapters and query hooks; persistent feature state uses a generic customer-state storage adapter. Both select bundled mock behavior or HTTP from the same environment switch.

Business resources use the same mock/HTTP adapter boundary. Checkout sends one create-order request and order screens read records from the order adapter. Persistent feature stores use the generic customer-state contract; coupon validation and gift-card balance operations have dedicated contracts. Authentication verification/recovery, guest/social sign-in, AI helpers and static presentation content (size charts, product editorial material/care, onboarding copy, return reason/status labels, tracking timeline copy and loyalty tier rules) remain simulated, local or bundled. Mock mode may seed demo feature snapshots (returns, shopping lists, product requests, notifications, loyalty history) so screens are not empty; HTTP mode starts empty. Theme, locale, currency, onboarding progress and temporary checkout fields remain device-local preferences or UI state.

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. The ten locales are selectable and every UI key used by the app is present in each file. English remains the fallback in src/lib/i18n.ts so any key you add is still safe before you translate it. AI response copy is English-only in the demo.

AI Layer

The AI features run through a provider boundary in src/services/ai/index.ts. The bundled mock provider simulates thinking latency 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. Inline AI insight cards carry a visible Demo badge.

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.

The assistant chat can use a provider implemented in src/services/ai/index.ts when EXPO_PUBLIC_USE_MOCK_AI=false. Guided flow, comparison, visual search, search interpretation, home recommendations, favorites insight and review summaries are exported from the same AI layer and call the local demo implementation until integrated with a provider. No API keys ship in the app.

Live-service costs: connecting a live backend or third-party services is not included and will incur additional costs paid directly to their providers. This can include AI provider usage/tokens, cloud hosting, database and storage, map tiles/geocoding/routing, payment gateway fees, email/SMS/OTP delivery, push notifications and app-store fees. The bundled demo uses mock data and incurs none of these costs.

AI usage disclosure. AI tools were used to assist with parts of the source code and written documentation of this item; all output was reviewed, tested and refined by the author before submission. The ZOVEN logo and bundled brand marks are author-made placeholder assets. Promotional artwork used in some preview screenshots may have been created with the assistance of AI tools. Product and category images bundled with the app are demo placeholders; replace them with your own licensed photography before production. All in-app AI features are simulated offline demos and are labeled as demos.

Features & Screens

All 78 screens are listed below by area. Screens use the API adapter boundaries with bundled mock behavior by default. Real payment processing and identity providers are not included; AI and selected account workflows are labeled demos as described in each section.

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 campaign banner slider with auto-play:

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

Resources: section backgrounds and promo art in src/assets/images/backgrounds/ (background-1..4, plus background-5.webp and background-6.webp for the seasonal sale bands); 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. The demo tree has 39 categories across Clothing, Bags & Luggage, Jewelry & Watches, Fragrance & Beauty, Home & Living and Eyewear.

Search

Search Results & Filters

Product Detail

Favorites

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

Brands & Outlets

Resources: product photos in src/assets/images/products/ (600×600 WebP named zoven-<id>-<colour>.webp, referenced from src/lib/data/products/*); category tiles in src/assets/images/categories/ (category-1.webp ... category-39.webp, 39 files); brand logos in src/assets/images/brands/ - 10 transparent marks (brand-1.png ... brand-10.png) matching the ten house labels in src/lib/data/brands.ts (all logos ship local, no remote URLs).

Cart & Checkout

Cart

Checkout

A single scrolling checkout with the address, delivery choice, gift options, coupon / gift card, payment and review in one flow.

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 & Exchanges

Product Requests

Customers can ask the store to source a piece 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 placeholder you can swap. Replace a file with your art at the same size (keep the file name) and the layout stays untouched.

Some demo background/editorial artwork shown in the preview build and screenshots is sourced from Freepik under its license. The downloadable main template ships with dimension placeholders and does not include the Freepik artwork files.

Colors & Theme

All colors flow from design tokens in src/global.css, with the ten palettes mirrored in src/lib/theme/themes.ts. Change the default once and the whole app follows:

--color-primary: #183B32;        /* brand forest (Zoven Signature) */
--color-background / --color-foreground
--color-card / --color-muted / --color-border

The default palette is Zoven Signature - forest #183B32, leather #3D3028, sage #8FA892, oat canvas #E8E1D5, paper #FBF7EE. To add your own, append an entry to PALETTES; the picker, the CSS variables and the contrast gate all pick it up. Run npm run theme:check to verify every palette clears WCAG AA, and npm run theme:check also fails if global.css drifts from the default palette. 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, sample rate). All prices format through useFormatCurrency, so a new currency applies everywhere at once. Rates in the demo are sample values - fetch production rates from a trusted service and keep prices in a single server-side base currency.

Backend Integration

All server-owned app data follows one adapter path. The bundled demo uses mock handlers and mock persistence; connecting your server does not require screen-by-screen data-source changes.

The server must validate prices, stock, discounts, tax quotes, gift-card balances, payment state and order totals. Coupon validation and gift-card balance operations have dedicated resource endpoints. Generic customer-state snapshots provide a convenient integration contract for UI-kit feature state; a production commerce backend can replace the generic snapshots with normalized resource APIs, but you should review the mock-mode feature seeds and static presentation content before claiming all screens are server-driven. Password recovery/verification, guest/social login and AI widgets are demos and require provider-specific implementation before production.

Auth headers are attached by the Axios client in src/services/apiClient.ts. Keep map providers configured with appropriate production credentials and usage policies.

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
npm run verify     # data + navigation integrity checks
npm run theme:check # WCAG AA contrast of every palette
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), order totals (including gift wrap and gift cards), size-chart integrity, the fit-finder recommender and loyalty tier maths. 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. npm run theme:check measures every palette against WCAG AA and fails if global.css drifts from the default palette.

Demo Data Reference

Troubleshooting

Source & Credits

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

Demo catalog text, brand names (ZOVRA, VENZEL, ZENOVA ...), outlet names, addresses, coordinates and imagery are fictional placeholders created for this kit and are not affiliated with any real company or retail location.

Version Log

Support

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

Thank you for choosing ZOVEN.