Mobile App Architecture

Akan mobile apps are built by opening a CSR web client inside a Capacitor native shell, then packaging that shell as Android and iOS apps. The screen is developed with the same Akan UI system, while Capacitor provides the native project, app identity, and device bridge.

Akan mobile architecture

If the app declares multiple basePaths, one Akan app can release multiple mobile packages. For example, a customer app, an admin stock app, and a field worker app can each open a different basePath while sharing the same services, permissions, database rules, and generated fetch calls.

apps/myapp/akan.config.ts

CSR web surface: The app opens a Single Page Application client, not a separate native UI rewrite.

Capacitor package: Capacitor wraps the CSR client with Android and iOS project files, app metadata, and device APIs.

Shared business logic: Web and mobile use the same Akan service, signal, document, auth, and generated client helpers.

CSR Web Workflow

Akan mobile work starts as normal UI work. Build the page, component, st state, fetch calls, and dictionary text the same way you would for the web. Then test it as a CSR Single Page Application before packaging it into Android or iOS.

Open a CSR page in the browser

The csr=true search parameter is useful when you want to check SPA navigation, client state, page transition, and mobile-like behavior from the browser. This is faster than opening the simulator for every small UI change.

page/store/product/[productId].tsx

transition: Controls how screens move. Detail pages often use stack; tab roots often use none.

safeArea: Prevents content from colliding with notches, home indicators, and system bars.

topInset / bottomInset: Reserves space for fixed headers, tab bars, keyboards, or bottom actions.

cache: Keeps CSR page state when users return to list or tab screens.

FAQ: Are hybrid apps worse than native apps?

Akan improves the user experience with page transitions, safe-area handling, inset support, CSR page cache, and mobile pageConfig. Device capabilities are not blocked by the hybrid model: Capacitor plugins can bridge camera, Bluetooth, device, haptics, keyboard, safe area, and other native APIs when needed.

Android Packaging Workflow

Use the Android flow when you want to run the CSR client in an emulator/device, verify the native Android project, or prepare Play Store artifacts. Akan prepares the Capacitor project, syncs Android, applies metadata, and builds APK or AAB outputs.

Run on emulator or device: Use startAndroid while developing screens and checking live reload.

Build native package: Use buildAndroid to prepare the Android project and verify the release bundle.

Release for Play Store: Use releaseAndroid with a non-local env and a store-ready assemble type such as aab.

Android commands

Android release needs stable package identity and signing. Keep appId stable after release, increase buildNum for native releases, and prepare release keystore settings for Play Store artifacts.

For device APIs and Capacitor details, use the Capacitor documentation as the native bridge reference. Capacitor Docs

iOS Packaging Workflow

Use the iOS flow when you want to run the CSR client in the iOS simulator/device, verify the Xcode project, or prepare App Store artifacts. Akan prepares the Capacitor project, syncs iOS, applies bundle metadata, and opens or builds the native project.

Run on simulator or device: Use startIos while developing screens and checking live reload.

Build native project: Use buildIos to prepare the iOS project, sync Capacitor, and verify the native build.

Release for App Store: Use releaseIos with a non-local env, then finish signing, archive, and submission in the Apple toolchain.

iOS commands

iOS release needs stable bundle identity and Apple signing setup. Keep appId stable after release, increase buildNum for native releases, and verify provisioning, certificates, and App Store Connect settings before submission.

Mobile App Architecture

CSR Web Workflow

Android Packaging Workflow

iOS Packaging Workflow

Business Service

CSS And Styling