Topic 4: Android Application Structure (Folder Structure)

📖 8 min read · 🎯 beginner · 🧭 Prerequisites: android-application-components-required-to-make-an-application, java-day-i-introduction-to-oops

Why this matters

Picture this: you open an Android project for the first time and your screen fills with folders — manifests, java, res, Gradle files everywhere. Where do you even start? I've watched so many beginners close the laptop at this point, completely overwhelmed. Here's the thing — that folder structure isn't chaos. Every folder has a job, and once you know what goes where, you stop hunting for files and start building. In this lesson, we walk through every folder and file Android Studio creates for you, so nothing in that project tree feels foreign again.

What You'll Learn

• Identify every folder and file Android Studio generates when you create a new project
• Understand the purpose of AndroidManifest.xml and what it declares to the Android system
• Read and distinguish between the top-level and module-level build.gradle files
• Organize your Java source code by feature layers (activities, fragments, view models, repositories, models, utils)

The Analogy

Think of an Android project as a municipal building — City Hall. The root directory is the entire city block: it holds the master blueprints (build.gradle), utility contracts (gradle.properties), and the city directory (settings.gradle). The app/ module is the actual building where work happens. Inside, the main/ wing is the public-facing floors open to visitors (your real app code and resources), test/ is the internal quality-control lab on the basement level, and androidTest/ is the inspection team that tours the building while it's actually running. Every architect knows which wing to walk into before they start drawing.

Chapter 1: The Full Project Tree

When Android Studio creates a new project called MyApp, it generates this directory structure automatically:

MyApp/
├── app/
│   ├── build/
│   ├── libs/
│   ├── src/
│   │   ├── androidTest/
│   │   │   └── java/
│   │   │       └── com/example/myapp/
│   │   ├── main/
│   │   │   ├── java/
│   │   │   │   └── com/example/myapp/
│   │   │   ├── res/
│   │   │   ├── AndroidManifest.xml
│   │   └── test/
│   │       └── java/
│   │           └── com/example/myapp/
│   ├── build.gradle
│   └── proguard-rules.pro
├── build/
├── .gradle/
├── .idea/
├── gradle/
├── gradle.properties
├── gradlew
├── gradlew.bat
├── settings.gradle
└── build.gradle

Every file here has a job. Nothing is filler. Let's walk the map room by room.

Chapter 2: Root Directory — MyApp/

The root is the outer shell of the entire project. Android Studio and Gradle live here.

The Gradle wrapper files (gradlew, gradlew.bat, gradle/) are especially important: they let any developer clone the repo and build it with the exact same Gradle version, no local installation required.

Chapter 3: The App Module — app/

The app/ directory is your project's primary module. Everything the user installs on their phone comes from here.

• build/ — compiled output and build artifacts; generated automatically, never hand-edit
• libs/ — local .jar or .aar library files your app depends on
• src/ — all source code, split into three source sets:
  • main/ — production app code and resources (ships to users)
  • androidTest/ — Android Instrumented Tests that run on a real device or emulator; UI tests live here
  • test/ — local JVM unit tests that run fast on your development machine without a device
• build.gradle — module-level build script (dependencies, SDK versions, build types)
• proguard-rules.pro — custom rules for ProGuard / R8 code shrinking and obfuscation

Inside src/main/

src/main/
├── java/
│   └── com/example/myapp/    ← your package, application code goes here
├── res/                       ← non-code resources
│   ├── layout/                ← XML layout files
│   ├── drawable/              ← images and drawable resources
│   ├── values/                ← strings, colors, styles, dimensions
│   ├── mipmap/                ← launcher icons (multiple densities)
│   ├── anim/                  ← animation resource files
│   ├── menu/                  ← XML files defining menus
│   ├── raw/                   ← arbitrary raw files (audio, data)
│   └── xml/                   ← miscellaneous XML files
└── AndroidManifest.xml

The res/ subdirectories cover every category of non-code asset the Android resource system understands. The values/ folder alone drives themes, string localisation, and color schemes across your entire app.

Chapter 4: AndroidManifest.xml

AndroidManifest.xml is the identity document of your application. Every app must have one. The Android system reads it before launching anything. It declares:

• The package name (globally unique identifier for your app)
• All components: activities, services, broadcast receivers, and content providers
• Permissions the app requires from the user or system
• Minimum and target SDK versions

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.example.myapp">
    <application
        android:allowBackup="true"
        android:icon="@mipmap/ic_launcher"
        android:label="@string/app_name"
        android:roundIcon="@mipmap/ic_launcher_round"
        android:supportsRtl="true"
        android:theme="@style/AppTheme">
        <activity android:name=".MainActivity">
            <intent-filter>
                <action android:name="android.intent.action.MAIN" />
                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>
        </activity>
        <activity android:name=".SecondActivity" />
    </application>
</manifest>

The <intent-filter> on MainActivity is what makes it the launch screen — Android sees action.MAIN + category.LAUNCHER and places it on the home screen. Any activity not listed in the manifest is invisible to the system.

Chapter 5: Build Files — Gradle Configuration

Android projects use two levels of Gradle build files.

Top-level build.gradle

Sits at the project root. Defines repositories and build tooling shared by every module.

// Top-level build file where you can add configuration options common to all sub-projects/modules.
buildscript {
    repositories {
        google()
        mavenCentral()
    }
    dependencies {
        classpath "com.android.tools.build:gradle:7.0.2"
        // NOTE: Do not place your application dependencies here; they belong
        // in the individual module build.gradle files
    }
}
allprojects {
    repositories {
        google()
        mavenCentral()
    }
}
task clean(type: Delete) {
    delete rootProject.buildDir
}

The comment is a real guard rail: if you accidentally add implementation dependencies here, they won't apply as you expect.

Module-level build.gradle (app/build.gradle)

Controls everything specific to the app module: SDK targets, app identity, build types, and library dependencies.

plugins {
    id 'com.android.application'
}
android {
    compileSdkVersion 30
    defaultConfig {
        applicationId "com.example.myapp"
        minSdkVersion 16
        targetSdkVersion 30
        versionCode 1
        versionName "1.0"
        testInstrumentationRunner "androidx.test.runner.AndroidJUnitRunner"
    }
    buildTypes {
        release {
            minifyEnabled false
            proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'
        }
    }
}
dependencies {
    implementation 'androidx.appcompat:appcompat:1.3.1'
    implementation 'com.google.android.material:material:1.4.0'
    implementation 'androidx.constraintlayout:constraintlayout:2.1.0'
    testImplementation 'junit:junit:4.13.2'
    androidTestImplementation 'androidx.test.ext:junit:1.1.3'
    androidTestImplementation 'androidx.test.espresso:espresso-core:3.4.0'
}

Key fields:

• compileSdkVersion — which Android API to compile against
• minSdkVersion — oldest Android version your app supports
• targetSdkVersion — the API version your app is designed and tested for
• versionCode — integer used by the Play Store to compare versions
• versionName — human-readable version string shown to users

Chapter 6: Organizing the Java Source Directory

The java/ directory under src/main/ holds your app's logic. As projects grow, dumping all classes in one flat package becomes unmaintainable. The standard approach is to organize by feature layer:

com/example/myapp/
├── activities/
│   ├── MainActivity.java
│   └── SecondActivity.java
├── fragments/
│   └── MyFragment.java
├── viewmodels/
│   └── MyViewModel.java
├── repositories/
│   └── MyRepository.java
├── models/
│   └── User.java
└── utils/
    └── Utils.java

This layout mirrors the MVVM architecture pattern widely used in Android development and makes it easy to add new features without cluttering existing packages.

🧪 Try It Yourself

Task: Create a new Android project in Android Studio and verify you can locate every major section of the structure.

1. Open Android Studio → New Project → Empty Activity → name it MyApp.
2. Once the project loads, expand the Project pane (set the dropdown to Android view, then switch to Project view).
3. Find and open each of these files — note what's inside each one:
   • app/src/main/AndroidManifest.xml
   • app/build.gradle (module level)
   • Root-level build.gradle
4. Inside app/src/main/java/com/example/myapp/, create a new package called utils and add an empty class Utils.java.

Success criterion: You should see the utils/Utils.java file appear correctly nested under your package in the Project view, matching the layer structure shown in Chapter 6.

🔍 Checkpoint Quiz

Q1. Which file tells the Android system about your app's components, permissions, and minimum SDK version?

A) build.gradle B) gradle.properties C) AndroidManifest.xml D) proguard-rules.pro

Q2. Given this snippet from app/build.gradle:

defaultConfig {
    applicationId "com.example.myapp"
    minSdkVersion 16
    targetSdkVersion 30
    versionCode 1
    versionName "1.0"
}

A user is running Android API level 14. What happens when they try to install this app?

A) The app installs and runs normally B) The app installs but crashes on launch C) The Play Store / system rejects the install because API 14 < minSdkVersion 16 D) The app runs but with reduced features

Q3. Where do you write UI tests that interact with your app running on a real device or emulator?

A) src/test/java/ B) src/main/java/ C) src/androidTest/java/ D) libs/

Q4. A new developer joins your team and needs to build the project without installing Gradle on their machine. Which files make that possible, and why?

(Open-ended — write 2–3 sentences.)

A1. C) AndroidManifest.xml — it is the app's identity document, read by the Android system before any component is launched.

A2. C) The system rejects the install. minSdkVersion 16 means the app will not install on any device below API 16; API 14 falls below that floor.

A3. C) src/androidTest/java/ — this source set is specifically for instrumented tests that run on an Android device or emulator, where you can interact with real Views and system services.

A4. The gradlew (Unix) and gradlew.bat (Windows) shell scripts, together with the gradle/ wrapper directory, download and use the exact Gradle version pinned in the project. No local Gradle installation is needed — the wrapper manages everything, ensuring every developer builds with the same toolchain.

🪞 Recap

• Android Studio generates a predefined directory tree; every file and folder serves a distinct build or runtime purpose.
• AndroidManifest.xml is the app's identity document — all components, permissions, and SDK requirements are declared there.
• Two build.gradle files exist: the root-level one configures tooling shared across all modules; the module-level one configures the app module's SDK versions, identity, and library dependencies.
• The res/ directory holds all non-code assets, subdivided by type: layout/, drawable/, values/, mipmap/, anim/, menu/, raw/, and xml/.
• Organizing the java/ source directory into feature layers (activities, fragments, viewmodels, repositories, models, utils) keeps your codebase scalable and easy to navigate.

📚 Further Reading

• Android Studio Project Overview — Official Docs — the source of truth on project and module structure
• AndroidManifest.xml Reference — every element and attribute the manifest supports
• Configure Your Build — Gradle for Android — deep dive into build variants, flavors, and dependency scopes
• ⬅️ Previous: Java Day I — Introduction to OOPs
• ➡️ Next: Operators in Java