Mobile App Architecture: [App name]
Architecture document for a mobile application: platforms and
development approach, app architecture pattern, modules, networking and
offline sync, local storage and encryption, push notifications,
authentication, analytics and privacy, performance targets, release
management (store review, phased rollout, forced update), crash
reporting and testing. Based on common industry practice and the
published platform guidance from Apple and Google. Replace every
[bracketed] value and every row marked Example; the examples follow
a field-service app used by technicians with poor connectivity.
| Field | Value |
|---|
| Document ID | [MOB-ARCH-001] |
| App | [Name, bundle ID / application ID] |
| Version | [0.1] |
| Status | [Draft / In review / Approved] |
| Owner | [@mobile-lead] |
| Reviewers | [@architect], [@security], [@backend-lead] |
| Last updated | YYYY-MM-DD |
| Related | [API specification], [Design system], [Privacy assessment], [ADRs] |
1. Context and drivers
| Item | Value |
|---|
| Users | Example: 3,500 field technicians; 40,000 customers using the booking feature |
| Devices | Example: Company Android rugged devices (Android 12+), personal iPhones (iOS 17+) |
| Connectivity | Example: Often offline in basements and rural sites for up to 8 hours |
| Key journeys | View job list, complete checklist, capture photos and signature, sync |
| Key requirements | Full offline job completion; no data loss; photos up to 30 per job |
| ID | Driver | Target |
|---|
| MOB-01 | Example: Offline completion of a job | 100% of job steps work without network |
| MOB-02 | Example: Data safety | Zero lost job records; sync conflicts resolved without user data loss |
| MOB-03 | Example: Time to release a fix | Critical fix in users' hands within 48 h |
| [MOB-nn] | [Driver] | [Target] |
2. Platforms and development approach
| Option | Strengths | Weaknesses | Fit |
|---|
| Native (Swift / Kotlin) | Best platform fidelity and API access; best performance | Two codebases and teams | Example: Medium |
| Cross-platform with native rendering (for example Flutter, React Native) | One codebase for most UI and logic | Bridge or engine overhead; native modules still needed | Example: High |
| Shared logic only (for example Kotlin Multiplatform) | Shared domain and data layers; native UI | Two UI codebases | Example: Medium |
| Web or PWA | One codebase; no store review | Limited background sync and device APIs on iOS | Low for offline-heavy use |
Decision: [approach, framework and version policy, ADR link]. Example:
cross-platform framework for UI and logic, with native modules for the
barcode scanner and background upload; minimum OS versions iOS 17 and
Android 12 (ADR-014).
3. App architecture pattern and modules
Pattern: [e.g. MVVM with Clean Architecture layers]. Dependencies point
inwards: UI depends on view models, view models on use cases, use cases
on repository interfaces; data sources implement those interfaces.
| Module | Responsibility | Owner |
|---|
core-domain | Example: Entities, use cases, validation rules | [@team] |
core-data | Repositories, local database, API client, sync engine | [@team] |
feature-jobs | Job list and job detail screens | [@team] |
feature-checklist | Checklists, photos, signature | [@team] |
platform-services | Camera, location, push, secure storage wrappers | [@team] |
design-system | Tokens and shared components | [@team] |
| [module] | [Responsibility] | [@team] |
4. Networking and offline sync
| Topic | Design |
|---|
| API style | Example: REST over HTTPS via the mobile BFF; JSON; gzip |
| Timeouts and retries | Connect 10 s, read 30 s; exponential backoff with jitter; retry only idempotent calls or calls with an idempotency key |
| Offline model | Local database is the source for the UI; writes go to local database and an outbound sync queue |
| Sync trigger | On connectivity change, app foreground, and background task every 15 min where the OS allows |
| Download | Delta sync using updated_since cursor; jobs for the next 3 days pre-fetched |
| Upload | Queue processed in order per job; photos uploaded in chunks with resume |
| Conflict resolution | Example: Server wins for job assignment; field-level merge for checklist answers; user prompted only when the same answer differs |
| Certificate handling | System trust store; certificate pinning considered and rejected because of rotation risk (ADR-016) |
5. Local storage and encryption
| Data | Store | Protection | Retention |
|---|
| Example: Jobs, checklists | SQLite database | Encrypted with a key held in Keychain or Android Keystore | Deleted 7 days after sync |
| Example: Photos | App sandbox files | File protection class "complete until first user authentication" (iOS); encrypted file API (Android) | Deleted after confirmed upload |
| Example: Tokens | Keychain / Keystore | Hardware-backed where available | Until logout or expiry |
| Example: Preferences | Platform preferences | Not sensitive | App lifetime |
Rules: no personal or business data in logs; screenshots blocked on
screens with customer data where policy requires; remote wipe of app data
on device unenrolment through mobile device management.
6. Push notifications
| Topic | Design |
|---|
| Providers | APNs (iOS) and Firebase Cloud Messaging (Android) via [notification service] |
| Payload | Example: Notification text plus job ID; no customer data in payload |
| Permission | Requested in context after the first job assignment, not at first launch |
| Deep links | app://jobs/{id} handled by router; verified universal links / app links for web URLs |
| Silent pushes | Used to trigger sync; app tolerates them being throttled by the OS |
| Token management | Registered at login; removed at logout; refreshed on change |
7. Authentication and authorisation
| Topic | Design |
|---|
| Flow | Example: OAuth 2.0 authorisation code with PKCE in the system browser (ASWebAuthenticationSession, Custom Tabs) |
| Tokens | Short-lived access token (15 min); refresh token rotated on use, stored in secure storage |
| Offline | App usable offline for up to 72 h after last successful refresh; then re-authentication required |
| Device unlock | Optional biometric unlock of the local session |
| Authorisation | Enforced by the API; app hides actions the role cannot perform |
8. Analytics and privacy
| Topic | Design |
|---|
| Events collected | Example: Screen views, sync success and failure, job completion time; no free text, no location trails |
| Consent | Analytics off until consent where required; choice changeable in settings |
| Tracking | No cross-app tracking; App Tracking Transparency prompt therefore not needed |
| Store declarations | Apple privacy nutrition labels and Google Play Data safety form updated with every change to data collection |
| Privacy manifest | iOS privacy manifest lists required-reason APIs and SDKs |
| Third-party SDKs | Allow-list reviewed for data collection; versions pinned |
9. Performance targets
| Metric | Target | Measured on |
|---|
| Cold start to interactive | Example: p90 <= 2.0 s | Low-end supported Android device |
| Screen transition | p90 <= 300 ms | Both platforms |
| Frame rendering | < 1% slow frames on job list | Both platforms |
| Crash-free sessions | >= 99.8% | Production |
| ANR rate (Android) | Below Google Play's bad-behaviour threshold; Example: internal target 0.2% | Android vitals |
| App download size | <= 40 MB | Store listing |
| Full sync of 3 days of jobs | <= 20 s on 4G | Field test |
10. Release management
| Topic | Design |
|---|
| Cadence | Example: Every two weeks; release branch cut on Monday |
| Store review | Submit 3 working days before target date; expedited review only for critical fixes |
| Phased rollout | iOS phased release over 7 days; Google Play staged rollout 5%, 20%, 50%, 100% |
| Rollout gates | Halt if crash-free sessions fall below 99.5% or sync failure rate doubles |
| Feature flags and remote config | New features shipped dark and enabled remotely; kill switch per feature |
| Forced update | Backend returns minimum supported version; app shows blocking update screen below it, soft prompt below recommended version |
| API compatibility | Backend supports the last 3 app versions or 90 days, whichever is longer |
| Signing | Keys held in CI secrets and platform signing services; access limited to release managers |
11. Crash reporting and monitoring
| Topic | Design |
|---|
| Crash reporting | Example: [Crash reporting SDK] with dSYM and mapping file upload in CI |
| Non-fatal errors | Sync failures and API errors reported with error code and app version |
| Personal data | Scrubbed from breadcrumbs and logs before sending |
| Alerting | New crash cluster affecting > 0.1% of sessions pages the mobile on-call |
| Triage | Daily during rollout; weekly otherwise |
12. Testing
| Layer | Scope | Tooling | When |
|---|
| Unit | Use cases, view models, sync logic | Example: Platform unit test frameworks | Every pull request |
| Integration | Repositories with local database and mocked API | Test containers or mock server | Every pull request |
| UI | Key journeys | Platform UI testing frameworks | Nightly |
| Device matrix | 8 devices covering min OS, small screens, low memory | Device cloud | Before release |
| Offline and sync | Airplane mode, flaky network, conflicts | Network conditioner and scripted scenarios | Before release |
| Upgrade | Install previous version, create data, upgrade | Scripted | Before release |
| Accessibility | Screen readers, dynamic type, contrast | VoiceOver, TalkBack, scanners | Each release |
Standard and licence note
Based on common industry practice for mobile application architecture and
on public platform guidance from Apple and Google (store review,
phased or staged rollout, privacy declarations). Store policies and
thresholds change; check the current versions before each release.
Original text written for this collection; examples are illustrative and
not legal advice. Template licence: MIT.