Em dashes are a common AI-writing tell; swap them (and en dashes) for plain
hyphens across the README and all KDoc/comment prose so the repo reads as
hand-authored. Byte-level replace of U+2014/U+2013 -> '-'; arrows and the
ellipsis are left untouched.
The two functional em dashes are intentionally kept: the `DASH = "—"`
blank-field UI placeholder in CharacterDetailUi and the preview sample that
mirrors it -- those are deliberate UX, not prose.
Make the repo read as a hand-authored reference project by dropping
references to the authoring tooling — the internal convention "skills", the
Linear backlog, and the REDI issue ids — from the README and source comments.
- README: remove the "Convention skills index" section and its TOC entry,
strip every `See **android-...**` / koin-constructor-dsl citation, drop the
Linear backlog link, and reword the REDI-99 Room reference to "an optional
stretch".
- Source comments: neutralize the four skill citations in HttpClientExt,
CharactersPresentationModule, CharacterListRobot, ErrorDemoViewModel.
- Also correct the testing section that the MockK migration left stale: it
described "Fakes, not mocks" / FakeCharacterRepository (now deleted) — now
describes MockK, and adds MockK to the stack lists.
Verified: git grep finds no AI/Claude/Anthropic/Linear/skill references in any
tracked file; assembleDebug + assembleDebugAndroidTest green.
Replace the hand-written CharacterRepository fakes in the ViewModel and
UseCase unit tests with MockK mocks (coEvery / coVerify). This is a
deliberate showcase of MockK and intentionally diverges from the repo's
"prefer fakes over mocks" guidance.
- Add io.mockk:mockk 1.14.3 to the version catalog and the unit-test bundle;
add it explicitly to DomainModuleConventionPlugin (domain does not consume
the bundle).
- CharacterListViewModelTest: strict mockk, per-page coEvery stubs; the
paging/in-flight guards are expressed via coVerify(exactly = ...) and
coVerifyOrder instead of fake call counters.
- CharacterDetailViewModelTest: relaxed mockk so "missing id" needs no
stubbing; explicit coEvery elsewhere.
- GetCharactersPageUseCaseTest: mockk + coVerify replaces the inline fake.
- Move character()/characterDetails() fixtures to CharacterFixtures.kt and
delete FakeCharacterRepository.kt.
- NetworkCharacterRepositoryTest stays on Ktor MockEngine (MockK is for
Kotlin collaborator interfaces, not the HTTP transport).
Document module structure + dependency rules, the full data->UI flow (DTO ->
mapper -> domain -> UseCase -> VM -> UiModel), MVI vs MVVM, one-ViewModel-two-
renderers (Compose vs Views + interop + the Material3-XML-theme gotcha),
Result/DataError/UiText with the error-demo walkthrough, navigation, Koin
constructor DSL, the testing approach (incl. the JUnit5-on-AGP9 and Espresso
notes), build/run via the android CLI, and the optional Room stretch. Each
section cites its convention skill.
NetworkCharacterRepositoryTest swaps a Ktor MockEngine into HttpClientFactory and
covers success mapping (incl. request URL/page-param construction), 404 ->
NOT_FOUND, 500 -> SERVER_ERROR, and malformed body -> SERIALIZATION. That last
case exposed a real bug: Ktor wraps the kotlinx SerializationException in its own
ContentConvertException, so safeCall mapped it to UNKNOWN; safeCall now scans the
cause chain and maps it to SERIALIZATION. Adds an instrumented Compose UI test
(CharacterListScreen) using the chaining CharacterListRobot: rendered items,
empty/error states, and tap -> Action.
Test CharacterListViewModel and CharacterDetailViewModel entirely through their
MVI surface with a FakeCharacterRepository (a fake, not a mock) and a directly
constructed SavedStateHandle, on StandardTestDispatcher. Coverage: happy path,
error -> UiText + snackbar Event, pagination end-reached, the in-flight and
duplicate next-page guards, process-death restore, and both branches of OnRetry.
Also a domain test for GetCharactersPageUseCase (delegation + error
propagation).
Add an architecture.android.unit.test convention plugin that runs local unit
tests on the JUnit5 platform via useJUnitPlatform() (AndroidUnitTest extends
Gradle's Test) + the unit-test bundle. Deliberately NOT using the
de.mannodermaus plugin (targets AGP 8.x; we're on AGP 9). Add
junit-platform-launcher (Gradle 9 dropped the bundled launcher); set the
instrumentation runner; add a compose-ui-test bundle pinning espresso/runner to
current versions (transitive espresso 3.5.0 calls the removed
InputManager.getInstance() on API 34+). CI now runs ./gradlew test and compiles
the instrumented tests. Drop unused testing catalog entries.
A runnable MVI screen (reached from the list overflow menu) that forces a real
DataError.Network case and routes it through the same pipeline a genuine call
uses: Result.Error -> onFailure -> DataError.toUiText() -> design-system
ErrorState. Three distinct cases (NO_INTERNET, NOT_FOUND, SERVER_ERROR) each
render their mapped message; Retry re-issues the last attempt via an Action; a
successful load clears the error. Wired as intra-feature navigation
(ErrorDemoRoute) and registered in Koin (incl. the UseCase factoryOf).
Add a domain UseCase (operator invoke) in :feature:characters:domain delegating
to CharacterRepository, and have CharacterListViewModel depend on it instead of
the repository directly. The UseCase is a deliberate thin pass-through that
documents the 'when to add a UseCase' convention (real logic / multi-source
composition vs. a single forwarded call).
Add a Presentation patterns (MVI vs MVVM) section with a comparison table and the
'one ViewModel, two renderers' explanation, and update the status/stack (Timber, not
Kermit; Breadth & Contrast complete).
:app now owns the cross-toolkit interop. MainActivity becomes a FragmentActivity and
hosts CharacterListFragment inside the Compose NavHost via AndroidFragment at a new
@Serializable CharactersViewsRoute (defined in :app, since :app owns interop — the Views
module stays nav-agnostic). The overflow menu's 'Open as Views' / 'About' entries and the
Views item-click -> detail navigation are all injected as callbacks, keeping the renderers
decoupled. Assemble aboutPresentationModule in Koin; add androidx.fragment:fragment-compose.
The Material3 Activity theme styles both toolkits.
Add :feature:characters:presentation-views — a classic Fragment + ViewBinding +
RecyclerView/DiffUtil renderer driving the SAME CharacterListViewModel as the Compose
screen (obtained via Koin's by viewModel()), proving the presentation logic is truly
UI-agnostic. State is observed with viewLifecycleOwner.repeatOnLifecycle(STARTED),
one-time Events are collected, UiText is resolved via Context, and the binding is nulled
in onDestroyView. Coil loads avatars into ImageView with a circle-crop transform; the
module has no Compose dependency.
Paging scroll listener guards the empty-list case (lastVisible >= 0), uses a safe
layoutManager cast, and is removed in onDestroyView.
Add a deliberately small MVVM About screen: AboutViewModel exposes a StateFlow plus
plain public methods (onToggleMvvmNote) with NO Action sealed type and NO Event channel
— the explicit contrast to the app's MVI screens. AboutScreen collects state and calls
the VM method directly; links open via LocalUriHandler. Static showcase copy lives in
the VM as state to demonstrate the StateFlow-as-content shape. aboutGraph + @Serializable
AboutRoute + aboutPresentationModule wire it in. A code comment and the README explain
why this is MVVM and when each pattern fits.
Add a CharacterDetail MVI stack (State/Action/Event/ViewModel + CharacterDetailUi)
to the UI-agnostic :feature:characters:presentation. The detail ViewModel reads the
typed characterId from SavedStateHandle (populated by the type-safe CharacterDetailRoute),
so the module keeps zero navigation/Compose deps.
Add CharacterDetailScreen (Root/Screen, image header, attribute rows, loading/error)
and CharacterDetailRoute to :presentation-compose; refactor charactersGraph to drive
list->detail via NavController and expose About / Views entries as callbacks. Extract
shared CharacterStatus label/colour helpers; add an overflow menu to the list app bar.
Add material-icons-core to the compose bundle for the app-bar icons.
- Race: isLoadingNextPage was set inside the launched coroutine, so a rapid second
OnLoadNextPage passed the guard before the flag flipped -> the same page loaded twice and
items were appended twice. Set the loading flag synchronously before launching.
- Restore: when a middle page failed after earlier pages loaded, the error was swallowed
(error=null, no event). Now any restore failure emits a ShowSnackbar; partial restores show
the loaded list + snackbar, full failures show the error state.
Found by the milestone review.
- charactersPresentationModule: viewModelOf(::CharacterListViewModel) (in the UI-agnostic module).
- @Serializable CharacterListRoute + NavGraphBuilder.charactersGraph { composable<CharacterListRoute> }
in presentation-compose (serialization plugin added for type-safe routes).
- :app registers coreDataModule + charactersDataModule + charactersPresentationModule in startKoin,
and hosts a NavHost(startDestination = CharacterListRoute) calling charactersGraph.
- core:data manifest declares INTERNET (merges into :app) for live API calls.
- CharacterListRoot: koinViewModel(), ObserveAsEvents, forwards nav + shows snackbar via Context asString.
- CharacterListScreen: pure state+onAction; AppScaffold + LazyColumn (key=id), design-system
NetworkImage (contentDescription)/AppCard, loading/error/empty states, snapshot-based
scroll-to-end -> OnLoadNextPage (ViewModel guards duplicates).
- Loaded + error previews wrapped in AppTheme.
- feature:characters:presentation now exposes kotlinx-immutable as api (ImmutableList is in the state API).
- CharacterListState (characters, isLoading, isLoadingNextPage, currentPage, endReached, error: UiText?),
CharacterListAction (OnCharacterClick/OnRetry/OnLoadNextPage), CharacterListEvent (NavigateToDetail/ShowSnackbar).
- CharacterListViewModel: state via .update, one-time events via Channel, DataError -> UiText on failure,
pagination persisted in SavedStateHandle (rebuilds list up to the saved page after process death).
- CharacterUi + Character.toCharacterUi().
- NO Compose/Views deps: verified no androidx.compose on the compile classpath. Stability via
ImmutableList instead of @Stable (which would require compose-runtime) — the only compose-named
transitive is kotlinx-immutable's annotations-only stub, not the Compose framework.
- @Serializable CharacterDto/CharactersResponseDto/PageInfoDto in dto/.
- mappers/CharacterMapper.kt: internal, pure toDomain()/toCharacter()/toCharacterDetails();
nextPage parsed from info.next URL. No mapping inside DTO/data-source classes.
- KtorCharacterDataSource via the typed HttpClient.get helpers (errors -> DataError.Network).
- NetworkCharacterRepository (not *Impl) maps DTO -> domain; DataError.Network widens to DataError.
- charactersDataModule: singleOf(::KtorCharacterDataSource) + singleOf(::NetworkCharacterRepository) { bind<CharacterRepository>() }.
- core:data: expose ktor-client-core as api (public inline helpers are inlined into consumers) and
move Timber logging into a @PublishedApi internal fn so Timber doesn't leak across modules.
Android-only project, so Timber (the de-facto Android logging lib) fits better than the
KMP-oriented Kermit.
- Catalog: kermit -> timber (com.jakewharton.timber:timber 5.0.1).
- core:data: Ktor Logging bridged to Timber; safeCall logs via Timber.
- app: plant Timber.DebugTree() in debug only (buildConfig enabled for BuildConfig.DEBUG).
Deserialization happens in responseToResult via response.body<T>() on the 2xx branch.
That call was outside safeCall's try/catch, so a malformed 2xx body threw an uncaught
SerializationException (crash) instead of mapping to DataError.Network.SERIALIZATION.
Move responseToResult(execute()) inside the try so both transport and parse errors are typed.
Found by the milestone review.
- ArchitectureApp.Application: startKoin { androidLogger; androidContext; modules(coreDataModule) }.
Modules are assembled only here; feature modules will append to the list.
- MainActivity hosts a themed empty screen via AppTheme + AppScaffold (design-system).
- Activity XML theme upgraded to Theme.Material3.DayNight.NoActionBar (Compose themes via AppTheme;
the Material3 XML theme lets the later Views renderer inherit Material3 styling).
- :app depends on :core:data + :core:design-system; applies the koin convention.
- UiText sealed interface (DynamicString / StringResource) — Compose-free type so the
UI-agnostic presentation module can hold UiText? in state without depending on Compose.
- Two resolvers: @Composable UiText.asString() (Compose renderer) and
UiText.asString(context) (Views renderer).
- ObserveAsEvents: lifecycle-aware one-time event collection on Main.immediate.
- DataError.toUiText() covering all displayed cases with else -> unknown; error strings here.
Kotlin-only reference repo — move the app's main/test/androidTest source roots
from src/main/java to src/main/kotlin (the core/feature modules already use kotlin).
Verified: :app:compileDebugKotlin produces MainActivity from src/main/kotlin.
Foundation milestone (REDI-78, REDI-79):
- Multi-module skeleton: :app, :core:{domain,data,presentation,design-system},
:feature:characters:{domain,data,presentation,presentation-compose,presentation-views},
:feature:about:presentation, plus the :build-logic composite build.
- gradle/libs.versions.toml as the single source of truth ([versions]/[libraries]/
[bundles]/[plugins]); no inline versions in any build file.
- Convention plugins: architecture.android.{application,library,feature,feature.views},
domain.module, compose, koin, ktor, kotlinx.serialization.
- Pure-Kotlin domain modules; presentation-compose uses android.feature;
presentation-views uses android.feature.views (ViewBinding on, Compose off);
the UI-agnostic :presentation has neither Compose nor Views deps.
- Toolchain: AGP 9.0.1, Kotlin 2.3.20, Gradle 9.1.0, compileSdk 36, minSdk 24, Java 17.
- Minimal MainActivity placeholder; CI (assembleDebug) via GitHub Actions.
Verified: ./gradlew projects lists the full tree and ./gradlew assemble is green.
