Skip to content
All books
New

Controlled Change: architecture, reliability, and evolution for mobile systems

61 chapters in pressure order, from decision discipline and data under failure to AI on mobile and a nine-case casebook.

A mobile architecture book for staff iOS and Android engineers

Most architecture material begins in a clean room. Mobile systems live on constrained devices, across operating-system generations, behind app-store review, with old client versions still running and releases that cannot be recalled.

This book treats those facts as the centre of architecture. It discusses Clean Architecture, MVVM, MVI, Redux, TCA, VIPER, RIBs, Workflow, feature modules, Domain-Driven Design, reactive systems and dependency injection, and presents none of them as a destination. Each is examined as a response to pressure.

It is written in pressure order rather than pattern order, around Atlas, a fictional marketplace and field-operations product that grows from a two-engineer prototype into a multi-team platform with offline work, progressive rollout and an AI assistant.

What you get

  • A decision discipline: characteristics, budgets and evidence, the economics of abstraction, and ADRs with revisit triggers
  • Data under failure: Swift concurrency and Kotlin coroutines as architecture, process death, offline-first, a sync engine, conflicts and schema evolution
  • Scale and teams: feature modules, the module graph, platform engineering, cross-platform with escape hatches, SDKs and legacy migration
  • Production systems: failure-model testing, performance, observability, security, release architecture, feature flags and kill switches, server-driven UI
  • AI on mobile: on-device, cloud and hybrid routing, context and RAG, a governed tool gateway for agentic apps, model lifecycle and evaluation
  • Staff practice, a nine-case casebook and nine appendices, including 12 example ADRs, 10 migration playbooks and a Staff+ interview bank

Where mobile architecture loses control of change

Well illustrated, not well architected

A cleanly separated app that cannot be migrated, observed, released safely or understood by the team is a diagram, not an architecture.

Abstraction borrowed without a return

A layer template repeated across seventy trivial features creates hundreds of types whose purpose is structural compliance.

The release you cannot recall

Old clients stay installed for months, share the backend with new ones, and meet every contract change you ship.

The response lost after commit

A retry without operation identity turns a timeout into a duplicate charge or a false confirmation.

Modules that always change together

A uniform module template looks enforceable until most product changes touch three or four modules of the same capability.

A decision you did not get to make

The framework, the date and the vendors were fixed before any architecture review, and the open questions are still yours.

Good architecture did not predict the future. It made being wrong affordable.
From Controlled Change

What changes when you use it

You stopYou stop asking what pattern the app uses.

You startYou ask how cheaply and safely the product can absorb the next important change.

You stopYou stop borrowing abstractions without naming the return.

You startYou test each boundary for volatility, consequence, multiplicity and coordination.

You stopYou stop marking checkout complete when the payment sheet closes.

You startYou wait for the authority's canonical result and show a pending state until it arrives.

You stopYou stop describing a rewrite by its destination.

You startYou describe coexistence, migration, rollback and deletion.

You stopYou stop relitigating a decision that was imposed on you.

You startYou decide everything the decision did not.

Signs the architecture costs more than it buys

  • A shared module gains consumers faster than owners, and every edit to it rebuilds most of the app.
  • Release flags have no owner and no removal date.
  • A remote UI payload has grown conditions, validation and actions that chain other actions.
  • Retry three times is the whole failure policy.
  • A migration cannot finish without stopping the release train.
  • Nobody can say which representation wins when local intent, cache and the server disagree.

Why this book exists

I tried to write the book I wanted when I was the one holding the decision and the pager at the same time.

Where the book makes a consequential claim, it states what evidence would challenge it. Where it states a trade-off, it names what the trade-off costs, not only what it buys.

Where a large company's practice is instructive, I kept the lesson and dropped the logo. The point was never that a famous team did it. The point is whether the pressure that justified their choice exists in your product.

The book is dedicated to the engineers who inherited the diagram after the people who drew it had left.

A page from the book

Copied as printed, so you can judge the format before you buy.

Free field guide, page 4, from chapters 10, 21, 22, 49 and 54

One attempt, one identity

The client creates the key before durable acceptance and reuses it for every replay; the server keeps a ledger of canonical results.

Born with the intent.

Before the intent is accepted, owned by the durable command. Not at the tap, and never in the transport adapter.

Claimed before the work.

A production ledger claims the key before it books, so only one request wins and a concurrent replay gets an in-progress status. The single-threaded simulator leaves this part to you.

Answered from the ledger.

A replay returns the stored outcome: the receipt, or a business rejection such as a conflict. Nothing runs twice.

Remembered long enough.

Longer than a phone can hold the operation, counting queue age and time offline. Past that window, look up the affected entity by its stable client reference instead of replaying.

Want more pages?

Free PDF, no sign-up: desktop layout, 12 pages or phone layout, 16 pages.

Before and after

An architecture that was imposed on you

Before

I disagree.

After

I will deliver this, and here are the conditions under which it stays reversible.

Server authority is unchanged, risky capabilities stay behind a native boundary, contracts come first, and vendors sit behind ports.

A checkout that says Booked

Before

The payment sheet closed, so show Booked.

After

The client never marks checkout completed just because the payment sheet closed successfully. It waits for the booking authority’s canonical result.

Until then the screen shows a pending receipt state with a status lookup: slightly more complex, but truthful and recoverable.

Failure handling in a system design answer

Before

Retry three times.

After

The send command includes the client ID and idempotency key.

Receiving the same event by socket and by pull is expected. Event IDs and sequence numbers make applying it idempotent.

Choose your edition

Both editions are on one Gumroad page: you pick the edition there, before you pay. Every edition includes free lifetime updates.

Book

The complete book

$199

The complete Controlled Change book, to read, study and apply the architecture decisions.

  • PDF and EPUB
  • 505 pages
  • 61 chapters in eight parts
  • Appendices A to I
  • 74 diagrams
  • Start Here guide, 2 pages
  • Lifetime updates
Choose Book, $199

Secure checkout on Gumroad. Instant PDF and EPUB download. Lifetime updates.

Pro

The book and the Atlas reference system

$299

Everything in Book, plus the Atlas reference system the book follows, so you can inspect how boundaries, contracts, state, ownership and decisions become implementation.

Choose Pro if you want to see the decisions in a real implementation.

  • Everything in Book
  • Toolkit, 83 pages
  • Workbook, 19 pages
  • Atlas Code Guide, 17 pages
  • Start Here guide, 3 pages
  • Atlas reference code, 5 projects: iOS, Android, Kotlin Multiplatform, Backend and shared contract schemas
  • Lifetime updates
Choose Pro, $299

Secure checkout on Gumroad. Instant PDF and EPUB download. Lifetime updates.

Extended

Everything in Pro, plus more platforms and failure tools

$399

Everything in Pro, plus React Native, Flutter and a sync simulator, to compare platforms and explore failure off the happy path.

Choose Extended if you want to compare the architecture across more clients and test it under failure.

  • Everything in Pro
  • Atlas reference code, 8 projects: Pro plus React Native, Flutter and the sync simulator
  • Sync simulator scenarios: duplicate events, reordered writes, process death, model failure
  • Atlas Code Guide, 20 pages, covering all 8 projects
  • Lifetime updates
Choose Extended, $399

Secure checkout on Gumroad. Instant PDF and EPUB download. Lifetime updates.

Atlas and nine cases, from prototype to the imposed decision

The casebook and the Atlas reference system are fictional. They combine common engineering pressures so the trade-offs can be argued without exposing any organisation's systems. In each case several architectures can be defensible, provided their assumptions are explicit.

Chapter 52

Atlas: from prototype to platform

  • Five stages, from two engineers to 150 across mobile and backend
  • Seven decisions that carry most of the outcome
  • Three decisions Atlas had to reverse
  • A three-release migration exercise

Chapter 53

The offline field operation

  • Inspectors offline for days on shared devices
  • Per-artefact durable operations and one submission command
  • Saved on this device is not Submitted
  • A fourteen-case failure test plan

Chapter 54

The global checkout

  • Limited inventory in many currencies and regions
  • Confirmation bound to an exact quote
  • One booking command, orchestrated by the backend
  • A pending receipt instead of an optimistic Booked

Chapter 55

The messaging system

  • Offline compose with no duplicates after retry
  • Ordering per conversation, not global
  • Live channel, push hint and cursor pull
  • No direct Send tool for the model

Chapter 56

The regulated finance app

  • Several jurisdictions with different disclosures and retention
  • Only trusted server systems authorise a transfer
  • Biometric success does not authorise a transfer
  • Incident: an unknown status mapped to Failed

Chapter 57

The cross-platform rewrite

  • Sixty native engineers and an eighteen-month rewrite proposal
  • Measure the delay before choosing a framework
  • Kotlin Multiplatform for selected domain rules, native UI kept
  • Stop conditions for expansion

Chapter 58

The AI trip operator

  • A task inventory that places authority task by task
  • Trip-scoped context policy
  • Typed tools with prepare, confirm and execute
  • A prompt injection rejected at the tool gateway

Chapter 59

The mobile platform program

  • Twelve product teams and five flag wrappers
  • A year-one sequence, quarter by quarter
  • Golden paths teams can trim
  • A year that ends with removed systems

Chapter 60

The agent in the engineering loop

  • Can coding agents merge some of their own changes without a human review
  • Six task classes, sorted by what they touch and how reversible the damage is
  • Only dependency bumps and presentation qualify for reduced review
  • Deny lists for signing, store metadata, release branches and production flags

Chapter 61

The imposed decision

  • A React Native partner app announced before any review
  • What the decision fixed, and what is still open
  • Every consequence classified by reversibility
  • Survivable, not optimal

What is inside

  1. 1Architecture Is Controlled Changep. 16
  2. 2Why Mobile Is Differentp. 21
  3. 3Characteristics, Budgets, and Evidencep. 26
  4. 4The Economics of Abstractionp. 31
  5. 5Decisions, ADRs, and Revisit Triggersp. 36
  6. 6Architecture Across Product Stagesp. 41
  7. 7From Screen to Featurep. 47
  8. 8Dependency Direction Without Ceremonyp. 52
  9. 9Domain-Driven Mobile Boundariesp. 58
  10. 10State Ownership and Unidirectional Flowp. 64
  11. 11The Pattern Laboratoryp. 70
  12. 12Navigation, Lifecycle, and Restorationp. 75
  13. 13Dependencies, Composition, and Injectionp. 80
  14. 14Swift Concurrency as Architecturep. 87
  15. 15Kotlin Coroutines as Architecturep. 93
  16. 16Process Death, Background Work, and Timep. 99
  17. 17Data Authority and Repository Designp. 106
  18. 18Local Data, Cache, and Freshnessp. 112
  19. 19Offline-First Is a Product Decisionp. 117
  20. 20Building a Sync Enginep. 124
  21. 21Conflicts, Idempotency, and Reconciliationp. 132
  22. 22Schema Evolution and Version Skewp. 140
  23. 23Real-Time and Event-Driven Mobilep. 148
  24. 24Feature-Based Modularisationp. 156
  25. 25Designing the Module Graphp. 162
  26. 26When Modularisation Goes Wrongp. 169
  27. 27Team Topologies and Ownershipp. 175
  28. 28Build Architecture and Feedback Loopsp. 181
  29. 29Mobile Platform Engineeringp. 189
  30. 30Cross-Platform with Escape Hatchesp. 196
  31. 31SDK Architecture and Compatibilityp. 203
  32. 32Migrating Legacy Mobile Systemsp. 210
  33. 33Testing the Failure Modelp. 217
  34. 34Performance as an Architecture Characteristicp. 224
  35. 35Observability, Reliability, and Field Truthp. 231
  36. 36Security, Privacy, and Trust Boundariesp. 239
  37. 37Accessibility, Adaptivity, and Device Diversityp. 247
  38. 38Release Architecturep. 254
  39. 39Feature Flags, Experiments, and Kill Switchesp. 262
  40. 40Server-Driven UI and Remote Experiencesp. 269
  41. 41The AI-Native Mobile Stackp. 277
  42. 42On-Device, Cloud, and Hybrid Routingp. 285
  43. 43Context, Memory, RAG, and Multimodalityp. 293
  44. 44Agentic Apps, Permissions, and Toolsp. 300
  45. 45Offline AI, Model Lifecycle, and Evaluationp. 308
  46. 46Architecture Reviews That Workp. 318
  47. 47Fitness Functions, Governance, and Debtp. 324
  48. 48Influence, RFCs, and Architecture Roadmapsp. 330
  49. 49Incident-Led Architecturep. 336
  50. 50Mobile System Design Interviewsp. 342
  51. 51Designing Systems That Can Be Replacedp. 348
  52. 52Atlas: From Prototype to Platformp. 355
  53. 53The Offline Field Operationp. 365
  54. 54The Global Checkoutp. 372
  55. 55The Messaging Systemp. 379
  56. 56The Regulated Finance Appp. 386
  57. 57The Cross-Platform Rewritep. 393
  58. 58The AI Trip Operatorp. 399
  59. 59The Mobile Platform Programp. 404
  60. 60The Agent in the Engineering Loopp. 409
  61. 61The Imposed Decisionp. 416
  62. Appendix A. Mobile Architecture Decision Canvasp. 426
  63. Appendix B. ADR Libraryp. 433
  64. Appendix C. Architecture Review Rubricp. 442
  65. Appendix D. Migration Playbooksp. 448
  66. Appendix E. Testing and Failure Catalogp. 454
  67. Appendix F. Performance and Reliability Budgetsp. 460
  68. Appendix G. Security and Privacy Checklistp. 477
  69. Appendix H. Staff+ Interview Bankp. 482
  70. Appendix I. Glossaryp. 488

Mobile architecture books: where Controlled Change fits

Most architecture material begins in a clean room: the requirements are legible, the network responds, the database is empty and the team agrees. Controlled Change starts from what makes mobile different: old client versions still running, app-store review, operating-system generations, and releases that cannot be recalled like a server deployment.

It is a book about architectural judgement, not an implementation encyclopedia, a framework manual or a catalog of universal patterns. It assumes you can already build and ship a mobile app, and begins where judgement becomes the harder problem.

Which of my architecture books do you need?

Three books, three different jobs.

  1. Mobile System Design Blueprint. Practice. 20 decision chapters, 12 system scenarios and 50 exercises with answer keys, for rehearsing the decisions behind evolving, migrating, releasing and operating mobile systems.
  2. Altitude. Staff systems beyond the app. 556 pages and 30 chapters on backend contracts and BFFs, security and identity, observability, cloud and incidents, with the app as one node in a larger system.
  3. Controlled Change. The architecture inside the app, across its whole life. 505 pages and 61 chapters plus appendices A to I on boundaries, state ownership, offline sync, version skew, modularisation, release control and AI on mobile.

MVVM, MVI, TCA, Redux, VIPER and RIBs, compared not crowned

Chapter 11, the pattern laboratory, runs the same Atlas checkout through several patterns and compares the cost of change: direct state, MVVM, MVI, Redux, The Composable Architecture, VIPER, RIBs and Workflow. For each one the question is the same: what pressure does it answer, what does it cost, and what signal says it no longer pays.

None is presented as a destination. Direct state is treated as an appropriate starting point with an explicit extraction trigger, not as amateur architecture.

Where this shows up on salari.dev

Free articles on this site that point to Controlled Change as the place to go deeper.

Early reader reviews

Five engineers with 5 to 15 years of experience in iOS, Android, frontend, mobile, staff and tech lead roles are reading it now. Their reviews appear here in their own words as they arrive.

Read the sample while you wait

Who this is for

This is for you ifyou can build the app; the hard part now is deciding which boundary is worth its cost and changing a live system without losing control.

  • You can already build a mobile app: you have shipped features, fixed the crash, argued about MVVM in a pull request.
  • You decide which boundary is worth its cost, and which migration can run without stopping the release train.
  • You want decisions that will still be defensible in three years, when the person who made them has left.
  • You are a Staff or Principal mobile engineer, a mobile architect, a platform lead, or the engineering manager who funds their decisions.

Not for

  • Engineers learning their first architecture
  • Anyone looking for a code walk-through that teaches dependency injection from scratch
  • Anyone looking for a folder template to copy
  • Anyone who wants one framework crowned as the answer
The library pathWhere this fits
  1. 01Get foundThe Silent Rejection
  2. 02Build the record and negotiateThe iOS Engineer Playbook · Leverage
  3. 03InterviewThe iOS Interview Blueprint · The Senior Signal · Top 300 React Native Interview Questions · The Flutter Interview Book · The Senior SDET Interview Handbook
  4. 04Answer practice and live roundsThe 24-Hour iOS Interview Answer Book · The 24-Hour Android Interview Answer Book · Share Your Screen
  5. 05Architecture and qualitySwiftUI Under Load · Mobile System Design Blueprint · Security Is a Feature · The Second Pass
  6. 06Staff systems and ownershipAltitude · Ticket Taker, Outcome Owner
  7. 07Build with AIBuild With Your Brain On (coming soon) · Engineering Software with Coding Agents
  8. 08LeadBefore the Room
  9. 09ArchitectControlled ChangeYou are here
Portrait of Mike Salari

About the author

Mike Salari

Staff mobile engineer · 500+ technical interviews from the hiring side.

I have spent 15 years in mobile and sat through 500+ technical interviews from the hiring side. At staff level the strong answers do not name the most patterns. They say which boundary is worth its cost, what it costs, and what evidence would change the decision. I wrote this book for the engineer who holds that decision.

15 years building production mobile software, with experience across Apple, Adobe, Cisco, Mastercard and Visa.

Read the full story

Before or after you buy

FAQ

Controlled Change: questions before you buy

What is Controlled Change about?

Controlled Change is a 505-page, 61-chapter book on mobile architecture for staff and principal mobile engineers, mobile architects and platform leads. It treats Clean Architecture, MVVM, MVI, Redux, TCA, VIPER, RIBs and feature modules as responses to pressure, not destinations, and is written in pressure order around Atlas, a fictional marketplace app.

What is the difference between Book, Pro and Extended?

Book is the book alone, PDF and EPUB with lifetime updates. Pro is the book with the Atlas reference system: native iOS and Android, Kotlin Multiplatform, backend and contract code. Extended adds React Native, Flutter and the sync simulator that injects duplicate events, reordered writes, process death and model failure.

Does it cover AI on mobile?

Yes. Part VI covers on-device, cloud and hybrid routing, context and RAG, agents and tools, and model lifecycle and evaluation.

Is Controlled Change an iOS or an Android architecture book?

Both. The iOS and Android implementations stay native where platform mechanics matter, and Swift concurrency and Kotlin coroutines each get a chapter. Kotlin Multiplatform, React Native and Flutter are treated as boundaries of shared code, in a chapter on cross-platform with escape hatches and a casebook chapter on a cross-platform rewrite.

Does it cover offline-first and sync?

Yes. Part III, Data under failure, covers process death and background work, data authority, cache and freshness, offline-first as a product decision, building a sync engine, conflicts, idempotency and reconciliation, schema evolution and version skew, and real-time events.

How is it different from Mobile System Design Blueprint and Altitude?

Mobile System Design Blueprint is practice: decision chapters, system scenarios and exercises with answer keys. Altitude is staff systems beyond the app: backend contracts, security, observability and incidents. Controlled Change is the architecture decisions inside the app across its whole life.

Is it for beginners?

No. It assumes you can already build and ship a mobile app, and starts where architectural judgement becomes the harder problem.

Share this book