Architecture &
Technical Reference

Multi-module Clean Architecture. Cores are reusable contracts; feature modules own their data flow end-to-end; composeApp wires them together.

Stale-while-revalidate: cached data reaches the UI before the network call completes. The StaleBanner component indicates revalidation in progress and disappears on fresh success.

Generic unpacker — no feature-specific logic. The 18 Eurostat datasets all flow through this same parser before being shaped into typed domain models by per-feature CellMapper extensions.

// core-common: Result<T> sealed interface
sealed interface Result<out T> {
    data object Loading : Result<Nothing>
    data class  Success<T>(val data: T, val isStale: Boolean = false) : Result<T>
    data class  Error(val error: AppError) : Result<Nothing>
}

// core-common: AppError sealed hierarchy
sealed interface AppError {
    data class NetworkError(val cause: Throwable?) : AppError
    data class ParseError(val message: String) : AppError
    data class CacheError(val cause: Throwable?) : AppError
    data object NotFound : AppError
    data object Unknown : AppError
}

// feature-xxx: repository interface (domain layer)
interface XxxRepository {
    fun observe(query: XxxQuery): Flow<Result<List<XxxDataPoint>>>
}

// implementation sketch (data layer)
override fun observe(query: XxxQuery) = flow {
    emit(Result.Loading)
    val cached = cache.read(query.cacheKey)
    if (cached != null) emit(Result.Success(cached, isStale = true))
    try {
        val fresh = api.fetch(query).let(mapper::fromCells)
        cache.write(query.cacheKey, fresh)
        emit(Result.Success(fresh, isStale = false))
    } catch (e: CancellationException) { throw e }   // always rethrow
    catch (e: Exception) {
        if (cached == null) emit(Result.Error(AppError.NetworkError(e)))
        // else: stale cache was emitted — swallow silently
    }
}.flowOn(dispatchers.io)

The repository emits Loading immediately, then emits cached Success(isStale=true) if the cache has data, then revalidates via the network. On network success it writes to cache and emits Success(isStale=false). On network failure it emits Error only if no stale cache was available; otherwise the failure is swallowed silently and the StaleBanner remains visible. CancellationException is always rethrown — never swallowed — so structured concurrency works correctly. No other exception crosses the data/domain boundary; everything surfaces as a typed Result.Error(AppError).

Tests run on JVM via commonTest. KMP-friendly fakes — no Mockk (iOS would reject it). Turbine for Flow assertions: flow.test { assertEquals(Loading, awaitItem()); ... }.

• Package root is eu.eurostat.{module} — e.g. eu.eurostat.feature.population.domain. One class per file; file name matches public class name.
• Sealed types as sealed interface, not sealed class, unless state fields are needed.
• Prefer extension functions over utility classes.
• No !! operator anywhere — use requireNotNull, checkNotNull, or sealed Result handling.
• KDoc on every public type, every interface method, every non-obvious algorithm.
• Never reference Dispatchers.IO or Dispatchers.Default directly — inject DispatcherProvider and use dispatchers.io, etc.
• No exceptions cross the data/domain boundary — every failure surfaces as Result.Error(AppError). CancellationException is always rethrown.
• Unit tests in commonTest whenever possible (run on JVM, fast). Fakes implement the interface directly — no Mockk (KMP-incompatible on iOS).
• Navigation via Decompose — not Voyager, not Compose Navigation. Component interface exposes StateFlow<XxxUiState> and onIntent(XxxIntent).
• All UI tokens come from object Euro (colors, typography, spacing, shapes, moduleAccents) — no hardcoded values in feature screens.