📱 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
- 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"intocapacitor.config.json. - Emulator Loopback Defaults: Scaffolding tools often defaulted to
http://10.0.2.2:8000. On a physical phone,10.0.2.2does not exist, causing instant connection refusal. - Empty Scaffolding: Standard
npx cap add androidcreates a blankMainActivity.javawith 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:
- Omit
--server-urland--live-sync. - The framework automatically builds
www/with all precompiled CSS, HTMX, and bridge scripts. capacitor.config.jsoncontains zero remote IP references.- Output binary:
android/app/build/outputs/apk/debug/app-debug.apkand./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:
- Automatically detects your Mac/PC's local Wi-Fi IP (e.g.
192.168.1.100:8000) and injects it intocapacitor.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:
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
PyDataUIWebViewInterceptor.java:- Attached to the WebView via
BridgeWebViewClient.shouldInterceptRequest(...). - Intercepts any request directed to
/_pdu/*or/api/*. - Dispatches in-memory directly to Python via Chaquopy JNI, returning a synthetic
WebResourceResponsewith<1 mslatency. PyDataUIBridgePlugin.java:- Capacitor plugin exposing
window.Capacitor.Plugins.PyDataUIBridge.dispatch(...)to JavaScript. - Module Auto-Discovery in
bridge.py: - Automatically detects active
Appinstances 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
- Instant Client-Side Tab Switcher:
- Toggles visibility classes (
hidden/block) on.tab-panelcontainers in0 ms. - Automatically preserves the active tab across HTMX partial re-renders via
localStorage. - Payload Scoping:
- Automatically strips legacy blanket
#pdu-rootincludes on client actions, keeping network and JNI payloads minimal (~0–12 bytes). - Micro-Latency Telemetry:
- Measures and logs exact round-trip times for every user interaction:
- Offline Resilience & Error Toast:
- Catches network interruptions and displays a smooth in-app toast (
⚡ Offline Mode — Local Cache Active) instead of letting the WebView display a crash screen. - Runtime Backend Host Switcher:
- Allows users or testers to switch between Offline Mode and a Remote Server URL at runtime:
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
}
"server" block).
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.