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.

Akan CSR pages can apply mobile-style page transitions from pageConfig. Use the demos below to compare the four transition presets in a browser CSR environment before packaging the same pages into a native shell.

bottomup

Good for modal-like flows or pages that should rise from the bottom.

fade

Keeps the movement calm when the screen context changes without hierarchy.

scale

Adds a light zoom motion for focused entry into the next page.

stack

Works well for detail pages that push over a list or parent screen.

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 local prerequisites

apps/myapp/package.json

Declare the Capacitor packages that your app uses in the app package.json with "*" versions. This lets Capacitor sync discover and link native plugins from the app project, while the workspace controls the actual installed versions.

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

For iOS, keep the same app-level Capacitor dependencies in apps/myapp/package.json before running start-ios or build-ios. If a plugin is missing there, the JavaScript module can load while the native iOS plugin is not linked, causing "plugin is not implemented" errors in the simulator.

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.

Native Build Troubleshooting

Most mobile build issues come from native toolchain setup, plugin sync state, or confusing local mode with release mode. Check these items before debugging page code.

Android SDK: Set ANDROID_HOME or android/local.properties so Gradle can find the SDK. Start an emulator or connect a device before running start-android.

Java 21: Capacitor Android builds require a Java 21 compiler. If you see invalid source release: 21, update JAVA_HOME and PATH to JDK 21.

Plugin sync: After adding or removing Capacitor packages, rerun start-ios/start-android or a build command so native projects regenerate plugin files.

iOS plugins: If Safari console says a plugin is not implemented, the JavaScript module loaded but the native plugin was not linked. Check app package.json and rerun iOS sync/build.

Safe area: safeArea handles device system bars; topInset and bottomInset handle app UI such as nav bars, tabs, and fixed bottom actions.

Common local fixes

Local mode uses a live server.url and does not package built CSR assets into the native app. Release mode builds CSR output first and copies the target HTML into the Capacitor webDir.

Mobile App Architecture

CSR Web Workflow

Android Packaging Workflow

iOS Packaging Workflow

Native Build Troubleshooting

Business Service

CSS And Styling