Skip to content

📱 Native Offline Parity & Standalone Mobile Architecture

PyDataUI provides React Native-grade offline parity for mobile applications. You can compile fully self-contained Android APKs and iOS bundles that run 100% offline in Airplane Mode, cold-start in <150 ms, and execute state interactions directly in-process with zero TCP loopback sockets.


1. Problem Statement: Why "Web Page Not Available" Occurred

In traditional hybrid frameworks (and early Capacitor builds), mobile scaffolding assumes a live development server running on the developer's laptop:

flowchart TD
    subgraph Legacy_Flawed_Model["Legacy Model (Wi-Fi Dependent)"]
        Mac["Developer Laptop\n(192.168.31.205:8000)"]
        Phone["Physical Phone\n(Installs APK)"]
        CapConfig["capacitor.config.json\nserver.url: http://192.168.31.205:8000"]
        Err["💥 net::ERR_CONNECTION_REFUSED\n'Web Page Not Available'"]

        Phone --> CapConfig
        CapConfig -->|Attempts connection| Mac
        Mac -.->|Laptop off / 4G / Airplane Mode| Err
    end

The Three Framework Bottlenecks

  1. Unconditional LAN IP Injection: Build tools would automatically detect the local machine's Wi-Fi IP and hardcode "url": "http://192.168.x.x:8000" into capacitor.config.json.
  2. Emulator Loopback Defaults: Scaffolding tools often defaulted to http://10.0.2.2:8000. On a physical phone, 10.0.2.2 does not exist, causing instant connection refusal.
  3. Empty Scaffolding: Standard npx cap add android creates a blank MainActivity.java with no in-process dispatcher or offline request interceptor.

2. Target Architecture: React Native Parity

In React Native and Flutter, Standalone/Release Mode and Live-Sync Dev Mode are strictly decoupled:

flowchart LR
    subgraph Mode_A["Mode A: Standalone Mode (Default)"]
        APK1["Standalone APK / IPA"]
        Assets1["assets/public/index.html\n(Bundled in device flash storage)"]
        Scheme1["https://localhost/\n(<150 ms cold start)"]
        JNI1["In-Process JNI Bridge\n(Chaquopy ASGI Dispatcher)"]

        APK1 --> Assets1 --> Scheme1 --> JNI1
    end

    subgraph Mode_B["Mode B: Live-Sync Mode (Dev)"]
        APK2["Dev APK"]
        ServerURL["capacitor.config.json\nserver.url: http://192.168.x.x:8000"]
        Laptop["Developer Machine\n(Hot Reload & Instant Iteration)"]

        APK2 --> ServerURL --> Laptop
    end
Feature Mode A: Standalone (Default) Mode B: Live-Sync (Dev)
External Network Required ❌ Zero (100% Offline & Airplane Mode) ✅ Requires same local Wi-Fi or tunnel
Asset Location Bundled inside APK (assets/public/) Served live from laptop PyDataUI port
Capacitor Scheme https://localhost/ http://192.168.x.x:8000
Cold Start < 150 ms (from device flash memory) ~800–2,000 ms (network handshake)
State Handling In-Process JNI Bridge (PyDataUIWebViewInterceptor) TCP Loopback Socket / HTTP Requests
Use Case Production distribution, Store releases, Field apps Fast local UI iteration, Hot-reloading

3. CLI Commands & Workflow

A. Build a 100% Offline Standalone APK (Default)

To build a standalone APK ready for distribution or offline testing:

pydataui mobile build --platform android
  • Omit --server-url and --live-sync.
  • The framework automatically builds www/ with all precompiled CSS, HTMX, and bridge scripts.
  • capacitor.config.json contains zero remote IP references.
  • Output binary: android/app/build/outputs/apk/debug/app-debug.apk and ./app-debug.apk.

B. Build for Live Wi-Fi Sync (Development Mode)

If you are actively styling your app and want changes to reflect on your physical phone over Wi-Fi without rebuilding the APK:

pydataui mobile build --platform android --live-sync
  • Automatically detects your Mac/PC's local Wi-Fi IP (e.g. 192.168.1.100:8000) and injects it into capacitor.config.json.
  • Requires phone and computer to be connected to the same Wi-Fi network.

C. Build Against a Remote Production API

If your mobile app connects to a cloud-hosted PyDataUI backend:

pydataui mobile build --platform android --server-url https://api.mycompany.com

4. In-Process JNI Bridge Architecture

To eliminate the need for a background Python daemon process or TCP loopback sockets on Android, PyDataUI provides native Java interceptors:

sequenceDiagram
    participant WebView as Android WebView (Chromium)
    participant Interceptor as PyDataUIWebViewInterceptor (Java)
    participant Plugin as PyDataUIBridgePlugin (Capacitor)
    participant JNI as Chaquopy JNI Runtime
    participant App as PyDataUI ASGI Engine (Python)

    WebView->>Interceptor: Request /_pdu/event/State/method
    Note over Interceptor: Intercepts request before network socket opens
    Interceptor->>JNI: callAttr("dispatch_in_process", method, url, headers, body)
    JNI->>App: dispatch_request(method, path, headers, body)
    App-->>JNI: (status_code, body_bytes, headers)
    JNI-->>Interceptor: PyObject result
    Interceptor-->>WebView: WebResourceResponse (200 OK, HTML fragment)

Components

  1. PyDataUIWebViewInterceptor.java:
  2. Attached to the WebView via BridgeWebViewClient.shouldInterceptRequest(...).
  3. Intercepts any request directed to /_pdu/* or /api/*.
  4. Dispatches in-memory directly to Python via Chaquopy JNI, returning a synthetic WebResourceResponse with <1 ms latency.
  5. PyDataUIBridgePlugin.java:
  6. Capacitor plugin exposing window.Capacitor.Plugins.PyDataUIBridge.dispatch(...) to JavaScript.
  7. Module Auto-Discovery in bridge.py:
  8. Automatically detects active App instances across standard entry points (mobile_app, app, main), ensuring zero configuration when launched inside Android.

5. Client-Side Bridge (pdu-bridge.js)

The client-side bridge script (pydataui/styling/js/pdu-bridge.js) guarantees sub-16 ms UI interactions:

Features

  1. Instant Client-Side Tab Switcher:
    window.switchTabMobile('transfers');
    
  2. Toggles visibility classes (hidden / block) on .tab-panel containers in 0 ms.
  3. Automatically preserves the active tab across HTMX partial re-renders via localStorage.
  4. Payload Scoping:
  5. Automatically strips legacy blanket #pdu-root includes on client actions, keeping network and JNI payloads minimal (~0–12 bytes).
  6. Micro-Latency Telemetry:
  7. Measures and logs exact round-trip times for every user interaction:
    ⚡ [PyDataUI] Action round-trip: 12ms
    
  8. Offline Resilience & Error Toast:
  9. Catches network interruptions and displays a smooth in-app toast (⚡ Offline Mode — Local Cache Active) instead of letting the WebView display a crash screen.
  10. Runtime Backend Host Switcher:
  11. Allows users or testers to switch between Offline Mode and a Remote Server URL at runtime:
    window.promptBackendConfig();
    

6. How to Verify a Standalone APK

After building your APK, verify that zero remote IP addresses leaked into the bundle:

# 1. Inspect the embedded Capacitor configuration inside the APK
unzip -p app-debug.apk assets/capacitor.config.json

Expected Standalone Output:

{
  "appId": "com.pydataui.app",
  "appName": "PyDataUI App",
  "webDir": "www",
  "bundledWebRuntime": false
}
(Notice the complete absence of a "server" block).

# 2. Verify all offline public assets are bundled
unzip -l app-debug.apk "assets/public/*"

Expected Assets: - assets/public/index.html (~100 KB pre-rendered app shell) - assets/public/pydataui.css (precompiled stylesheet) - assets/public/htmx.min.js (offline interaction runtime) - assets/public/pdu-bridge.js (client bridge)


7. Installing Directly on Device via ADB

# List connected devices
adb devices

# Install standalone APK directly
adb install -r android/app/build/outputs/apk/debug/app-debug.apk

# Launch app
adb shell am start -n com.pydataui.app/.MainActivity

Turn on Airplane Mode on your physical phone and open the app: * App opens instantly (<150 ms). * All styles, navigation, tabs, and client interactions function cleanly without an internet connection.