Android ViewModel Migration Lab

AI-guided OSS lab for safely migrating legacy Android AAC/ViewModel shared-state samples to Kotlin, Compose, ViewModel, and StateFlow.

This repository turns a 2017 Android AAC/ViewModel practice project into a documented, tested, AI-guided OSS migration lab where humans and AI coding agents can modernize legacy shared-state code through small, reviewable, guideline-driven pull requests.

Motivation

Many Android apps still depend on older architecture patterns such as early Android Architecture Components, shared state between screens, and mixed legacy APIs.

Small migration changes in those apps are risky, especially when multiple screens must stay synchronized. This repository turns a 2017 Android AAC/ViewModel practice sample into a documented, tested migration lab that can be followed safely.

The goal is to provide a clear path where humans and AI coding agents can modernize legacy code in small, reviewable steps.

This project started as Android-AAC-ViewModel-Practice, and the identity is now aligned to the migration-lab purpose.

What this project is

• a legacy Android architecture migration lab
• a small runnable Kotlin + Compose sample
• a ViewModel + StateFlow shared-state example
• a documentation-first OSS project
• a reference workflow for AI-assisted migration pull requests

What this project is not

• a production app
• a full Android architecture framework
• a business-domain sample
• a Reserve.M project
• a Hilt / Room / Firebase / Navigation showcase

Core scenario

Article List
↓
Article Detail
↓
Edit Article
↓
Save
↓
Back to List
↓
Updated Article is reflected

Current modern solution

The modern version provides:

• Kotlin + Compose UI
• ViewModel
• StateFlow
• Reducer-style state updates

What this project will teach

• How to keep shared state synchronized across multiple screens
• How to migrate legacy Android Architecture Components patterns to modern Kotlin/Compose architecture
• How to structure reducer and ViewModel tests

Current status

Completed in this phase:

• Project direction clarified as Android ViewModel Migration Lab
• Legacy README preserved as historical documentation
• OSS metadata files added (LICENSE, CONTRIBUTING.md, SECURITY.md, CODE_OF_CONDUCT.md, CHANGELOG.md)
• GitHub issue/PR templates added
• Modern Kotlin/Compose baseline created
• Article domain model, reducer, ViewModel, and tests added
• Compose list/detail screens implemented
• Android CI workflow added
• Release workflow added for v0.1.0-oss-alpha.1 tag push
• v0.1.0-oss-alpha.1 first OSS alpha release is published
  • GitHub Release: v0.1.0-oss-alpha.1
  • Sample debug APK: app-debug.apk

AI-guided migration workflow

This repository is designed so both humans and AI coding agents can follow the same process.

1. Read docs/oss-remake-task-plan.md
2. Pick one migration task
3. Create a small pull request
4. Add/adjust tests for behavior changes
5. Update documentation together with behavior changes
6. Run ./gradlew test
7. Run ./gradlew assembleDebug
8. Merge only when scope is clear and CI is green

The preferred approach is small, incremental migration.

Requirements

• Android Studio
• JDK 17
• Android SDK
• Git

If you use Android Studio, the bundled JBR is usually enough.

Quick start

1. Clone the repository

   git clone https://github.com/leesunghyun/android-viewmodel-migration-lab.git
   cd android-viewmodel-migration-lab

2. Run tests

macOS / Linux:

./gradlew test
./gradlew assembleDebug

Windows:

gradlew.bat test
gradlew.bat assembleDebug

3. Open in Android Studio and run the app module.

Demo

The first alpha flow is: List → Detail/Edit → Save → List with shared state update.

Manual smoke check:

1. Open the app and confirm the article list screen appears.
2. Tap an article, open detail/edit, change title/body.
3. Tap Save and return to list.
4. Confirm the edited item is immediately updated in the list.

Release status

• First OSS alpha release: v0.1.0-oss-alpha.1
• v0.2 alpha preparation: v0.2.0-oss-alpha.1 notes/guide are prepared
  • Release Notes: v0.2.0-oss-alpha.1
  • Release Guide: v0.2.0-oss-alpha.1
• APK is provided as a sample debug artifact for manual smoke testing (not production release).

Codex for OSS readiness

• Readiness Spec
• Codex Submission Package (prepare-ready draft)
• Codex Strategy
• Metrics check script

For full release details and run verification commands, see:

• Release Notes
• Release Guide

Project structure

app/        Modern Kotlin + Compose sample app (built in this alpha)
legacy-app/ Original 2017 Android AAC sample (archive only, reference)
docs/       Migration documentation and release notes

Only app/ is built in the first alpha. legacy-app/ is preserved for historical reference only.

Migration docs

• 2017 Legacy Architecture
• Modern Architecture
• Shared State Problem
• LiveData to StateFlow
• Compose UI Guide
• Release Notes: v0.1.0-oss-alpha.1
• Release Guide: v0.1.0-oss-alpha.1
• Release Notes: v0.2.0-oss-alpha.1
• Release Guide: v0.2.0-oss-alpha.1
• Roadmap: v0.2.0
• Migration Task Plan (source of truth)
• Codex for OSS

Archive

• Historical planning references

Roadmap

• Preserve legacy baseline as archive (legacy-app/)
• Preserve legacy 2017 snapshot (legacy/2017-original, v0.0.0-legacy-2017)
• Move original app code into legacy-app/
• Add modern app baseline
• Add Article domain/model and reducer
• Add ArticleListReducer tests
• Add ViewModel + StateFlow implementation
• Add Compose screens
• Add unit tests
• Add Android CI workflow
• Publish migration document bundle
• Add release notes and changelog section for v0.1.0-oss-alpha.1

Next milestones (planned, v0.2)

• Replace demo placeholder with real screen recording (docs/images/demo.gif)
• Improve Article detail validation UX
• Add before/after diagram for v0.2 release docs
• Improve connected test coverage for back-without-save and invalid selection scenarios

Recently completed after v0.1.0

• Add collectAsStateWithLifecycle in Compose state collection
• Add Compose UI smoke tests (ArticleUiSmokeTest)

Repository settings

The GitHub repository identity has been updated to match the migration-lab purpose:

• Repository name: android-viewmodel-migration-lab
• Description: AI-guided OSS lab for safely migrating legacy Android AAC/ViewModel shared-state samples to Kotlin, Compose, ViewModel, and StateFlow.
• Topics: android, kotlin, jetpack-compose, viewmodel, stateflow, legacy-code, migration-guide, ai-assisted-development

Contributing

Please read CONTRIBUTING.md and add small, focused changes.

License

Apache-2.0. See LICENSE.