Event-Driven UI with Kotlin Multiplatform

A Kotlin Multiplatform project implementing Event-Driven UI (Server-Driven UI) pattern using Firebase Cloud Messaging (FCM). The server pushes notifications to mobile apps, which automatically update their UI state based on event types.

Overview

• Single Codebase: Share 70-80% of code between Android and iOS
• Event-Driven UI: Server triggers UI updates via FCM without manual refresh
• Clean Architecture: Repository pattern, Use Cases, ViewModels with Koin DI
• Reactive State: StateFlow for reactive UI updates across platforms

Architecture Flow

User Action (Mobile App)
         |
API Call to Server (Ktor Client)
         |
Server Process (Ktor Server)
         |
Send FCM Notification (Firebase Admin SDK)
         |
    +----+----+
    |         |
Android    iOS (via APNS)
    |         |
Platform-Specific Receiver
         |
Shared Event Handler (KMP)
         |
Shared State Manager (StateFlow)
         |
UI Update (Compose Multiplatform)

Project Structure

AmaryPay/
├── composeApp/           # Compose Multiplatform UI
│   ├── commonMain/       # Shared UI code
│   ├── androidMain/      # Android-specific (FCM Service)
│   └── iosMain/          # iOS-specific (MainViewController)
├── shared/               # Shared business logic
│   ├── commonMain/       # Platform-agnostic code
│   │   ├── data/         # Repository, API Service, DataStore
│   │   ├── domain/       # Use Cases, Models
│   │   ├── presentation/ # ViewModels
│   │   ├── fcm/          # Event handling, State management
│   │   └── di/           # Koin modules
│   ├── androidMain/      # Android implementations
│   ├── iosMain/          # iOS implementations
│   └── jvmMain/          # JVM implementations (for server)
├── iosApp/               # iOS app wrapper (Swift)
└── server/               # Ktor backend server
    ├── models/           # Event types, Notification payloads
    ├── routes/           # API endpoints
    └── services/         # Firebase service

Quick Start

Prerequisites

• Android Studio or IntelliJ IDEA
• Xcode (for iOS)
• JDK 17+
• Firebase project with FCM enabled

1. Setup Firebase

Android: Download google-services.json and copy to composeApp/

iOS: Download GoogleService-Info.plist, add to iosApp/iosApp/ in Xcode, generate APNs Auth Key

Server: Generate service account key, copy to server/src/main/resources/firebase-service-account.json

See FCM_SETUP_GUIDE.md for detailed instructions.

2. Build and Run

Server:

./gradlew :server:run

Android:

./gradlew :composeApp:installDebug

iOS:

cd iosApp && pod install && open iosApp.xcworkspace

Event Types

Category	Events
Payment	PAYMENT_SUCCESS, PAYMENT_FAILED, PAYMENT_PENDING, PAYMENT_REFUNDED
Transaction	TRANSACTION_CREATED, TRANSACTION_UPDATED, TRANSACTION_CANCELLED, TRANSACTION_COMPLETED
Account	BALANCE_UPDATED, ACCOUNT_VERIFIED, ACCOUNT_SUSPENDED, PROFILE_UPDATED
Notification	NEW_PROMOTION, MAINTENANCE_SCHEDULED, SECURITY_ALERT, SYSTEM_ANNOUNCEMENT
UI State	REFRESH_HOME, REFRESH_TRANSACTIONS, REFRESH_PROFILE, UPDATE_BADGE, CLEAR_CACHE

API Endpoints

Endpoint	Description
GET /health	Health check
POST /api/notifications/send	Send to single device
POST /api/notifications/send-bulk	Send to multiple devices
POST /api/notifications/send-topic	Send to topic subscribers
POST /api/notifications/trigger-event	Simplified event trigger

Demo App

Silent Notify	Non-Silent Notify
Screen_recording_20260126_012826.mp4	Screen_recording_20260126_012259.mp4

Documentation

Mobile App

• MOBILE_APP_README.md - Mobile app overview and architecture
• FCM_SETUP_GUIDE.md - Firebase Cloud Messaging setup
• FCM_TESTING_EXAMPLES.md - Testing examples and scenarios
• KMP_IMPLEMENTATION_GUIDE.md - Kotlin Multiplatform implementation
• PLATFORM_DIFFERENCES.md - Android vs iOS FCM differences

Server

• server/README.md - Server documentation
• server/QUICK_START.md - Quick start guide
• server/EXAMPLES.md - Use case examples
• server/PROJECT_STRUCTURE.md - Server project structure
• server/test-api.http - HTTP request examples

Tech Stack

Component	Technology
Shared Code	Kotlin Multiplatform
UI	Compose Multiplatform
Server	Ktor
Push Notifications	Firebase Cloud Messaging
HTTP Client	Ktor Client
Dependency Injection	Koin
Local Storage	DataStore
State Management	StateFlow
Serialization	kotlinx.serialization

Key Features

• Event-Driven UI: Server pushes events, app updates automatically
• Silent Notifications: Background UI updates without disturbing user
• Cross-Platform: Single codebase for Android and iOS
• Clean Architecture: Separation of concerns with layers
• Delayed FCM: Server returns response immediately, sends FCM with delay

License

This project is licensed under the MIT License.