Capstone Project: A Complete Android App

[Prices list] --(tap item)--> [Item detail: history + cheapest market]
     |
     +--(FAB)--> [Add price form]

PriceEntry
  id            Long (auto)
  itemName      String        "Garri (white, 1 paint bucket)"
  marketName    String        "Bodija"
  amountKobo    Long          money as whole kobo, never Double
  recordedAtMs  Long          epoch millis

com.example.marketmate
 ├─ MarketMateApp.kt             @HiltAndroidApp
 ├─ MainActivity.kt
 ├─ data/                         Room entity, DAO, database, repository
 ├─ domain/                       models, use cases, validation
 ├─ ui/
 │   ├─ theme/
 │   ├─ list/   (ListScreen, ListViewModel)
 │   ├─ detail/ (DetailScreen, DetailViewModel)
 │   ├─ add/    (AddScreen, AddViewModel)
 │   └─ navigation/ (routes, NavHost)
 └─ di/                           Hilt modules

// data/PriceEntry.kt
@Entity(tableName = "price_entries")
data class PriceEntryEntity(
 @PrimaryKey(autoGenerate = true) val id: Long = 0,
 val itemName: String,
 val marketName: String,
 val amountKobo: Long,
 val recordedAtMs: Long
)

// data/PriceDao.kt
@Dao
interface PriceDao {
 @Query("SELECT * FROM price_entries ORDER BY recordedAtMs DESC")
 fun observeAll(): Flow<List<PriceEntryEntity>>
 @Query("SELECT * FROM price_entries WHERE itemName = :item ORDER BY recordedAtMs DESC")
 fun observeForItem(item: String): Flow<List<PriceEntryEntity>>
 @Insert
 suspend fun insert(entry: PriceEntryEntity)
 @Query("DELETE FROM price_entries WHERE id = :id")
 suspend fun delete(id: Long)
}

// data/MarketDatabase.kt
@Database(entities = [PriceEntryEntity::class], version = 1, exportSchema = true)
abstract class MarketDatabase : RoomDatabase() {
 abstract fun priceDao(): PriceDao
}

// domain/PriceEntry.kt
data class PriceEntry(
 val id: Long,
 val itemName: String,
 val marketName: String,
 val amountNaira: Double, // for display only; computed from kobo
 val amountKobo: Long,
 val recordedAt: Instant
)
fun PriceEntryEntity.toModel() = PriceEntry(
 id = id,
 itemName = itemName,
 marketName = marketName,
 amountNaira = amountKobo / 100.0,
 amountKobo = amountKobo,
 recordedAt = Instant.ofEpochMilli(recordedAtMs)
)

// data/PriceRepository.kt
interface PriceRepository {
 fun observeAll(): Flow<List<PriceEntry>>
 fun observeForItem(item: String): Flow<List<PriceEntry>>
 suspend fun add(item: String, market: String, amountKobo: Long, recordedAtMs: Long)
 suspend fun delete(id: Long)
}
class OfflinePriceRepository @Inject constructor(
 private val dao: PriceDao,
 @IoDispatcher private val io: CoroutineDispatcher
) : PriceRepository {
 override fun observeAll() = dao.observeAll()
 .map { list -> list.map { it.toModel() } }
 .flowOn(io)
 override fun observeForItem(item: String) = dao.observeForItem(item)
 .map { list -> list.map { it.toModel() } }
 .flowOn(io)
 override suspend fun add(item: String, market: String, amountKobo: Long, recordedAtMs: Long) =
 withContext(io) {
 dao.insert(PriceEntryEntity(itemName = item, marketName = market,
 amountKobo = amountKobo, recordedAtMs = recordedAtMs))
 }
 override suspend fun delete(id: Long) = withContext(io) { dao.delete(id) }
}

@Module
@InstallIn(SingletonComponent::class)
object DataModule {
 @Provides @Singleton
 fun provideDb(@ApplicationContext context: Context): MarketDatabase =
 Room.databaseBuilder<MarketDatabase>(context, "marketmate.db")
 .setDriver(AndroidSQLiteDriver())
 .build()
 @Provides fun provideDao(db: MarketDatabase): PriceDao = db.priceDao()
 @Provides @IoDispatcher fun provideIo(): CoroutineDispatcher = Dispatchers.IO
}
@Module
@InstallIn(SingletonComponent::class)
abstract class RepositoryModule {
 @Binds @Singleton abstract fun bindRepo(impl: OfflinePriceRepository): PriceRepository
}

// domain/ValidatePrice.kt
sealed interface ValidationResult {
 data class Valid(val item: String, val market: String, val amountKobo: Long) : ValidationResult
 data class Invalid(val itemError: String? = null, val marketError: String? = null, val amountError: String? = null) : ValidationResult
}
class ValidatePriceUseCase @Inject constructor() {
 operator fun invoke(item: String, market: String, amountText: String): ValidationResult {
 val cleanItem = item.trim()
 val cleanMarket = market.trim()
 val naira = amountText.trim().toDoubleOrNull()
 val itemError = if (cleanItem.isEmpty()) "Enter the item" else null
 val marketError = if (cleanMarket.isEmpty()) "Enter the market" else null
 val amountError = when {
 naira == null -> "Enter a number"
 naira <= 0.0 -> "Amount must be more than zero"
 else -> null
 }
 return if (itemError == null && marketError == null && amountError == null) {
 ValidationResult.Valid(cleanItem, cleanMarket, Math.round(naira!! * 100))
 } else {
 ValidationResult.Invalid(itemError, marketError, amountError)
 }
 }
}

// domain/CheapestMarket.kt
data class MarketAverage(val market: String, val averageKobo: Long, val samples: Int)
class FindCheapestMarketUseCase @Inject constructor() {
 operator fun invoke(entries: List<PriceEntry>, now: Instant, days: Long = 30): MarketAverage? {
 val cutoff = now.minus(days, ChronoUnit.DAYS)
 return entries
 .filter { it.recordedAt >= cutoff }
 .groupBy { it.marketName }
 .map { (market, list) ->
 MarketAverage(market, list.sumOf { it.amountKobo } / list.size, list.size)
 }
 .minWithOrNull(compareBy<MarketAverage> { it.averageKobo }.thenBy { it.market })
 }
}

class FindCheapestMarketUseCaseTest {
 private val now = Instant.parse("2026-10-24T10:00:00Z")
 private fun entry(market: String, kobo: Long, daysAgo: Long) = PriceEntry(
 id = 0, itemName = "Garri", marketName = market,
 amountNaira = kobo / 100.0, amountKobo = kobo, recordedAt = now.minus(daysAgo, ChronoUnit.DAYS)
 )
 @Test
 fun picks_lowest_average_in_window() {
 val entries = listOf(
 entry("Bodija", 200_000, 2), entry("Bodija", 220_000, 5),
 entry("Dugbe", 190_000, 3)
 )
 assertEquals("Dugbe", FindCheapestMarketUseCase()(entries, now)?.market)
 }
 @Test
 fun ignores_entries_older_than_30_days() {
 val entries = listOf(entry("Dugbe", 100_000, 45), entry("Bodija", 200_000, 1))
 assertEquals("Bodija", FindCheapestMarketUseCase()(entries, now)?.market)
 }
 @Test
 fun returns_null_when_no_recent_entries() {
 assertNull(FindCheapestMarketUseCase()(listOf(entry("Dugbe", 1, 60)), now))
 }
}
class ValidatePriceUseCaseTest {
 @Test
 fun rejects_zero_and_blank() {
 val result = ValidatePriceUseCase()("  ", "Bodija", "0") as ValidationResult.Invalid
 assertNotNull(result.itemError)
 assertNotNull(result.amountError)
 }
 @Test
 fun converts_naira_to_kobo() {
 val result = ValidatePriceUseCase()("Garri", "Bodija", "2500") as ValidationResult.Valid
 assertEquals(250_000L, result.amountKobo)
 }
}

@Serializable object ListRoute
@Serializable data class DetailRoute(val itemName: String)
@Serializable object AddRoute

data class ListUiState(
 val query: String = "",
 val entries: List<PriceEntry> = emptyList(),
 val loading: Boolean = true
)
@HiltViewModel
class ListViewModel @Inject constructor(
 private val repository: PriceRepository,
 private val savedState: SavedStateHandle
) : ViewModel() {
 private val query = savedState.getStateFlow("query", "")
 val uiState: StateFlow<ListUiState> =
 combine(repository.observeAll(), query) { entries, q ->
 ListUiState(
 query = q,
 entries = entries.filter { it.itemName.contains(q, ignoreCase = true) },
 loading = false
 )
 }.stateIn(viewModelScope, SharingStarted.WhileSubscribed(5_000), ListUiState())
 fun onQueryChange(value: String) { savedState["query"] = value }
 fun delete(id: Long) { viewModelScope.launch { repository.delete(id) } }
}

@OptIn(ExperimentalMaterial3Api::class)
@Composable
fun ListScreen(
 onOpenItem: (String) -> Unit,
 onAdd: () -> Unit,
 viewModel: ListViewModel = hiltViewModel()
) {
 val state by viewModel.uiState.collectAsStateWithLifecycle()
 Scaffold(
 topBar = { TopAppBar(title = { Text("MarketMate") }) },
 floatingActionButton = {
 FloatingActionButton(onClick = onAdd) {
 Icon(Icons.Default.Add, contentDescription = "Add a price")
 }
 }
 ) { padding ->
 Column(Modifier.padding(padding)) {
 OutlinedTextField(
 value = state.query,
 onValueChange = viewModel::onQueryChange,
 label = { Text("Search items") },
 singleLine = true,
 modifier = Modifier.fillMaxWidth().padding(16.dp)
 )
 when {
 state.loading -> Box(Modifier.fillMaxSize(), Alignment.Center) { CircularProgressIndicator() }
 state.entries.isEmpty() -> EmptyState("No prices yet. Tap + to add the first one.")
 else -> LazyColumn(contentPadding = PaddingValues(horizontal = 16.dp, vertical = 8.dp)) {
 items(state.entries, key = { it.id }) { entry ->
 PriceRow(
 entry = entry,
 onClick = { onOpenItem(entry.itemName) },
 onDelete = { viewModel.delete(entry.id) }
 )
 }
 }
 }
 }
 }
}
@Composable
fun PriceRow(entry: PriceEntry, onClick: () -> Unit, onDelete: () -> Unit) {
 val price = formatNaira(entry.amountKobo)
 ListItem(
 headlineContent = { Text(entry.itemName) },
 supportingContent = { Text("${entry.marketName} · ${formatDate(entry.recordedAt)}") },
 trailingContent = {
 Row(verticalAlignment = Alignment.CenterVertically) {
 Text(price, style = MaterialTheme.typography.titleMedium)
 IconButton(onClick = onDelete) {
 Icon(Icons.Default.Delete, contentDescription = "Delete ${entry.itemName} at $price")
 }
 }
 },
 modifier = Modifier.clickable(onClick = onClick, onClickLabel = "Open ${entry.itemName}")
 )
}
fun formatNaira(kobo: Long): String =
 NumberFormat.getCurrencyInstance(Locale("en", "NG")).format(kobo / 100.0)
fun formatDate(instant: Instant): String =
 DateTimeFormatter.ofPattern("d MMM yyyy").withZone(ZoneId.systemDefault()).format(instant)
@Composable
fun EmptyState(message: String) {
 Box(Modifier.fillMaxSize().padding(32.dp), Alignment.Center) {
 Text(message, style = MaterialTheme.typography.bodyLarge, textAlign = TextAlign.Center)
 }
}

data class DetailUiState(
 val itemName: String = "",
 val entries: List<PriceEntry> = emptyList(),
 val cheapest: MarketAverage? = null
)
@HiltViewModel
class DetailViewModel @Inject constructor(
 savedState: SavedStateHandle,
 repository: PriceRepository,
 findCheapest: FindCheapestMarketUseCase
) : ViewModel() {
 private val itemName = savedState.toRoute<DetailRoute>().itemName
 val uiState: StateFlow<DetailUiState> = repository.observeForItem(itemName)
 .map { entries -> DetailUiState(itemName, entries, findCheapest(entries, Instant.now())) }
 .stateIn(viewModelScope, SharingStarted.WhileSubscribed(5_000), DetailUiState(itemName))
}
@OptIn(ExperimentalMaterial3Api::class)
@Composable
fun DetailScreen(onBack: () -> Unit, viewModel: DetailViewModel = hiltViewModel()) {
 val state by viewModel.uiState.collectAsStateWithLifecycle()
 Scaffold(
 topBar = {
 TopAppBar(
 title = { Text(state.itemName) },
 navigationIcon = {
 IconButton(onClick = onBack) {
 Icon(Icons.AutoMirrored.Filled.ArrowBack, contentDescription = "Back")
 }
 }
 )
 }
 ) { padding ->
 LazyColumn(Modifier.padding(padding), contentPadding = PaddingValues(16.dp)) {
 item {
 state.cheapest?.let {
 Card(Modifier.fillMaxWidth()) {
 Column(Modifier.padding(16.dp)) {
 Text("Cheapest in the last 30 days", style = MaterialTheme.typography.labelLarge)
 Text("${it.market}: ${formatNaira(it.averageKobo)} (${it.samples} entries)",
 style = MaterialTheme.typography.titleMedium)
 }
 }
 } ?: Text("Not enough recent prices to compare markets.")
 Spacer(Modifier.height(16.dp))
 Text("History", style = MaterialTheme.typography.titleLarge)
 }
 items(state.entries, key = { it.id }) { entry ->
 ListItem(
 headlineContent = { Text(formatNaira(entry.amountKobo)) },
 supportingContent = { Text("${entry.marketName} · ${formatDate(entry.recordedAt)}") }
 )
 }
 }
 }
}

data class AddUiState(
 val item: String = "",
 val market: String = "",
 val amount: String = "",
 val errors: ValidationResult.Invalid? = null,
 val saved: Boolean = false
)
@HiltViewModel
class AddViewModel @Inject constructor(
 private val repository: PriceRepository,
 private val validate: ValidatePriceUseCase
) : ViewModel() {
 private val _state = MutableStateFlow(AddUiState())
 val state: StateFlow<AddUiState> = _state.asStateFlow()
 fun onItem(v: String) = _state.update { it.copy(item = v, errors = null) }
 fun onMarket(v: String) = _state.update { it.copy(market = v, errors = null) }
 fun onAmount(v: String) = _state.update { it.copy(amount = v, errors = null) }
 fun save() {
 val s = _state.value
 when (val result = validate(s.item, s.market, s.amount)) {
 is ValidationResult.Invalid -> _state.update { it.copy(errors = result) }
 is ValidationResult.Valid -> viewModelScope.launch {
 repository.add(result.item, result.market, result.amountKobo, System.currentTimeMillis())
 _state.update { it.copy(saved = true) }
 }
 }
 }
}

@OptIn(ExperimentalMaterial3Api::class)
@Composable
fun AddScreen(onDone: () -> Unit, viewModel: AddViewModel = hiltViewModel()) {
 val state by viewModel.state.collectAsStateWithLifecycle()
 LaunchedEffect(state.saved) { if (state.saved) onDone() }
 Scaffold(topBar = {
 TopAppBar(
 title = { Text("Add a price") },
 navigationIcon = { IconButton(onClick = onDone) { Icon(Icons.AutoMirrored.Filled.ArrowBack, "Cancel") } }
 )
 }) { padding ->
 Column(
 Modifier.padding(padding).padding(16.dp).verticalScroll(rememberScrollState()),
 verticalArrangement = Arrangement.spacedBy(12.dp)
 ) {
 FormField("Item (for example, Garri, 1 paint bucket)", state.item, viewModel::onItem, state.errors?.itemError)
 FormField("Market", state.market, viewModel::onMarket, state.errors?.marketError)
 FormField(
 "Price in naira", state.amount, viewModel::onAmount, state.errors?.amountError,
 keyboardType = KeyboardType.Decimal
 )
 Button(onClick = viewModel::save, modifier = Modifier.fillMaxWidth().heightIn(min = 48.dp)) {
 Text("Save price")
 }
 }
 }
}
@Composable
fun FormField(
 label: String, value: String, onChange: (String) -> Unit, error: String?,
 keyboardType: KeyboardType = KeyboardType.Text
) {
 OutlinedTextField(
 value = value,
 onValueChange = onChange,
 label = { Text(label) },
 isError = error != null,
 supportingText = { error?.let { Text(it) } },
 keyboardOptions = KeyboardOptions(keyboardType = keyboardType),
 singleLine = true,
 modifier = Modifier.fillMaxWidth()
 )
}

@Composable
fun MarketMateNavHost() {
 val navController = rememberNavController()
 NavHost(navController, startDestination = ListRoute) {
 composable<ListRoute> {
 ListScreen(
 onOpenItem = { navController.navigate(DetailRoute(it)) },
 onAdd = { navController.navigate(AddRoute) }
 )
 }
 composable<DetailRoute> { DetailScreen(onBack = { navController.popBackStack() }) }
 composable<AddRoute> { AddScreen(onDone = { navController.popBackStack() }) }
 }
}
@AndroidEntryPoint
class MainActivity : ComponentActivity() {
 override fun onCreate(savedInstanceState: Bundle?) {
 super.onCreate(savedInstanceState)
 enableEdgeToEdge()
 setContent { MarketMateTheme { MarketMateNavHost() } }
 }
}

class AddViewModelTest {
 @get:Rule val mainRule = MainDispatcherRule()
 @Test
 fun invalid_input_sets_errors_and_does_not_save() = runTest {
 val repo = FakePriceRepository()
 val vm = AddViewModel(repo, ValidatePriceUseCase())
 vm.save()
 assertNotNull(vm.state.value.errors)
 assertTrue(repo.added.isEmpty())
 }
 @Test
 fun valid_input_saves_and_marks_saved() = runTest {
 val repo = FakePriceRepository()
 val vm = AddViewModel(repo, ValidatePriceUseCase())
 vm.onItem("Garri"); vm.onMarket("Bodija"); vm.onAmount("2500")
 vm.save()
 advanceUntilIdle()
 assertEquals(1, repo.added.size)
 assertTrue(vm.state.value.saved)
 }
}
class FakePriceRepository : PriceRepository {
 val added = mutableListOf<Triple<String, String, Long>>()
 private val all = MutableStateFlow<List<PriceEntry>>(emptyList())
 override fun observeAll() = all
 override fun observeForItem(item: String) = all.map { list -> list.filter { it.itemName == item } }
 override suspend fun add(item: String, market: String, amountKobo: Long, recordedAtMs: Long) {
 added += Triple(item, market, amountKobo)
 }
 override suspend fun delete(id: Long) {}
}

class AddScreenTest {
 @get:Rule val rule = createComposeRule()
 @Test
 fun shows_error_when_amount_missing() {
 rule.setContent { MarketMateTheme { AddScreenPreviewHost() } } // hosts AddScreen with a fake ViewModel
 rule.onNodeWithText("Save price").performClick()
 rule.onNodeWithText("Enter a number").assertExists()
 }
}

[ ] applicationId and versionName/versionCode set; package name is yours
[ ] Release build: minify on (R8), shrink resources; test the release build, not just debug
[ ] Keep rules checked (Room, Hilt, kotlinx.serialization) - app does not crash on release
[ ] Signing: upload key created; Play App Signing enabled; keystore backed up safely
[ ] Target API meets the current Google Play requirement (check Play Console help)
[ ] App icon (adaptive) and screenshots (phone, and tablet if supported)
[ ] Store listing: title, short and full description, privacy policy URL
[ ] Data safety form: this version collects no data and has no network
[ ] Content rating questionnaire completed
[ ] Internal test track install on a real device; then closed test if your account type requires one
[ ] Crash-free and ANR-free in testing; accessibility review done

# MarketMate

Record and compare foodstuff prices across Ibadan markets. Works offline.

## Features
- Add, search and delete price entries
- Item history and "cheapest market in the last 30 days"
- Works with no internet; data stored on the device

## Tech
Kotlin, Jetpack Compose (Material 3), Navigation (type-safe routes), Room, Hilt, Coroutines/Flow

## Architecture
UI (Compose + ViewModel) -> Domain (use cases) -> Data (Room repository). Unidirectional data flow.
[diagram]

## Testing
Unit tests for domain rules and ViewModels; Compose UI tests; accessibility review notes in /docs.

## What I learned / next steps
...