MetatroncubeSoftwareSolutions/Metatron_Student_ERP
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Metatron_Student_ERP/PHASE_13_ANDROID_BUILD_REPORT.md

13 KiB
Raw Blame History

Phase 13: Metatron Student ERP — Android Build Environment Setup and Release APK Report

Date: October 15, 2026
Auditor/Build Engineer: Antigravity Autonomous Agent
Host Architecture: macOS 26.6.2 (Darwin arm64 - Apple Silicon)
Flutter SDK: Flutter 3.47.7 (Channel stable, Dart 3.13.5)
Backend: Odoo 19 Community Edition (metatron_academic) | PostgreSQL 15 (metatron_aca_erp)
Repository Branch: main (HEAD: 921ddc9)

1. Executive Summary and Build Status

An in-depth inspection of the Android build environment and Flutter mobile application (flutter_app/) was performed to evaluate readiness for Android Release APK and Android App Bundle (AAB) builds.

Check / Phase Status Details
Flutter Static Analysis PASSED flutter analyze reported 0 issues
Flutter Unit & Widget Tests PASSED 64 / 64 unit and widget tests passed
Flutter Live Integration Tests PASSED 12 / 12 end-to-end tests passed against live backend
Android Application Configuration VERIFIED App ID, permissions, labels, and network security verified
Environment & HTTPS Validation VERIFIED AppEnvironment enforces HTTPS, rejects localhost in prod
Release Signing Architecture VERIFIED Dynamic key.properties loading with debug fallback
Host Toolchain Check (Java / Android SDK) MISSING No JDK or Android SDK installed on this macOS host
Release APK Build Attempt ENV-BLOCKED Blocked by missing Android SDK toolchain
Release App Bundle (AAB) Attempt ENV-BLOCKED Blocked by missing Android SDK toolchain

2. Host Environment Inspection

Flutter Toolchain Status (flutter doctor -v)

[✓] Flutter (Channel stable, 3.47.7, on macOS 26.6.2 25G83 darwin-arm64, locale en-IN)
    • Flutter version 3.47.7 on channel stable at /opt/homebrew/share/flutter
    • Framework revision abaf9c5237 (2026-10-08 09:51:21 -0700)
    • Engine revision deb287481e
    • Dart version 3.13.5
    • DevTools version 2.60.0

[✗] Android toolchain - develop for Android devices
    ✗ Unable to locate Android SDK.
      Install Android Studio from: https://developer.android.com/studio/index.html
      On first launch it will assist you in installing the Android SDK components.
      (or visit https://flutter.dev/to/macos-android-setup for detailed instructions).
      If the Android SDK has been installed to a custom location, please use
      `flutter config --android-sdk` to update to that location.

[!] Xcode - develop for iOS and macOS
    ✗ Xcode installation is incomplete; full installation required for iOS/macOS.
    ! CocoaPods not installed.

[✓] Chrome - develop for the web
[✓] Connected device (2 available: macOS desktop, Chrome)
[✓] Network resources: Available

Detailed Tool Discovery Results

  1. Java Runtime:
    • /usr/bin/java: Returns The operation couldn’t be completed. Unable to locate a Java Runtime.
    • /usr/libexec/java_home -V: No Java virtual machines installed in /Library/Java/JavaVirtualMachines/.
    • JAVA_HOME: Unset.
  2. Android Studio:
    • /Applications/Android Studio.app: Not installed.
    • ~/Applications/Android Studio.app: Not installed.
  3. Android SDK / Command-Line Tools:
    • ~/Library/Android/sdk: Directory does not exist.
    • /Library/Android: Directory does not exist.
    • /opt/homebrew/share/android-commandlinetools: Not installed.
    • ANDROID_HOME / ANDROID_SDK_ROOT: Unset.

3. Exact Mac Installation and Configuration Steps

Because the host machine currently lacks Java and the Android SDK, the following two standard installation options are available. Choose Option A (GUI - Recommended) or Option B (Headless CLI via Homebrew):

Option A: Android Studio Installation (Recommended)

  1. Download and Install Android Studio:
  2. Launch the Setup Wizard:
    • Open Android Studio. The Setup Wizard will automatically install:
      • Android SDK (API 34 / Android 14)
      • Android SDK Platform-Tools
      • Android SDK Build-Tools (34.0.0+)
      • OpenJDK bundled with Android Studio
  3. Install Android SDK Command-line Tools:
    • In Android Studio, go to Settings (Preferences) -> Languages & Frameworks -> Android SDK -> SDK Tools.
    • Check Android SDK Command-line Tools (latest) and click Apply.
  4. Accept Android Licenses: 
    flutter doctor --android-licenses
    (Press y to accept all SDK licenses).

Option B: Headless Command-Line Installation (via Homebrew)

If you prefer configuring without the full Android Studio IDE:

  1. Install OpenJDK 17 and Command-line Tools via Homebrew:

    brew install openjdk@17
brew install --cask android-commandlinetools

  2. Configure Environment Variables in ~/.zshrc:

    # Add to ~/.zshrc:
export JAVA_HOME="/opt/homebrew/opt/openjdk@17/libexec/openjdk.jdk/Contents/Home"
export ANDROID_HOME="/opt/homebrew/share/android-commandlinetools"
export ANDROID_SDK_ROOT="$ANDROID_HOME"
export PATH="$JAVA_HOME/bin:$ANDROID_HOME/cmdline-tools/latest/bin:$ANDROID_HOME/platform-tools:$PATH"

    Reload shell:

    source ~/.zshrc

  3. Install Required SDK Platforms and Build-Tools via sdkmanager:

    sdkmanager --install "platforms;android-34" "build-tools;34.0.0" "platform-tools"

  4. Link Android SDK Path to Flutter and Accept Licenses:

    flutter config --android-sdk /opt/homebrew/share/android-commandlinetools
flutter doctor --android-licenses

  5. Verify Setup:

    flutter doctor -v

    (Confirmed target: [✓] Android toolchain - develop for Android devices).

4. Android App Configuration Verification

The application configuration in flutter_app/ was inspected and verified against Google Play and production requirements:

1. Application Identity & Versioning

  • Application ID / Package: in.metatroncube.metatron_student_erp (defined in android/app/build.gradle.kts)
  • Application Label: Metatron Student ERP (defined in android/app/src/main/AndroidManifest.xml)
  • Version Name: 1.0.0 (from pubspec.yaml)
  • Version Code: 1 (from pubspec.yaml)
  • Min SDK: 21 (Android 5.0 Lollipop)
  • Target / Compile SDK: 34 (Android 14)
  • JVM Target: Java 17

2. Permissions Declared

  • android.permission.INTERNET (Network communication with Odoo backend)
  • android.permission.ACCESS_NETWORK_STATE (Network connectivity detection)

3. Network Security Configuration (network_security_config.xml)

  • Location: flutter_app/android/app/src/main/res/xml/network_security_config.xml
  • Default Policy: Strict HTTPS enforcement (cleartextTrafficPermitted="false") across all public network traffic.
  • Development Overrides: Cleartext traffic permitted exclusively for 10.0.2.2 (Android emulator loopback) and localhost/127.0.0.1 during debug testing.

4. Release Signing Setup

  • Configured in flutter_app/android/app/build.gradle.kts using dynamic properties loading: 
    val keystoreProperties = Properties()
val keystorePropertiesFile = rootProject.file("key.properties")
if (keystorePropertiesFile.exists()) {
    keystoreProperties.load(FileInputStream(keystorePropertiesFile))
}
  • Security Guardrail:
    • Production builds load credentials from key.properties.
    • key.properties and *.keystore / *.jks are protected in root and app .gitignore.
    • If key.properties is absent, the build safely falls back to signingConfigs.debug only to permit internal compile checks, preventing hard compilation crashes while guaranteeing no debug keystore is mistakenly shipped as a production secret.

5. API Environment Configuration & Security

The Flutter client uses compile-time environment defines (--dart-define) to enforce endpoint security:

// lib/core/api/api_config.dart
enum AppEnvironment { development, staging, production }

Environment Matrix

  1. Production Mode (--dart-define=ENVIRONMENT=production):
    • Requires valid HTTPS endpoint (e.g. --dart-define=API_BASE_URL=https://erp.yourdomain.edu).
    • Rejects unencrypted http:// endpoints.
    • Localhost Fallback Blocked: If API_BASE_URL is omitted, the app does not fall back to localhost:10008; it halts with ApiException(code: NOT_CONFIGURED), prompting configuration via Settings.
  2. Staging Mode (--dart-define=ENVIRONMENT=staging):
    • Points to dedicated staging server (e.g. https://staging-erp.yourdomain.edu).
  3. Development Mode (Default):
    • Automatically routes to http://10.0.2.2:10008 on Android emulator and http://localhost:10008 on macOS/web.

6. Automated Test Results

1. Flutter Static Analysis

  • Command: flutter analyze
  • Result: No issues found! (ran in 1.4s)

2. Flutter Unit & Widget Test Suite

  • Command: flutter test
  • Result: All 64 tests passed!
    • Authentication state, secure token storage, and session lifecycle: PASSED
    • Dashboard screen, metric cards, and academic timeline: PASSED
    • Student profile, contact editing, and verification status: PASSED
    • Attendance session filters, statistics ring, and leave requests: PASSED
    • Timetable period cards and weekday navigation: PASSED
    • Exams schedule and published grades/result views: PASSED
    • Announcements noticeboard, unread badges, and modal sheets: PASSED
    • Finance fees overview, invoice line breakdown, and payment history: PASSED
    • Document upload and certificate request workflows: PASSED

3. Flutter Live End-to-End Integration

  • Command: flutter test test/live_odoo_integration_test.dart
  • Result: All 12 live integration tests passed! (connected against live Odoo 19 backend container)

7. Build Diagnostics & Artifact Paths

Release Build Commands Attempted

  1. Release APK: 
    flutter build apk --release
    Output: [!] No Android SDK found. Try setting the ANDROID_HOME environment variable.
  2. Release App Bundle (AAB): 
    flutter build appbundle --release
    Output: [!] No Android SDK found. Try setting the ANDROID_HOME environment variable.

Target Artifact Locations (Once SDK is Installed)

When the Android SDK toolchain is installed per Section 3, executing the build commands will generate artifacts at the following canonical locations:

Build Type Command Generated Artifact Path Target Use Case
Release APK (Fat) flutter build apk --release flutter_app/build/app/outputs/flutter-apk/app-release.apk Direct sideload testing on physical test devices
Release APK (Split ABI) flutter build apk --release --split-per-abi flutter_app/build/app/outputs/flutter-apk/app-arm64-v8a-release.apk
flutter_app/build/app/outputs/flutter-apk/app-armeabi-v7a-release.apk		 Optimized size for physical device distribution
Android App Bundle flutter build appbundle --release flutter_app/build/app/outputs/bundle/release/app-release.aab Official Google Play Store distribution

8. Step-by-Step Build Execution Commands (Post-Toolchain Setup)

Once OpenJDK 17 and Android SDK 34 are installed:

Step 1: Set Up Private Release Keystore (Production Only)

# 1. Copy template:
cp flutter_app/android/key.properties.example flutter_app/android/key.properties

# 2. Populate key.properties with real values:
cat << 'EOF' > flutter_app/android/key.properties
storePassword=your_secure_keystore_password
keyPassword=your_secure_key_password
keyAlias=metatron_release
storeFile=/absolute/path/to/metatron_release.jks
EOF

Step 2: Build Release APK for Internal Staging QA

cd flutter_app

# Builds release APK configured for staging server
flutter build apk --release \
  --dart-define=ENVIRONMENT=staging \
  --dart-define=API_BASE_URL=https://staging-erp.yourdomain.edu

Step 3: Build Production Android App Bundle for Google Play

cd flutter_app

# Builds signed AAB configured for production server
flutter build appbundle --release \
  --dart-define=ENVIRONMENT=production \
  --dart-define=API_BASE_URL=https://erp.yourdomain.edu

9. Remaining Blockers & Next Actions

  1. Host Toolchain Installation:
    • Execute either Option A (Android Studio) or Option B (Homebrew CLI) as outlined in Section 3 to install OpenJDK 17 and Android SDK 34.
  2. Institutional Production API Domain:
    • Coordinate with the network/systems administrator to confirm the live HTTPS domain (e.g. https://erp.metatroncube.in or institutional domain) and configure DNS/SSL certificates.
  3. Production Signing Keystore:
    • Generate and securely store the production .jks file outside version control and supply key.properties for the final Google Play AAB build.

Report completed. All code changes and configurations remain unpushed and within the workspace.