# 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.

<!--
Guidance: How to use this template
- Start with users, devices and connectivity (section 1). Offline needs
  and the device range drive most mobile architecture decisions.
- Remember that you cannot roll back a release on users' phones. Design
  for remote configuration, feature flags and a forced-update path before
  the first release.
- Keep platform-specific code at the edges (UI, platform services) and
  shared logic in the core, whichever approach you choose.
- Review store policies and platform privacy rules at each major release;
  they change yearly.
-->

| 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

<!-- Guidance: Describe users, devices, connectivity and the requirements that shape the architecture. Use numbers from analytics or research. -->

| 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

<!-- Guidance: Compare native and cross-platform options against your drivers. Consider team skills, needed device APIs and UI fidelity. -->

| 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

<!-- Guidance: Choose a pattern (MVVM, Clean Architecture, MVI) and describe the layers and the dependency rule. Then list modules and their owners. -->

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.

```mermaid
flowchart TD
    UI["UI screens"] --> VM["View models (state, events)"]
    VM --> UC["Use cases (domain)"]
    UC --> RI["Repository interfaces"]
    RP["Repositories (data)"] --> RI
    RP --> LDB["Local database"]
    RP --> API["Remote API client"]
    RP --> SQ["Sync queue"]
```

| 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

<!-- Guidance: Describe the API style, how requests behave on poor networks, and the sync model including conflict resolution. This is the hardest part of most offline-capable apps. -->

| 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

<!-- Guidance: List what is stored on the device, where, how it is protected, and when it is deleted. Treat lost or stolen devices as a normal event. -->

| 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

<!-- Guidance: Describe providers, payload rules, permission strategy and how notifications are routed into the app. -->

| 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

<!-- Guidance: Use the system browser for sign-in with OAuth 2.0 and PKCE; describe session lifetime and offline behaviour. -->

| 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

<!-- Guidance: Collect the minimum, honour consent and platform rules, and keep store privacy declarations in sync with what the app actually does. This is a design summary, not legal advice. -->

| 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

<!-- Guidance: Set measurable targets on representative low-end devices, and monitor them in production. -->

| 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

<!-- Guidance: Plan for store review time, staged rollout, monitoring gates and a forced-update mechanism. You cannot hot-fix compiled code on devices. -->

| 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

<!-- Guidance: Describe crash and error collection, symbol upload, alerting and triage. -->

| 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

<!-- Guidance: Define test layers, device coverage and how offline and upgrade paths are tested. -->

| 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.