mobile-modern-clean-architecture

name: mobile-modern-clean-architecture description: Modern clean architecture workflow for Android (Kotlin, Compose/XML, coroutines) and Flutter (Dart, widget/state architecture). Use when designing new features, refactoring legacy modules, auditing code quality, or upgrading architecture and async patterns with low-risk, incremental changes.

Mobile Modern Clean Architecture

Overview

Audit and improve Android/Flutter projects using modern architecture boundaries, coroutine/async safety, and compact maintainable code patterns. Default to stability-first behavior and skip risky modernization when evidence is insufficient.

Safety Mode (Default)

• Default mode is SAFE.
• In SAFE mode, do only low-risk, incremental changes with clear rollback.
• If stability confidence is below threshold, output NO-CHANGE and provide a safer next step instead of patching.
• Use safe-refactor-guard rules as mandatory constraints unless user explicitly requests broader refactor.

Workflow

1. Snapshot current state

• Run scripts/mobile_modern_snapshot.sh <repo_root>.
• Identify platform stacks, dependency/toolchain markers, and large-risk files.

2. Apply architecture lane

• Android lane: UI -> state holder (ViewModel) -> use case/domain -> repository -> data source.
• Flutter lane: presentation -> application/state -> domain -> data/infrastructure.
• Keep boundaries explicit; avoid mixing UI, business rules, and transport models.

3. Enforce modern async rules

• Kotlin coroutines: structured concurrency, dispatcher injection, cancellation-safe flows, immutable state exposure.
• Flutter async: isolate heavy work from UI thread, explicit error/loading handling, repository boundaries for IO.

4. Run stability gate before patching

• Required confidence checks:
  • behavior impact is understood,
  • verification command exists,
  • rollback path is obvious,
  • touched files are minimal and local.
• If any check fails, do not patch; return NO-CHANGE.

5. Plan incremental modernization

• Prefer thin slices over big rewrites.
• Tackle highest-risk hotspots first (very large files, unstable async paths, boundary violations).
• Keep each patch reviewable and reversible.

6. Verify and report

• Map each proposed change to verification (unit tests, state/flow checks, UI smoke checks).
• Return prioritized roadmap with effort and risk.

Android Rules

• Use immutable UI state models (StateFlow/single source of truth).
• Keep ViewModels orchestration-focused, not data-transport heavy.
• Keep DTO/network models out of UI/domain APIs.
• Avoid GlobalScope; prefer lifecycle/owner scopes.

Flutter Rules

• Keep widgets focused on presentation; business logic in controllers/blocs/notifiers/use-cases.
• Prefer feature-first module grouping for scale.
• Keep async side effects behind repository/services.
• Split oversized widget files into cohesive components.

Output Format

Use this structure:

# Modernization Report

## Safety Decision
- GO-SAFE | NO-CHANGE
- Confidence:
- Reason:

## Current State
- Android findings:
- Flutter findings:

## Top Risks
1. ...

## Priority Plan
1. [Now] ...
2. [Next] ...
3. [Later] ...

## Minimal Patch Scope
- Files:
- Boundary preserved:

## Verification
- Commands:
- Expected signals:

Guardrails

• No architecture rewrite unless requested.
• No module/file moves or renames in safe mode.
• No dependency upgrades in safe mode unless user explicitly asks and compatibility evidence is shown.
• No public API contract changes in safe mode.
• No unverified async refactors.
• Keep changes compact and evidence-backed.
• Max patch scope in safe mode: one feature/module at a time.

Resources

• scripts/mobile_modern_snapshot.sh
• references/android-modern-checklist.md
• references/flutter-modern-checklist.md
• references/stability-gate.md