android-clean-architecture

Android Clean Architecture Excellence 🏗️

Standardized architectural patterns for scalable, testable, and maintainable Android applications.

⚡ When to Use

• App Structure: Planning or refactoring the module/package layout.
• Data Fetching: Implementing Retrofit or Room repositories.
• Business Logic: Writing Use Cases or Interactors.
• UI Architecture: Choosing between MVI, MVVM, or custom patterns.
• State Management: Consuming data from Flow/StateFlow in ViewModels.

🏗️ The Three Pillars

1. Presentation Layer (UI & ViewModels)

• Pattern: Always use Jetpack ViewModel.
• State: Use MutableStateFlow in ViewModel. In Compose UI, ALWAYS collect using collectAsStateWithLifecycle() (requires androidx.lifecycle:lifecycle-runtime-compose). NEVER use collectAsState() as it wastes resources in the background.
• MVI/MVVM: Prefer State + Events + Effects for complex screens.
• Anti-Pattern (No Stubs): NEVER generate stubbed empty callbacks (e.g., onClicked = { /* Future implementation */ }) when scaffolding. If tasked to build a feature, ALWAYS implement the full event flow from UI to ViewModel to Repository.
• Navigation: Use Compose Navigation with Safe Args (Type-safe routing via Kotlinx Serialization) instead of manual screen swapping.

2. Domain Layer (The Core)

• Rule: NO Android dependencies (except maybe @Inject). Pure Kotlin.

• Use Cases: Each Use Case should have a single responsibility.

  class GetUserUseCase @Inject constructor(private val repository: UserRepository) {
      operator fun invoke(id: String): Flow<User> = repository.getUser(id)
  }
  

• Models: Pure Kotlin data classes (Domain-specific).

• CRITICAL ANTI-HALLUCINATION GUARD: NEVER assume or guess the properties of a data class (e.g., guessing a TodoItem has a dueDate). You MUST explicitly read the data classes in domain/model/ before writing ViewModel or Repository mapping logic to prevent Unresolved reference or constructor errors.