Mobile Architecture

Mobile Architecture

When to use

Invoke after architecture/system-design has approved a product that includes a native or cross-platform-native mobile application, and before implementations/mobile/<ecosystem> skills generate platform code. Covers iOS, Android, cross-platform-native (React Native / Flutter / KMP), hybrid, tablet/foldable, and companion apps.

Do not use when the product has no mobile client, for pure backend architecture (use backend-architecture), for mobile-web or PWA (use frontend-architecture), for UI or visual design (use frontend-design), for vendor-specific SDK implementation, or when the architecture is finalized and only implementation remains.

Inputs

Required:

• Approved system-design.md and the relevant ADRs.
• Mobile product requirements and the primary user journeys.
• Supported platforms and minimum OS versions.
• Performance and offline expectations.

Optional:

• Backend / API contracts; identity and session model.
• Design system or UX guidelines; accessibility requirements.
• Analytics, notification, and device-capability requirements.
• Security / compliance constraints; release cadence; regional constraints.
• The product's frontend-architecture.md (optional, non-binding cross-reference for shared concerns).

Operating rules

• Treat the mobile app as a constrained distributed system: assume unreliable networks, intermittent connectivity, limited battery, and abrupt termination; design for recovery and resumability.
• Architect before choosing native vs cross-platform-native vs hybrid; the platform-target decision is an ADR, not a prescription, and is never defaulted to cross-platform without evaluating UX, startup, memory, animation, offline, and native-API trade-offs.
• Define device/backend state ownership explicitly; navigation, state, sync, and caching are first-class architectural concerns.
• Minimize background work unless product-critical; define degraded behavior explicitly for every critical journey.
• Native platform conventions take precedence over framework convenience; accessibility and responsiveness are mandatory architectural qualities.
• Mobile security/privacy and release/operations are callouts here, not owned: summarize the mobile-specific concern and raise an ADR candidate against system-design; ownership stays with security and operations/infrastructure-platform.
• No device feature without measurable user value; no premature optimization for unsupported platforms; no vendor SDK detail unless it materially changes architecture behavior.
• Mobile-web/PWA is out of scope and belongs to frontend-architecture.

Output contract

mobile-architecture.md MUST conform to standards/architecture-schema, which is authoritative for its frontmatter, the 18-section required/conditional structure, conditional-omission rules, the §9/§15 callout framing, and system-design.md traceability. Skill structure conforms to documentation-standards. Use assets/mobile-architecture.template.md as the scaffold. The artifact is independently valid without a frontend-architecture.md; cross-references to it are optional and non-binding.

Progressive references

• Read references/mobile-architecture-playbook.md when defining any owned area or checking the anti-pattern list.
• Read references/mobile-architecture-quality-rubric.md before finalizing and use it as the validation checklist.
• Use assets/mobile-architecture.template.md for mobile-architecture.md.

Process

ADR candidates are drafted inline as decisions are made (notably the platform-target decision and the §9/§15 callouts). The final step consolidates them; it does not retrofit ADRs from prose.

• Step 1: Load system-design.md and relevant ADRs. Identify mobile surfaces, user journeys, supported platforms, device capabilities, network/session assumptions, and operational constraints; mark latency-sensitive and offline-sensitive flows.
• Step 2: Decide platform strategy (native vs cross-platform-native vs hybrid). Document rationale, trade-offs, unsupported scenarios, minimum OS, device classes, tablet/foldable behavior. Draft an ADR candidate for the platform-target decision.
• Step 3: Define application architecture: layers, module boundaries, dependency ownership, feature isolation, shared services, state ownership, side-effect handling, concurrency model, lifecycle, dependency injection. Avoid over-abstraction beyond current platform scope.
• Step 4: Define navigation architecture: hierarchy, route ownership, deep-link handling, modal strategy, auth transitions, tab/shell architecture, back-navigation and state restoration after interruption.
• Step 5: Define state management: local UI, session, cached remote, persistent storage, synchronization ownership, optimistic updates, conflict resolution, rollback, stale-data handling, cache expiration.
• Step 6: Define offline & synchronization architecture: offline capabilities, sync model, queueing, retry, conflict resolution, authoritative sources, reconciliation; state explicitly what works offline, what partially works, and what fails gracefully.
• Step 7: Define device-capability integration: per capability state permission strategy, fallback behavior, privacy expectations, battery impact, failure handling, and platform-specific limits.
• Step 8: Define performance & battery budgets: cold/warm start, transition latency, interaction responsiveness, memory, background execution, battery, network, storage growth; degradation under low memory, poor connectivity, thermal throttling, and battery-saver.
• Step 9: Security & privacy callouts: summarize mobile-specific auth/token/secure-storage/jailbreak/encryption concerns and draft ADR candidates. Defer ownership to security; do not produce an owned security design here.
• Step 10: Define accessibility & localization: screen-reader support, dynamic text, reduced motion, color contrast, RTL, font scaling, internationalization. Accessibility failures are architectural failures.
• Step 11: Define notifications & background behavior: push types, delivery expectations, priority classes, background refresh, routing, opt-in, rate-limiting, silent notifications. No background execution without measurable user value.
• Step 12: Define error handling & recovery: global error strategy, retry ceilings, crash recovery, interrupted-session handling, partial-failure behavior, degraded-mode UX.
• Step 13: Define observability & analytics: crash reporting, performance telemetry, network tracing, journey/screen analytics, startup and battery telemetry, release monitoring, logging policy, PII redaction, sampling, retention.
• Step 14: Define testing strategy: unit/integration/UI-automation/offline/device-compat/accessibility/performance-regression scope, emulator vs physical-device expectations, release gating, rollback validation.
• Step 15: Release & operations callouts: summarize channels, staged rollout, store submission, forced-upgrade, deprecation as ADR candidates. Defer ownership to operations / infrastructure-platform.
• Step 16: Define the failure taxonomy: startup, network, sync conflict, rendering degradation, termination, permission denial, notification failure, API incompatibility, storage exhaustion, background failure; per failure define detection, mitigation, recovery, observability, and user-facing behavior.
• Step 17: Generate mobile-architecture.md from assets/mobile-architecture.template.md. Consolidate ADR candidates (numbering, status, alternatives, downsides). Validate against standards/architecture-schema and references/mobile-architecture-quality-rubric.md; revise until both pass or explicitly note any unresolved gap.

Outputs

Required:

• mobile-architecture.md at docs/architecture/<product-slug>/mobile-architecture.md, with frontmatter and the 18-section structure per standards/architecture-schema.

Optional, when applicable:

• Navigation diagrams; state-ownership maps; offline-sync diagrams; notification-routing diagrams.
• Performance-budget tables; failure-mode matrices; ADR drafts.

Output rules:

• Keep the architecture decision-oriented and user-impact focused, not framework-decorative.
• Document tradeoffs and the rejected alternative, not only the chosen path.
• Keep security/privacy and release/operations as callouts and ADR candidates, never owned designs.
• No vendor SDK detail unless it materially changes architecture behavior.

Quality checks

• references/mobile-architecture-quality-rubric.md was loaded before finalizing.
• mobile-architecture.md validates against standards/architecture-schema: frontmatter complete; required sections present; conditional sections present with content or listed under ## Omitted sections with rationale.
• Platform strategy records rationale and trade-offs as an ADR candidate.
• Navigation ownership and state-restoration behavior are defined.
• State ownership and synchronization rules are explicit.
• Offline behavior is defined for every critical user journey.
• Device-capability usage names a permission strategy, privacy posture, and fallback.
• Performance and battery budgets state measurable targets and degradation behavior.
• Accessibility posture is explicitly documented.
• Notification and interruption policies are documented.
• Error handling and degraded behavior are defined.
• Observability includes crash, latency, and release telemetry with PII redaction.
• Testing covers offline, accessibility, and device compatibility.
• Security/privacy and release/operations appear only as callouts / ADR candidates, not owned designs.
• No vendor SDK implementation detail appears unless it materially changes architecture behavior.

References

• Upstream: architecture/system-design.
• Related: backend-architecture, security (mobile security callouts), operations / infrastructure-platform (release/signing callouts), performance, quality-engineering, frontend-architecture (optional shared cross-reference; mobile-web/PWA boundary).
• Downstream implementation skills: future implementations/mobile/<ecosystem> (e.g. ios, android, cross-platform).