Architecture Decision Records

# ADR-NNNN: <Title>
 
- **Status:** proposed | accepted | superseded by ADR-XXXX
- **Date:** YYYY-MM-DD
- **Deciders:** @mobile-lead, @platform
- **Release clock:** OTA | store binary | backend | none
 
## Context
What problem and constraints? (team size, brownfield, compliance)
 
## Decision
We will <choice> because <one paragraph>.
 
## Consequences
### Positive
- …
### Negative
- …
### Rollback / reversal
- OTA: `eas update --roll-back --channel <ch>`
- Store: ship <version> binary; feature flag <name> off
 
## Alternatives considered
| Option | Rejected because |
| --- | --- |
| … | … |

# Repo layout
docs/adr/
  0001-ota-vs-store-for-checkout-copy.md
  0002-expo-camera-vs-custom-scanner.md
  README.md   # index with status table

# ADR-0007: Checkout error copy via OTA
 
- **Status:** accepted
- **Date:** 2026-03-12
- **Deciders:** @mobile-lead, @pm-checkout
- **Release clock:** OTA (`production` channel)
 
## Context
Support needs clearer card-decline messaging before weekend campaign.
No API, native, or `runtimeVersion` change. Live binary: `2.4.1` (runtimeVersion `2.4.0`).
 
## Decision
Ship copy change with `eas update` to `production` after staging channel QA.
Do not cut store release `2.4.2` for text-only change.
 
## Consequences
### Positive
- Same-day ship; rollback in minutes
- Avoids store review queue during campaign
### Negative
- Users on ancient sideload builds off channel may not receive update
### Rollback
`eas update --roll-back --channel production`
Known-good update ID: recorded in release ticket MOB-4821
 
## Alternatives considered
| Option | Rejected because |
| --- | --- |
| Store submit 2.4.2 | 2–5 day review for zero native benefit |
| Backend-driven copy only | Offline checkout still needs local strings |

# ADR-0008: Barcode scan - expo-camera vs custom Vision module
 
- **Status:** accepted
- **Date:** 2026-04-02
- **Deciders:** @mobile-lead, @android-lead, @ios-lead
- **Release clock:** store binary (new native dependency)
 
## Context
Warehouse app needs Code 128 scan at 30 fps on mid-tier Android.
`expo-camera` barcode API meets MVP; custom ML Kit wrapper promised 2× speed.
 
## Decision
Use **expo-camera** `CameraView` barcode scanning for v1.
Revisit custom module only if field metrics show >5% scan failure on Pixel 6a class.
 
## Consequences
### Positive
- Config plugin + Expo SDK upgrade path maintained by Expo
- One less Swift/Kotlin module for juniors to maintain
### Negative
- May not match dedicated scanner hardware latency
- Still requires **dev client** rebuild - not OTA-able as native add
### Rollback
Feature flag `warehouse_scan_v1` off; prior manual entry flow remains
 
## Alternatives considered
| Option | Rejected because |
| --- | --- |
| Custom TurboModule + ML Kit | 2 eng-months maintenance; no field data yet |
| WebView + browser scan | Poor offline; store WebView policy risk |
| Third-party RN scanner (unmaintained) | Last commit 18 months ago; RN 0.86 untested |

# ADR-0009: Push - Expo Notifications vs OneSignal SDK
 
- **Status:** accepted
- **Date:** 2026-05-18
- **Deciders:** @mobile-lead, @growth
- **Release clock:** store binary if switching later
 
## Context
Growth wants A/B rich push; engineering wants minimal native surface.
 
## Decision
**expo-notifications** + server-side campaign tooling for v1.
OneSignal evaluated - defer until marketing needs in-app IAM beyond product scope.
 
## Consequences
### Positive
- Aligns with EAS credentials and Expo push token flow
- Smaller native binary vs dual SDK
### Negative
- Advanced segmentation lives in our backend, not vendor UI
### Rollback
Stay on expo-notifications; no vendor SDK to remove
 
## Alternatives considered
| Option | Rejected because |
| --- | --- |
| OneSignal RN SDK | Extra native dep + duplicate FCM/APNs wiring |
| Firebase only (no Expo wrapper) | Loses unified Expo push DX for managed workflow |

# ADR index
 
| ID | Title | Status | Clock |
| --- | --- | --- | --- |
| 0007 | Checkout copy OTA | accepted | OTA |
| 0008 | expo-camera scan | accepted | store |
| 0009 | expo-notifications | accepted | store |
| 0010 | Expo Router (greenfield) | accepted | - |