Getting Started — Mobile App

This guide walks you through setting up your local environment to build and run the Association App on both Android and iOS.

---

Prerequisites

All platforms

Tool	Version	Notes
JDK	17+	Required by Gradle; use SDKMAN or Homebrew
Android Studio	Meerkat (2024.3+)	Includes Gradle toolchain
Kotlin Plugin	2.3.x	Bundled with Android Studio

iOS (macOS only)

Tool	Version	Notes
macOS	Sequoia 15+	Required by Xcode 16
Xcode	16.2+	Install from the Mac App Store
iOS Simulator	iOS 18.2	Install via Xcode → Settings → Platforms

info

iOS builds require a Mac. Android builds can be done on any OS.

---

Clone the Repository

git clone https://github.com/your-org/Association-App-KMP.git
cd Association-App-KMP

---

Project Structure

Association-App-KMP/
├── composeApp/                        # Shared KMP module
│   ├── src/
│   │   ├── commonMain/kotlin/         # All shared code (UI, VMs, data)
│   │   ├── androidMain/kotlin/        # Android entry point & config
│   │   └── iosMain/kotlin/            # iOS-specific DI bootstrap
│   ├── src/androidMain/res/           # Android resources (icons, strings)
│   ├── google-services.json           # Firebase config (Android)
│   └── build.gradle.kts
├── iosApp/
│   ├── iosApp/
│   │   ├── iOSApp.swift               # iOS app entry point
│   │   ├── ContentView.swift          # Compose root view
│   │   └── GoogleService-Info.plist   # Firebase config (iOS)
│   ├── iosApp.xcodeproj/
│   └── Configuration/config.xcconfig  # Build vars (team ID, bundle ID)
├── gradle/
│   └── libs.versions.toml             # Centralised dependency version catalog
├── settings.gradle.kts
└── build.gradle.kts

---

Android Setup

1. Open in Android Studio

1. Open Android Studio
2. Choose Open and select the Association-App-KMP directory
3. Wait for Gradle sync to complete (first sync downloads ~1 GB of dependencies)

2. Configure Firebase (Android)

The composeApp/google-services.json file is required for Firebase Analytics, Crashlytics, and push notifications. Obtain it from the Firebase Console under Project Settings → Your Apps → Android app and place it at:

composeApp/google-services.json

3. Run on Android

Select the composeApp run configuration and choose a device or emulator:

Run → Run 'composeApp'

Or via Gradle:

./gradlew :composeApp:installDebug

Android SDK requirements

Setting	Value
Compile SDK	36
Target SDK	36
Min SDK	24 (Android 7.0)
JVM Target	11

Make sure the required SDK platforms are installed via Android Studio → SDK Manager.

---

iOS Setup

1. Build the KMP Framework

Xcode does not run Gradle directly — the KMP Gradle plugin must compile the shared ComposeApp.framework first. Android Studio (or the terminal) handles this automatically as part of the Xcode build phases.

Open a terminal and run:

./gradlew :composeApp:generateDummyFramework

This only needs to be done once before opening Xcode for the first time, or after cleaning the project.

2. Configure Firebase (iOS)

Place the GoogleService-Info.plist (obtained from Firebase Console → iOS app) at:

iosApp/iosApp/GoogleService-Info.plist

3. Open in Xcode

open iosApp/iosApp.xcodeproj

caution

Always open the .xcodeproj file, not an .xcworkspace. This project does not use CocoaPods, so there is no workspace.

4. Configure Signing

1. Select the iosApp target in Xcode
2. Go to Signing & Capabilities
3. Set Team to your Apple Developer team
4. Xcode will automatically manage provisioning profiles

The Configuration/config.xcconfig file contains the base values:

TEAM_ID = YLHRD57WF7
BUNDLE_ID = com.app2dc.associationapp
MARKETING_VERSION = 2.0.0
CURRENT_PROJECT_VERSION = 135

5. Run on Simulator

Select an iPhone 15 Pro or newer simulator running iOS 18.2+ and press Run (⌘R).

---

Environment / API Configuration

The app's API base URL and feature flags are defined in:

composeApp/src/commonMain/kotlin/.../AppConfig.kt

object AppConfig {
    const val API_BASE_URL = "https://api-dev.theassociationapp.com.au/api"
    const val USE_MOCK_DATA = false
}

Change API_BASE_URL to point at a local backend instance for fully offline development.

---

Dependency Management

All dependency versions are centralised in gradle/libs.versions.toml. To update a library:

1. Bump the version in [versions]
2. Run ./gradlew :composeApp:dependencies to verify resolution
3. Re-sync Android Studio

---

Useful Gradle Tasks

Task	Description
./gradlew :composeApp:assembleDebug	Build debug APK
./gradlew :composeApp:assembleRelease	Build release APK
./gradlew :composeApp:installDebug	Install debug APK on connected device
./gradlew :composeApp:testDebugUnitTest	Run unit tests
./gradlew :composeApp:linkDebugFrameworkIosSimulatorArm64	Build iOS framework for simulator
./gradlew :composeApp:linkReleaseFrameworkIosArm64	Build iOS framework for device

---

Troubleshooting

Problem	Fix
Gradle sync fails on first open	Ensure JDK 17+ is selected in Android Studio → Build Tools → Gradle JDK
google-services.json missing error	Add the file from Firebase Console (see above)
iOS framework not found in Xcode	Run ./gradlew :composeApp:generateDummyFramework then rebuild
Xcode code signing error	Set your developer team in Signing & Capabilities
Push notifications not working in simulator	FCM does not work on iOS simulators; test on a physical device
Cleartext traffic error on Android	Dev builds allow cleartext (usesCleartextTraffic=true); ensure your local API is reachable