B03 — Tiny notes

An app that stores data has to answer three questions: where the data lives, who owns it, and what the UI does while it loads. Room, a repository and a ViewModel are the conventional answers, and building the smallest version of each makes the conventions legible.

What you are building#

A list of notes with an add button, backed by a Room database. Each note has an id, a title and a body. The list updates automatically when the database changes, and a note survives process death.

Steps#

1. Add the dependencies

   Add Room, the Room compiler via KSP, and the lifecycle ViewModel library. Use a version catalog if your project has one; otherwise declare versions once in the module's build file.¹

   You should seeThe project still builds.
2. Define the entity

   Create a Note entity with an auto-generated id, a title and a body. Annotate the class with @Entity and the id with @PrimaryKey(autoGenerate = true).

   You should seeA data class with a primary key.

The entity is a plain data class with annotations:

@Entity(tableName = "notes")
data class Note(
    @PrimaryKey(autoGenerate = true) val id: Long = 0,
    val title: String,
    val body: String,
)

3. Define the DAO

   Create a NoteDao interface with a query returning a Flow<List<Note>> and an insert function marked suspend. The Flow is what makes the list live: the query re-emits when the table changes.

   You should seeCompiles, with generated code.

The DAO exposes a reactive query and a suspend insert:

@Dao
interface NoteDao {
    @Query("SELECT * FROM notes ORDER BY id DESC")
    fun observeAll(): Flow<List<Note>>
 
    @Insert
    suspend fun insert(note: Note): Long
}

4. Create the database

   Build a RoomDatabase with Room.databaseBuilder, register the entity and expose the DAO. Keep the instance in a single place; a second instance is a second connection and a source of confusion.

   You should seeA database instance that opens.
5. Add a repository

   Wrap the DAO in a repository that exposes the flow and the insert. It looks like ceremony for one table; it is the seam where a cache or a network source would go, and it keeps the ViewModel from knowing about Room.

   You should seeThe ViewModel has one dependency.
6. Add the ViewModel

   Expose the notes as a StateFlow derived from the repository's flow, with stateIn and a viewModelScope. The UI collects it; the ViewModel survives a rotation.

   You should seeA state flow of notes.
7. Build the UI

   Compose a LazyColumn over the notes, with a button that opens a simple form and inserts. Collect the state with collectAsStateWithLifecycle so collection stops when the app is not visible.

   You should seeA list that updates when you add a note.
8. Kill the process and reopen

   Use adb shell am kill on the package while the app is backgrounded, then reopen. The database persists, the ViewModel does not, and the data survives — which is the whole point of the data layer.

   You should seeThe notes are still there.

$ adb shell run-as com.example.tinynotes ls databases
adb shell run-as com.example.tinynotes ls -l databases
adb shell am kill com.example.tinynotes

Illustrative — the schema and path depend on your build.

Verification#

Add a note, rotate the device, kill the process, reopen. The note should be present after all three. Then change the query to return a plain list instead of a Flow and observe that the UI no longer updates without a manual refresh — that is the difference the reactive query buys you.

What you learned#

• The database is the source of truth, not the UI state. The UI observes it.
• A repository is a seam, not ceremony: it is where a second data source would be added.
• The ViewModel survives configuration changes but not process death; the database survives both.
• Reactive queries remove a class of bugs, because there is no separate refresh path to forget.

Read App data and databases for the storage model, and Data and domain layers for where the repository fits in a larger app.

Extend it#

1. Add a search query that filters with a WHERE title LIKE :term, and observe that the flow re-emits on both edits and new inserts.
2. Add a second table with a relation, and use @Relation to load a note with its tags.
3. Add an export that writes the notes to a file in the app's external files directory, then pull it with adb pull.

Sources#