--- title: "Customer App engineering guide" description: "Set up, validate, and build the Ordering.co Customer App repository safely." canonical: https://docs.ordering.co/docs/developers/customer-app/engineering-guide/ --- # 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.json` and 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: ```bash git submodule update --init --recursive yarn install --frozen-lockfile ``` For iOS, install the checked-in native dependency graph from the `ios` directory: ```bash 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](https://docs.ordering.co/docs/developers/customer-app/configuration/) and [Native integration boundaries](https://docs.ordering.co/docs/developers/customer-app/native-integrations/) before changing an integration surface. ## Run locally Start Metro in one terminal: ```bash yarn start ``` Run the intended platform from another terminal: ```bash yarn ios ``` ```bash 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: ```bash 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](https://docs.ordering.co/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](https://docs.ordering.co/docs/developers/customer-app/) · [Configuration boundaries](https://docs.ordering.co/docs/developers/customer-app/configuration/) · [App-link boundaries](https://docs.ordering.co/docs/developers/customer-app/deep-links/) · [Native integration boundaries](https://docs.ordering.co/docs/developers/customer-app/native-integrations/)