App Mobile

App Mobile module

Runs the real customer UI with native or fail-closed device and backend services; no simulated success.

What executes when an Android or iOS HSLG app starts

The mobile runtime is the real customer application, not the multi-phone browser showcase. src/main.ts is the Vite entry and src/CapacitorBoot.ts creates the Capacitor device-service adapter, configures an optional HSLG API account coordinator and registers native lifecycle wiring. The shared screens use the service contract supplied by src/NativeServices.js. src/StartNative.js boots the actual shared UI. No demo payment, reservation or account success may be imported into this runtime.

Why native capabilities are separate adapters

The shared UI asks for operations such as scan QR, report connectivity and save customer details. It should not import Android or iOS plugin modules directly. native-adapters/CapacitorDeviceServices.ts translates those operations into official Capacitor Network, App, Barcode Scanner, Haptics, Keyboard, Orientation and Splash Screen calls. This separation lets the presentation use a fake scanner response for demonstration while the APK must open a physical camera with OS permission handling. It also gives tests a place to inject controlled failures.

Startup and failure behaviour

The bootstrap configures device services and then tries to initialize the shared experience. The account coordinator is configured only if a public HTTPS API origin is supplied; no secret API credentials are embedded. An encrypted native token vault is still absent, so a login must fail rather than store credentials insecurely. The source handles bootstrap errors without inventing a success result. A phone test must still verify that the app is visible, that splash handling and keyboard listeners work, and that hardware callbacks actually reach the shared UI.

What is explicitly not provided

The production runtime has empty live catalogue/event/offer providers until the proper backend connection exists. Foreground NFC, native SQLite, Stripe PaymentSheet, biometrics, push notifications and social-login providers remain unimplemented or outside this adapter. The current Android folder is scaffolded source; there is no verified complete Capacitor APK from this checkpoint. A signed WebView-only preview is not evidence of Capacitor plugin integration.

How to change safely

For a new native feature, first extend the capability contract, then implement one narrow native adapter, then wire the intended shared UI action. Handle permission denial, cancellation, unsupported OS and network errors explicitly. Update Android manifest/iOS entitlements and add genuine device tests. Confirm that the presenter still uses only its own demo adapter. Rebuild and sync the native project rather than assuming TypeScript compile alone proves plugin availability.

Review and tests

Start at src/CapacitorBoot.ts, read native-adapters/CapacitorDeviceServices.ts, then examine src/NativeServices.js. The Node native wiring contract test is under tests/contracts/native-mobile-wiring.test.cjs. Device journeys live in the runtime test suite, but browser tests cannot replace actual Android testing. The native gate must resolve the package lockfile and Gradle dependencies before a release can claim physical-device readiness.

Source files in this module

Maintenance and evidence

Check all affected file references and the matching human-readable user/architecture page when source changes. Run the module’s contract or governance checks; staging, payment and native hardware tests remain independent of source inventory coverage.