mobile-architecture-decisions

name	mobile-architecture-decisions
description	How to write and maintain Architecture Decision Records (ADRs) for mobile teams, and the canonical set of decisions every mobile project must record. Use when starting a project or when an architectural change is being proposed.

Mobile Architecture Decisions

Instructions

Most mobile architecture debates repeat across projects. Capture decisions in Architecture Decision Records (ADRs) so the agent and future contributors inherit context instead of re-arguing it.

1. ADR Format

Keep ADRs short, markdown, and numbered. One decision per file under docs/adr/.

# ADR-0007: Use Coroutines + Flow for Android Domain Layer

## Status
Accepted 2026-04-19. Supersedes ADR-0003.

## Context
- We had RxJava in the legacy Android app; iOS uses Combine.
- New domain logic is being shared via KMP.

## Decision
Use Kotlin Coroutines and Flow in the shared domain and Android presentation.
Bridge to Swift via KMP suspend interop; do not introduce RxSwift on iOS.

## Consequences
+ One async primitive across Kotlin codebases.
+ Structured concurrency is a first-class feature.
- Swift side needs adapter helpers for Flow collection.
- RxJava usages in legacy modules must be migrated or frozen.

Lifecycle states: Proposed, Accepted, Superseded by ADR-NNNN, Deprecated. Never delete ADRs.

2. Canonical Mobile ADR Set

Every mobile project should have accepted ADRs covering at least:

1. Stack choice (see mobile-tech-stack-selection).
2. Minimum OS versions and the policy for dropping them.
3. Architecture pattern -- MVVM, MVI, TEA, Redux, Clean, etc.
4. Navigation approach -- coordinator, declarative router, stack-based.
5. State management library -- Riverpod, BLoC, Redux Toolkit, Compose state, SwiftUI state.
6. Networking layer -- URLSession, Retrofit, Ktor, Dio, fetch/axios, generated client.
7. Persistence -- SQLite wrapper, Room, Core Data, Drift, SQLDelight, Realm.
8. DI strategy -- constructor, Hilt, Koin, Riverpod, SwiftUI EnvironmentObject.
9. Error model -- sealed error types, Result, exceptions, typed failures.
10. Observability stack -- crash reporter, analytics, logging, performance.
11. Feature flag system -- config service, build-time flags, remote config.
12. Release strategy -- staged rollout percentages, kill switches, flavors.
13. CI system and signing -- GitHub Actions, Bitrise, Codemagic, Xcode Cloud.
14. Privacy boundaries -- what leaves the device and through which SDK.

3. How to Propose a New ADR

An ADR becomes mandatory when a decision:

• Affects more than one module or platform.
• Is expensive to reverse (migrations, data model, public API surface).
• Introduces a new runtime dependency.
• Changes the deployment or compliance surface.

Otherwise, a code comment or CODEOWNERS note is enough.

4. Decision Anti-Patterns

• Whiteboard-only decisions. Write them down, even a week late.
• Implicit decisions. "We are using X because it is already there" must still become an ADR if any of the triggers in Section 3 apply.
• Mega-ADRs. Split decisions so each can be superseded independently.
• Vague consequences. Name specific costs (binary size, startup time, team learning curve).

5. Example Matrix of Architectural Decisions per Stack

Use this to seed ADRs on day one. Adjust to the chosen stack.

Concern	Native iOS	Native Android	Flutter	React Native	KMP
UI pattern	SwiftUI + MV	Compose + MVVM	Widgets + Riverpod/BLoC	RN + hooks + Redux/Zustand	Compose MP or native UI
Nav	NavigationStack	Navigation-Compose	go_router	React Navigation	expect/actual + platform nav
Async	async/await	Coroutines + Flow	Future / Stream	async/await + RxJS optional	Coroutines + Flow
Persistence	Core Data / SwiftData	Room	Drift / sqflite	WatermelonDB / SQLite	SQLDelight
DI	plain init + EnvironmentObject	Hilt / Koin	Riverpod / get_it	plain context / DI libs	Koin
HTTP	URLSession	Retrofit / Ktor	Dio	fetch / axios	Ktor
Errors	typed enums + Result	sealed class + Result	sealed unions (freezed)	discriminated unions	sealed class

6. Keeping ADRs Alive

• Link the ADR index from the top of the README.
• Require an ADR reference in the PR template for any change touching the listed surfaces.
• Review ADRs quarterly; supersede anything that no longer matches reality.
• When onboarding, read the ADR index before reading code.

7. Example ADR Index Snippet

# Architecture Decisions

| # | Title | Status |
| --- | --- | --- |
| 0001 | Mobile stack: KMP + native UI | Accepted |
| 0002 | Minimum iOS 15 / Android 24 | Accepted |
| 0003 | Compose MVVM with unidirectional data flow | Accepted |
| 0004 | Networking via Ktor shared client | Accepted |
| 0005 | SQLDelight for persistence | Accepted |
| 0006 | Crashlytics + Sentry for releases | Accepted |
| 0007 | Coroutines + Flow async model | Accepted |

Checklist

• docs/adr/ exists with the canonical ADR set for the project.
• Each ADR has Status, Context, Decision, Consequences, and a date.
• ADRs are numbered and never deleted, only superseded.
• PR template references ADR IDs for architectural changes.
• ADR index is linked from the README.
• Decisions that span platforms call out per-platform consequences.