Android Development Setup

Repository: ngwenya-android
Submodule: ngwenya-front/mobile/android
Requirements: Android Studio Ladybug 2024.2+, JDK 17, Apple Silicon Mac
Tested on: M1 Max, 64 GB RAM, macOS 15

Quick Start

# 1. Clone (or init submodule)
cd /path/to/ngwenya-front
git submodule update --init mobile/android
cd mobile/android

# 2. Open in Android Studio
open -a "Android Studio" .

# 3. Wait for Gradle sync → Select emulator → ▶ Run

Prerequisites

Install Android Studio

1. Download the Mac (Apple Silicon) .dmg from developer.android.com/studio
2. Drag to /Applications → Launch
3. Complete the Setup Wizard:
   • Install Type: Standard
   • Accept all SDK licenses
   • Skip Intel HAXM (Apple Silicon uses Hypervisor.framework natively)

Configure PATH

Add to ~/.zshrc:

export ANDROID_HOME=$HOME/Library/Android/sdk
export PATH=$ANDROID_HOME/emulator:$ANDROID_HOME/platform-tools:$PATH

Then source ~/.zshrc and verify:

adb --version   # Android Debug Bridge version 1.0.41+
emulator -version  # Android emulator version 35.x

Install SDK Components

Settings (⌘,) → Languages & Frameworks → Android SDK:

Open the Project

Step 1: Clone

# Via submodule
cd /path/to/ngwenya-front
git submodule update --init mobile/android

# Or standalone
git clone https://github.com/mall-dev/ngwenya-android.git

Step 2: Open in Android Studio

open -a "Android Studio" /path/to/mobile/android

Click Trust Project when prompted.

Step 3: Gradle Sync

Android Studio triggers Gradle sync automatically. Look for:

• ✅ "Gradle sync finished" in the status bar
• ~200 MB of dependencies downloaded on first run

If it doesn't auto-trigger: File → Sync Project with Gradle Files (⌘⇧O)

Step 4: Verify Project Structure

The Project pane (Android view) should show:

app/
├── manifests/
│   └── AndroidManifest.xml
├── java/com.mallnline.ngwenya/
│   ├── MainActivity.kt
│   ├── NgwenyaApp.kt
│   ├── bridge/WebViewBridge.kt
│   ├── services/NgwenyaFirebaseService.kt
│   └── ui/Screens.kt
├── res/values/
│   └── themes.xml
└── build.gradle.kts

Build Configuration

The project uses Gradle Kotlin DSL with these key settings:

Key Dependencies

Gradle Performance (M1 Max)

The gradle.properties is tuned for your hardware:

org.gradle.jvmargs=-Xmx4096m -Dfile.encoding=UTF-8
org.gradle.parallel=true
org.gradle.caching=true

Expected build times on M1 Max / 64 GB:

• First build: ~90 seconds
• Incremental builds: ~5-10 seconds
• Clean rebuild: ~45 seconds

Configure Firebase (FCM)

Firebase Cloud Messaging requires a google-services.json file.

Step 1: Create Firebase Project

1. Go to Firebase Console
2. Add Project → Name: Ngwenya → Create

Step 2: Register Android App

1. Click Add App → Android
2. Package name: com.mallnline.ngwenya
3. App nickname: Ngwenya Android
4. Click Register App

Step 3: Download Config

Download google-services.json → place in app/ directory:

cp ~/Downloads/google-services.json app/

Step 4: Add Plugin

Update build.gradle.kts (root):

plugins {
    // ...existing plugins...
    id("com.google.gms.google-services") version "4.4.2" apply false
}

Update app/build.gradle.kts:

plugins {
    // ...existing plugins...
    id("com.google.gms.google-services")
}

Step 5: Re-sync Gradle

File → Sync Project with Gradle Files

Running Without Firebase

To build without push notifications (e.g., for pure UI development), comment out the Firebase dependencies in app/build.gradle.kts:

// implementation(platform("com.google.firebase:firebase-bom:33.7.0"))
// implementation("com.google.firebase:firebase-messaging-ktx")

The app compiles and runs — push features are non-functional.

Backend Configuration

Once FCM is configured, set these environment variables in the alerts subgraph:

FCM_PROJECT_ID=your-firebase-project-id
FCM_CLIENT_EMAIL=firebase-adminsdk-xxx@your-project.iam.gserviceaccount.com
FCM_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----"

See Mobile Push Infrastructure for the full backend dispatch architecture.

Create an Emulator

Important: Use ARM64 Images on Apple Silicon

Critical: Select arm64-v8a system images. x86_64 images use Rosetta 2 translation and run 5-10x slower.

Step-by-Step

1. Tools → Device Manager → Create Virtual Device
2. Select hardware:

3. Select system image: VanillaIceCream (API 35) — ABI must show arm64-v8a ✅
4. Configure:

5. Click Finish → ▶ to launch

With 64 GB RAM, you can run 2-3 emulators simultaneously. Each instance uses ~2-3 GB.

Run the App

On Emulator

1. Select emulator from device dropdown
2. Press ▶ Run (⌃R) or ./gradlew :app:installDebug

On Physical Device

1. Enable Developer Options: Settings → About phone → tap Build number 7 times
2. Enable USB Debugging in Developer Options
3. Connect via USB-C → Accept debugging prompt → select device → ▶ Run

Wireless Debugging

adb tcpip 5555
adb connect 192.168.1.XXX:5555
# Disconnect USB — you're wireless

Verify

You should see:

• ✅ Material3 bottom navigation with 6 tabs
• ✅ Notification permission dialog (Android 13+)
• ✅ Logcat: [NgwenyaApp] Notification channel created: ngwenya_default

Local Backend Development

Emulator → Host Machine

The Android Emulator maps 10.0.2.2 to your Mac's localhost:

// In NgwenyaApp.kt or a config file:
const val API_URL = "http://10.0.2.2:30000/graphql"  // Gateway
const val WEB_URL = "http://10.0.2.2:5173"           // Vite dev server

Physical Device → Mac

Both must be on the same Wi-Fi. Use your Mac's IP:

const val API_URL = "http://192.168.1.XXX:30000/graphql"
const val WEB_URL = "http://192.168.1.XXX:5173"

Cleartext Traffic (HTTP)

For local development with HTTP, create app/src/main/res/xml/network_security_config.xml:

<?xml version="1.0" encoding="utf-8"?>
<network-security-config>
    <domain-config cleartextTrafficPermitted="true">
        <domain includeSubdomains="false">10.0.2.2</domain>
        <domain includeSubdomains="false">192.168.1.0</domain>
    </domain-config>
</network-security-config>

Reference in AndroidManifest.xml:

<application android:networkSecurityConfig="@xml/network_security_config" ... >

WebView Bridge Testing

Enable WebView Debugging

Already enabled in debug builds via:

WebView.setWebContentsDebuggingEnabled(BuildConfig.DEBUG)

Chrome DevTools

1. Open Chrome on Mac: chrome://inspect/#devices
2. Your emulator/device WebView appears under Remote Target
3. Click inspect to open DevTools

Test Injected Globals

In Chrome DevTools console:

window.__NGWENYA_TOKEN__    // → JWT string
window.__NGWENYA_PLATFORM__ // → "android"

Test Bridge Interface

NgwenyaBridge.navigate(JSON.stringify({ route: "/cart" }));
// Check Logcat for: [WebViewBridge] Navigate: /cart

The frontend detects this context via mobileUtils.ts — isMobileWebView(), getMobilePlatform(), and sendBridgeMessage().

Build Variants

# Debug APK
./gradlew :app:assembleDebug
# → app/build/outputs/apk/debug/app-debug.apk

# Release AAB (Play Store)
./gradlew :app:bundleRelease

Useful Commands

# Clean + rebuild
./gradlew clean assembleDebug

# Run unit tests
./gradlew test

# Run instrumented tests (requires emulator)
./gradlew connectedAndroidTest

# Lint report
./gradlew lint
# → app/build/reports/lint-results-debug.html

# View logs (filtered to our app)
adb logcat --pid=$(adb shell pidof com.mallnline.ngwenya.debug)

# Direct install
adb install app/build/outputs/apk/debug/app-debug.apk

Troubleshooting

Related

• Mobile Push Infrastructure — In-house APNs/FCM dispatch and backend TCP event wiring
• Mobile SDK Architecture — KMP shared module and OIDC/PKCE auth adapters
• iOS Development Setup — Companion guide for the iOS app
• MFA & Passkeys — Additional auth factors for native apps
• User Guide: Notifications — Visitor-facing notification management