Android / KMP Presentation Layer (MVI)

State

Choose the State structure based on the screen's UI:

Data class — states coexist (forms, pull-to-refresh)

data class NoteEditorState(
    val title: String = "",
    val body: String = "",
    val isSaving: Boolean = false,
    val titleError: UiText? = null
)

Sealed — screen fully changes between phases

sealed interface NoteListState {
    data object Loading : NoteListState
    data class Content(val notes: List<NoteUi>) : NoteListState
    data class Error(val message: UiText) : NoteListState
}

Hybrid — exclusive phases + combined fields inside

sealed interface NoteListState {
    data object Loading : NoteListState
    data class Content(
        val notes: List<NoteUi>,
        val isRefreshing: Boolean = false,
        val searchQuery: String = ""
    ) : NoteListState
    data class Error(val message: UiText) : NoteListState
}

Decision rule: Look at the UI — does the screen fully change between states?

• Yes → sealed
• No → data class
• First load changes fully, then inside one state there are variations → hybrid

Always update state with .update { } — never replace the entire flow:

_state.update { it.copy(isLoading = true) }

Action / ViewIntent

sealed interface NoteListIntent {
    data object OnRefreshClick : NoteListIntent
    data class OnNoteClick(val noteId: String) : NoteListIntent
    data class OnDeleteNote(val noteId: String) : NoteListIntent
}

Event / ViewSideEffect

sealed interface NoteListSideEffect {
    data class NavigateToDetail(val noteId: String) : NoteListSideEffect
    data class ShowSnackbar(val message: UiText) : NoteListSideEffect
}

ViewModel

@HiltViewModel // or no annotation for Koin
class NoteListViewModel(
    private val noteRepository: NoteRepository
) : ViewModel() {

    private val _state = MutableStateFlow(NoteListState())
    val state = _state.asStateFlow()

    private val _sideEffects = Channel<NoteListSideEffect>()
    val sideEffects = _sideEffects.receiveAsFlow()

    fun onIntent(intent: NoteListIntent) {
        when (intent) {
            is NoteListIntent.OnRefreshClick -> loadNotes()
            is NoteListIntent.OnNoteClick -> {
                viewModelScope.launch {
                    _sideEffects.send(NoteListSideEffect.NavigateToDetail(intent.noteId))
                }
            }
        }
    }

    private fun loadNotes() {
        viewModelScope.launch {
            _state.update { it.copy(isLoading = true) }
            noteRepository.getNotes()
                .onSuccess { notes ->
                    _state.update { it.copy(notes = notes.map { it.toNoteUi() }, isLoading = false) }
                }
                .onFailure { error ->
                    _state.update { it.copy(isLoading = false) }
                    _sideEffects.send(NoteListSideEffect.ShowSnackbar(error.toUiText()))
                }
        }
    }
}

Coroutine Dispatchers

Do not inject unless the class is unit-tested and dispatches to a non-main dispatcher.

suspend fun compressImage(bytes: ByteArray): ByteArray = withContext(Dispatchers.IO) {
    // blocking compression logic
}

Only inject CoroutineDispatcher when:

1. The class dispatches to a non-main dispatcher (e.g., IO), AND
2. That class is directly unit-tested.

Mapping Errors to UI Strings

UiText wraps strings from string resources or dynamic values:

sealed interface UiText {
    data class DynamicString(val value: String) : UiText
    class StringResource(val id: Int, val args: Array<Any> = emptyArray()) : UiText
}

• Use UiText for error messages that map to R.string.*
• Use plain String for always-dynamic values (user name, formatted date)

data class NoteListState(val error: UiText? = null)
data class NoteUi(val authorName: String, val formattedDate: String)

UI Model

data class NoteUi(
    val id: String,
    val title: String,
    val formattedDate: String
)

fun Note.toNoteUi(): NoteUi = NoteUi(
    id = id,
    title = title,
    formattedDate = date.format(...)
)

UI models are always suffixed with Ui.

Composable Structure

Screen composable (*Screen.kt) — stateful

Receives ViewModel (via hiltViewModel() or koinViewModel()), observes side effects, passes state and onIntent down.

Content composable (*Content.kt) — stateless

Receives only state and onIntent. No ViewModel reference. Can be previewed independently.

// NoteListScreen.kt — stateful
@Composable
fun NoteListScreen(
    onNavigateToDetail: (String) -> Unit,
    viewModel: NoteListViewModel = hiltViewModel() // or koinViewModel()
) {
    val state by viewModel.state.collectAsStateWithLifecycle()

    ObserveAsEvents(viewModel.sideEffects) { effect ->
        when (effect) {
            is NoteListSideEffect.NavigateToDetail -> onNavigateToDetail(effect.noteId)
            is NoteListSideEffect.ShowSnackbar -> { /* show snackbar */ }
        }
    }

    NoteListContent(
        state = state,
        onIntent = viewModel::onIntent
    )
}

// NoteListContent.kt — stateless
@Composable
fun NoteListContent(
    state: NoteListState,
    onIntent: (NoteListIntent) -> Unit
) { ... }

@Preview
@Composable
private fun NoteListContentPreview() {
    AppTheme {
        NoteListContent(state = NoteListState(), onIntent = {})
    }
}

Component Decomposition Rules

• SRP: one logical role per composable file
• Reusable components → :core module, grouped by type (buttons/, inputs/, cards/)
• Feature components → always in feature/ui/<screen>/components/ subpackage — no exceptions, regardless of count

Process Death

Use SavedStateHandle only for forms with user input:

@HiltViewModel
class NoteEditorViewModel @Inject constructor(
    private val savedStateHandle: SavedStateHandle,
    private val noteRepository: NoteRepository
) : ViewModel() {

    private val _state = MutableStateFlow(
        NoteEditorState(
            title = savedStateHandle["title"] ?: "",
            body = savedStateHandle["body"] ?: ""
        )
    )

    fun onIntent(intent: NoteEditorIntent) {
        when (intent) {
            is NoteEditorIntent.OnTitleChange -> {
                savedStateHandle["title"] = intent.title
                _state.update { it.copy(title = intent.title) }
            }
        }
    }
}

Only save what truly matters after process death — not the entire state.

Naming Conventions

Checklist: Adding a New Screen

• Detect DI framework (Hilt/Koin) and naming conventions (Intent/Action, SideEffect/Event) from project
• Choose State type: data class / sealed / hybrid based on UI
• Define State, Intent/Action, SideEffect/Event
• Implement ViewModel
• Create <Screen>Screen.kt (stateful — holds ViewModel, observes side effects)
• Create <Screen>Content.kt (stateless — pure state + onIntent, previewable)
• Decompose components by SRP, group by screen → section
• Map domain errors to UiText
• Add SavedStateHandle for form fields that must survive process death