Mobile Architecture (React Native)

Mobile Architecture — Hexagonal in React Native

BINDING RULES FOR ALL AI AGENTS: The layer placement rules below are MANDATORY. domain/ and application/ MUST NOT import React, React Native, Expo, or any I/O library. Every outbound dependency (storage, HTTP, push, clock, randomness) MUST go through a port. Violations of dependency direction are NEVER acceptable. Cross-cutting concerns (caching, retry, analytics, logging) MUST be implemented as decorator adapters, not sprinkled into use cases.

Decisions: every architecturally significant choice (port shape, adapter technology, state management library, navigation strategy, offline/sync topology, module boundary change) MUST be captured as an ADR per adr.md before merging. Default template = MADR. Default location = docs/adr/.

Project-agnostic: this guide describes patterns, not a specific app. Samples use a placeholder Expense domain. Replace with your actual domain.

Companion commands: /mobile-init-project (scaffold), /mobile-scaffold-feature (full vertical slice), /mobile-add-usecase, /mobile-add-adapter (port + adapter + boundary parsing).

This is the mobile counterpart of hexagonal-architecture.md. The rules are the same; only the language and the adapter technologies change. For the JVM equivalents of these patterns see hexagonal-architecture.md; for TypeScript conventions see typescript-code-style.md.

1. When to use this architecture

Hexagonal is not free. Apply the decision matrix before adopting it.

The deciding question is: does this app own rules that would still be true if the UI disappeared? If yes, those rules deserve a domain/ that never imports React.

Record the answer as an ADR. Do not re-litigate it per feature.

2. Layer rules (MEMORIZE)

Dependencies always point inward: ui → application → domain. Adapters in infrastructure point inward too — they implement interfaces that application owns.

Zod is the one allowed exception in domain: schemas that express domain invariants may live there. Everything else parses at the boundary (§7).

3. Folder layout

1
src/
2
├── domain/                     Pure TypeScript. Zero framework.
3
│   ├── expense/
4
│   │   ├── Expense.ts          entity / value objects
5
│   │   ├── Money.ts            value object with invariants
6
│   │   └── ExpenseError.ts     domain error union
7
│   └── shared/
8
│       ├── Result.ts           Result<T, E>
9
│       └── brand.ts            branded primitive types
10
│
11
├── application/                Use cases + ports. Zero React.
12
│   ├── expense/
13
│   │   ├── createExpense.ts        use case
14
│   │   ├── listExpenses.ts
15
│   │   └── port/
16
│   │       ├── ExpenseRepository.ts    outbound port
17
│   │       └── ExpenseApi.ts
18
│   └── port/
19
│       ├── Clock.ts            inbound-of-time; never call Date.now() directly
20
│       ├── IdGenerator.ts
21
│       ├── Analytics.ts
22
│       └── Logger.ts
23
│
24
├── infrastructure/             Adapters. Libraries live here and ONLY here.
25
│   ├── storage/
26
│   │   └── MmkvExpenseRepository.ts
27
│   ├── http/
28
│   │   ├── client.ts
29
│   │   └── HttpExpenseApi.ts
30
│   ├── secure/
31
│   │   └── SecureStoreTokenStore.ts
32
│   ├── decorator/
33
│   │   ├── CachedExpenseRepository.ts
34
│   │   └── LoggedExpenseRepository.ts
35
│   └── di/
36
│       └── container.ts        the ONLY place that wires concretes
37
│
38
├── ui/                         React Native lives here and ONLY here.
39
│   ├── feature/
40
│   │   └── expense/
41
│   │       ├── ExpenseListScreen.tsx
42
│   │       ├── ExpenseListScreen.test.tsx
43
│   │       └── component/
44
│   ├── hook/
45
│   │   └── useCreateExpense.ts    bridges React ↔ use case
46
│   ├── design/                    tokens + primitives — see mobile-ui.md
47
│   └── navigation/
48
│
49
└── app/                        Expo Router route files. Thin. Re-export screens.

Feature-first inside each layer, not layer-first inside each feature. A developer touching “expense” opens four folders, but each one has a single, obvious responsibility. The alternative — components/, hooks/, utils/, services/ — is the anti-pattern this architecture exists to prevent.

Co-locate tests next to the file under test. Expense.ts and Expense.test.ts are siblings.

4. Domain layer

Pure TypeScript. If a file in domain/ needs a mock to be tested, it is in the wrong layer.

Entities and value objects

Immutable. Construct through a factory that validates, never through a bare object literal.

1
import type { Result } from '../shared/Result'
2
import { ok, err } from '../shared/Result'
3

4
const SCALE = 2
5

6
export type Money = Readonly<{
7
  readonly _tag: 'Money'
8
  amountMinor: number      // integer minor units. NEVER a float.
9
  currency: Currency
10
}>
11

12
export type MoneyError = { kind: 'NotAnInteger' } | { kind: 'Negative' }
13

14
export function money(amountMinor: number, currency: Currency): Result<Money, MoneyError> {
15
  if (!Number.isInteger(amountMinor)) return err({ kind: 'NotAnInteger' })
16
  if (amountMinor < 0) return err({ kind: 'Negative' })
17
  return ok({ _tag: 'Money', amountMinor, currency })
18
}
19

20
export function add(a: Money, b: Money): Result<Money, CurrencyMismatch> {
21
  if (a.currency !== b.currency) return err({ kind: 'CurrencyMismatch', a: a.currency, b: b.currency })
22
  return money(a.amountMinor + b.amountMinor, a.currency)
23
}

Never represent money as a float. 0.1 + 0.2 !== 0.3 in IEEE 754. Store minor units as integers, or use a decimal library — never number for a decimal amount.

Branded types over primitives

1
declare const brand: unique symbol
2
export type Brand<T, B extends string> = T & { readonly [brand]: B }
3

4
// domain/expense/Expense.ts
5
export type ExpenseId = Brand<string, 'ExpenseId'>
6
export type UserId    = Brand<string, 'UserId'>

Now createExpense(userId, expenseId) fails to compile if the arguments are swapped. With bare string it silently ships.

Domain errors are values, not exceptions

1
export type ExpenseError =
2
  | { kind: 'AmountTooLarge'; max: number }
3
  | { kind: 'CategoryUnknown'; category: string }
4
  | { kind: 'DateInFuture'; date: string }

A discriminated union forces the caller to handle every case, and switch exhaustiveness is checked at compile time. A throw inside a hook is invisible until production. See typescript-code-style.md §Errors.

Forbidden in domain/

• ❌ import ... from 'react' / 'react-native' / 'expo-*'
• ❌ Date.now(), new Date(), Math.random() — inject Clock and IdGenerator instead. Non-determinism makes tests flaky and time-zone bugs invisible.
• ❌ fetch, AsyncStorage, MMKV, any I/O
• ❌ console.log — inject Logger
• ❌ throw for expected business outcomes

5. Application layer

Use cases

A use case is a plain function. It takes its dependencies as an argument, orchestrates the domain, and returns a Result. No classes needed, no decorators, no annotations.

1
import type { Result } from '../../domain/shared/Result'
2
import type { Expense, ExpenseError } from '../../domain/expense/Expense'
3
import { newExpense } from '../../domain/expense/Expense'
4
import type { ExpenseRepository } from './port/ExpenseRepository'
5
import type { Clock } from '../port/Clock'
6
import type { IdGenerator } from '../port/IdGenerator'
7

8
export type CreateExpenseCommand = Readonly<{
9
  amountMinor: number
10
  currency: Currency
11
  category: string
12
  note?: string
13
}>
14

15
export type CreateExpenseDeps = Readonly<{
16
  repository: ExpenseRepository
17
  clock: Clock
18
  ids: IdGenerator
19
}>
20

21
export function createExpense(deps: CreateExpenseDeps) {
22
  return async (command: CreateExpenseCommand): Promise<Result<Expense, ExpenseError>> => {
23
    const expense = newExpense({
24
      id: deps.ids.next(),
25
      occurredAt: deps.clock.now(),
26
      ...command,
27
    })
28
    if (!expense.ok) return expense
29

30
    return deps.repository.save(expense.value)
31
  }
32
}

Rules:

• Max 3 parameters — use a command object (see coding-style rules). deps and command is two.
• One use case per file. The file name is the use case name.
• No React. No useState. No hooks. A use case must be callable from a background task or a test with no renderer.
• No try/catch around business outcomes — return Result.

Ports

Ports are interfaces owned by application/, implemented by infrastructure/.

1
export interface ExpenseRepository {
2
  save(expense: Expense): Promise<Result<Expense, PersistenceError>>
3
  findById(id: ExpenseId): Promise<Expense | null>
4
  findByPeriod(period: Period): Promise<readonly Expense[]>
5
}

Naming:

• Outbound ports get the role name: ExpenseRepository, ExpenseApi, TokenStore, PushNotifier.
• Never name a port after its technology. MmkvExpenseRepository is an adapter; ExpenseRepository is the port. If the port name contains Mmkv, Http, Sqlite or Firebase, the abstraction has already leaked.

Always port these, even though they look trivial:

6. Infrastructure layer

Adapters implement ports. This is the only layer allowed to import libraries.

1
import type { MMKV } from 'react-native-mmkv'
2
import type { ExpenseRepository } from '../../application/expense/port/ExpenseRepository'
3
import { expenseSchema } from './schema'
4

5
// MMKV v4: the class is a type; instances come from createMMKV(). v3's `new MMKV()`
6
// and `.delete()` are gone — the methods are `remove()` and `clearAll()`.
7
export function mmkvExpenseRepository(storage: MMKV): ExpenseRepository {
8
  return {
9
    async save(expense) { /* ... */ },
10

11
    async findById(id) {
12
      const raw = storage.getString(`expense:${id}`)
13
      if (!raw) return null
14
      const parsed = expenseSchema.safeParse(JSON.parse(raw))
15
      return parsed.success ? parsed.data : null   // corrupt row → treat as missing
16
    },
17

18
    async findByPeriod(period) { /* ... */ },
19
  }
20
}

Persisted data is untrusted input. It was written by an older version of your app, possibly with a different shape. Parse it on read (§7). A schema migration you forgot becomes a crash loop that only a reinstall fixes — and users uninstall instead.

Cross-cutting concerns are decorators

Never put caching, retry, logging or metrics inside a use case. Wrap the port.

1
export function cached(inner: ExpenseRepository, cache: Cache): ExpenseRepository {
2
  return {
3
    ...inner,
4
    async findById(id) {
5
      const hit = cache.get(id)
6
      if (hit) return hit
7
      const found = await inner.findById(id)
8
      if (found) cache.set(id, found)
9
      return found
10
    },
11
  }
12
}

Compose in the container: cached(logged(mmkvExpenseRepository(storage)), cache). Same Chain of Responsibility rule as hexagonal-architecture.md.

The DI container

One file. Plain functions, no DI framework.

1
export function buildContainer(env: Env) {
2
  const storage  = createMMKV({ id: 'app' })
3
  const clock    = systemClock()
4
  const ids      = uuidGenerator()
5
  const logger   = env.isProduction ? sentryLogger() : consoleLogger()
6

7
  const expenseRepository = cached(logged(mmkvExpenseRepository(storage), logger), memoryCache())
8

9
  return {
10
    createExpense: createExpense({ repository: expenseRepository, clock, ids }),
11
    listExpenses:  listExpenses({ repository: expenseRepository }),
12
  } as const
13
}
14

15
export type Container = ReturnType<typeof buildContainer>

Exposed to React through a single Context at the root:

1
const ContainerContext = createContext<Container | null>(null)
2

3
export function useContainer(): Container {
4
  const c = useContext(ContainerContext)
5
  if (!c) throw new Error('useContainer must be used inside ContainerProvider')
6
  return c
7
}

This is the only place ui touches infrastructure. Tests swap the whole container for fakes in one line.

7. The boundary: parse, don’t validate

Everything crossing into the app is untrusted, regardless of what its TypeScript type claims. TypeScript does not exist at runtime.

Parse with Zod at the adapter, return domain types inward:

1
const responseSchema = z.object({
2
  id: z.string().uuid(),
3
  amount_minor: z.number().int(),
4
  currency: z.enum(['COP', 'USD', 'EUR']),
5
})
6

7
export function httpExpenseApi(client: HttpClient): ExpenseApi {
8
  return {
9
    async fetchById(id) {
10
      const raw = await client.get(`/expenses/${id}`)
11
      const parsed = responseSchema.safeParse(raw)
12
      if (!parsed.success) return err({ kind: 'ContractViolation', issues: parsed.error.issues })
13
      return ok(toDomain(parsed.data))
14
    },
15
  }
16
}

Never let a wire-format type (amount_minor, snake_case) leak past the adapter. Map to domain types at the edge. Same rule as the three-layer mapping chain in ports-and-commands.md.

8. UI layer

React Native lives only here. The UI’s job is rendering and gesture handling — nothing else.

Hooks bridge React and use cases

1
export function useCreateExpense() {
2
  const { createExpense } = useContainer()
3
  const queryClient = useQueryClient()
4

5
  return useMutation({
6
    mutationFn: createExpense,
7
    onSuccess: () => queryClient.invalidateQueries({ queryKey: ['expenses'] }),
8
  })
9
}

The hook adapts; it does not decide. If you find business logic in a hook, it belongs in a use case.

Screens

1
export function ExpenseListScreen() {
2
  const { data, isLoading, error } = useExpenses()
3

4
  if (isLoading) return <ScreenSkeleton />
5
  if (error) return <ErrorState error={error} onRetry={...} />
6
  if (data.length === 0) return <EmptyState />
7

8
  return <FlashList data={data} renderItem={...} />
9
}

Every screen handles four states: loading, empty, error, content. A screen that only renders the happy path is incomplete, not “to be done later”. See mobile-ui.md.

Forbidden in ui/

• ❌ fetch or storage calls directly in a component
• ❌ Business rules in a useEffect
• ❌ Importing from infrastructure/ (except the container provider)
• ❌ Server state in Zustand — see react-native.md §State

9. Enforcing the boundaries

Discipline does not survive deadlines. Enforce mechanically — this is the RN equivalent of ArchUnit.

eslint-plugin-boundaries or import/no-restricted-paths:

1
// .eslintrc.json  (excerpt)
2
{
3
  "rules": {
4
    "import/no-restricted-paths": ["error", {
5
      "zones": [
6
        { "target": "./src/domain",         "from": "./src/application" },
7
        { "target": "./src/domain",         "from": "./src/infrastructure" },
8
        { "target": "./src/domain",         "from": "./src/ui" },
9
        { "target": "./src/application",    "from": "./src/infrastructure" },
10
        { "target": "./src/application",    "from": "./src/ui" },
11
        { "target": "./src/ui",             "from": "./src/infrastructure",
12
          "except": ["./src/infrastructure/di"] }
13
      ]
14
    }],
15
    "no-restricted-imports": ["error", {
16
      "patterns": [
17
        { "group": ["react", "react-native", "expo*"],
18
          "message": "Framework imports are banned in domain/ and application/." }
19
      ]
20
    }]
21
  },
22
  "overrides": [
23
    { "files": ["src/domain/**", "src/application/**"],
24
      "rules": { "no-restricted-imports": "error" } }
25
  ]
26
}

Wire it into CI. A boundary violation must fail the build, not produce a warning nobody reads.

10. Offline and sync

Offline is a domain concern, not a networking detail. Decide and record it as an ADR.

The outbox is the same pattern as the backend one in messaging.md, scaled down: a local queue of pending mutations, drained when connectivity returns.

1
export interface MutationOutbox {
2
  enqueue(mutation: PendingMutation): Promise<void>
3
  pending(): Promise<readonly PendingMutation[]>
4
  markSynced(id: MutationId): Promise<void>
5
}

Non-negotiables when you adopt it:

• Every mutation carries a client-generated idempotency key. Retries after a timeout are certain; duplicates must not be.
• Conflict resolution is an explicit, documented decision — last-write-wins, server-wins, or user-resolves. “We’ll figure it out later” means silent data loss.
• The queue is bounded. An unbounded outbox on a device that has been offline for a month fills storage.

11. Monorepo

Only when there are ≥2 apps or ≥2 teams. Otherwise it is pure overhead.

1
apps/
2
  mobile/            Expo app
3
  web/               (optional)
4
packages/
5
  domain/            pure TS — reusable across platforms verbatim
6
  application/       use cases + ports — reusable
7
  ui-native/         RN design system
8
  config-eslint/     shared configs

Turborepo + pnpm workspaces. The payoff of hexagonal shows up here: domain/ and application/ have zero platform dependencies, so they move to a shared package with no changes at all.

12. Feature-Sliced Design — the alternative

For thin-CRUD apps, use FSD instead. Do not mix the two in one codebase.

1
src/
2
├── app/        providers, router, global styles
3
├── pages/      full screens
4
├── widgets/    composed reusable blocks
5
├── features/   user actions
6
├── entities/   business models
7
└── shared/     ui kit, api client, lib, config

The one rule that makes FSD work: a layer may only import from layers below it, and slices on the same layer may not import each other. Enforce with eslint-plugin-boundaries, same as §9.

If the app later grows real business rules, the migration path is: extract entities/ logic into a domain/, then introduce ports. FSD is not a dead end.

13. Anti-patterns

14. Pre-merge checklist

• domain/ and application/ import no framework and no I/O
• Every new outbound dependency has a port; the adapter implements it
• No port is named after its technology
• All external input parsed with a schema at the adapter
• Domain errors are a discriminated union, not thrown exceptions
• Clock / IdGenerator injected wherever time or ids are used
• Cross-cutting concerns are decorators, not inlined
• New concretes wired only in infrastructure/di/container.ts
• ESLint boundary rules pass
• Domain and use cases near 100% covered — see mobile-testing.md
• Architecturally significant decision captured as an ADR