Flutter Android Build System — Authoritative Reference

When to Load

• ANY Flutter project creating/editing android/app/build.gradle.kts
• ANY release/deployment task
• ANY CI/CD pipeline setup
• When flutter build apk fails with native errors

1. Namespace vs ApplicationId — The #1 Crash Source

From developer.android.com (Official AGP Docs)

android {
    namespace = "com.example.app"  // R class, BuildConfig, manifest .ClassName resolution
    defaultConfig {
        applicationId = "com.example.app"  // Unique ID on device + Play Store
    }
}

CRITICAL RULE: namespace MUST equal the Kotlin package of MainActivity.kt.

AndroidManifest:  android:name=".MainActivity"
         ↓ resolved relative to namespace
Android looks for: {namespace}.MainActivity
         ↓
If namespace ≠ Kotlin package → ClassNotFoundException → CRASH BEFORE SPLASH

Verification (MANDATORY before every build)

NS=$(grep -oP 'namespace\s*=\s*"\K[^"]+' android/app/build.gradle.kts)
PKG=$(grep -oP '^package\s+\K\S+' android/app/src/main/kotlin/**/MainActivity.kt)
[ "$NS" = "$PKG" ] || { echo "BLOCKED: namespace ≠ package"; exit 1; }

2. ProGuard / R8 — The Isar Incompatibility

From developer.android.com

buildTypes {
    release {
        isMinifyEnabled = true   // Enables R8 code shrinking
        isShrinkResources = true // Shrinks resources
        proguardFiles(
            getDefaultProguardFile("proguard-android-optimize.txt"),
            "proguard-rules.pro"
        )
    }
}

⚠️ Isar + isMinifyEnabled = CRASH

R8 strips classes NOT directly referenced in Java/Kotlin. Isar adapter classes (CachedSessionAdapter, etc.) are loaded REFLECTIVELY by native code → stripped → IsarError → crash.

Rule: If isar: in pubspec.yaml, isMinifyEnabled MUST be false OR add explicit -keep rules.

Isar ProGuard Keep Rules (from isar.dev)

# Isar native bindings — DO NOT REMOVE
-keep class io.isar.** { *; }
-keepclassmembers class * {
    @io.isar.annotations.** <fields>;
}

# Isar generated adapters — loaded reflectively
-keep class * extends io.isar.IsarCollectionSchema { *; }

# If using isar_flutter_libs
-keep class com.example.isar_flutter_libs.** { *; }
-dontwarn com.example.isar_flutter_libs.**

Full ProGuard Rules for Flutter + Isar

# ─── Flutter Engine ───
-keep class io.flutter.app.** { *; }
-keep class io.flutter.plugin.** { *; }
-keep class io.flutter.embedding.** { *; }
-keep class io.flutter.** { *; }

# ─── Isar ───
-keep class io.isar.** { *; }
-keepclassmembers class * {
    @io.isar.annotations.** <fields>;
}
-keep class * extends io.isar.IsarCollectionSchema { *; }

# ─── Dio / OkHttp ───
-keep class okhttp3.** { *; }
-dontwarn okhttp3.**
-dontwarn okio.**

# ─── App Code ───
-keep class com.jahfali.hermex_android.** { *; }
-keepattributes Signature
-keepattributes *Annotation*

# ─── Secure Storage ───
-keep class com.it_nomads.fluttersecurestorage.** { *; }

3. AGP Version Compatibility

Fix: isar_flutter_libs + AGP 8.8+

The gradle.projectsEvaluated hook below fixes the manifest package attribute rejection. It does NOT fix the lStar resource incompatibility — that requires either an AGP 8+ compatible Isar fork or deferring Isar entirely.

// android/build.gradle.kts (root)
gradle.projectsEvaluated {
    subprojects {
        if (name == "isar_flutter_libs") {
            // Disable verifyReleaseResources
            tasks.matching { it.name.contains("verifyReleaseResources") }.configureEach {
                enabled = false
            }
            // Strip package attribute from AndroidManifest
            tasks.matching { it.name.startsWith("process") && it.name.contains("Manifest") }.configureEach {
                doFirst {
                    val mf = file("${project.projectDir}/src/main/AndroidManifest.xml")
                    if (mf.exists() && mf.readText().contains("package=")) {
                        mf.writeText(mf.readText().replace(Regex("""package="[^"]*"\s*"""), ""))
                    }
                }
            }
        }
    }
}

4. Standard build.gradle.kts Template

// android/app/build.gradle.kts
plugins {
    id("com.android.application")
    id("kotlin-android")
    id("dev.flutter.flutter-gradle-plugin")
}

android {
    namespace = "com.jahfali.hermex_android"  // ← MUST match MainActivity.kt package!
    compileSdk = flutter.compileSdkVersion
    ndkVersion = flutter.ndkVersion

    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_17
        targetCompatibility = JavaVersion.VERSION_17
    }

    kotlinOptions {
        jvmTarget = JavaVersion.VERSION_17.toString()
    }

    defaultConfig {
        applicationId = "com.jahfali.hermex_android"
        minSdk = 26
        targetSdk = 34
        versionCode = flutter.versionCode
        versionName = flutter.versionName
    }

    buildTypes {
        debug {
            isDebuggable = true
            applicationIdSuffix = ".debug"
        }
        release {
            isDebuggable = false
            isMinifyEnabled = false  // OFF if Isar in pubspec.yaml
            isShrinkResources = false
            proguardFiles(
                getDefaultProguardFile("proguard-android-optimize.txt"),
                "proguard-rules.pro"
            )
            signingConfig = signingConfigs.getByName("debug")
        }
    }
}

flutter {
    source = "../.."
}

5. Network Security Config — LL-027 CRITICAL

The Rule

For apps connecting to local Hermes servers via HTTP:

<!-- android/app/src/main/res/xml/network_security_config.xml -->
<network-security-config>
    <!-- Permit cleartext for local servers — Dart validates RFC 1918 only -->
    <base-config cleartextTrafficPermitted="true">
        <trust-anchors>
            <certificates src="system" />
        </trust-anchors>
    </base-config>
</network-security-config>

Why: Android's <domain> element does NOT support CIDR notation. If you whitelist specific IPs (192.168.1.1, 192.168.0.1), any other private IP (192.168.8.80, 10.0.0.50) is silently blocked. The connection times out with zero network activity reaching the server.

LL-027: 2+ hours lost debugging macOS firewall, port binding, gateway restarts — the actual bug was cleartextTrafficPermitted="false" in base-config blocking 192.168.8.80.

name: Build APK
on:
  push:
    branches: [main]
  workflow_dispatch:

permissions:
  contents: write

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Android Preflight Check
        run: bash scripts/android-preflight.sh
      
      - uses: subosito/flutter-action@v2
        with:
          flutter-version: '3.41.6'
          channel: 'stable'
          cache: true
      
      - run: flutter pub get
      - run: flutter analyze
      - run: flutter test
      - run: flutter build apk --release
      
      - name: Publish to Releases
        uses: softprops/action-gh-release@v2
        with:
          tag_name: latest
          name: "Latest APK Build"
          files: build/app/outputs/flutter-apk/app-release.apk
          make_latest: true

6. Common Failures — Quick Reference

7. macOS Firewall — LL-028 CRITICAL

The Problem

macOS Application Firewall (socketfilterfw) blocks incoming connections to Python binaries it doesn't recognize. Hermes uses Python from uv's cache path which is NOT in the default firewall allow list.

Symptoms

• curl localhost:8642 → 200 ✓
• Phone/external → 192.168.x.x:8642 → timeout ✗
• lsof -i :8642 shows *:8642 (correctly bound)
• But external connections silently dropped at OS level

Fix

sudo /usr/libexec/ApplicationFirewall/socketfilterfw --add \
  ~/.local/share/uv/python/cpython-3.11*-macos-aarch64-none/bin/python3.11
sudo /usr/libexec/ApplicationFirewall/socketfilterfw --unblockapp \
  ~/.local/share/uv/python/cpython-3.11*-macos-aarch64-none/bin/python3.11

Or GUI: System Settings → Network → Firewall → Options → + → add Python binary.

Prevention

After any hermes update or Python upgrade, verify the new binary is allowed. The path changes with each Python patch version.

8. Bash Portability — set -e + Arithmetic (CI)

Pitfall

set -euo pipefail
PASS=0
((PASS++))  # GNU bash: 0++ = 0 (false) → exit 1 → set -e kills script

GNU bash (Ubuntu CI) and macOS bash handle arithmetic exit codes differently.

Fix

_inc() { eval "$1=\$((\${$1} + 1))"; }
_inc PASS  # Always returns exit 0

Never use ((VAR++)) with set -e in portable scripts.

9. Dart/Riverpod State Mutation — LL-029

When building chat/message history in Riverpod providers:

// ❌ WRONG: history snapshot taken AFTER mutation → duplicate messages
state = state.copyWith(messages: [...state.messages, userMessage]);
final history = _buildHistory();  // contains the just-added userMessage!

// ✅ RIGHT: snapshot BEFORE mutation
final history = _buildHistory();  // only previous messages
state = state.copyWith(messages: [...state.messages, userMessage]);

This causes: Two consecutive role: user messages in API requests → Hermes API rejects (strict alternation enforcement).

Prevention: Unit test verifying exactly one role: user per send. PR checklist: "Does state.copyWith() precede a history snapshot?"

7. Preflight Verification (run before every build)

#!/bin/bash
# scripts/android-preflight.sh
# MoA-audited: LL-024, LL-025 enforcement

set -e
echo "=== Android Preflight Verification ==="

# Gate 1: namespace == MainActivity.kt package
NS=$(grep -oP 'namespace\s*=\s*"\K[^"]+' android/app/build.gradle.kts 2>/dev/null || echo "")
PKG=$(find android/app/src/main/kotlin -name "*.kt" -exec grep -oP '^package\s+\K\S+' {} \; 2>/dev/null || echo "")
if [ -z "$NS" ] || [ -z "$PKG" ]; then
    echo "❌ GATE 1 FAILED: Cannot extract namespace or package"
    exit 1
fi
if [ "$NS" != "$PKG" ]; then
    echo "❌ GATE 1 FAILED: namespace='$NS' ≠ package='$PKG'"
    echo "   Fix: Make namespace in build.gradle.kts match MainActivity.kt package."
    exit 1
fi
echo "✅ Gate 1: namespace == package ($NS)"

# Gate 2: Isar + isMinifyEnabled
if grep -q 'isar:' pubspec.yaml 2>/dev/null; then
    if grep -q 'isMinifyEnabled\s*=\s*true' android/app/build.gradle.kts 2>/dev/null; then
        echo "❌ GATE 2 FAILED: Isar detected + isMinifyEnabled=true"
        echo "   Fix: Set isMinifyEnabled=false or add -keep rules from isar.dev."
        exit 1
    fi
    echo "✅ Gate 2: Isar + ProGuard compatible (isMinifyEnabled=false)"
fi

# Gate 3: applicationId consistency
APP_ID=$(grep -oP 'applicationId\s*=\s*"\K[^"]+' android/app/build.gradle.kts 2>/dev/null || echo "")
if [ -n "$APP_ID" ] && [ "$APP_ID" != "$NS" ]; then
    echo "⚠️  Gate 3 WARNING: applicationId='$APP_ID' ≠ namespace='$NS'"
    echo "   Valid but unusual. Verify intent."
else
    echo "✅ Gate 3: applicationId consistent"
fi

# Gate 4: AGP + isar_flutter_libs compat
if grep -q 'isar_flutter_libs' pubspec.yaml 2>/dev/null; then
    if ! grep -q 'gradle.projectsEvaluated' android/build.gradle.kts 2>/dev/null; then
        echo "❌ GATE 4 FAILED: isar_flutter_libs detected but no AGP 8.8+ compat hook"
        echo "   Fix: Add gradle.projectsEvaluated block from flutter-android-build-system §3."
        exit 1
    fi
    echo "✅ Gate 4: isar_flutter_libs AGP compat hook present"
fi

echo ""
echo "=== ALL GATES PASSED — Safe to build ==="

Sources (MoA-Verified)

• https://developer.android.com/build/gradle-build-overview
• https://isar.dev (ProGuard keep rules for Isar)
• https://docs.flutter.dev/deployment/android
• https://developer.android.com/build/releases/past-releases (AGP release notes)

10. Dart-Side HTTP Validation — isLocalNetwork() Pattern (LL-030)

The Pattern

For apps connecting to servers with user-provided URLs, enforce HTTP-only-on-local-network at the Dart level (complementing network_security_config.xml):

static bool isLocalNetwork(String url) {
  final uri = Uri.tryParse(_normalizeUrl(url));
  if (uri == null) return false;
  final host = uri.host.toLowerCase();

  if (host == 'localhost' || host == '127.0.0.1') return true;
  if (host.startsWith('192.168.')) return true;
  if (host.startsWith('10.')) return true;
  if (host.startsWith('172.') && _isPrivate172(host)) return true;
  // Tailscale / CGNAT: 100.64.0.0/10
  if (host.startsWith('100.') && _secondOctetBetween(host, 64, 127)) return true;
  return false;
}

Key ranges:

• RFC 1918: 192.168.0.0/16, 10.0.0.0/8, 172.16.0.0/12
• Tailscale/CGNAT: 100.64.0.0/10 (second octet 64–127)

Anti-Pitfall: Duplicated _validateUrl()

Do NOT duplicate the validation logic in both the UI form validator and the repository layer. One static validateUrl() method on the repository, called by both:

// ✅ Right: UI delegates to repository
String? _validateUrl(String? value) {
  return ServerRepository.validateUrl(value?.trim() ?? '');
}

// ❌ Wrong: copy-pasted validation logic in ConnectionScreen AND ServerRepository

Duplication caused a real bug where the repository's isLocalNetwork() was fixed but the UI validator appeared stale — actually a hot-reload build-cache issue (see §6 Quick Reference), but the structural duplication made debugging harder.

See references/is-local-network-validation.md for the full audit trace including all call sites and test cases.

11. Dart HttpClient + UTF-8 Encoding (SSE/REST)

Pitfall: request.write() on Android with non-ASCII

HttpClientRequest.write(String) fails on some Android versions when the body contains non-ASCII characters (Arabic, CJK, emoji). Error: Invalid argument (string): Contains invalid characters.

Fix — use bytes, not strings:

// Fails on Android:
request.write(jsonEncode(body));

// Always works:
request.headers.set('Content-Type', 'application/json; charset=utf-8');
final bodyBytes = utf8.encode(jsonEncode(body));
request.contentLength = bodyBytes.length;
request.add(bodyBytes);

This applies to SSE streaming (sse_client.dart) and any REST client using dart:io HttpClient.

12. AAB Build + Play Store Submission (LL-034)

The Arabic-Indic Numeral Problem

On macOS with Arabic locale (ar_SA), flutter build appbundle --release fails with:

FAILURE: Invalid dex file indices, expecting file 'classes٢.dex' but found 'classes2.dex'

Root cause: Java's String.format("%d", ...) and Integer.toString() respect the system locale. On ar_SA, numbers are formatted with Arabic-Indic digits (٠١٢٣٤٥٦٧٨٩). D8/R8 generates .dex files with these numerals, but AGP's bundletool expects ASCII digits (0-9).

The error direction (٢→2 vs 2→٢) depends on which build step cached which numeral style first. Both directions have been observed.

Why APK works but AAB fails: flutter build apk uses a different packaging pipeline (apkbuilder) that is locale-agnostic. Only bundleRelease → bundletool triggers the mismatch.

Fix (Three Steps — ALL Required)

# 1. Purge stale Gradle cache with wrong-numeral dex files
rm -rf build android/.gradle android/app/build

# 2. Force C locale (ASCII) for shell, AND English locale for JVM
LC_ALL=C JAVA_TOOL_OPTIONS="-Duser.language=en -Duser.country=US" \
  flutter build appbundle --release

# 3. Verify
ls -lh build/app/outputs/bundle/release/app-release.aab

On CI (Ubuntu): Not affected — CI always runs with LANG=C.UTF-8 or en_US.UTF-8. This is a macOS + Arabic-locale-specific issue.

Version Code Management

Play Store requires monotonically increasing versionCode. Best practice: manage in one place:

// android/app/build.gradle.kts
defaultConfig {
    versionCode = flutter.versionCode   // reads from pubspec.yaml
    versionName = flutter.versionName
}

# pubspec.yaml — single source of truth
version: 0.2.0+6   # +6 = versionCode

Play Store Checklist

See references/playstore-submission-checklist.md for the full submission workflow including:

• Privacy policy hosting (GitHub Pages from /docs)
• AAB upload vs APK
• Store listing asset requirements (screenshots, feature graphic, icon)
• Content rating questionnaire
• Data safety section
• App signing key backup