# App Architecture

> Design mobile app architecture — navigation patterns, state management, data layer, and module boundaries

- Skill: `uitbreidenos/app-architecture` (Agent Skill)
- Install (CLI): `npx skillmds@latest add uitbreidenos/app-architecture`
- Raw SKILL.md: https://api.skillmd.com/api/skills/uitbreidenos/app-architecture/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: UitbreidenOS (https://skillmd.com/u/uitbreidenos)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/uitbreidenos/app-architecture

---


## When to activate

- Designing navigation structure for a new mobile app
- Choosing state management approach (Redux, Zustand, Riverpod, etc.)
- Defining data layer architecture (API clients, caching, persistence)
- Setting up module boundaries and feature-based folder structure
- Migrating from monolithic to modular architecture

## When NOT to use

- For backend API architecture (use API Developer Stack)
- For web app architecture
- For UI component design (framework-specific skills)

## Instructions

1. **Define app complexity tier.** Simple (1-5 screens), Medium (5-20 screens, 2-3 features), Complex (20+ screens, deep linking, offline).
2. **Choose navigation pattern.** Stack (simple), Tab + Stack (medium), Drawer + Tab + Stack (complex). Map user flows.
3. **Select state management.** Local state for UI, global store for shared data, server state for API. Match to framework (Zustand/Redux for RN, Riverpod/Bloc for Flutter, @Observable for SwiftUI).
4. **Design data layer.** Repository pattern: API client → cache (in-memory + persistent) → repository → view model → UI.
5. **Define module boundaries.** Feature-based folders: `features/auth/`, `features/feed/`, `features/profile/`. Shared: `core/`, `shared/ui/`, `shared/utils/`.
6. **Plan deep linking.** Map URL schemes to screens: `app://profile/123` → ProfileScreen(userId: "123").
7. **Document architecture decisions.** ADRs for each major choice with alternatives considered.

## Example

```
Architecture Decision: Medium-complexity e-commerce app

Navigation: Bottom tabs (Home, Search, Cart, Profile) + Stack per tab
State: Zustand (global: cart, auth) + React Query (server: products, orders)
Data: API client (axios) → React Query cache → MMKV persistence
Modules:
  features/auth/     — Login, register, forgot password
  features/catalog/  — Product list, detail, search
  features/cart/     — Cart, checkout, payment
  features/profile/  — Account, orders, settings
  core/              — Navigation, theme, i18n, analytics
  shared/            — UI components, utils, types
```