Source document · Mobile-app/docs/ARCHITECTURE.md

Mobile Architecture

Direction

The application uses Kotlin Multiplatform to share domain and application logic across Android and iOS. Shared code must stay independent of concrete Android and iOS APIs. Platform capabilities are exposed through narrow interfaces implemented per platform.

Planned modules

composeApp/ or shared/
├── core/
│   ├── model
│   ├── network
│   ├── database
│   ├── design-system
│   ├── navigation
│   └── localization
├── feature/
│   ├── auth
│   ├── home
│   ├── search
│   ├── booking
│   ├── orders
│   ├── provider
│   ├── chat
│   ├── videos
│   ├── lifestyle
│   ├── meetings
│   └── settings
├── platform/
│   ├── secure-storage
│   ├── media-picker
│   ├── permissions
│   ├── notifications
│   ├── deep-links
│   ├── sharing
│   └── webrtc
├── androidApp/
└── iosApp/

The final Gradle module names may vary, but responsibilities and dependency direction must remain clear.

Data flow

Screen/UI
   ↓ user intent
Feature state holder / ViewModel
   ↓
Use case or repository
   ↓
API client and local cache
   ↓
Go API

UI state includes loading, content, empty, stale/offline, retry, and error states. A local optimistic state must never appear as server-confirmed payment or order completion.

API and models

Generate or maintain typed DTOs from the versioned OpenAPI contract. Map transport DTOs into mobile domain models so API details do not leak through every screen. Preserve stable API error codes and map them to localized user messages.

The current Android transport uses HttpURLConnection behind the shared HttpApiClient decoder. It connects the category grid to the public service catalog endpoint. The Android base URL is set with the Gradle property apiBaseUrl; only the debug manifest permits cleartext local development.

Offline and cache

Cache public catalog content, recent own orders, and recent conversation data according to the Mobile SRS. Cached content exposes staleness. Queue only operations designed for safe retry. Order creation uses the same idempotency key when retrying an uncertain submission.

Native capabilities

Secure credentials use Keychain and Android Keystore-backed storage. Permissions, media pickers, push, deep links, sharing, and WebRTC use platform implementations behind shared interfaces. Denying one permission disables only its related feature.

Feature ownership

Each feature owns its state, screen composition, and user intent handling. Core modules provide reusable capabilities and must not import feature modules. Features may coordinate through navigation contracts or shared domain interfaces rather than reaching into each other’s internal state.