Skip to content
Back to skills

Android Data Layer

ASecurity

Repositories and data sources per Google's data layer guide: models per layer, main-safety, lifetimes, errors, caching, WorkManager, offline-first sync. Use for repository, data source, Room, DataStore, network, or sync work, and when saves are cancelled on leaving a screen, work must survive process death, network or database models leak past repositories, or the app must work offline.

  • 5 stars
  • 0 votes
  • 0 copies
  • 0 views
  • Added November 18, 2026
developmentgokotlintestingapidatabase

Works with

  • api

Security analysis

A100/100

Pro scans all 3 files and shows the line behind each finding

Scanned November 18, 2026

npx -y skills add pablitoarango/android-skills --skill android-data-layer --agent claude-code

Installs into .claude/skills of the current project.

Are you the author of Android Data Layer?

Add the live security badge to your README. It updates with every re-scan.

Security grade badge for Android Data Layer
[![Security: A — Skills Directory](https://www.skillsdirectory.com/api/skills/pablitoarango-android-data-layer/badge)](https://www.skillsdirectory.com/skills/pablitoarango-android-data-layer)

More formats (shields.io, HTML) on the badges page. Keep it an A: scan every change in CI with Pro.

Download with Pro
SKILL.md
---
name: android-data-layer
description: "Repositories and data sources per Google's data layer guide: models per layer, main-safety, lifetimes, errors, caching, WorkManager, offline-first sync. Use for repository, data source, Room, DataStore, network, or sync work, and when saves are cancelled on leaving a screen, work must survive process death, network or database models leak past repositories, or the app must work offline."
---

# Android Data Layer

Sources of truth: [Data layer](https://developer.android.com/topic/architecture/data-layer), [Offline-first](https://developer.android.com/topic/architecture/data-layer/offline-first), [Hilt and WorkManager](https://developer.android.com/training/dependency-injection/hilt-jetpack#workmanager), [WorkManager custom configuration](https://developer.android.com/develop/background-work/background-tasks/persistent/configuration/custom-configuration).

For offline-first reads, write strategies, synchronization and conflict resolution, read [`offline-first.md`](offline-first.md).

## 1. Responsibilities

The data layer holds the app data **and the business logic** that gives it value:

- Exposes data to the rest of the app as immutable types.
- Centralizes every change to that data.
- Resolves conflicts between data sources.
- Hides data sources from the rest of the app.

## 2. Structure

```
Repository (public)          one per data type; the only entry point
  ├── XxxLocalDataSource     internal; one source each (Room, DataStore, file)
  └── XxxRemoteDataSource    internal; one source each (Retrofit, Firebase)
```

- Create a repository **even for a single data source**.
- Each repository defines **one source of truth**. For offline-first data it is the local database.
- Each data source works with exactly one source of data.
- Name data sources by role, not technology: `NewsRemoteDataSource`, not `NewsRetrofitDataSource`.
- Repositories may depend on other repositories when combining data; such a class may optionally be named `<DataType>Manager` (`UserManager`).
- ViewModels, use cases and composables never inject a DAO, Retrofit service, DataStore or data source.

```kotlin
interface NewsRepository {
    fun getNewsStream(): Flow<List<Article>>
    suspend fun refreshNews()
}

internal class OfflineFirstNewsRepository @Inject constructor(
    private val localDataSource: NewsLocalDataSource,
    private val remoteDataSource: NewsRemoteDataSource,
) : NewsRepository {

    override fun getNewsStream(): Flow<List<Article>> =
        localDataSource.getArticlesStream().map { entities -> entities.map(ArticleEntity::asExternalModel) }

    override suspend fun refreshNews() {
        val articles = remoteDataSource.fetchLatestNews()
        localDataSource.upsertArticles(articles.map(NetworkArticle::asEntity))
    }
}
```

Bind it in the data module:

```kotlin
@Module
@InstallIn(SingletonComponent::class)
internal abstract class NewsDataModule {
    @Binds
    abstract fun bindsNewsRepository(impl: OfflineFirstNewsRepository): NewsRepository
}
```

## 3. API shape

- **One-shot operations**: `suspend fun`.
- **Data that changes over time**: `Flow<T>`, named `get<Model>Stream()` (`getArticlesStream()` for lists).
- Expose immutable types only.
- Every public function is **main-safe**.

## 4. Models per layer

| Model | Example | Visibility |
|---|---|---|
| Network | `NetworkArticle` (`@Serializable`, mirrors the API) | `internal` |
| Database | `ArticleEntity` (Room `@Entity`) | `internal` |
| External | `Article` (only fields the app needs) | public, in `:core:model` |

Mappers are extension functions: `NetworkArticle.asEntity()`, `ArticleEntity.asExternalModel()`. Create a separate model whenever the source shape differs from what the app needs; do not leak network or database models past the repository.

The table assumes sources and repositories share a module. For separate network/database modules, expose a minimal API to repository consumers; `internal` types cannot cross module boundaries. See `android-architecture`.

## 5. Threading

- Classes that do blocking work move it to an **injected** dispatcher with `withContext`.
- Room DAO `suspend`/`Flow` functions and Retrofit `suspend` functions are already main-safe, so wrapping them in `withContext(io)` or `flowOn(io)` is unnecessary. Switch dispatchers for truly blocking work (file I/O, parsing large payloads, legacy blocking SDKs).

```kotlin
internal class NewsRemoteDataSource @Inject constructor(
    private val newsApi: NewsApi,
) {
    suspend fun fetchLatestNews(): List<NetworkArticle> = newsApi.fetchLatestNews()
}
```

## 6. Lifetime of operations

| Operation | Must survive | Implementation |
|---|---|---|
| UI-oriented | Caller's lifetime | Caller's scope through `suspend`; `viewModelScope` cancels when the ViewModel is cleared, not merely hidden |
| App-oriented | Navigation away from the screen, while the app is open | Injected application `CoroutineScope` (`externalScope`) |
| Business-oriented | Process death | WorkManager |

App-oriented work with an in-memory cache uses a separate one-shot contract in this example:

```kotlin
interface LatestNewsRepository {
    suspend fun getLatestNews(refresh: Boolean = false): List<Article>
}

@Singleton
internal class DefaultLatestNewsRepository @Inject constructor(
    private val remoteDataSource: NewsRemoteDataSource,
    @ApplicationScope private val externalScope: CoroutineScope,
) : LatestNewsRepository {

    private val latestNewsMutex = Mutex()
    private var latestNews: List<Article> = emptyList()

    override suspend fun getLatestNews(refresh: Boolean): List<Article> {
        if (refresh || latestNewsMutex.withLock { latestNews.isEmpty() }) {
            externalScope.async {
                remoteDataSource.fetchLatestNews().map(NetworkArticle::asExternalModel).also { fresh ->
                    latestNewsMutex.withLock { latestNews = fresh }
                }
            }.await()
        }
        return latestNewsMutex.withLock { latestNews }
    }
}
```

Business-oriented work:

```kotlin
@HiltWorker
class RefreshLatestNewsWorker @AssistedInject constructor(
    @Assisted context: Context,
    @Assisted params: WorkerParameters,
    private val newsRepository: NewsRepository,
) : CoroutineWorker(context, params) {
    override suspend fun doWork(): Result = try {
        newsRepository.refreshNews()
        Result.success()
    } catch (e: IOException) {
        Result.retry()
    }
}
```

Put enqueuing and cancelling in a task data source named after its data (`NewsTasksDataSource` wrapping `WorkManager`) that the repository depends on. Trigger startup work from an App Startup `Initializer` that calls the repository.

`@HiltWorker` needs `androidx.hilt:hilt-work` plus `androidx.hilt:hilt-compiler` (KSP); see the [Hilt release page](https://developer.android.com/jetpack/androidx/releases/hilt). The `Application` must implement `Configuration.Provider` with an injected `HiltWorkerFactory`, and the default WorkManager initializer must be removed from the manifest ([custom configuration](https://developer.android.com/develop/background-work/background-tasks/persistent/configuration/custom-configuration)). Workers may only use `@Singleton` or unscoped bindings.

Scope DI bindings to the lifetime of the data they hold: `@Singleton` for app-wide caches, a narrower component for flow-specific data, nothing for stateless classes.

## 7. Errors

- Let data sources throw; the repository either lets exceptions propagate or translates them into meaningful custom exceptions (`UserNotAuthenticatedException`).
- Alternatively return `Result<T>` from the repository. Pick one style per repository and keep it consistent.
- Never swallow `CancellationException`. When wrapping in `Result`, use `suspendRunCatching` from `android-coroutines`, not `runCatching`.
- Flows: handle with the `catch` operator at the consumer (usually the ViewModel).
- The UI layer decides how an error is shown.

## 8. Choosing storage

| Data | Storage |
|---|---|
| Large, queryable, relational, partial updates | Room |
| Small key-value data (settings, preferences) | DataStore (one instance per concern) |
| Large blobs (JSON documents, images) | Files |

## 9. Testing

- Unit test repositories on the JVM with **fake data sources**; tests of consumers use **fake repositories**.
- Integration test Room DAOs with an in-memory database.
- Integration test network data sources against MockWebServer.
- See `android-testing`.

## 10. Checklist

- [ ] Every data type is exposed by a repository; nothing outside the data layer touches a data source.
- [ ] Each repository has one source of truth.
- [ ] Co-located data implementation types are `internal`; split modules expose a minimal repository-facing API. Mappers convert at the repository.
- [ ] `suspend` for one-shot, `Flow` named `get...Stream()` for changes; all main-safe.
- [ ] Dispatchers are injected; blocking work is moved off the main thread.
- [ ] Work that must outlive the screen uses the external scope; work that must survive process death uses WorkManager.
- [ ] Errors propagate as exceptions or `Result` consistently; `CancellationException` is rethrown.

Files in this skill

  • SKILL.md9 KB
  • agents/openai.yaml122 B
  • offline-first.md5 KB

Attribution

Is this your skill, or is something wrong with this listing? Request removal or report an issue. Author removals are honored within 72 hours.

View all in development →

Comments

Loading comments…

Newsletter

Get the weekly list of safe new skills, and the ones we pulled.