App architecture: layers and repositories

Why layers?

Small apps can live in a few files. Real apps grow: more screens, offline support, new APIs, more developers. Without structure, network code ends up inside screens, the same logic is copied in three places, and every change breaks something. Separating the app into layers with clear jobs keeps changes small and code testable.

┌──────────────── UI layer ────────────────┐
│ Composables  <--state--  ViewModels      │
│              --events-->                 │
└───────────────────┬──────────────────────┘
                    │ calls
┌───────── Domain layer (optional) ────────┐
│ Use cases: PlaceOrderUseCase, ...        │
└───────────────────┬──────────────────────┘
                    │ calls
┌──────────────── Data layer ──────────────┐
│ Repositories: OrderRepository, ...       │
│   ├── Remote data source (Retrofit API)  │
│   └── Local data source (Room, DataStore)│
└──────────────────────────────────────────┘

The UI layer

Composables show state and send events; ViewModels hold UI state and call the layers below. The UI layer should not know whether data came from a server or a database.

The data layer and repositories

A repository is a class that is the single entry point for one kind of data, such as orders or products. It decides where the data comes from (network, database, cache), combines and caches it, and exposes clean functions and flows. A data source is a lower-level class that talks to exactly one source, like the Retrofit API or the Room DAO.

class OrderRepository(
    private val api: OrderApi,          // remote data source
    private val dao: OrderDao,          // local data source
) {
    // Single source of truth: the UI always reads from the database
    val orders: Flow<List<Order>> = dao.observeAll()

    suspend fun refresh() {
        val fresh = api.getOrders()      // network
        dao.replaceAll(fresh)            // save; the Flow above emits the new list
    }
}

Single source of truth (SSOT) means each piece of data has one owner that everyone reads from. Here the database is the SSOT for orders, so the list looks the same on every screen, works offline, and updates everywhere when it changes.

The optional domain layer

When several ViewModels need the same business logic (for example "apply coupon and calculate GST"), put it in a use case class with one public function, such as CalculateBillUseCase. Small apps can skip this layer; add it when you see duplication.

Unidirectional data flow

Across all layers, state flows down (database to repository to ViewModel to UI) and events flow up (UI to ViewModel to repository). Data is never changed from two directions at once, which removes a whole family of "why did this change?" bugs.

Common mistakes

• Calling Retrofit directly from a ViewModel or composable. Go through a repository.
• Repositories that return Android UI types (Color, painter). Keep the data layer free of UI.
• Several sources of truth (one list in memory, another in the database) that drift apart.
• Adding every layer and abstraction to a tiny app. Start simple; add layers as the app grows.