How ramonsantospinto/cards_circulos works
Purpose and runtime
Cards & Circles is a single-module Android study app demonstrating feature-oriented Clean Architecture, unidirectional data flow, and lifecycle-aware UI state. It runs as a native Kotlin Android application using Jetpack Compose, ViewModel, StateFlow, coroutines, and Compose Navigation. No backend, persistence layer, or external service is indicated.
Application entry and composition root
app/src/main/java/com/example/cards/MainActivity.kt is the Android entry point and top-level composition root. It initializes the Compose UI, owns the application-level Scaffold/navigation orchestration, and connects route selection to feature screens. Android packaging, launcher configuration, theme resources, and platform declarations begin at app/src/main/AndroidManifest.xml.
Navigation boundary
Navigation is centralized rather than embedded in feature implementations. app/src/main/java/com/example/cards/core/navigation/Screen.kt defines the shared screen/route model used by MainActivity and the destination graph. This core boundary lets feature presentation code expose UI destinations while keeping route identity and transitions consistent across the app.
Home feature: state-driven card grid
The Home feature represents the primary card-grid interaction flow:
• app/src/main/java/com/example/cards/features/home/presentation/HomeScreen.kt renders the declarative home UI and forwards user events.
• app/src/main/java/com/example/cards/features/home/presentation/HomeViewModel.kt receives those events, owns lifecycle-aware presentation state, and applies state transitions.
• app/src/main/java/com/example/cards/features/home/presentation/HomeUiState.kt is the explicit UI-state contract consumed by Compose.
The intended UDF path is UI event → ViewModel → StateFlow-backed HomeUiState update → Compose recomposition. UI rendering remains state-derived rather than holding business interaction state locally.
Circles feature: isolated interactive presentation
The Circles feature is a separate presentation slice for color/circle interaction:
• app/src/main/java/com/example/cards/features/circles/presentation/CirclesScreen.kt
• app/src/main/java/com/example/cards/features/circles/presentation/CirclesViewModel.kt
Its screen observes ViewModel-managed reactive state and emits user actions upward; its ViewModel is the control boundary for circle interaction logic and asynchronous/stateful behavior. Feature isolation allows its presentation model to evolve independently from Home, connected only through shared navigation and the app shell.
State, lifecycle, and rendering flow
ViewModels are the durable state holders across Compose recompositions and Activity lifecycle events. StateFlow and coroutines provide the reactive/asynchronous mechanism: feature ViewModels publish state, screens collect it, and Compose redraws from the latest value. MainActivity controls destination-level composition; each feature controls its own presentation-state transitions.
Build and platform boundaries
Gradle defines a conventional Android application module at app/build.gradle.kts, with repository-wide build setup in build.gradle.kts and settings.gradle.kts. Android resources and themes remain platform-facing boundaries under app/src/main/res, while code shrinker retention policy is isolated at app/src/main/keepRules/rules.keep.
Main entry points: MainActivity.kt Main Activity · HomeScreen.kt Home Screen · CirclesScreen.kt Circles Screen · Screen.kt Screen Routes
Components 12
Android Platform
- Gradle Build · Defines the Android application module and repository build setup.
app/build.gradle.kts - Android Manifest · Declares Android packaging and launcher integration.
app/src/main/AndroidManifest.xml - Resources & Themes · Platform-facing Android resources and themes.
app/src/main/res - Android Runtime
App Shell
- Main Activity · Hosts Compose, scaffold orchestration, and destination composition.
app/src/main/java/com/example/cards/MainActivity.kt - Screen Routes · Shared route identity for app destinations.
app/src/main/java/com/example/cards/core/navigation/Screen.kt - StateFlow & Coroutines · Delivers lifecycle-aware asynchronous state updates.
Home Feature
- Home Screen · Renders the card grid from state and forwards user events.
app/src/main/java/com/example/cards/features/home/presentation/HomeScreen.kt - Home ViewModel · Handles home events and publishes presentation state.
app/src/main/java/com/example/cards/features/home/presentation/HomeViewModel.kt - Home UI State · Explicit state consumed by the Home composable.
app/src/main/java/com/example/cards/features/home/presentation/HomeUiState.kt
Circles Feature
- Circles Screen · Renders circle interaction state and emits actions.
app/src/main/java/com/example/cards/features/circles/presentation/CirclesScreen.kt - Circles ViewModel · Controls circle interaction and reactive state.
app/src/main/java/com/example/cards/features/circles/presentation/CirclesViewModel.kt
Connections 17
- Gradle Build → Android Runtime: builds
- Android Manifest → Android Runtime: declares app
- Resources & Themes → Main Activity: themes UI
- Android Runtime → Main Activity: launches
- Main Activity → Screen Routes: uses routes
- Main Activity → Home Screen: composes destination
- Main Activity → Circles Screen: composes destination
- Screen Routes → Home Screen: selects
- Screen Routes → Circles Screen: selects
- Home Screen → Home ViewModel: user events
- Home ViewModel → Home UI State: updates
- Home ViewModel → StateFlow & Coroutines: publishes via
- StateFlow & Coroutines → Home Screen: state collection
- Home UI State → Home Screen: renders
- Circles Screen → Circles ViewModel: user actions
- Circles ViewModel → StateFlow & Coroutines: publishes via
- StateFlow & Coroutines → Circles Screen: state collection