Customer App engineering guide
Use this guide when contributing to the Customer App repository. Repository access requires authorization. This guide covers the checked-in bare React Native project and its local quality gates. Native credentials, customer data, signing, store access, and release approval remain outside this guide.
Architecture
Customer App is a bare React Native 0.81.1 application using React 19.1. index.js registers the
native application, App.tsx establishes the safe-area root, and src/TemplateApp.tsx composes the
theme, permissions, session, API, configuration, consent, and navigation boundaries. React Navigation
owns the screen hierarchy under src/navigators.
Shared commerce behavior and UI are pinned through the src/@/components Git submodule. Native
platform projects live in ios/ and android/; JavaScript changes can still require matching native
pods, Gradle configuration, permissions, URL schemes, or provider capabilities.
Repository map
| Path | Responsibility |
|---|---|
index.js and App.tsx | Native registration and application root. |
src/TemplateApp.tsx | Provider composition, runtime gates, and top-level app behavior. |
src/navigators/ | Navigation container, stacks, tabs, and typed app destinations. |
src/screens/ and src/components/ | Customer journeys and app-specific UI. |
src/contexts/ | App-owned state such as consent and checkout-field behavior. |
src/@/components/ | Pinned shared Components submodule. |
src/config.json, src/config.js, and src/theme.json | Browser-independent app defaults and theme configuration. |
ios/ | Xcode workspace, app target, extension, pods, entitlements, and Apple-platform resources. |
android/ | Gradle project, manifests, resources, and Android application target. |
__tests__/, src/**/*.test.*, and jest/ | Jest, React Native Testing Library, mocks, and coverage configuration. |
i18n/ | Generated locale catalog checks and translation utilities. |
patches/ | Versioned patch-package changes applied after install. |
Prerequisites
Install the platform tooling for the target you plan to run:
- Git with submodule support.
- Node.js 20 or newer, matching
package.jsonand CI. - Yarn Classic with the checked-in
yarn.lock. - Android: Android Studio, an SDK compatible with the checked-in Gradle project, Java 17, and an emulator or connected device.
- iOS: macOS, a compatible Xcode installation, Ruby, Bundler, CocoaPods, and an installed simulator runtime. The repository's Gemfile constrains CocoaPods and supporting gems.
Obtain repository access from its owner and use the approved authentication method. From an authorized checkout, initialize the pinned Components revision and install dependencies:
git submodule update --init --recursive
yarn install --frozen-lockfile
For iOS, install the checked-in native dependency graph from the ios directory:
bundle install
cd ios
bundle exec pod install
cd ..
Do not delete lockfiles as routine setup. Changes to yarn.lock, Gemfile.lock, Podfile.lock, the
Gradle wrapper, or the submodule pointer are dependency changes and should be reviewed as such.
Configure a safe development build
src/config.json supplies client-visible app defaults and src/config.js normalizes them. Native
provider files, manifests, schemes, entitlements, and signing settings add platform-specific inputs.
- Start from an authorized development project and non-production accounts.
- Treat configuration bundled in the app as extractable by an end user.
- Never commit API secrets, private keys, signing material, service-account files, customer exports, payment data, session tokens, or reusable provider credentials.
- Keep application identifiers, URL schemes, notification configuration, and provider applications aligned to the same approved build variant. Source presence alone does not prove that a provider is configured or enabled.
- Do not replace checked-in provider files with production copies to make a local build pass.
Review Customer App configuration boundaries and Native integration boundaries before changing an integration surface.
Run locally
Start Metro in one terminal:
yarn start
Run the intended platform from another terminal:
yarn ios
yarn android
You can also open ios/ReactNativeAppsTemplate5.xcworkspace in Xcode or the android/ project in
Android Studio when native diagnostics are required. Select a development target; do not reuse a
distribution signing configuration for routine local work.
Validate changes
The pull-request CI gate checks lint, unit tests, generated translations, translation validity, and coverage. Run the relevant commands locally:
yarn lint:check
yarn test
yarn i18n:check-generated
yarn i18n:verify
yarn test:coverage
Jest excludes the shared Components submodule from this repository's coverage calculation; changes
to that submodule need validation in its owning repository. yarn lint writes fixes, while
yarn lint:check reports without rewriting files.
JavaScript tests do not replace a native build. For changes to pods, Gradle, permissions, schemes, deep links, notifications, payments, maps, or social sign-in, compile and exercise the affected platform with provider effects disabled or isolated.
Build and release boundary
This repository does not define a package script that publishes an app-store release. A distributable build requires platform-owner review of native configuration, identifiers, signing, privacy metadata, provider applications, versioning, store records, and the exact source and submodule revisions.
A simulator launch, local archive, CI pass, or provider SDK initialization is not evidence that an App Store or Play Store release was built, submitted, approved, or deployed. Only an authorized release owner should use signing credentials or external store systems.
Troubleshooting
| Symptom | Check |
|---|---|
| Shared aliases or commerce modules cannot resolve | Run git submodule status, then initialize the pinned submodule. Confirm Babel and Jest still point to the maintained aliases. |
| Metro serves stale or duplicate modules | Stop Metro, confirm one repository and one dependency tree are in use, then restart with the repository script before clearing broader caches. |
| CocoaPods cannot resolve or compile | Use the repository Ruby and lockfile constraints, run bundle exec pod install, and open the .xcworkspace, not the .xcodeproj. Review the first native compiler error. |
| Android cannot find its SDK or Java toolchain | Confirm Android Studio SDK paths, a running emulator/device, and Java 17 before changing Gradle files. |
| A provider button is missing | Check the approved build, platform, project, native capability, and public availability gate. Do not infer an outage or add credentials to source. |
| A deep link opens the wrong state | Verify the native scheme and intent registration, then the typed route and current session/project gates. A link never grants resource access. |
| Generated translations fail CI | Run both i18n checks and update source keys and generated catalogs together. |
| Unit tests pass but the device build fails | Reproduce in Xcode or Android Studio; JavaScript tests do not compile native dependencies or entitlements. |
Security boundaries
- Store sessions and provider results only through the maintained secure lifecycle. Never print them to Metro, device logs, analytics, screenshots, or documentation fixtures.
- Reauthorize orders, messages, wallets, payment state, and account data after every external or push navigation. A deep link or notification is an intent, not proof of access.
- Keep raw card data inside supported payment-provider components. Do not persist payment tokens in logs, URLs, general application storage, or test snapshots.
- Separate operating-system permission, customer consent, provider registration, Ordering.co binding, message delivery, and notification-open state.
- Reject late callbacks after logout, account change, project change, cancellation, or a new attempt.
- Validate native changes on both platforms when the contract is shared; never infer Android behavior from iOS success or the reverse.
- Use the API Reference for published server contracts. Client code and SDK calls do not establish server authorization or provider guarantees.
Related references: Customer App developer reference · Configuration boundaries · App-link boundaries · Native integration boundaries