What just happened? Anatomy of your app

Twenty files, and you only wrote one line

Pocket Studio made a lot of files in Lesson 0.3. You typed into exactly one of them.

That is normal and it is not a trick. Every Android project has the same skeleton, because Gradle and Android both need certain things in certain places. Once you have seen the skeleton once, you can open any Android project ever made and know where to look.

Ten minutes here saves you from the most demoralising beginner experience there is: opening a project, seeing files you do not recognise, and quietly closing it again.

The whole tree

Here it is. Ignore the detail for a moment and just notice that it splits cleanly in two.

1Hello Pocket/
2├── settings.gradle.kts
3├── build.gradle.kts
4├── gradle.properties
5├── gradlew
6├── gradle/
7│   ├── libs.versions.toml
8│   └── wrapper/
9└── app/
10    ├── build.gradle.kts
11    └── src/main/
12        ├── AndroidManifest.xml
13        ├── java/com/yourname/hellopocket/
14        │   └── MainActivity.kt
15        └── res/
16            ├── values/strings.xml
17            ├── values/themes.xml
18            └── mipmap-anydpi-v26/

Everything ending in .kts, .properties or .toml is how to build it.

Everything under app/src/main is what to build.

Beginners lose hours by not knowing which half a file is in. A build.gradle.kts mistake stops the build before your code is even read; a MainActivity.kt mistake is your app misbehaving. Different problems, different places to look.

Half one — the plans

settings.gradle.kts

Two jobs. It names the project, and it lists which modules are in the build.

A module is a part of the project that gets built into one thing. Hello Pocket has exactly one, called :app. Big apps split into several; yours will not, all course.

It also lists where Gradle is allowed to download from — Google's repository and Maven Central. Those two lines are why implementation(...) works at all.

build.gradle.kts (the top-level one)

Short and slightly odd. It names the plugins the build uses — the Android plugin, the Kotlin plugin, the Compose plugin — but switches them off with apply false. It is a declaration, not an instruction. The module below turns them on.

app/build.gradle.kts — the one you will edit

This is the most important build file in the project, and the one you come back to whenever you add a library. The interesting part:

1android {
2  namespace = "com.yourname.hellopocket"
3  compileSdk = 35
4
5  defaultConfig {
6    applicationId = "com.yourname.hellopocket"
7    minSdk = 26
8    targetSdk = 35
9    versionCode = 1
10    versionName = "1.0"
11  }
12}

• namespace — the name your code lives under while it is being compiled.
• applicationId — the app's permanent, globally unique ID on a device and in the Play Store. It starts identical to the namespace, and the two are free to differ later.
• compileSdk 35 — which version of Android's code library you are allowed to type against. It does not affect which phones can install the app.
• minSdk 26 — the oldest Android that will accept your APK.
• targetSdk 35 — the version you promise you have tested on.
• versionCode / versionName — 1 is what Android compares to decide "is this an update?". "1.0" is the human-readable one people see.

Underneath sits a dependencies { } block listing the borrowed code your app uses. Hello Pocket's list is deliberately tiny — Compose, Material 3, and the glue that connects an Activity to Compose. Nothing else.

That matters more here than on a laptop. You are building on a phone: fewer dependencies means faster, cooler builds. Every entry in that list is something Gradle has to fetch, unpack and feed to the compiler on a device running off a battery.

gradle/libs.versions.toml

The version catalog: one file listing every version number in the project, so they are declared once rather than sprinkled across files.

1[versions]
2agp = "8.7.3"
3kotlin = "2.1.0"
4composeBom = "2024.12.01"

When a build file says libs.plugins.kotlin.android, it is reading this file. To upgrade Kotlin across the whole project you change one number here.

gradlew and gradle/wrapper/

The Gradle wrapper. gradlew is a small launcher script, and beside it is a file naming the exact Gradle version this project wants — gradle-8.11.1-bin.zip.

This is why nobody installs Gradle. Every project carries the exact version it was built with, downloads it on first use, and builds identically for everyone. It is also why your first build had a Downloading gradle-8.11.1-bin.zip line and your second did not.

gradle.properties

Settings for the build process itself, rather than for your app — chiefly how much memory Gradle may use. You will not touch it in this course.

Half two — the rooms

app/src/main/AndroidManifest.xml

Your app's ID card. Android reads this before it will run a single line of your code.

1<manifest xmlns:android="http://schemas.android.com/apk/res/android">
2  <application
3    android:icon="@mipmap/ic_launcher"
4    android:label="@string/app_name"
5    android:theme="@style/Theme.HelloPocket">
6    <activity
7      android:name=".MainActivity"
8      android:exported="true">
9      <intent-filter>
10        <action android:name="android.intent.action.MAIN" />
11        <category android:name="android.intent.category.LAUNCHER" />
12      </intent-filter>
13    </activity>
14  </application>
15</manifest>

The <intent-filter> block is the interesting one. MAIN plus LAUNCHER is Android's way of saying "this is the screen to open when someone taps the icon". Delete those five lines and your app builds perfectly, installs perfectly, and has no icon in the launcher at all.

android:exported="true" says other apps — including the home screen — are allowed to start this Activity. A launcher screen must be exported; screens deep inside your app usually should not be.

Notice that nothing here says "Hello Pocket". It says @string/app_name, which is a pointer. Which brings us to:

app/src/main/res/ — the resources

Everything in your app that is not code: text, colours, icons, shapes.

1<resources>
2  <string name="app_name">Hello Pocket</string>
3</resources>

That is where the words under your icon actually live. Keeping text out of the code is what makes translating an app possible later: add a values-fr/strings.xml and French phones pick it up with no code change at all.

values/themes.xml holds the theme the manifest points at. mipmap-anydpi-v26/ holds the launcher icon, which Part 6 replaces with something you designed.

app/src/main/java/.../MainActivity.kt

Your code. The only file you have written in so far, and the file the manifest names with android:name=".MainActivity".

The folder path matches the package line at the top of the file. That is not a coincidence — if you move the file without changing the package line, the build fails.

And the thing that came out

There is one more folder: app/build/. You did not make it — Gradle did, during the build. Everything in it can be deleted safely, and Gradle will make it again next time.

Deep inside is the file that is your app:

app/build/outputs/apk/debug/app-debug.apk

Unzip an APK — it really is a zip file — and you find roughly this:

1app-debug.apk
2├── AndroidManifest.xml    packed into a compact binary form
3├── classes.dex            all your compiled code, in one file
4├── resources.arsc         your text and colours, indexed
5├── res/                   icons and other picture files
6└── META-INF/              the signature that proves it is yours

classes.dex is the interesting one. Your Kotlin was compiled into an intermediate form, and then a tool called d8 repacked it into Dex, the format Android's runtime actually executes. That is the dexBuilderDebug line you watched scroll past.

META-INF/ holds the signature. Yours came from an automatic throwaway key, which is what makes it a debug build — instantly installable on your own phone, and not publishable. Part 6 covers the other kind.