Clean Architecture in Android: Practical Lessons

// Plain Kotlin: no Android, Room or serialization annotations.
data class Article(
    val id: String,
    val title: String,
    val savedAt: java.time.Instant,
    val isPinned: Boolean,
)

interface SavedArticlesRepository {
    fun observeSaved(): kotlinx.coroutines.flow.Flow<List<Article>>
    suspend fun refresh()
    suspend fun unsave(id: String)
}

import java.time.Clock
import java.time.Duration
import javax.inject.Inject
import kotlinx.coroutines.flow.Flow
import kotlinx.coroutines.flow.map

/** Business rule: hide unpinned items saved more than 90 days ago; pinned first, newest first. */
class GetVisibleSavedArticlesUseCase @Inject constructor(
    private val repository: SavedArticlesRepository,
    private val clock: Clock,                          // injectable → deterministic tests
) {
    operator fun invoke(): Flow<List<Article>> = repository.observeSaved().map { articles ->
        val cutoff = clock.instant().minus(Duration.ofDays(90))
        articles
            .filter { it.isPinned || it.savedAt.isAfter(cutoff) }
            .sortedWith(compareByDescending<Article> { it.isPinned }.thenByDescending { it.savedAt })
    }
}

class SavedArticlesRepositoryImpl @Inject constructor(
    private val api: SavedArticlesApi,          // Retrofit
    private val dao: SavedArticleDao,           // Room
) : SavedArticlesRepository {

    // Room is the single source of truth; the UI always reads from the database.
    override fun observeSaved(): Flow<List<Article>> =
        dao.observeAll().map { entities -> entities.map { it.toDomain() } }

    override suspend fun refresh() {
        val remote = api.getSaved()                       // throws IOException/HttpException
        dao.replaceAll(remote.map { it.toEntity() })      // @Transaction in the DAO
    }

    override suspend fun unsave(id: String) {
        dao.delete(id)                                    // optimistic local update
        api.unsave(id)                                    // in production: queue with WorkManager on failure
    }
}

// Mappers live at the boundary that needs them.
private fun SavedArticleEntity.toDomain() =
    Article(id = id, title = title, savedAt = Instant.ofEpochMilli(savedAtMillis), isPinned = pinned)

private fun SavedArticleDto.toEntity() =
    SavedArticleEntity(id = id, title = title, savedAtMillis = savedAt, pinned = pinned)

data class SavedUiState(
    val articles: List<Article> = emptyList(),
    val isRefreshing: Boolean = false,
    val message: String? = null,
)

@HiltViewModel
class SavedArticlesViewModel @Inject constructor(
    getVisibleSaved: GetVisibleSavedArticlesUseCase,
    private val repository: SavedArticlesRepository,      // simple actions call the repository directly
) : ViewModel() {

    private val refreshing = MutableStateFlow(false)
    private val message = MutableStateFlow<String?>(null)

    val uiState: StateFlow<SavedUiState> =
        combine(getVisibleSaved(), refreshing, message) { articles, isRefreshing, msg ->
            SavedUiState(articles, isRefreshing, msg)
        }.stateIn(viewModelScope, SharingStarted.WhileSubscribed(5_000), SavedUiState())

    init { refresh() }

    fun refresh() = viewModelScope.launch {
        refreshing.value = true
        try {
            repository.refresh()
        } catch (e: IOException) {
            message.value = "Showing saved copies. Couldn't reach the server."
        } finally {
            refreshing.value = false
        }
    }

    fun unsave(id: String) = viewModelScope.launch { repository.unsave(id) }
    fun messageShown() { message.value = null }
}

@Module
@InstallIn(SingletonComponent::class)
abstract class DataModule {
    @Binds
    abstract fun bindSavedArticlesRepository(impl: SavedArticlesRepositoryImpl): SavedArticlesRepository
}

@Module
@InstallIn(SingletonComponent::class)
object TimeModule {
    @Provides
    fun provideClock(): Clock = Clock.systemUTC()
}

class GetVisibleSavedArticlesUseCaseTest {
    private val now = Instant.parse("2026-10-14T10:00:00Z")
    private val clock = Clock.fixed(now, ZoneOffset.UTC)

    private class FakeRepo(private val items: List<Article>) : SavedArticlesRepository {
        override fun observeSaved() = flowOf(items)
        override suspend fun refresh() = Unit
        override suspend fun unsave(id: String) = Unit
    }

    @Test
    fun `old unpinned articles are hidden, pinned ones stay first`() = runTest {
        val old = Article("1", "Old", now.minus(Duration.ofDays(120)), isPinned = false)
        val oldPinned = Article("2", "Old pinned", now.minus(Duration.ofDays(200)), isPinned = true)
        val recent = Article("3", "Recent", now.minus(Duration.ofDays(2)), isPinned = false)

        val result = GetVisibleSavedArticlesUseCase(FakeRepo(listOf(old, oldPinned, recent)), clock)().first()

        assertEquals(listOf("2", "3"), result.map { it.id })
    }
}

:app                         ← navigation, DI graph assembly
:feature:saved               ← UI + ViewModels for "Saved articles"
:feature:search
:core:domain                 ← pure Kotlin: models, repository interfaces, use cases
:core:data                   ← repository implementations
:core:network                ← Retrofit setup, DTOs
:core:database               ← Room database, DAOs, entities
:core:designsystem           ← theme, shared composables