android-architecture-samples: one to-do app, a branch per architecture

Each architecture is a branch, and the repository publishes no releases

The organisation of this repository is the first thing to understand, because it is unusual and it dictates everything else. The same to-do app is implemented with small differences in the repository's different branches, not in different directories of one tree. The top level confirms the shape: a single `app/` directory, one `build.gradle.kts`, one `settings.gradle.kts`, one `shared-test/` directory. There are also no GitHub releases, so there is no tag, no version, and no artifact to depend on. What you consume is a branch, and a branch is a moving target with no name you can write down. The consequences stack up. Browsing the alternatives means knowing in advance that they exist, because a clone of the default branch shows one architecture and says nothing about the others. Switching approach is a checkout that replaces the whole tree rather than a module you add alongside. And an automated job that wants a particular approach has to pin a branch, not a version, and re-pin it whenever that branch moves. The single command the file offers is a clone, and it comes with the instruction to check out one of the sample branches first, then open the root directory in Android Studio:

git clone [email protected]:android/architecture-samples.git

Finally open the `architecture-samples/` directory in Android Studio.

The file describes one branch, and the phrase in this branch does the work

After the general statement about branches, the file says In this branch you'll find, and then enumerates what is in it. The user interface is built with Jetpack Compose. The architecture is single-activity using Navigation Compose. The presentation layer holds a Compose screen, referred to as a View, and a ViewModel per screen or per feature. Asynchronous work uses Flow and coroutines. The data layer is a repository with two data sources, local using Room and a fake remote. There are two product flavors, `mock` and `prod`, described as easing development and testing. There is a collection of unit, integration and e2e tests, including shared tests that can be run on emulator or device. Dependency injection is Hilt. That is an accurate and complete description of one architecture, but the two words introducing it are the only signal that other arrangements exist and that this one is the default. Nothing in the file enumerates the sibling branches, names them, or says which to pick.

The remote data source is fake, and network access is explicitly out of scope

Two statements in the same file draw the boundary of the data layer. The architecture includes a data layer with a repository and two data sources, one local using Room and one a fake remote. And the project states it is not a real production app with network access or user authentication, pointing readers to Now in Android for that. Together they mean the repository pattern is shown at the interface level while the transport underneath is a stand-in. So a sample like this can demonstrate shape: a repository the presentation layer talks to, a local source of truth in Room, and a seam where a real implementation would go. It cannot demonstrate the parts of a data layer that decide whether a product works, because there is no real client, no response to parse, no status code to branch on, and no session to expire. A team copying the repository interface inherits a clean abstraction and none of the failure handling, which is the part that has to be written against their own backend.

mock and prod are build-time flavors, not a runtime switch

The mechanism for keeping the fake remote out of the way is a pair of product flavors named `mock` and `prod`, described as easing development and testing, with a link to a post about leveraging product flavors in Android. What that buys is a compile-time substitution. The build produces more than one variant, and which data source a given build wires in is decided when the package is produced, not when it runs. The consequences are worth spelling out. A developer who builds the wrong variant gets a fully working application that silently reads invented data, with no error and no visual difference, so the mistake surfaces as a puzzling report rather than a build failure. The same applies to continuous integration, where the flavor becomes a job parameter. Because the choice lives in the Gradle configuration, it is not inspectable from the running app, and the file does not say which flavor a shipping build is meant to use. Nor does it say where the substitution is wired, so finding it means searching the source.

The app specification lives in a differently named repository

The file explains the choice of app with a link to the app's specification, and that link deserves a close look. It points at the wiki of googlesamples/android-architecture, on a page named To-do-app-specification. The repository you are reading is android/architecture-samples. The document that defines what the sample is supposed to do, the requirements the architecture is meant to satisfy, is therefore not in this repository and does not sit under the same owner or the same name. The top level bears this out, since there is no specification file among the entries, only README.md, CONTRIBUTING.md, CODEOWNERS, and LICENSE beside the build files and the app directory. The consequence is that the one document which would let you judge whether the architecture meets its brief requires leaving the repository and trusting a link. For a project whose stated purpose is to be discussed and compared, the requirements and the implementation sit in different places.

Three times the file redirects you to a different repository

The project has a section titled What is it not, and it answers with three redirects. It is not a template, and for that there are Architecture Templates. It is not a UI or Material Design sample, with the note that the interface is deliberately kept simple so the focus stays on architecture, and for that there are the Compose Samples. And it is not a real production app with network access and user authentication, and for that there is Now in Android. The last two are the most useful sentences in the file, because they tell you what you will not find here. Deliberately plain interface code is not a model for your own screens, and a repository over a fake remote is not a model for a production data layer. Set that against the audience section, which names intermediate developers and beginners looking for a way to structure an app in a testable and maintainable way and advanced developers looking for quick reference, and the repository is positioning itself as a reference to read.

The wrapper, renovate.json, and spotless decide what you can change

The top level tells you how the repository is policed as much as how it is built. `gradlew` and `gradlew.bat` are committed alongside a `gradle/` directory, so the Gradle version the build expects travels with the code rather than depending on what you have installed. A `renovate.json` file sits at the root, which is the configuration for automated dependency update pull requests, so version bumps arrive as generated changes rather than as decisions somebody reviewed. A `spotless/` directory is present, which is a formatter enforced by the build rather than a style argued about in review, and there is a `CODEOWNERS` file and a `CONTRIBUTING.md` for routing and expectations. A `.google/` directory sits beside them. The practical effect is that formatting is not yours to change and dependency versions are not yours to schedule. Combine that with the absence of releases and the things a reader actually controls narrow to the branch they check out and the questions they ask of it.

Editorial conclusion

Use this repository as reading material rather than as a codebase to start from, because the project says so itself three times and points you to Architecture Templates, Compose Samples, and Now in Android for the cases it deliberately does not cover. What the default branch gives you is a clear and small demonstration of one arrangement: Compose, a single activity with Navigation Compose, a ViewModel per screen, Flow and coroutines, a repository over Room and a fake remote, mock and prod flavors, and Hilt. Before adopting any of it, hold on to three facts. The data layer has no real network behind it, the specification that defines what the app is supposed to do lives in a wiki under a different repository name, and there are no releases, so the version you read is whatever the branch happened to hold today.

Frequently asked questions

Official sources

1. Official README
2. Project repository