Drawing the Right Boundaries Between Clean Architecture Layers in Android

// ✅ Pure Kotlin. No imports from Android, Room, Retrofit, or anything else.
data class User(
    val id: UserId,
    val email: Email,
    val role: UserRole
) {
    fun canAccessAdminPanel(): Boolean = role == UserRole.ADMIN
}

// Wrap primitives with value types where the domain demands it.
@JvmInline
value class UserId(val value: String)

@JvmInline
value class Email(val value: String) {
    init {
        require(value.contains('@')) { "Invalid email: $value" }
    }
}

// Domain defines what it NEEDS, not how it's provided
interface UserRepository {
    suspend fun getUserById(id: UserId): Result<User>
    suspend fun updateDisplayName(id: UserId, name: String): Result<Unit>
    fun observeUser(id: UserId): Flow<User?>
}

class UpdateUserDisplayNameUseCase @Inject constructor(
    private val userRepository: UserRepository,  // interface, not impl
    private val analyticsRepository: AnalyticsRepository
) {
    suspend operator fun invoke(
        userId: UserId,
        newName: String
    ): Result<Unit> {
        if (newName.isBlank() || newName.length < 2) {
            return Result.failure(InvalidDisplayNameException())
        }
        return userRepository
            .updateDisplayName(userId, newName)
            .onSuccess { analyticsRepository.track(Event.ProfileUpdated) }
    }
}

class UserRepositoryImpl @Inject constructor(
    private val remoteDataSource: UserRemoteDataSource,
    private val localDataSource: UserLocalDataSource,
    private val mapper: UserMapper
) : UserRepository {  // ← implements the domain interface

    override suspend fun getUserById(id: UserId): Result<User> {
        return runCatching {
            val dto = remoteDataSource.fetchUser(id.value)
            mapper.toDomain(dto)  // ← always map at the boundary
        }.recoverCatching {
            val entity = localDataSource.getUser(id.value)
                ?: throw UserNotFoundException(id)
            mapper.toDomain(entity)
        }
    }
}

// Remote — knows about Retrofit, API models
class UserRemoteDataSource @Inject constructor(
    private val api: UserApi
) {
    suspend fun fetchUser(id: String): UserDto = api.getUser(id)
}

// Local — knows about Room
class UserLocalDataSource @Inject constructor(
    private val dao: UserDao
) {
    suspend fun getUser(id: String): UserEntity? = dao.findById(id)
    suspend fun upsertUser(entity: UserEntity) = dao.upsert(entity)
}

// ✅ ViewModel depends on use cases, never on repositories directly
class UserProfileViewModel @Inject constructor(
    private val getUserProfile: GetUserProfileUseCase
) : ViewModel() {

    private val _uiState = MutableStateFlow<UserProfileUiState>(UserProfileUiState.Loading)
    val uiState: StateFlow<UserProfileUiState> = _uiState.asStateFlow()

    fun loadProfile(userId: String) {
        viewModelScope.launch {
            _uiState.value = UserProfileUiState.Loading
            getUserProfile(UserId(userId))
                .onSuccess { profile ->
                    _uiState.value = UserProfileUiState.Success(profile.toUiModel())
                }
                .onFailure { error ->
                    _uiState.value = UserProfileUiState.Error(error.toUiMessage())
                }
        }
    }
}

// Presentation mapper — lives in the presentation layer
fun User.toUiModel(): UserProfileUiModel = UserProfileUiModel(
    displayName = "${firstName.uppercase()} $lastName",
    avatarUrl = avatarUrl ?: DEFAULT_AVATAR,
    badgeText = if (role == UserRole.ADMIN) "Admin" else null
)

// ✅ Hilt module wires up the dependency graph in the outermost layer
@Module
@InstallIn(SingletonComponent::class)
object DataModule {

    @Provides
    @Singleton
    fun provideUserRepository(
        userDao: UserDao,
        apiService: UserApiService,
        mapper: UserEntityMapper
    ): UserRepository = UserRepositoryImpl(userDao, apiService, mapper)
}

// ❌ LiveData is an Android type. Domain layer must not know it exists.
interface UserRepository {
    fun getUser(id: String): LiveData<User>
}

// ✅ Use Kotlin coroutines or plain suspend functions instead.
interface UserRepository {
    suspend fun findById(id: UserId): User?
    fun observeUser(id: UserId): Flow<User?>
}

// ❌ Room entity used directly in the domain layer
@Entity(tableName = "users")
data class UserEntity(
    @PrimaryKey val id: String,
    @ColumnInfo(name = "email") val email: String,
    @ColumnInfo(name = "role") val role: String  // stringly-typed!
)

// ✅ Separate models, separate concerns
// Domain model (no Room annotations, strongly typed)
data class User(val id: UserId, val email: Email, val role: UserRole)

// Data model (Room-specific)
@Entity(tableName = "users")
data class UserEntity(
    @PrimaryKey val id: String,
    val email: String,
    val role: String
)

// Mapper lives in the data layer
class UserEntityMapper {
    fun toDomain(entity: UserEntity): User = User(
        id = UserId(entity.id),
        email = Email(entity.email),
        role = UserRole.valueOf(entity.role)
    )
    fun toEntity(domain: User): UserEntity = UserEntity(
        id = domain.id.value,
        email = domain.email.value,
        role = domain.role.name
    )
}

// ❌ "God" use case — orchestrates, transforms, caches, logs, and formats
class UserUseCase(private val repo: UserRepository) {
    suspend fun getFormattedUserName(id: String): String {
        val user = repo.findById(UserId(id)) ?: throw Exception("Not found")
        analyticsService.log("user_fetched") // Where did this come from?
        return "${user.firstName.uppercase()} ${user.lastName}"  // UI formatting in domain!
    }
}

// ✅ Use case handles one application-level concern
class GetUserUseCase(private val repo: UserRepository) {
    suspend operator fun invoke(id: UserId): Result<User> =
        runCatching { repo.findById(id) ?: throw UserNotFoundException(id) }
}

// Formatting belongs in the presentation layer (a UiModel mapper)
fun User.toUiModel(): UserUiModel = UserUiModel(
    displayName = "${firstName.uppercase()} $lastName"
)

// ❌ ViewModel bypasses the domain layer entirely
class UserViewModel(private val repo: UserRepositoryImpl) : ViewModel() {
    fun loadUser(id: String) = repo.getUser(id) // Direct Room access, no business logic
}

// ✅ ViewModel depends on a use case, which depends on a repository interface
class UserViewModel(private val getUser: GetUserUseCase) : ViewModel() {
    fun loadUser(id: String) {
        viewModelScope.launch {
            getUser(UserId(id)).onSuccess { /* update state */ }
        }
    }
}

// ❌ Context in a use case — untestable and wrong
class GetLocaleUseCase(private val context: Context) {
    operator fun invoke(): Locale = context.resources.configuration.locales[0]
}

// ✅ Define what you need as an interface in the domain layer
interface LocaleProvider {
    fun currentLocale(): Locale
}

class GetLocaleUseCase(private val localeProvider: LocaleProvider) {
    operator fun invoke(): Locale = localeProvider.currentLocale()
}

// Implement it in the framework layer
class AndroidLocaleProvider(private val context: Context) : LocaleProvider {
    override fun currentLocale(): Locale =
        context.resources.configuration.locales[0]
}

// domain/build.gradle.kts — zero Android dependencies
plugins {
    id("java-library")
    alias(libs.plugins.kotlin.jvm)
}

dependencies {
    implementation(libs.kotlinx.coroutines.core) // ✅ Pure Kotlin, acceptable
    // No androidx. No Room. No Retrofit. Ever.
}

// data/build.gradle.kts
dependencies {
    implementation(project(":domain"))   // knows domain interfaces
    implementation(libs.room.runtime)
    implementation(libs.retrofit)
    // ❌ Cannot accidentally import :presentation — it's not in the graph
}

// presentation/build.gradle.kts
dependencies {
    implementation(project(":domain"))   // calls use cases, maps entities to UiModels
    // ❌ Cannot import :data — Room and Retrofit are invisible from here
}

class UpdateUserDisplayNameUseCaseTest {

    private val userRepository: UserRepository = mockk()
    private val analyticsRepository: AnalyticsRepository = mockk(relaxed = true)
    private val useCase = UpdateUserDisplayNameUseCase(userRepository, analyticsRepository)

    @Test
    fun `returns failure when name is blank`() = runTest {
        val result = useCase(UserId("123"), newName = "  ")
        assertTrue(result.isFailure)
        assertIs<InvalidDisplayNameException>(result.exceptionOrNull())
        coVerify(exactly = 0) { userRepository.updateDisplayName(any(), any()) }
    }

    @Test
    fun `tracks analytics event on success`() = runTest {
        coEvery { userRepository.updateDisplayName(any(), any()) } returns Result.success(Unit)
        useCase(UserId("123"), newName = "Jane")
        coVerify { analyticsRepository.track(Event.ProfileUpdated) }
    }
}

class UserProfileViewModelTest {

    @get:Rule
    val mainDispatcherRule = MainDispatcherRule()

    @Test
    fun `emits Success state when use case returns a user`() = runTest {
        val fakeUseCase = FakeGetUserProfileUseCase(
            result = Result.success(testUser())
        )
        val viewModel = UserProfileViewModel(fakeUseCase)

        viewModel.loadProfile("123")

        val state = viewModel.uiState.value
        assertIs<UserProfileUiState.Success>(state)
        assertEquals("JANE Doe", state.profile.displayName)
    }

    @Test
    fun `emits Error state when use case fails`() = runTest {
        val fakeUseCase = FakeGetUserProfileUseCase(
            result = Result.failure(UserNotFoundException(UserId("123")))
        )
        val viewModel = UserProfileViewModel(fakeUseCase)

        viewModel.loadProfile("123")

        assertIs<UserProfileUiState.Error>(viewModel.uiState.value)
    }
}