Project Structure & Gradle Explained

Why this matters

When you open an Android project for the first time, the long list of folders can feel overwhelming. But almost all your work happens in just a few places. Once you understand them, navigating any Android project becomes easy.

The key folders and files

• app/src/main/java/ (or kotlin/) — your code: Activities, classes, ViewModels.
• app/src/main/res/layout/ — XML layouts, one file per screen.
• res/values/strings.xml — all your text, in one place (makes translation easy).
• res/values/colors.xml and themes.xml — colors and the app’s theme.
• res/drawable/ — images, icons and shape definitions.
• res/mipmap/ — the app launcher icon in different sizes.
• AndroidManifest.xml — the app declaration (components + permissions).
• build.gradle.kts (Module :app) — dependencies and SDK versions for your app.
• build.gradle.kts (Project) — settings shared across all modules.

What is Gradle?

Gradle is the build tool. It downloads the libraries you ask for, compiles your Kotlin into bytecode, packages everything with your resources, and produces an installable .apk or .aab file. You configure it with build.gradle files.

Adding a library (dependency)

Need a library — say, for loading images? You add one line in the module build.gradle.kts and Gradle fetches it:

dependencies {
    implementation("androidx.core:core-ktx:1.13.1")
    implementation("androidx.appcompat:appcompat:1.7.0")
    implementation("com.google.android.material:material:1.12.0")
    implementation("io.coil-kt:coil:2.6.0") // image loading
}

After editing, click Sync Now so Gradle downloads the new library.

Important version settings

android {
    compileSdk = 34          // SDK you compile against
    defaultConfig {
        minSdk = 24          // oldest Android you support
        targetSdk = 34       // version you tested for
        versionCode = 1      // internal build number (increase each release)
        versionName = "1.0"  // version users see
    }
}

• minSdk — lower = more devices, but fewer modern features.
• targetSdk — keep this current; the Play Store requires it.
• versionCode — must increase with every upload to the Play Store.

Debug vs Release builds

Gradle makes two build types: debug (used while developing, easy to install) and release (optimised, shrunk, and signed for the Play Store). You’ll create a release build when you publish.

Common mistakes

• Editing the project Gradle file when you meant the module (:app) one — dependencies go in the module file.
• Forgetting to press Sync Now after adding a dependency.
• Mixing incompatible library versions — use Google’s BoM or the suggested versions.

Summary: Your code lives in java/, screens in res/layout/, text in strings.xml. Gradle builds it all; add libraries in the module build.gradle and Sync.