Use when a product requires native or cross-platform-native mobile application architecture after an approved system design and before mobile implementation begins. Produces platform strategy, application and navigation architecture, state and offline/sync design, device-capability integration, performance and battery budgets, accessibility and localization, notifications and background behavior, error handling, observability, testing strategy, failure taxonomy, and implementation handoffs. Do not use for mobile-web or PWA (use frontend-architecture), backend service design (use backend-architecture), UI or visual design (use frontend-design), vendor-specific SDK implementation, deep mobile security (use security), or store-release and signing depth (use operations or infrastructure-platform).
Use when a product requires native or cross-platform-native mobile application architecture after an approved system design and before mobile implementation begins. Produces platform strategy, application and navigation architecture, state and offline/sync design, device-capability integration, performance and battery budgets, accessibility and localization, notifications and background behavior, error handling, observability, testing strategy, failure taxonomy, and implementation handoffs. Do not use for mobile-web or PWA (use frontend-architecture), backend service design (use backend-architecture), UI or visual design (use frontend-design), vendor-specific SDK implementation, deep mobile security (use security), or store-release and signing depth (use operations or infrastructure-platform).
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.
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 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 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.
Outputs
Required:
mobile-architecture.md at docs/architecture/<product-slug>/mobile-architecture.md, with frontmatter and the 18-section structure per standards/architecture-schema.
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.
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.
