Related Articles

Understanding the Android Framework: The Backbone of Android Development

1 hour ago

یک نوشته دیگر

January 24, 2015

نوشته آزمایشی

September 24, 2014

Understanding the structure of an Android project is one of the first steps toward becoming an effective Android developer. Android Studio creates a well-organized project structure that separates source code, resources, configuration files, and build settings. Knowing the purpose of each folder and file helps developers maintain clean, scalable, and manageable applications.

Overview of an Android Project

When you create a new Android application in Android Studio, several directories and files are generated automatically. These components work together to build and run the application.

A typical Android project consists of:

• app/
• manifests/
• java/ or kotlin/
• res/
• Gradle Scripts
• build.gradle files
• AndroidManifest.xml

Let’s explore each part in detail.

Project Structure Overview

MyApplication/
│
├── app/
│   ├── manifests/
│   │   └── AndroidManifest.xml
│   │
│   ├── java/
│   │   ├── com.example.myapplication
│   │   ├── androidTest/
│   │   └── test/
│   │
│   ├── res/
│   │   ├── drawable/
│   │   ├── layout/
│   │   ├── mipmap/
│   │   ├── values/
│   │   └── xml/
│   │
│   ├── build.gradle.kts
│   └── proguard-rules.pro
│
├── build.gradle.kts
├── settings.gradle.kts
├── gradle.properties
└── gradlew

1. app Module

The app module is the main module of an Android application. It contains all the code, resources, and configurations needed to build the APK or App Bundle.

app/

This module includes:

• Source code
• Resources
• Manifest file
• Dependencies
• Build configuration

2. AndroidManifest.xml

The AndroidManifest.xml file provides essential information about the application to the Android system.In addition to defining the application’s components, the AndroidManifest.xml file serves as a communication bridge between the app and the Android operating system. It specifies which activities, services, broadcast receivers, and content providers are available, allowing Android to correctly launch and manage these components. The manifest also declares hardware and software requirements, ensuring that the application is installed only on compatible devices.

Furthermore, the manifest is used to request permissions required by the application, such as internet access, camera usage, location services, or notifications. It can also define intent filters that allow the app to respond to specific actions, such as opening web links or sharing content. Because of its central role in configuring an Android application, the AndroidManifest.xml file is considered one of the most important files in every Android project.

Location:

app/src/main/AndroidManifest.xml

It defines:

• Application name
• Package name
• Activities
• Services
• Broadcast Receivers
• Permissions
• Intent filters
• Minimum SDK requirements

Example:

<manifest package="com.example.myapplication">

    <application
        android:label="My Application">

        <activity
            android:name=".MainActivity">

            <intent-filter>
                <action android:name="android.intent.action.MAIN"/>
                <category android:name="android.intent.category.LAUNCHER"/>
            </intent-filter>

        </activity>

    </application>

</manifest>

3. Source Code Directory (java/ or kotlin/)

The source code directory contains all the Kotlin or Java files that implement the application’s functionality and business logic. Activities, Fragments, ViewModels, repositories, network classes, and utility functions are typically organized into packages within this directory to keep the project modular and easy to maintain. As the application grows, developers often adopt architectural patterns such as MVVM or Clean Architecture to separate responsibilities and improve code readability.

In addition to the main application code, this directory may contain multiple packages dedicated to specific features or layers of the app. Proper organization of source files makes collaboration easier, simplifies debugging, and helps developers scale the project over time. Android Studio automatically recognizes these packages and compiles the source code into executable bytecode that runs on the Android Runtime (ART).

app/src/main/java/

or

app/src/main/kotlin/

Example:

java/
└── com.example.myapplication
    ├── MainActivity.kt
    ├── LoginActivity.kt
    ├── UserRepository.kt
    └── ViewModel/

Typically, developers organize code into packages such as:

com.example.app
│
├── ui
├── data
├── repository
├── network
├── model
├── viewmodel
└── utils

This structure improves readability and maintainability.

4. Resource Directory (res)

The res (resources) folder contains all non-code assets that define the appearance and behavior of an Android application. These resources include layouts, images, icons, strings, colors, styles, animations, and other XML configuration files. By separating resources from source code, Android makes it easier to maintain applications, support multiple screen sizes, and provide localization for different languages.

Resources inside the res directory are compiled and assigned unique identifiers in the generated R class, allowing developers to access them directly from code. The folder is further divided into specialized subdirectories such as layout for user interface files, drawable for images and shapes, mipmap for launcher icons, and values for strings, colors, dimensions, and themes. This structured approach helps keep Android projects organized and promotes code reusability and maintainability.

app/src/main/res/

layout/

The layout directory stores XML files that define the structure and appearance of an application’s user interface. Each layout file describes how UI components such as TextViews, Buttons, ImageViews, and RecyclerViews are arranged on the screen. These XML files separate the presentation layer from the application logic, making the code easier to maintain and modify.

Android applications can have multiple layout files for different screens and configurations, allowing developers to create responsive interfaces that adapt to various device sizes and orientations. At runtime, these XML layouts are inflated into View objects, enabling the application to display and interact with the user interface efficiently. This approach promotes reusability, consistency, and a clear separation between UI design and business logic.

Example:

res/layout/
├── activity_main.xml
├── activity_login.xml
└── item_user.xml

Example layout:

<TextView
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:text="Hello Android"/>

drawable/

The drawable directory contains images and drawable resources used throughout the application. These resources can include bitmap images such as PNG, JPG, and WebP files, as well as XML-based drawables like shapes, gradients, selectors, and vector graphics. Drawables are commonly used for backgrounds, icons, buttons, and other visual elements that contribute to the app’s appearance.

Android automatically selects the most appropriate drawable based on the device’s screen density, helping applications display sharp and optimized graphics across different devices. Developers can also create reusable XML drawables to define custom shapes and states without relying on image files, reducing application size and improving maintainability. All drawable resources are compiled and made accessible through the generated R.drawable class.

Examples:

res/drawable/
├── background.xml
├── button_shape.xml
└── logo.png

Supported formats:

• PNG
• JPG
• WebP
• Vector Drawables

mipmap/

The mipmap directory stores the application’s launcher icons, which are displayed on the device’s home screen, app drawer, and system settings. Android provides separate mipmap folders for different screen densities, allowing the system to choose the most appropriate icon size for each device and ensuring that icons appear sharp and clear.

Keeping launcher icons in the mipmap directory instead of the drawable directory allows Android to optimize icon handling and support adaptive icons introduced in newer Android versions. These adaptive icons consist of foreground and background layers, enabling the system to apply various shapes and visual effects while maintaining a consistent appearance across different devices and launchers.

Example:

res/mipmap/
├── ic_launcher.png
├── ic_launcher_round.png

Android uses different icon sizes for various screen densities.

values/

Contains XML files for reusable values.

Common files include:

strings.xml

Stores text resources.

<resources>
    <string name="app_name">My Application</string>
</resources>

colors.xml

The colors.xml file defines color values that are used throughout the application. Instead of hardcoding color codes directly into layouts or source code, developers can store them in a centralized location and reference them by name. This approach improves consistency, makes color changes easier, and helps maintain a uniform design across the entire application.

Colors defined in colors.xml are commonly used for themes, backgrounds, text, buttons, and other UI elements. By managing colors in a single file, developers can quickly update the application’s appearance and support features such as light and dark themes. These color resources are compiled into the generated R.color class, making them easily accessible from both XML layouts and Kotlin or Java code.

<color name="primary">#6200EE</color>

themes.xml

Contains application themes.The themes.xml file contains the application’s themes, which define the overall look and feel of the user interface. Themes control visual attributes such as colors, typography, button styles, status bar appearance, and other UI properties that are applied consistently across activities and fragments. By using themes, developers can maintain a unified design and simplify the process of customizing the application’s appearance.

Modern Android applications often define separate themes for light mode and dark mode, allowing the interface to adapt automatically based on the user’s system settings. Themes can also inherit properties from Material Design themes, enabling developers to take advantage of predefined styles and components. Centralizing these settings in themes.xml makes it easier to update the app’s visual identity and ensure a consistent user experience throughout the application.

dimens.xml

Stores dimensions.The dimens.xml file stores dimension values used throughout the application, such as margins, padding, text sizes, and spacing. Instead of hardcoding these values directly into layout files, developers define them as reusable resources, making the user interface more consistent and easier to maintain. Centralizing dimensions also simplifies design updates, as changing a value in one place automatically affects all layouts that reference it.

Using dimension resources helps create responsive interfaces that adapt to different screen sizes and densities. Developers can provide alternative dimension files for various device configurations, such as tablets or landscape orientation, ensuring that the application delivers a consistent and visually appealing experience across a wide range of Android devices. These resources are compiled into the generated R.dimen class and can be accessed from both XML layouts and Kotlin or Java code.

<dimen name="padding_large">16dp</dimen>

Benefits:

• Easier localization
• Consistent styling
• Centralized resource management

menu/

Contains menu XML files.The menu directory contains XML files that define the structure and items of application menus. These menus are commonly used in toolbars, action bars, navigation drawers, and popup menus to provide users with quick access to key actions and features within the app. Each menu XML file describes items such as titles, icons, and actions that should be displayed to the user.

By defining menus in XML instead of hardcoding them in code, developers can easily manage and modify the app’s navigation options without changing the underlying logic. Menu resources can also be dynamically inflated at runtime and handled in activities or fragments, allowing the application to respond to user interactions such as clicks, selections, and contextual actions in a clean and structured way.

Example:

res/menu/
└── main_menu.xml

Used for:

• Toolbar menus
• Navigation drawers
• Popup menus

xml/

Contains additional XML configuration files.

Examples:

• File provider paths
• Backup rules
• Network security configuration

5. Assets Folder

The assets folder stores raw files that are accessed directly by the application.The assets folder stores raw files that are bundled with the application and accessed directly at runtime using the AssetManager. Unlike resources in the res directory, files inside assets are not assigned resource IDs, which means they cannot be referenced through the R class. Instead, they are accessed by their file path, giving developers more flexibility in handling custom file structures.

This folder is commonly used for storing files such as HTML pages, JSON data, fonts, audio files, or prebuilt databases. Because assets are kept in their original form, they are ideal for scenarios where the application needs to read structured or unprocessed data directly. Developers can open these files as input streams, making the assets directory especially useful for dynamic content loading and offline resources.

Location:

app/src/main/assets/

Examples:

• HTML files
• JSON files
• Fonts
• Databases

Example:

assets/
├── config.json
├── index.html
└── fonts/

Files inside assets do not receive resource IDs and are accessed using the AssetManager.

6. Raw Folder

Location:

res/raw/

Used for:

• Audio files
• Video files
• JSON files
• Databases

Example:

res/raw/
├── notification.mp3
├── intro.mp4
└── sample.json

Files can be referenced as:

R.raw.notification

7. Test Directories

Android projects contain two testing directories that are used to ensure the quality and correctness of the application. The first is the test/ directory, which is used for local unit tests. These tests run on the developer’s machine and are typically used to validate business logic, utility functions, and ViewModel behavior without requiring an Android device or emulator.

The second is the androidTest/ directory, which is used for instrumented tests. These tests run on real devices or emulators and are used to verify UI behavior, interactions, and components that depend on the Android framework. Tools like Espresso are commonly used in this directory to simulate user actions and ensure the application works correctly in real-world conditions.

Unit Tests

app/src/test/

Used for:

• JUnit tests
• Repository testing
• ViewModel testing

Example:

class CalculatorTest {
    @Test
    fun addition() {
        assertEquals(4, 2 + 2)
    }
}

Instrumented Tests

app/src/androidTest/

Used for:

• UI tests
• Espresso tests
• Device-specific tests

These tests run on emulators or physical devices.

8. Gradle Build Files

Gradle is Android’s build system that automates the process of compiling, packaging, and managing dependencies for an application. It takes the source code, resources, and configuration files and transforms them into a runnable APK or Android App Bundle. Gradle also handles tasks such as code compilation, resource merging, and optimization, making the build process efficient and consistent across different environments.

In addition to building the application, Gradle manages external libraries and dependencies through a declarative configuration system. Developers can define different build variants, such as debug and release versions, each with its own settings and optimizations. This flexibility allows teams to customize builds, enable features like code shrinking or obfuscation, and streamline the development workflow.

Project-Level build.gradle

Located at:

build.gradle.kts

Defines:

• Repositories
• Plugins
• Global configuration

Example:

plugins {
    alias(libs.plugins.android.application) apply false
    alias(libs.plugins.kotlin.android) apply false
}

Module-Level build.gradle

Located at:

app/build.gradle.kts

Contains:

android {
    namespace = "com.example.myapplication"

    compileSdk = 36

    defaultConfig {
        applicationId = "com.example.myapplication"
        minSdk = 24
        targetSdk = 36
        versionCode = 1
        versionName = "1.0"
    }
}

Also manages:

• Dependencies
• Build types
• Product flavors
• Signing configurations

9. settings.gradle

The settings.gradle file specifies which modules are included in an Android project. It acts as the entry point for Gradle’s project configuration and defines the structure of the entire build. When the project is built, Gradle reads this file to determine which modules it should compile and manage, such as the main app module and any additional feature or library modules.

In multi-module projects, settings.gradle becomes especially important because it allows developers to split an application into smaller, reusable components like data, domain, or feature modules. This modular approach improves scalability, build performance, and code organization by allowing each module to be developed and tested independently while still working together as a single application.

Example:

rootProject.name = "MyApplication"
include(":app")

Multi-module projects may contain:

include(":app")
include(":data")
include(":domain")
include(":feature-home")

10. Gradle Properties

File:

gradle.properties

Stores project-wide properties such as:

org.gradle.jvmargs=-Xmx2048m
android.useAndroidX=true
kotlin.code.style=official

These settings optimize build performance and configure Gradle behavior.

11. Generated Files

Android Studio automatically generates several files during compilation.

Examples include:

• R.java
• BuildConfig
• APK or App Bundle outputs

Developers usually do not edit these files manually.

Typical Android Folder Structure

app
├── manifests
│   └── AndroidManifest.xml
│
├── java
│   ├── main source code
│   ├── test
│   └── androidTest
│
├── res
│   ├── layout
│   ├── drawable
│   ├── mipmap
│   ├── values
│   ├── menu
│   ├── raw
│   └── xml
│
├── assets
├── build.gradle.kts
└── proguard-rules.pro

Conclusion

The Android project structure is designed to keep code, resources, and configurations organized and maintainable. The app module contains the application’s core components, while folders such as java, res, and assets separate code from resources. Build configuration files like Gradle scripts and AndroidManifest.xml control how the application is compiled and behaves on Android devices.

A solid understanding of the Android project structure provides the foundation for building scalable, maintainable, and professional Android applications.