Skip to main content

Business App engineering guide

Use this guide to develop and verify the React Native Business App. To confirm the app version installed by users, check your organization's release system and the API and provider configuration paired with that build.

Architecture​

The application separates shared headless logic, app-owned presentation, and native screen wiring:

index.js → App.tsx → src/BusinessApp.tsx → src/AppContainer.tsx
                                      └→ src/navigators/RootNavigator.tsx

src/@/components  shared headless controllers, hooks, and API client
src/ui             Business App presentation and app-owned contexts
src/pages          thin screen wrappers
src/navigators     authentication, tabs, stacks, push, and connectivity wiring
ios and android    native projects and platform integrations

src/@/components is a Git submodule. The React Native @components alias resolves to its native entry point. Coordinate shared logic changes in the Components repository; do not edit the submodule as if it were ordinary app source.

Business App screens use React Navigation and styled-components. Keep reusable visual work in src/ui, page-specific wiring in src/pages, navigation and native lifecycle behavior in src/navigators, and shared business/API logic in Ordering.co Components.

Repository map​

PathResponsibility
App.tsx, src/BusinessApp.tsx, src/AppContainer.tsxApp entry and provider composition
src/pagesOperator-facing screen wiring
src/navigatorsAuthentication gates, tabs, stacks, push handoff, and connectivity
src/uiApp-owned UI components, layouts, providers, and offline-action presentation
src/contextApp-owned permission state
src/@/componentsPinned shared Components submodule
src/config.jsonVersioned runtime settings consumed by the app
src/theme.jsonApp theme inputs and asset references
i18nTranslation catalog generation, validation, and synchronization tools
ios, androidNative workspaces, projects, manifests, entitlements, and Gradle configuration
jest, src/**/__tests__App test harness and test suites
patchesNative dependency patches applied during dependency installation

Keep the @, @ui, and @components aliases aligned between babel.config.js and tsconfig.json.

Prerequisites and setup​

  1. Install the React Native host requirements for the platform you will run: Xcode and CocoaPods for iOS, or Android Studio and a compatible JDK/Android SDK for Android.
  2. Use Yarn. The repository's NODE_VERSION.txt selects Node 22, while package.json accepts Node 20 or newer.
  3. Clone with submodules, or initialize them before installing dependencies.
git clone --recursive <authorized-repository-url>
cd <cloned-repository-directory>
yarn install --frozen-lockfile

For an existing clone:

git submodule update --init --recursive
yarn install --frozen-lockfile

For iOS, install the checked Ruby dependencies and Pods on the first setup and after native dependency changes:

bundle install
cd ios
bundle exec pod install
cd ..

Open ios/businessApp.xcworkspace when working in Xcode. The shared scheme is businessApp. Use the checked Gradle wrapper for Android rather than a separately installed Gradle version.

Configure safely​

src/config.json and src/theme.json are versioned application inputs, not a place for credentials. Keep secret keys, signing material, private hosts, customer records, tokens, order data, payment data, and provider credentials out of source, screenshots, logs, and tickets.

Before launching the app, have the environment owner confirm that the packaged app settings, paired Components revision, intended API environment, socket environment, and native provider configuration belong together. Do not copy values from another project or replace a checked setting with a guessed endpoint.

Normal startup can initialize API, socket, notification, permission, and other native-provider behavior. Use an approved non-production environment and purpose-minimal synthetic accounts. Treat notification registration, messages, order mutations, files, printing, and location access as effects that require an explicit test plan and cleanup.

Translation work should begin with local generation and verification. yarn i18n:sync is the documented dry run; yarn i18n:sync:live can write through an authorized API integration and must not be used as an exploratory command.

Run the app​

Start Metro in one terminal:

yarn start

Run one platform from another terminal:

yarn ios
yarn android

If Metro has stale module state, use yarn start:reset. For native changes, rebuild the native target instead of relying only on Fast Refresh.

Test and verify changes​

Use the non-mutating lint command in local checks. The plain yarn lint script applies fixes.

npx tsc --noEmit
yarn lint:check
yarn test
yarn i18n:check-generated
yarn i18n:verify

Useful focused commands include:

yarn test path/to/file.test.tsx
yarn test:coverage
yarn test:coverage:summary

The app's CI workflow installs the frozen Yarn lockfile and runs lint, TypeScript, Jest, translation checks, and coverage. Jest covers app-owned tests and excludes native folders and the Components submodule; validate a Components change in its own repository as well. Run UI and native changes on the affected simulator or device, and verify the supported state, error, cancellation, and cleanup paths.

Build and release handoff​

The repository documents native development builds through the React Native CLI, Xcode workspace, and Gradle wrapper. Its inspected workflows are quality gates, not evidence that an app-store build was signed, uploaded, reviewed, or released.

Before handing a candidate to the release owner:

  1. Record the app commit, exact Components submodule commit, lockfile state, and intended environment without including secret values.
  2. Start from a clean worktree and install dependencies from the checked lockfiles.
  3. Run typecheck, non-mutating lint, Jest, translation validation, and any change-specific native tests.
  4. Build the affected iOS and Android targets through their checked workspace/project configuration.
  5. Exercise only approved synthetic scenarios and record app, API, provider, and physical-output observations separately.
  6. Ask the release owner to apply the authorized signing, distribution, rollout, and rollback process.

A successful local build or CI run confirms that build or workflow only; verify app-store publication and signing through the release system used by your organization.

Troubleshooting​

SymptomCheck
@components cannot resolveConfirm the submodule is initialized and that the alias targets the native entry point.
Metro resolves stale filesStop Metro, run yarn start:reset, and rebuild after native changes.
iOS dependencies or symbols are missingRun Bundler and bundle exec pod install from ios, then open the workspace rather than the project.
Android build configuration disagrees with the checkoutUse android/gradlew and verify the installed JDK/SDK against the checked React Native and Gradle files.
UI and controller behavior divergeConfirm whether the change belongs in app-owned src/ui/src/pages or the pinned Components submodule.
A configured feature is absentVerify the exact app/Components pair, environment, authorization, and runtime prerequisites; a visible flag is not an entitlement guarantee.
Push, socket, print, file, map, or external-app behavior is ambiguousStop retries and inspect the owning integration contract.
CI and local results differCompare Node, lockfile installation, submodule commit, generated translations, and the exact command variant.

Security and escalation​

Stop and escalate when the intended environment, Components pin, signing identity, provider application, permission purpose, synthetic fixture, or cleanup observer is unknown. Report only the minimum redacted context: platform, app commit, Components commit, command, non-sensitive visible state, and whether any effect may still be pending.

Never paste credentials, raw configuration values, access tokens, customer or order details, precise coordinates, payment data, notification payloads, device identifiers, or signing material into an issue. A client request, resolved promise, toast, provider identifier, or opened system dialog does not prove server acceptance or external completion.