Android Architecture

This document describes the Clean Architecture design of the Visla GPS Android application, covering layer responsibilities, dependency flow, package organization, and the reasoning behind key architectural decisions.

Architecture Overview

The app follows Clean Architecture principles with 3 primary layers (UI, Domain, Data) and 2 supporting layers (Core for cross-cutting infrastructure, DI for dependency wiring). Each layer has a well-defined responsibility and communicates only through abstractions.

Dependency Flow

The Domain layer has zero dependencies on Data or UI. Both the UI and Data layers depend on Domain. Core provides cross-cutting infrastructure used by Data and UI but never contains business logic.

---

Package Structure

com.visla.vislagps/
├── MainActivity.kt
├── VislaGPSApp.kt                    # @HiltAndroidApp entry point
│
├── domain/                           # Pure Kotlin — no Android dependencies
│   ├── entities/                     # Business models
│   │   ├── Device.kt                # Device, DeviceWithPosition, DevicePermissions, DeviceStatus
│   │   ├── Position.kt              # Position with GPS attributes
│   │   ├── Event.kt                 # Device events
│   │   ├── Geofence.kt              # Geofence, GeofenceCreateData, GeofenceUpdateData
│   │   ├── User.kt                  # User profile
│   │   ├── Command.kt               # Device commands
│   │   ├── Subscription.kt          # Billing/subscription state
│   │   ├── Sharing.kt               # Share invites and permissions
│   │   ├── NotificationEntities.kt  # Notification history items
│   │   ├── NotificationNavigation.kt
│   │   ├── NotificationClickData.kt
│   │   ├── DeepLink.kt              # Deep link data
│   │   ├── DeviceIconCategory.kt    # Device icon categories and icons
│   │   └── LegalDocument.kt         # Terms/privacy documents
│   ├── repositories/                 # Port interfaces (12 interfaces)
│   │   ├── AuthRepository.kt
│   │   ├── DeviceRepository.kt
│   │   ├── DeviceLifecycleRepository.kt
│   │   ├── PositionRepository.kt
│   │   ├── EventRepository.kt
│   │   ├── GeofenceRepository.kt
│   │   ├── SharingRepository.kt
│   │   ├── SubscriptionRepository.kt
│   │   ├── CommandRepository.kt
│   │   ├── NotificationRepository.kt
│   │   ├── RealTimeRepository.kt
│   │   └── BillingRepository.kt
│   ├── usecases/                     # Business logic, organized by feature
│   │   ├── auth/                     # 17 use cases (login, register, 2FA, password, …)
│   │   ├── devices/                  # 5 use cases + DevicesInteractor
│   │   ├── geofences/                # 5 use cases (CRUD + list)
│   │   ├── commands/                 # 6 use cases (send, fetch, status)
│   │   ├── sharing/                  # 7 use cases (share, revoke, invites)
│   │   ├── billing/                  # License & subscription use cases
│   │   ├── events/                   # Event queries
│   │   ├── positions/                # Position history
│   │   ├── notifications/            # Push, history, settings
│   │   ├── realtime/                 # WebSocket connection management
│   │   └── deeplink/                 # Deep link parsing & handling
│   ├── errors/
│   │   └── DomainExceptions.kt       # Sealed exception hierarchy
│   ├── services/
│   │   └── PushTokenManager.kt       # FCM token abstraction
│   └── ValidationConstants.kt        # Shared validation rules
│
├── data/                             # Android/network dependencies
│   ├── remote/
│   │   ├── api/                      # Retrofit service interfaces (11 APIs)
│   │   └── dto/                      # Data Transfer Objects (10 files)
│   ├── repositories/                 # Repository implementations (15 classes)
│   ├── mappers/                      # DTO ↔ Entity mappers (9 mappers)
│   ├── network/
│   │   └── WebSocketManager.kt       # OkHttp WebSocket with auto-reconnect
│   ├── auth/
│   │   ├── GoogleAuthManager.kt
│   │   └── FacebookAuthManager.kt
│   ├── billing/
│   │   ├── IBillingManager.kt
│   │   └── BillingManager.kt         # Google Play Billing
│   ├── models/
│   │   └── LegacyModels.kt
│   └── MapProviderManager.kt         # Google Maps / Mapbox switching
│
├── ui/                               # Jetpack Compose UI
│   ├── base/
│   │   ├── BaseIntent.kt             # MVI intent marker interface
│   │   └── IntentViewModel.kt        # Base ViewModel with intent dispatch
│   ├── screens/                      # Feature screens (Screen + ViewModel pairs)
│   ├── viewmodels/                   # Shared ViewModels (MapViewModel, etc.)
│   ├── components/                   # Reusable Compose components
│   ├── navigation/
│   │   ├── MainNavigation.kt
│   │   ├── NavigationBar.kt
│   │   └── ProfilePreloadEntryPoint.kt
│   ├── handlers/
│   │   ├── DeepLinkHandler.kt
│   │   └── PushNotificationHandler.kt
│   ├── state/
│   │   └── NotificationState.kt
│   ├── formatters/                   # Display formatting utilities
│   ├── maps/                         # Map integration components
│   ├── subscription/                 # Subscription UI
│   ├── theme/                        # Material theme definitions
│   └── utils/                        # UI utility functions
│
├── core/                             # Cross-cutting infrastructure
│   ├── network/
│   │   ├── TokenManager.kt           # JWT storage, refresh, migration
│   │   ├── EncryptedTokenDataStore.kt # Encrypted token persistence
│   │   ├── AuthInterceptor.kt        # OkHttp auth header injection
│   │   ├── TokenAuthenticator.kt     # Automatic 401 → token refresh
│   │   ├── BaseUrlProvider.kt        # Environment-aware base URL
│   │   ├── NetworkConstants.kt
│   │   ├── HttpStatusCode.kt
│   │   └── NullOnEmptyConverterFactory.kt
│   ├── data/                         # Observable data stores (source of truth)
│   │   ├── DeviceDataStore.kt
│   │   ├── GeofenceDataStore.kt
│   │   ├── SharingDataStore.kt
│   │   ├── InviteDataStore.kt
│   │   ├── NotificationDataStore.kt
│   │   ├── RealTimeDataBridge.kt      # WebSocket → DataStore sync
│   │   └── AppPreferencesDataStore.kt
│   ├── cache/
│   │   └── MemoryCache.kt            # TTL-based in-memory cache
│   ├── config/
│   │   └── DeepLinkConfig.kt
│   ├── initialization/
│   │   └── AppInitializer.kt         # Logger, Facebook SDK setup
│   ├── notification/
│   │   └── NotificationManager.kt    # Android notification channels
│   ├── permissions/
│   │   └── PermissionManager.kt      # Runtime permission handling
│   ├── service/
│   │   ├── FCMService.kt             # Firebase Cloud Messaging receiver
│   │   └── FCMTokenManagerImpl.kt    # PushTokenManager implementation
│   ├── geometry/
│   │   ├── GeoConstants.kt
│   │   └── WktBuilder.kt             # WKT geometry construction
│   └── utils/
│       ├── Logger.kt                 # Structured logging
│       ├── LoggingConstants.kt
│       ├── LocaleManager.kt
│       ├── TimeConstants.kt
│       └── StringExtensions.kt
│
├── di/                               # Hilt dependency injection modules
│   ├── AppModule.kt                  # LocaleManager
│   ├── NetworkModule.kt              # OkHttp, Retrofit, all API interfaces
│   ├── RepositoryModule.kt           # Interface → Impl bindings (11 repos)
│   ├── ServiceModule.kt              # PushTokenManager → FCMTokenManagerImpl
│   ├── TokenManagerModule.kt         # TokenManager, EncryptedTokenDataStore
│   ├── BaseUrlModule.kt              # Environment-specific base URL
│   ├── BillingModule.kt              # Billing (debug/release variants)
│   └── AppPreferencesModule.kt       # SharedPreferences / DataStore
│
└── widget/                           # Home screen widget (Glance)
    ├── DeviceGridWidget.kt
    ├── WidgetDataStore.kt
    ├── WidgetDevice.kt
    ├── WidgetGridBuilder.kt
    └── WidgetSyncWorker.kt

---

Layer Details

Domain Layer

The domain layer is pure Kotlin with no Android framework dependencies. It defines the business rules of the application and serves as the stable core that other layers depend on.

Entities

Domain entities are immutable data classes representing core business concepts:

data class Device(
    val id: Int,
    val name: String,
    val uniqueId: String,
    val status: DeviceStatus,
    val disabled: Boolean,
    val lastUpdate: Instant?,
    val positionId: Int?,
    val isOwner: Boolean,
    val suspended: Boolean,
    val isMuted: Boolean,
    val permissions: DevicePermissions,
    // ...
)

data class DeviceWithPosition(
    val device: Device,
    val position: Position?
)

Entities never contain serialization annotations or framework-specific code.

Repository Interfaces (Ports)

Repository interfaces define the contracts for data access. The domain layer declares what data it needs without specifying how it's fetched:

interface DeviceRepository {
    val devicesWithPositionsFlow: StateFlow<List<DeviceWithPosition>>

    suspend fun getDevices(): List<Device>
    suspend fun getDevice(id: Int): Device
    suspend fun getDevicesWithPositions(): List<DeviceWithPosition>
    suspend fun refreshDevices(): List<DeviceWithPosition>
    suspend fun claimDevice(token: String): Device
    suspend fun updateDevice(
        id: Int, name: String? = null, icon: String? = null,
        color: String? = null, category: String? = null
    ): Device
    suspend fun unclaimDevice(id: Int)
    suspend fun invalidateCache()
    // ...
}

Reactive state is exposed via StateFlow for real-time data (positions, connection status), while one-shot operations use suspend functions. The RealTimeRepository exposes WebSocket events as Flows:

interface RealTimeRepository {
    val isConnected: StateFlow<Boolean>
    val positionUpdates: Flow<Position>
    val deviceStatusUpdates: Flow<Pair<Int, String>>
    val geofenceCreated: Flow<Geofence>
    val shareInviteReceived: Flow<ShareInviteReceivedEvent>
    // ...
    fun connect()
    fun disconnect()
}

Use Cases

Use cases encapsulate a single business operation. They follow the operator invoke() convention so they read like function calls:

class ClaimDeviceUseCase @Inject constructor(
    private val deviceRepository: DeviceRepository
) {
    suspend operator fun invoke(token: String): Device {
        val normalizedToken = token.trim().uppercase()

        if (normalizedToken.isEmpty()) {
            throw ValidationException("Claim token is required", "token")
        }

        val minLength = ValidationConstants.VERIFICATION_CODE_LENGTH
        if (normalizedToken.length < minLength) {
            throw InvalidClaimTokenException(
                "Token must be at least $minLength characters"
            )
        }

        return deviceRepository.claimDevice(normalizedToken)
    }
}

Use cases handle input validation, normalization, and business rule enforcement before delegating to repositories. They throw typed DomainExceptions on failure.

Interactors are facades that group related use cases for ViewModels that need multiple operations:

class DevicesInteractor @Inject constructor(
    private val fetchDevicesUseCase: FetchDevicesUseCase,
    private val claimDeviceUseCase: ClaimDeviceUseCase,
    private val unclaimDeviceUseCase: UnclaimDeviceUseCase,
    private val deviceRepository: DeviceRepository
)

Domain Exceptions

A sealed class hierarchy provides typed, context-rich error handling:

sealed class DomainException(message: String, cause: Throwable? = null)
    : Exception(message, cause)

// Auth
class AuthenticationException(...) : DomainException(...)
class TwoFactorRequiredException(val tempToken: String, val type: String) : DomainException(...)
class EmailNotVerifiedException(val email: String) : DomainException(...)

// Device
class DeviceNotFoundException(val deviceId: Int?) : DomainException(...)
class DeviceAccessDeniedException(val deviceId: Int) : DomainException(...)

// Network
class NetworkException(...) : DomainException(...)
class ServerException(val statusCode: Int) : DomainException(...)

// Subscription
class DeviceLimitReachedException(val limit: Int, val current: Int) : DomainException(...)
// ... ~27 exception types total

Each exception carries contextual data (device IDs, email addresses, status codes) that the UI layer uses to display meaningful error messages.

---

Data Layer

The data layer implements domain repository interfaces using Retrofit, OkHttp WebSockets, and local caching.

Retrofit API Interfaces

Each domain area has a corresponding Retrofit interface:

interface DeviceApi {
    @GET("api/devices/")
    suspend fun getDevices(): List<DeviceDto>

    @GET("api/devices/{id}")
    suspend fun getDevice(@Path("id") id: Int): DeviceDto

    @POST("api/devices/claim")
    suspend fun claimDevice(@Body request: ClaimDeviceRequest): DeviceClaimResponse

    @PUT("api/devices/{id}")
    suspend fun updateDevice(@Path("id") id: Int, @Body request: UpdateDeviceRequest): DeviceDto
    // ...
}

DTOs (Data Transfer Objects)

DTOs mirror the API contract and are kept separate from domain entities:

data class DeviceDto(
    val id: Int,
    val name: String,
    val uniqueId: String? = null,
    val status: String? = null,       // String, not enum — API contract
    val permissions: DevicePermissionsDto?,
    // ...
)

data class UpdateDeviceRequest(
    val name: String? = null,
    val icon: String? = null,
    val color: String? = null,
    val category: String? = null
)

Mappers

Dedicated mapper classes convert between DTOs and domain entities, handling nullability, defaults, and date parsing:

@Singleton
class DeviceMapper @Inject constructor() {

    fun toDomain(dto: DeviceDto): Device {
        return Device(
            id = dto.id,
            name = dto.name,
            status = DeviceStatus.fromString(dto.status),
            lastUpdate = dto.lastUpdate?.let { parseInstant(it) },
            permissions = mapPermissions(dto.permissions, dto.isOwner ?: true),
            // ...
        )
    }

    fun toDomainList(dtos: List<DeviceDto>): List<Device> = dtos.map { toDomain(it) }
}

Repository Implementations

Implementations wire together APIs, mappers, caches, and DataStores.

Note: Three data-layer repositories — NotificationPermissionRepository, NotificationSettingsRepository, and NotificationStateRepository — live in data/repositories/ without corresponding domain interfaces. These are Android-specific concerns (runtime permission state, notification channel settings, UI notification state) that don't warrant abstraction through the domain layer.

@Singleton
class DeviceRepositoryImpl @Inject constructor(
    private val deviceApi: DeviceApi,
    private val positionApi: PositionApi,
    private val deviceMapper: DeviceMapper,
    private val positionMapper: PositionMapper,
    private val deviceDataStore: DeviceDataStore
) : DeviceRepository {

    override val devicesWithPositionsFlow: StateFlow<List<DeviceWithPosition>>
        get() = deviceDataStore.devicesWithPositions

    override suspend fun getDevices(): List<Device> {
        // 1. Check DataStore cache
        // 2. Fetch from API on miss
        // 3. Map DTOs → Entities
        // 4. Update DataStore
    }
}

Data flow through the repository:

WebSocket (Real-Time Updates)

WebSocketManager maintains a persistent connection with auto-reconnect using fixed-delay reconnection (RECONNECT_DELAY_MS = 5_000L). It emits domain events through SharedFlows:

This ensures all ViewModels observing DeviceDataStore.devicesWithPositions automatically receive real-time position updates without explicit refresh calls.

---

UI Layer

The UI layer uses Jetpack Compose with an MVI (Model-View-Intent) pattern.

MVI Architecture

Every ViewModel extends IntentViewModel<I>, which provides a single entry point for user actions:

// Intent marker
interface BaseIntent

// Base ViewModel with centralized intent dispatch
abstract class IntentViewModel<I : BaseIntent> : ViewModel() {
    open fun handle(intent: I) {
        Logger.info("${javaClass.simpleName}: Handling intent",
            mapOf("intent" to intent.javaClass.simpleName))
        reduce(intent)
    }

    protected abstract fun reduce(intent: I)

    protected fun handleAsync(intent: I, block: suspend () -> Unit) { ... }
}

Each screen defines its own sealed intent class:

sealed class DeviceIntent : BaseIntent {
    data object LoadDevices : DeviceIntent()
    data object RefreshDevices : DeviceIntent()
    data object PullToRefresh : DeviceIntent()
    data class SelectDevice(val deviceId: Int?) : DeviceIntent()
    data class UnclaimDevice(val deviceId: Int) : DeviceIntent()
    data object ClearOperationResult : DeviceIntent()
    // ...
}

UI State

State is modeled as a sealed class, making impossible states unrepresentable:

sealed class DevicesUiState {
    object Loading : DevicesUiState()

    data class Success(
        val devices: List<DeviceWithPosition>,
        val isWebSocketConnected: Boolean,
        val licenseStatus: License?
    ) : DevicesUiState()

    data class Error(
        val message: String,
        val devices: List<DeviceWithPosition> = emptyList()
    ) : DevicesUiState()

    data class Refreshing(
        val devices: List<DeviceWithPosition>,
        val isWebSocketConnected: Boolean
    ) : DevicesUiState()
}

ViewModel Structure

ViewModels inject use cases / interactors (never repositories directly) and manage StateFlow-based UI state:

@HiltViewModel
class DevicesViewModel @Inject constructor(
    @param:ApplicationContext private val appContext: Context,
    private val devicesInteractor: DevicesInteractor,
    private val licenseInteractor: DeviceLicenseInteractor,
    private val realTimeDataBridge: RealTimeDataBridge,
    private val observeConnectionStateUseCase: ObserveConnectionStateUseCase
) : IntentViewModel<DeviceIntent>() {

    private val _uiState = MutableStateFlow<DevicesUiState>(DevicesUiState.Loading)
    val uiState: StateFlow<DevicesUiState> = _uiState.asStateFlow()

    override fun reduce(intent: DeviceIntent) {
        when (intent) {
            is DeviceIntent.LoadDevices -> loadDevices()
            is DeviceIntent.RefreshDevices -> refreshDevices()
            // ...
        }
    }
}

Screen Organization

Screens follow a co-located pattern — each screen and its ViewModel live in the same screens/ package:

screens/
├── DevicesListScreen.kt + DevicesViewModel.kt + DevicesUiState.kt
├── DeviceDetailScreen.kt + DeviceDetailViewModel.kt
├── LoginScreen.kt + LoginViewModel.kt
├── GeofenceEditorScreen.kt + GeofenceEditorViewModel.kt
├── SharingScreen.kt + SharingViewModel.kt
└── ... (~30 screen/viewmodel pairs)

---

Core Layer

The core layer provides cross-cutting infrastructure that doesn't belong to any single feature.

Token Management

TokenManager stores JWT tokens in encrypted DataStore with an in-memory cache for synchronous access by OkHttp interceptors. TokenAuthenticator automatically refreshes expired tokens using a separate @NoAuthClient OkHttp instance to avoid circular dependencies.

Observable DataStores

Core DataStores (DeviceDataStore, GeofenceDataStore, etc.) hold the single source of truth for domain data as StateFlows. RealTimeDataBridge subscribes to WebSocket events and pushes updates into these stores:

This eliminates the need for manual refresh — any ViewModel observing a DataStore's StateFlow receives updates automatically.

---

DI Layer

All dependency wiring uses Hilt with @InstallIn(SingletonComponent::class) for app-scoped singletons.

Module	Responsibility
RepositoryModule	Binds 11 domain repository interfaces → data implementations
NetworkModule	Provides OkHttp clients, Retrofit instance, all API interfaces
TokenManagerModule	Provides TokenManager and EncryptedTokenDataStore
ServiceModule	Binds PushTokenManager → FCMTokenManagerImpl
BillingModule	Provides billing (with debug/release build variants)
BaseUrlModule	Environment-specific API base URL
AppModule	LocaleManager singleton
AppPreferencesModule	SharedPreferences / DataStore instances

Repository binding example:

@Module
@InstallIn(SingletonComponent::class)
abstract class RepositoryModule {

    @Binds @Singleton
    abstract fun bindDeviceRepository(impl: DeviceRepositoryImpl): DeviceRepository

    @Binds @Singleton
    abstract fun bindAuthRepository(impl: AuthRepositoryImpl): AuthRepository

    // ... 11 bindings total
}

---

Widget Layer

The widget/ package is a self-contained concern for the Android home screen widget. It uses Jetpack Glance and has its own data pipeline:

• DeviceGridWidget — Glance widget rendering a device grid
• WidgetDataStore — Persisted widget state (independent from app DataStores)
• WidgetSyncWorker — WorkManager periodic sync to keep widget data fresh
• WidgetDevice / WidgetGridBuilder — Widget-specific models and layout

The widget syncs data via WidgetSyncWorker rather than sharing the app's DataStores, ensuring the widget functions even when the app process is not running.

---

Design Decisions

Why Clean Architecture?

Testability — Domain use cases can be unit-tested with mock repositories. No Android framework needed. ViewModels can be tested by providing fake use cases and asserting state transitions.

Maintainability — Changes to the API (new fields, endpoint changes) only affect the Data layer. The UI and business logic remain untouched. Similarly, switching from Retrofit to Ktor or from Compose to a different UI toolkit would not affect the Domain layer.

Team scalability — Clear boundaries let multiple developers work in parallel. One developer can build a new screen while another implements the backing API, as long as they agree on the repository interface.

Why Single-Module?

The app uses a single Gradle module with package-based separation rather than multi-module architecture. This was a deliberate trade-off:

• Reduced build complexity — No module dependency graph to manage, no cross-module visibility issues, simpler Hilt setup.
• Faster iteration — A single module compiles as one unit. For an app of this size (~30 screens, 12 repositories), the build time cost of a single module is negligible.
• Sufficient enforcement — Package-level organization with consistent naming conventions provides adequate separation. The dependency rule (UI → Domain ← Data) is enforced by convention and code review, which works well for a small team.

If the app grows significantly (50+ screens, multiple teams), migrating to multi-module would be straightforward because the package structure already mirrors a module boundary.

Why Feature-Based Use Case Organization?

Use cases are grouped by feature domain (auth/, devices/, geofences/) rather than by technical role:

usecases/
├── auth/          # Login, register, 2FA, password reset
├── devices/       # Claim, unclaim, update, fetch
├── geofences/     # CRUD operations
├── sharing/       # Share, revoke, invites
└── ...

This mirrors how the team thinks about the product. When working on "device sharing", all relevant use cases are in one place. It also scales naturally — adding a new feature means adding a new subdirectory, not scattering files across existing packages.

Why Domain Exceptions Over Result Type?

The app uses a sealed exception hierarchy (DomainException) rather than Kotlin's Result type or a custom Either/Resource wrapper:

• Contextual data — Exceptions carry typed fields (TwoFactorRequiredException.tempToken, DeviceLimitReachedException.limit) that drive UI behavior.
• Flow control — ViewModels catch specific exception types and react accordingly (e.g., TwoFactorRequiredException triggers a navigation to the 2FA screen).
• Simplicity — Use cases return the success type directly (suspend fun invoke(): Device) instead of wrapping in Result<Device>. This keeps the call site clean.
• Coroutine compatibility — Kotlin coroutines have built-in exception propagation. The sealed hierarchy integrates naturally with try/catch in ViewModel handleAsync blocks.

Why Separate core/ for Cross-Cutting Concerns?

Infrastructure like token management, network configuration, and observable DataStores doesn't belong in the Domain layer (it has Android dependencies) or the Data layer (it's not feature-specific). The core/ package provides a home for these concerns:

• core/network/ — TokenManager, AuthInterceptor, TokenAuthenticator form the auth infrastructure used across all API calls.
• core/data/ — Observable DataStores (DeviceDataStore, RealTimeDataBridge) serve as the single source of truth, consumed by both repositories and ViewModels.
• core/cache/ — Generic MemoryCache with TTL, reused by multiple repositories.

This prevents the Data layer from becoming a dumping ground for shared utilities and keeps feature-specific code cleanly separated from infrastructure.

Known layer-boundary exceptions. The strict dependency rule (UI → Domain ← Data) has a few pragmatic violations:

• GeofencesListViewModel directly imports GeofenceRepositoryImpl from the data layer, bypassing the domain abstraction.
• Three files in core/ import from data/: FCMTokenManagerImpl, TokenAuthenticator, and AppInitializer.

These are known tech debt, not intentional patterns. They exist because of expedient wiring choices that haven't yet been refactored behind domain interfaces.

Why MVI with IntentViewModel?

The IntentViewModel<I> base class enforces MVI by funneling all user actions through a handle(intent) → reduce(intent) pipeline:

• Single entry point — Every action goes through handle(), enabling centralized logging, analytics, and debugging.
• Predictable state — Sealed intent classes make all possible actions explicit and exhaustively handled.
• Testable — Tests dispatch intents and assert on resulting StateFlow values.
• Replay/debug — Intent streams can be logged and replayed for debugging.

Why Co-Located Screens and ViewModels?

Screen composables and their ViewModels live together in ui/screens/ rather than in separate ui/screens/ and ui/viewmodels/ packages:

• Locality — When modifying a screen, both the UI and its ViewModel are adjacent.
• Shared ViewModels exception — ViewModels shared across multiple screens (e.g., MapViewModel, NotificationSettingsViewModel) are placed in ui/viewmodels/.