5 Android Project Structure

Overview of an Android Project

When you first open an Android project in Android Studio, it can feel like a lot of folders and files. Many of them are created automatically so you can start building an app without wiring everything from scratch. Understanding what each major part does will help you navigate confidently and avoid breaking important pieces.

In this chapter you focus on the overall structure of a typical Android app project created by Android Studio. You will see where your code lives, where your layouts and images live, how configuration is separated, and how Android Studio organizes everything for you. Detailed explanations of Gradle, the manifest file, and resource directories will come in their own chapters, so here you only learn how they fit together at a high level.

The `Android` View in Android Studio

Android Studio can show your project files in different ways. For most Android work you use the Android view in the Project tool window. This view hides some low level files and groups related items in a way that matches how Android apps are usually built.

At the top level in the Android view you usually see at least two main entries. One is the app module, usually called app. Others might be additional modules or Gradle files. The app module contains almost everything related to the main application you build. Inside it are code directories, resource directories, and configuration files.

Even though Android Studio shows a simplified structure, underneath it all there is a normal file system with folders like app/src/main/java and app/src/main/res. Sometimes you will switch to the Project or Project Files view to see the actual folder layout, but for most everyday tasks the Android view is enough.

Modules in an Android Project

An Android project is often divided into one or more modules. A module is a logical piece of your app that can be built, tested, and packaged separately. For beginners, there is typically only one module called app, which produces the final Android application you can install.

Later, as apps grow, developers might add other modules for libraries, features, or shared code. These can be Android library modules that provide reusable UI and logic, or plain Kotlin/Java modules that hold common code. All modules of the project are linked together by Gradle, which you will study in another chapter.

Each module has its own source code, resources, and at least one Gradle build file. In most beginner projects, whenever you add a new Activity, Fragment, or resource, you are adding it to the app module.

Source Sets: `main`, `androidTest`, and `test`

Inside a module there are usually several source sets. A source set is just a group of directories that Gradle treats in a particular way. The most important one is main. This contains everything that ships in your application: your Kotlin code, XML layouts, images, and other resources.

There are two other common source sets: androidTest and test. The androidTest source set is for instrumentation tests that run on an Android device or emulator. The test source set is for plain unit tests that run on your computer without needing an Android device. In the Android view these are grouped under folders such as java and androidTest under the same module.

For now, you only need to remember that your app logic and UI go into the main source set, while tests use test or androidTest. You will see how to write tests in a separate testing chapter.

The `src` Folder and `main`

At the file system level, the app module has a src folder. Inside src you see the source sets main, androidTest, and test. The main folder is the heart of your app. It commonly contains three main child folders: java (or kotlin), res, and the AndroidManifest.xml file.

All your production app code for Activities, Fragments, ViewModels, and other classes lives inside src/main/java or src/main/kotlin. All your images, layouts, and values live in src/main/res. The manifest file in src/main/AndroidManifest.xml informs Android about your app components and permissions.

Other configurations, such as Gradle build files, sit outside src at the module level, which you will explore in the Gradle chapter.

Package Structure for Kotlin Code

Inside src/main/java or src/main/kotlin you will find packages. A package is a way to group related classes. For example, your project might have a base package such as com.example.myfirstapp. Inside it, some teams create subpackages like ui, data, and model. Android Studio often sets up the base package for you when you create a new project.

Every Kotlin file belongs to a package, usually declared at the top of the file with a line like:

package com.example.myfirstapp

As your app grows, you organize code by responsibility. Activities might go into com.example.myfirstapp.ui, data classes into com.example.myfirstapp.data, and so on. Kotlin basics and package imports are covered separately, so here it is enough to recognize that the java or kotlin folder in main is where all your app logic classes are stored.

The `res` Folder and Resources

While Kotlin files hold your logic, almost everything user facing that is not code is stored in the res folder inside src/main. This includes layouts, strings, colors, images, and many other types of resources. Each resource type has its own subfolder.

For example, XML layout files go in res/layout, drawable images and shapes go in various res/drawable* folders, and text labels for your app go into res/values/strings.xml. Instead of hardcoding text or colors in code, you typically reference them through resource IDs.

Android Studio expects resources to be placed in the correct subfolder so they can be compiled and accessed strongly typed from Kotlin. The details of specific resource directories will be explained more deeply in the resource directories chapter.

Manifest and Configuration Files

At the same level as java and res in the main source set you find the AndroidManifest.xml file. This file acts as a bridge between your code and the Android system. It declares the application package name, the launcher Activity, permissions, and other essential information.

Alongside the manifest are configuration files at the module and project level, such as build.gradle or settings.gradle. In the Android view they are grouped under "Gradle Scripts" or shown at the top of your project tree. These Gradle files define how your app is built, which libraries it uses, and which SDK versions it targets. You will learn their syntax and effects in the Gradle Build System chapter, so here you only need to recognize their location and purpose.

Generated Code and the `R` Class

Some parts of an Android project are generated automatically when you build. A key example is the R class. This class is not written by you but generated from your resources in the res folder. It provides IDs so you can access layouts, strings, and drawables from Kotlin code.

Android Studio shows generated files in special locations and usually warns you not to edit them. Instead, you edit the source that generates them, such as XML in res. When you rebuild, the generated code updates automatically. The project structure is set up so that generated files stay separate from your hand written code, which helps prevent accidental edits.

Gradle Scripts and Project Level Files

At the outer project level you typically see a Gradle Scripts section in the Android view. Inside it are files like the project level build.gradle, the module level build.gradle for the app module, and settings.gradle. These define how many modules your project has and how they are built.

The project root may also hold files like gradle.properties, .gitignore, or configuration for version control and tools. While these are important for real world development, as a beginner your focus stays mostly inside the app module in the code and resource folders.

Gradle specifics and the build process will be covered shortly in their own chapter, so at this stage you only need to know that Gradle files are the build configuration part of your project structure.

How the Pieces Work Together

All of these parts form a consistent structure. Kotlin code in src/main/java defines Activities and other components. XML layouts in src/main/res/layout describe how screens look. Strings and colors in res/values define text and styling. The manifest file connects the components with the Android operating system. Gradle build files control how everything is compiled into an installable app.

By understanding where each kind of file lives in your Android project, you become much faster at navigating, editing, and debugging. In the following chapters you will zoom into specific parts of this structure. You will explore Gradle in detail, then the Android manifest, and finally the many resource directories that control your app appearance and behavior.