Skip to main content
Android Development with Kotlin
CHAPTER 08 Beginner

Android Project Structure Explained

Updated: May 16, 2026
15 min read

# CHAPTER 8

Android Project Structure Explained

1. Introduction

When you create a new project in Android Studio, it immediately generates dozens of folders and files. For a beginner, the project panel looks like the control panel of a spaceship. Where do you put your code? Where do the images go? What is the AndroidManifest.xml? Understanding this directory structure is critical before you write a single line of UI code. In this chapter, we will master the Android Project Structure. We will dissect the app module, explore the res (Resources) directory, understand the gatekeeper that is the Manifest, and configure build parameters using Gradle scripts.

2. Learning Objectives

By the end of this chapter, you will be able to:
  • Navigate the Android window view in the Project Explorer.
  • Understand the role of the AndroidManifest.xml file.
  • Locate and manage Kotlin logic within the java directory.
  • Manage images, strings, and layouts within the res directory.
  • Differentiate between the Project-level and Module-level build.gradle.kts files.

3. The "Android" View

By default, the left-hand panel in Android Studio is set to the "Android" view. This is not the literal folder structure on your hard drive! It is a flattened, synthesized view designed by Google to make finding files easier for developers. It is split into two primary sections: app and Gradle Scripts.

4. The AndroidManifest.xml (The Rulebook)

Located at app -> manifests -> AndroidManifest.xml. Think of the Manifest as the "Rulebook" or the "Passport" of your app. When a user installs your app, the Android Operating System reads this file first. It contains:
  • The name of the app.
  • The app icon configuration.
  • Permissions: If your app needs the Camera or Internet, you MUST declare it here, or the app will crash instantly when you try to use them.
  • Activities: Every single screen (Activity) in your app must be registered here.
xml
1234567891011121314151617 
<!-- Example of declaring Internet permission in the Manifest -->
<manifest xmlns:android="http://schemas.android.com/apk/res/android">
    
    <uses-permission android:name="android.permission.INTERNET" />

    <application
        android:icon="@mipmap/ic_launcher"
        android:label="My Awesome App">
        <activity android:name=".MainActivity">
            <!-- This intent-filter tells Android: "Make this the opening screen!" -->
            <intent-filter>
                <action android:name="android.intent.action.MAIN" />
                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>
        </activity>
    </application>
</manifest>

5. The java Folder (The Brain)

Located at app -> java -> com.yourname.yourapp. *(Note: Even though we are writing Kotlin, Android Studio still labels the main code folder as "java" for historical compatibility reasons).* This folder holds all your .kt files. This is the "Brain" of the application. Your MainActivity.kt lives here, alongside any Data Classes, ViewModels, or network logic you create.

6. The res Folder (The Face)

Located at app -> res (Short for Resources). This folder holds EVERYTHING visual. No Kotlin code lives here. It is strictly for design files.
  • drawable: This is where you put your images (.png, .jpg, .xml vectors).
  • layout: This is where your UI screens are designed using XML (e.g., activity_main.xml).
  • mipmap: This is exclusively for your App Icon. It holds different sizes of the icon so it looks crisp on low-res and high-res phones.
  • values: Contains strings.xml and colors.xml.

*Pro Tip:* Never hardcode text directly into your UI. Always put the text in strings.xml. Why? Because if you want to translate your app into Spanish later, you just swap out the strings.xml file, and the entire app translates instantly!

7. Gradle Scripts (The Builder)

At the bottom of the Project panel, you will see Gradle Scripts. There are two critical files here:
  1. 1. build.gradle.kts (Project): Rules for the entire workspace. You rarely touch this.
  1. 2. build.gradle.kts (Module :app): This is the most important configuration file! It contains the instructions for compiling your specific app.

Inside the Module :app file, you will find:

  • compileSdk / targetSdk: The Android OS version you are building for.
  • minSdk: The oldest Android phone allowed to download your app (e.g., setting it to 24 means Android 7.0 and up).
  • dependencies { ... }: This is where you add third-party libraries! If you want to use a fancy animation library from GitHub, you paste the URL here and click "Sync Now".

8. The R Class (The Invisible Bridge)

How does your Kotlin code in the java folder know about a button you designed in the res/layout folder? When Gradle builds your app, it silently generates an invisible class called R (Resource). If you add an image named dog.png to the drawable folder, Android creates a memory address for it. In Kotlin, you can access that image by typing R.drawable.dog.

9. Common Mistakes

  • Capital Letters in the res folder: The Android resource compiler strictly forbids uppercase letters and spaces in file names within the res folder. If you drag an image named My Dog.png into the drawable folder, your entire app will break and refuse to compile. You must rename it to my_dog.png!
  • Ignoring Gradle Sync: If you paste a new dependency into your build.gradle.kts file, you MUST click the "Sync Now" prompt that appears in the top right corner. If you do not, Android Studio will not download the library, and your code will show massive red errors.

10. Best Practices

  • Package Organization: Don't throw 50 Kotlin files into the main java folder. Right-click and create "Packages" (sub-folders). Group them logically: com.myapp.ui, com.myapp.data, com.myapp.network. Clean architecture starts with a clean folder structure.

11. Exercises

  1. 1. Open an Android Studio project, locate the strings.xml file, and change the app's name to "Test Application".
  1. 2. Locate the AndroidManifest.xml file and identify which XML tags dictate the "Launcher" activity.

12. Coding Challenges

Challenge: Open the build.gradle.kts (Module :app) file. Locate the minSdk property. Research online to determine what percentage of global Android devices you would lose if you changed the minSdk from 24 to 33.

13. MCQ Quiz with Answers

Question 1

If an Android application requires access to the device's physical camera, in which specific architectural file must the developer declare the <uses-permission> tag?

Question 2

What is the strict naming convention mandated by the Android compiler for all files placed within the res/drawable directory?

14. Interview Questions

  • Q: Explain the mechanical function of the auto-generated R class in Android. How does it serve as a bridge between the compiled res directory and the Kotlin source code?
  • Q: Contrast the mipmap directory with the drawable directory. Why does Apple explicitly require app launcher icons to be placed in mipmap rather than drawable?
  • Q: Detail the purpose of the build.gradle.kts (Module :app) file. Specifically, what is the architectural difference between minSdk and targetSdk?

15. FAQs

Q: I accidentally deleted a file in the res folder and now my entire project is covered in red errors. How do I fix it? A: Go to the top menu bar, click Build, and select Clean Project, followed by Rebuild Project. This forces Gradle to delete the corrupted R class and regenerate it from scratch based on the current files!

16. Summary

In Chapter 8, we demystified the complex architectural scaffolding of an Android project. We explored the rigid separation of logic and visuals, housing our Kotlin Brains in the java directory and our visual Faces within the res directory. We analyzed the AndroidManifest.xml, the ultimate gatekeeper dictating permissions and application entry points. Finally, we navigated the Gradle build scripts, understanding how external dependencies and target SDK configurations are injected into the compilation pipeline.

17. Next Chapter Recommendation

We know where files go, but how does the code actually run? When a user opens an app, minimizes it, and reopens it, what happens to the code? Proceed to Chapter 9: Android Activity Lifecycle to understand the beating heart of mobile applications.

Finish this Chapter

Save your progress on your learning path and prepare for coding interview challenges.

Previous Chapter Collections and Null Safety in Kotlin
Next Chapter Android Activity Lifecycle

Discussion

Join the discussion

Log in or create a free account to participate.

Sort: ·

Explore More

📖 Related Tutorials 5