Design a Real-Time Chat Application

Reading from the network directly in the ViewModel breaks offline support, introduces loading states in the UI, and makes the UI depend on network availability. Room acts as a local cache that the UI always reads from — the same query works whether you're online or offline. The Repository syncs Room with the server silently in the background. This is the repository pattern and the foundation of offline-first architecture. The UI is always fast because local DB reads are microseconds, not hundreds of milliseconds.

If you wait for the server to generate an ID before inserting into Room, the user sees a loading spinner after tapping Send — which feels sluggish. The localId (a UUID generated on-device) lets you insert into Room immediately, render the bubble, and send to the server in the background. When the server ACK arrives, you write back the serverId to the same row. The localId also acts as an idempotency key — if the network request is retried, the server ignores duplicate frames with the same localId.

If you call the API directly from the ViewModel and the user closes the app mid-send, the coroutine is cancelled and the message is lost. WorkManager survives process death — it stores the work request in its own SQLite DB and re-executes it when the app restarts or connectivity returns. It also handles NETWORK_CONNECTED constraints automatically, so you don't need to manage connectivity callbacks yourself. For anything that must complete eventually regardless of app lifecycle, WorkManager is the right tool.

Use exponential backoff with jitter: delay = min(2ⁿ × 1000ms, 30000ms) + random(0–1000ms). The jitter prevents thousands of clients from reconnecting simultaneously after a server restart (thundering herd). Tie the connection to the app's foreground state using ProcessLifecycleOwner — connect on ON_START, disconnect on ON_STOP. When backgrounded, rely on FCM push to wake the app instead of keeping a persistent connection. Also register a ConnectivityManager.NetworkCallback to reconnect immediately when network becomes available, rather than waiting for the next backoff interval.

On reconnect: (1) The WebSocket connects and the server pushes any missed messages that arrived while the client was offline. (2) For a 3-day gap, the server may have too many messages to push via WebSocket — instead, the client calls a REST GET /messages?since={lastKnownServerTs} endpoint to fetch the backlog and writes them all to Room. (3) Any outbox messages (PENDING rows in Room) are immediately picked up by WorkManager and sent. The key is storing lastKnownServerTs persistently in DataStore so the sync-from point survives app restarts.

Sending a receipt per message is fine for low-traffic chats but doesn't scale. If a conversation has 100 unread messages, opening it would trigger 100 READ receipt frames simultaneously. Instead, batch them: send a single READ_ACK{ conversationId, upToMessageId } frame when the chat screen becomes visible. The server marks all messages up to that ID as read. This reduces receipt traffic by ~90%. For DELIVERED receipts, send one per incoming message immediately after writing to Room — this is unavoidable since delivery is per-message.

Use INSERT OR IGNORE (Room's OnConflictStrategy.IGNORE) when inserting incoming messages. The localId is the primary key — if the same frame arrives twice (reconnect scenario, server retry), the second insert is silently dropped. On the sender side, the outbox pattern ensures the message is in Room before any network call, so the bubble is never duplicated regardless of how many times WorkManager retries. The key insight: make every write idempotent at the DB level rather than trying to deduplicate at the UI level.

Group chat introduces fan-out: one message must be delivered to N recipients. Two strategies: (1) Fan-out on write (server-side) — when the server receives a message, it immediately pushes to all online group members' WebSocket connections and queues FCM for offline ones. Simple for the client, scales to ~100 members. (2) Fan-out on read (client-side) — the server stores one copy and clients pull. Simpler server, but more complex client sync logic. For the client, group messages add a groupId field and read receipts become per-member (you need to track who has read, not just whether the message was read).

Never block the message send on media upload. The flow: (1) Copy image to app-internal storage, compress to ≤300KB. (2) Insert a message row with mediaUri = localPath, status = PENDING — bubble renders immediately from local file. (3) MediaUploadWorker uploads to S3 via a pre-signed URL in the background using chunked multipart upload. Store the last uploaded byte offset in DataStore so uploads resume after interruption. (4) On success, update the row with the CDN URL. Coil swaps the image source transparently. The receiver downloads from CDN on first open and caches to disk.

When the app is killed, the WebSocket is gone. The server detects the disconnect and switches to FCM. Send a data-only push (not a notification push) — this wakes the app's FirebaseMessagingService even when the app is killed. In onMessageReceived(): (1) Connect the WebSocket briefly. (2) Fetch missed messages via REST GET /messages?since=lastTs. (3) Write to Room. (4) Show a local notification using NotificationManager. Use data push not notification push so you control the notification content (unread count, sender name) rather than FCM controlling it. Handle notification grouping for multiple conversations using NotificationCompat.InboxStyle.

Use Paging 3 with RemoteMediator. The PagingSource reads from Room (fast, local). When the user scrolls past the oldest locally cached message, RemoteMediator.load() fires and fetches the next page from REST GET /messages?before={oldestLocalServerId}&limit=50. Write the fetched page to Room. Paging 3 automatically emits the updated list — the UI scrolls smoothly with no manual handling. Use cursor-based pagination (by serverId or serverTs), never offset-based — offset pagination breaks when new messages are inserted during scrolling.

Never use the client timestamp (createdAt) as the canonical ordering key. Client clocks can be wrong by minutes or days. Use serverTs — the timestamp assigned by the server when it persists the message — for ordering. For display, show the client timestamp (so "just now" is accurate), but sort by serverTs. In Room: ORDER BY serverTs ASC, localId ASC — the localId as a tiebreaker handles the brief window where serverTs is null (PENDING messages). PENDING messages always appear at the bottom since their serverTs is null.

Use the Signal Protocol (X3DH + Double Ratchet). Key changes: (1) On first launch, generate an identity key pair and a set of one-time pre-keys. Upload public keys to the server's key distribution service. (2) Before the first message to a user, fetch their public keys and run X3DH to derive a shared session key. (3) Encrypt every message on-device before sending. The server only ever sees ciphertext. (4) Room stores encrypted blobs — you decrypt on read, in the ViewModel before mapping to UI models. Major trade-off: key management becomes complex. New device onboarding, key rotation, and message backup all require careful design. The server cannot moderate content.

Typing indicators are ephemeral — never persist them to Room. The flow: (1) When the user types, send a TYPING{ conversationId } WebSocket frame. (2) Debounce the send — only fire after 500ms of inactivity stops (don't send on every keystroke). (3) The server forwards the event to the recipient's WebSocket. (4) On receipt, show the indicator and start a 5-second timer. If another TYPING frame arrives, reset the timer. If it expires, hide the indicator. (5) Send a TYPING_STOP frame when the user clears the input or sends the message. Store the typing state in a simple MutableStateFlow<Boolean> in the ViewModel — no DB involved.

Each device maintains its own WebSocket connection identified by a deviceId. The server maintains a mapping of userId → [deviceId1, deviceId2, ...]. When a message is sent, the server fans out to all active WebSocket connections for that user. For offline devices, FCM is registered per-device so each gets its own push token. The client-side Room DB is per-device — messages sync independently on each device using lastSyncedTs. The trickiest part: read receipts. If a user reads a message on their tablet, the phone should also mark it as read. The server broadcasts a READ_SYNC event to all other devices of the same user.

The conversation list is a Room query with a reactive Flow. Use a Room @Query with a JOIN between conversations and messages tables:
SELECT c.*, m.text as lastMessageText FROM conversations c LEFT JOIN messages m ON m.localId = c.lastMessageId ORDER BY c.updatedAt DESC. Every time a new message is inserted, Room emits on this Flow automatically — the conversation list reorders and shows the new preview without any manual refresh. Unread count is a column on the conversations table, incremented on incoming message insert and reset to 0 when the chat screen opens.

Three layers: (1) Unit tests — Test SendMessageUseCase with a fake Repository. Test ChatViewModel using runTest + Turbine to assert StateFlow emissions. Test ChatRepository with a fake DAO and fake WebSocketManager. (2) Integration tests — Test Room DAO with an in-memory Room database (Room.inMemoryDatabaseBuilder) using runTest. Test the outbox flow with a TestListenableWorkerBuilder for WorkManager. (3) UI tests — Use MockWebServer (OkHttp) to simulate WebSocket frames and assert Compose UI reactions. Use Hilt's @UninstallModules + @TestInstallIn to replace real dependencies with fakes.

Delete for me: Soft-delete in the local Room DB — add a deletedForMe: Boolean flag. The Room query filters these out. Never actually delete the row (it may be needed for receipt sync). Delete for everyone: Send a DELETE{ serverId } WebSocket frame. The server marks the message as deleted in its DB and fans out a DELETE event to all recipients' devices. On receipt, the client sets deletedForEveryone = true in Room. The UI shows "This message was deleted" in place of the content. The content itself can be nulled out in Room. Hard limit: WhatsApp allows delete-for-everyone only within 60 hours — enforce this on the server.

The Android client itself doesn't change at scale — it still manages one WebSocket and one Room DB. The client-side concerns at scale are: (1) Reconnect storms — exponential backoff with jitter prevents all 1M clients hitting the server simultaneously after an outage. (2) Battery efficiency — the foreground/background WebSocket lifecycle pattern keeps battery impact minimal. (3) DB growth — implement a message retention policy: delete messages older than 30 days from Room (keep on server). Use a periodic WorkManager task for DB housekeeping. (4) Memory — Paging 3 ensures only the visible window of messages is in memory, not all 10,000.

Use Kotlin Multiplatform (KMM). The shareable layer includes: Repository, Use Cases, data models, and the outbox pattern logic. Room is replaced by SQLDelight (which generates type-safe Kotlin code from SQL for both Android and iOS). kotlinx.coroutines works on both platforms. The WebSocket client can use Ktor's WebSocket client (multiplatform). What stays platform-specific: UI (Compose on Android, SwiftUI on iOS), WorkManager (use BackgroundTasks on iOS), and FCM (use APNs on iOS). This approach typically reduces business logic duplication by 60–70%, but adds build complexity and requires the team to be comfortable with KMM's maturity limitations.