[Architecture FAQ] StateMachine ➔ Command ➔ ViewModel ➔ Event 구조의 설계 배경과 이점

[kez-lab]

[Architecture FAQ] StateMachine ➔ Command ➔ ViewModel ➔ Event 구조의 설계 배경과 이점

Afsm을 처음 도입하거나 검토할 때 가장 자주 제기되는 질문 중 하나는 다음과 같습니다:

"StateMachine에서 Command를 방출하고, ViewModel이 이를 받아 Repository를 호출한 뒤, 다시 Event로 머신에 전달하는 순환 구조(Loop)가 다소 복잡하거나 번거롭게 느껴질 수 있지 않나요? 상태 전이 체계를 파악하는 데 어떤 실익이 있나요?"

이 문서는 Afsm이 상태 머신(순수 비즈니스 규칙)과 ViewModel(비동기 I/O 실행)을 명확히 분리한 기술적 배경과 설계 이점을 설명합니다.

---

1. 0.1ms 단위의 모킹 없는 순수 JVM 단위 테스트

상태 머신 내부에서 Repository를 직접 호출하거나 코루틴 비동기 작업을 직접 실행할 경우, 상태 머신 테스트에 MockRepository, TestDispatcher, 가상 시간 조작 등 무거운 테스트 하네스가 필수적으로 결합됩니다.

Afsm은 상태 머신을 순수 함수(Pure Reducer) 형태로 격리합니다:

현재 State + Event -> 다음 State + Commands + Decision

• 머신은 외부 환경에 대한 부수 효과(Side-effect) 없이 오직 **"어떤 상태로 전이하고 어떤 작업(Command)을 실행해야 하는가"**만을 순수 데이터로 결정합니다.
• 이에 따라 네트워크나 Repository 모킹 없이, 서브 밀리초(0.1ms) 단위의 순수 JVM 단위 테스트로 모든 상태 전이와 조건 분기(Handled, Ignored, Invalid)를 100% 검증할 수 있습니다.

---

2. 상태 전이 규칙의 단일 공급원(SSOT)과 얇은 ViewModel 어댑터

전통적인 Android 아키텍처에서는 화면의 진행 상태와 비즈니스 규칙이 viewModelScope.launch, try-catch, 콜백 함수, 그리고 여러 boolean 플래그(isSaving, isLoading 등) 사이에 파편화되기 쉽습니다.

Afsm은 비즈니스 흐름과 관련된 모든 규칙을 *StateMachine.kt 및 KSP가 자동 생성하는 Mermaid 상태 다이어그램 한곳으로 집중시킵니다:

[Editing] --SaveClicked [유효한 입력]--> [Saving] (Command: SaveDraft)
                                            |
                                            +--DraftSaveCompleted--> [Saved]
                                            +--DraftSaveFailed-----> [Editing]

• 상태 흐름 파악: 전체 라이프사이클과 조건 분기는 상태 머신 정의와 시각화 다이어그램만 확인하면 명확하게 파악됩니다.
• ViewModel의 단순화: ViewModel은 비즈니스 분기(if/else)를 직접 다루지 않고, 머신이 지시한 Command를 실행하여 결과 Event를 회신하는 단순 어댑터(Thin Bridge) 역할을 담당합니다.

// ViewModel은 비즈니스 분기 없이 Command 실행 및 결과 회신만 담당
commandHandler = { command, send ->
    when (command) {
        is DraftCommand.SaveDraft -> repository.save(command.title).fold(
            onSuccess = { send(DraftEvent.DraftSaveCompleted) },
            onFailure = { send(DraftEvent.DraftSaveFailed(it.message.orEmpty())) },
        )
    }
}

---

3. 실무 적용 기준: 화면 복잡도에 따른 아키텍처 선택

Afsm은 모든 화면에 상태 머신을 일괄 적용하는 것을 권장하지 않으며, 화면 복잡도에 따라 유연하게 선택할 수 있도록 설계되었습니다.

화면 유형	권장 아키텍처	이유
단순 조회/표시 화면 (Loading ➔ Content / Error)	일반 ViewModel + StateFlow	단순한 상태 전이에는 일반 StateFlow 패턴이 가장 간결하며, FSM 구조는 불필요한 비용이 될 수 있습니다.
다단계 고분기 화면 (인증, 결제/주문, 복합 입력 폼)	Afsm (State Machine + Command)	중복 클릭 방어, 늦게 도착한 비동기 응답(Stale result) 방어, 재시도, 상태 복원 정책을 안전하게 집중 관리할 수 있습니다.

---

💡 요약

Afsm의 Command-Event 구조는 **"비즈니스 전이 규칙의 두뇌(Pure StateMachine)"**와 **"Android 플랫폼 I/O의 손발(ViewModel)"**을 분리하여, 복잡한 비동기 화면에서도 상태 전이 체계를 투명하게 조망하고 안전하게 검증할 수 있도록 돕는 설계입니다.

관련하여 궁금한 점이나 다른 아키텍처 의견이 있으시다면 편하게 댓글로 남겨주시기 바랍니다.