Project structure (app, gradle, manifests) in Android Kotlin - Deep Dive

Overview - Project structure (app, gradle, manifests)

What is it?

A project structure in Android development is how all the files and folders are organized to build an app. It includes the app module where your code lives, Gradle files that manage building and dependencies, and manifest files that describe app settings. This structure helps the system and developers understand how to compile and run the app.

Why it matters

Without a clear project structure, building and maintaining an app would be chaotic and error-prone. Gradle files automate building and managing libraries, the manifest tells Android important info about the app, and the app folder holds the actual code and resources. This organization saves time, prevents mistakes, and makes teamwork easier.

Where it fits

Before learning project structure, you should know basic Android app concepts like activities and layouts. After this, you can learn about writing Kotlin code, using Android Studio tools, and managing app resources effectively.

Mental Model

Core Idea

An Android project structure is like a well-organized toolbox where each part has a clear role to build, configure, and run your app smoothly.

Think of it like...

Imagine building a house: the app folder is the construction site with workers and materials, Gradle files are the project managers who schedule and gather supplies, and the manifest is the blueprint that tells everyone what the house should be like.

Project Root
├── build.gradle (Project-level)
├── settings.gradle
├── app
│   ├── build.gradle (Module-level)
│   ├── src
│   │   ├── main
│   │   │   ├── AndroidManifest.xml
│   │   │   ├── java/
│   │   │   └── res/
│   │   └── test/
│   └── proguard-rules.pro
└── gradle/
    └── wrapper/

Build-Up - 7 Steps

1

Foundation

Understanding the app module folder

Concept: The app module folder contains your app's source code, resources, and manifest file.

Inside the app folder, you find the 'src/main' directory. This holds the AndroidManifest.xml file, Kotlin or Java code in the 'java' folder, and UI resources like layouts and images in the 'res' folder. This is where you write and organize everything that makes your app work.

Result

You know where to put your code and resources so Android Studio can find and use them.

Knowing the app folder structure helps you organize your work and prevents confusion about where to add new features or assets.

2

Foundation

Role of AndroidManifest.xml

Concept: The manifest file declares essential app information to the Android system.

AndroidManifest.xml tells Android about your app's components like activities, permissions it needs, and app metadata such as the app name and icon. It acts like a map for Android to understand how to launch and manage your app.

Result

Your app can register screens and request permissions properly, so it runs as expected on devices.

Understanding the manifest is key to controlling app behavior and system interactions.

3

Intermediate

Gradle build files explained

🤔Before reading on: do you think Gradle files only compile code or also manage app settings? Commit to your answer.

Concept: Gradle files automate building, dependency management, and app configuration.

There are two main Gradle files: one at the project root and one inside the app module. The project-level build.gradle sets global settings and repositories. The app-level build.gradle defines app-specific settings like SDK versions, dependencies (libraries), and build types (debug/release). Gradle runs these scripts to build your app automatically.

Result

Your app builds correctly with all needed libraries and settings applied.

Knowing Gradle's role helps you customize builds and add libraries without manual steps.

4

Intermediate

How resources are organized in res folder

🤔Before reading on: do you think all images and layouts go in the same folder or separate folders? Commit to your answer.

Concept: The res folder organizes app resources by type for easy access and management.

Inside 'res', you find folders like 'layout' for UI XML files, 'drawable' for images, and 'values' for colors and strings. Android uses these folders to load resources efficiently and support different device configurations like screen sizes and languages.

Result

Your app can display images and layouts correctly and adapt to different devices.

Organizing resources properly ensures your app looks good and works well everywhere.

5

Advanced

Multi-module project structure basics

🤔Before reading on: do you think all code must be inside the app module or can it be split? Commit to your answer.

Concept: Large projects can split code into multiple modules for better organization and reuse.

Besides the app module, you can create other modules like libraries or features. Each module has its own build.gradle and source folders. This helps teams work on parts independently and reuse code across apps.

Result

Your project scales better and is easier to maintain as it grows.

Understanding multi-module structure prepares you for professional, large-scale app development.

6

Advanced

Gradle build variants and flavors

🤔Before reading on: do you think you can build different versions of your app from the same codebase? Commit to your answer.

Concept: Gradle supports building different app versions using build variants and product flavors.

You can define flavors like 'free' and 'paid' or build types like 'debug' and 'release' in your app-level build.gradle. Gradle combines these to create variants, letting you customize features, resources, or settings per version without duplicating code.

Result

You can produce multiple app versions efficiently from one project.

Knowing build variants helps manage app releases and testing workflows professionally.

7

Expert

Manifest merging and overrides

🤔Before reading on: do you think your app has only one manifest file or multiple that combine? Commit to your answer.

Concept: Android merges manifest files from different sources during build to create the final app manifest.

Besides your main AndroidManifest.xml, libraries and build variants can provide their own manifests. Gradle merges these files, resolving conflicts by rules or overrides you specify. This allows modular development but can cause unexpected behavior if not understood.

Result

Your app manifest correctly reflects all components and settings from all modules and dependencies.

Understanding manifest merging prevents build errors and unexpected app behavior in complex projects.

Under the Hood

When you build an Android app, Gradle reads the build scripts to know what to compile and how. It compiles Kotlin/Java code, processes resources, merges manifests, and packages everything into an APK or AAB file. The manifest file is parsed to register app components and permissions with the Android system. Gradle's build cache and incremental builds speed up this process by reusing unchanged parts.

Why designed this way?

Android projects are complex with many files and dependencies. Gradle was chosen for its flexibility and automation, replacing older manual build systems. The manifest centralizes app metadata for the system. This design balances developer control with automation, enabling scalable and maintainable app development.

Project Root
├─ build.gradle (Project-level)
│    └─ Defines global settings
├─ app/
│    ├─ build.gradle (Module-level)
│    │    └─ Defines app-specific build rules
│    ├─ src/main/
│    │    ├─ AndroidManifest.xml (App metadata)
│    │    ├─ java/ (Source code)
│    │    └─ res/ (Resources)
│    └─ proguard-rules.pro
└─ gradle/
     └─ wrapper/

Build Process:
Gradle scripts → Compile code + process resources → Merge manifests → Package APK/AAB

Myth Busters - 4 Common Misconceptions

Quick: Is the AndroidManifest.xml optional for an app to run? Commit yes or no.

Common Belief: Some think the manifest file is optional or just a formality.

Reality: The manifest is mandatory; without it, Android cannot run or recognize your app.

Why it matters: Skipping or misconfiguring the manifest causes build failures or runtime crashes.

Quick: Do you think Gradle files only compile code and do not affect app behavior? Commit yes or no.

Common Belief: Many believe Gradle only compiles code and does not influence app features.

Reality: Gradle controls dependencies, build variants, and app signing, directly affecting app behavior and releases.

Why it matters: Ignoring Gradle's full role leads to build errors and inability to customize app versions.

Quick: Can you put all your app resources in one folder without subfolders? Commit yes or no.

Common Belief: Some think all images, layouts, and strings can be mixed in one folder.

Reality: Resources must be organized in specific subfolders (drawable, layout, values) for Android to find and use them.

Why it matters: Misplaced resources cause build errors or missing UI elements.

Quick: Do you think manifest files from libraries override your app's manifest? Commit yes or no.

Common Belief: Some believe library manifests replace the app's manifest entirely.

Reality: Library manifests merge with the app manifest; conflicts are resolved by merging rules, not replacement.

Why it matters: Misunderstanding this causes unexpected app behavior or missing components.

Expert Zone

1

Gradle's incremental build system caches outputs to speed up builds, but misconfigurations can cause stale builds that confuse developers.

2

Manifest merging order depends on build variant and library priority, so subtle overrides can silently change app behavior.

3

Multi-module projects require careful dependency management to avoid version conflicts and duplicated resources.

When NOT to use

For very simple apps or prototypes, a full multi-module Gradle setup may be overkill; simpler build tools or single-module projects suffice. Also, if you need extreme build speed, alternative build systems like Bazel might be preferred.

Production Patterns

In production, teams use multi-module projects to separate features, Gradle flavors to build free/paid versions, and manifest placeholders to inject environment-specific values. Continuous integration pipelines automate Gradle builds and tests for reliable releases.

Connections

Software Build Systems

Project structure and Gradle are a specific example of build systems that automate compiling and packaging software.

Understanding Android's Gradle build helps grasp general build automation concepts used in many programming environments.

Modular Programming

Multi-module Android projects apply modular programming principles by splitting code into independent, reusable parts.

Knowing modular programming improves your ability to design scalable and maintainable Android apps.

Urban Planning

Organizing an Android project is like urban planning, where clear zones and infrastructure ensure smooth city function.

Seeing project structure as planning helps appreciate the importance of organization and roles in complex systems.

Common Pitfalls

#1 Placing Kotlin code outside the 'java' folder inside src/main.

Wrong approach:

app/src/main/MyActivity.kt

Correct approach:

app/src/main/java/com/example/myapp/MyActivity.kt

Root cause:

Misunderstanding that Android Studio expects source code inside the 'java' folder for compilation.

#2 Adding dependencies directly in the project-level build.gradle instead of the app module.

Wrong approach:

In project build.gradle: dependencies { implementation 'com.example:lib:1.0' }

Correct approach:

In app/build.gradle: dependencies { implementation 'com.example:lib:1.0' }

Root cause:

Confusing global project settings with module-specific dependencies.

#3 Forgetting to declare a new activity in AndroidManifest.xml.

Wrong approach:

missing in manifest

Correct approach:

added inside in manifest

Root cause:

Not realizing that all app components must be registered in the manifest to function.

Key Takeaways

An Android project structure organizes code, resources, and configuration files to build and run your app efficiently.

The app module holds your source code and resources, while Gradle files automate building and managing dependencies.

AndroidManifest.xml declares app components and permissions, acting as a map for the Android system.

Gradle supports complex builds with multiple modules, variants, and flavors to handle real-world app needs.

Understanding manifest merging and resource organization prevents common build errors and unexpected app behavior.