App shell & gates

8 screens and overlays, 28 states, 3 flows. Frames show a real screenshot where one was captured and a wireframe card where the state needs data or conditions a device run cannot produce.

Flows

Cold start as guest

Step 1

Wireframe

Splash and startup

Splash while initialising

Session still pending and app not ready; native splash is held.

Not reachable on a device: Needs a network fault, crash, race or code change to show

Native splash holds while the session loads

Session ready

Account gate, Guest, no gate (iOS) — Account gate lets a guest straight through

Account gate, Guest, no gate (Android) — Account gate lets a guest straight through

Redirect

Step 3

Wireframe

App root redirect

Not reachable on a device: Pure redirect with no UI to photograph

Root redirect sends the user to the Home tab

Land on Home

Home (iOS) — Home tab loads for the guest

Home (Android) — Home tab loads for the guest

Branches and edge cases

Edgefrom step 1

Wireframe

Splash and startup

Offline

Session slow, continue as guest

Session pending for 10 s (offline or stalled); app proceeds as a guest.

Not reachable on a device: Needs a network fault, crash, race or code change to show

Session stalls for 10 s

Edgefrom step 1

Wireframe

Splash and startup

Edge

Deep link replayed after Home

A link that arrived before Home existed is replayed once Home is built.

Not reachable on a device: Cold-start timing race

Deep link allowed: opens over Home

Edgefrom step 1

Wireframe

Deep link screening

Edge

Android link held until Home exists

Warm link before Home is parked and replayed; links older than 60 s are dropped.

Not reachable on a device: Android cold-start timing race

Android link arrives before Home exists

Deep link screening, Rejected link is silent (iOS) — Deep link rejected

Deep link screening, Rejected link is silent (Android) — Deep link rejected

Errorfrom step 1

Wireframe

App Error

Error

App Error

Uncaught render error. Body: Something went wrong, but we can try to recover.

Not reachable on a device: Needs an uncaught render error

Uncaught crash during startup

Edgefrom step 1

Wireframe

App Error

Edge

Restart signs the user out

Restart App and automatic critical recovery sign out, then reload the app.

Not reachable on a device: Needs an uncaught render error

Crash screen: Restart App

Flow diagram

Cold start as signed-in user

Step 1

Wireframe

Splash and startup

Splash cover over first screen

Overlay stays until Home reports content ready, with a 12 s backstop.

Not reachable on a device: Needs a network fault, crash, race or code change to show

Splash cover stays until Home reports content

Account stage resolves

Step 2

Wireframe

Account gate

Blocking splash on cold start

Signed-in cold start while the account stage loads; later token refreshes never block.

Not reachable on a device: Needs a network fault, crash, race or code change to show

Account gate blocks on the account stage

Stage is Ready

Branches and edge cases

Errorfrom step 2

Wireframe

Account gate

Error

Can't load your account

Profile wait gives up after 5 s or the 15 s backstop fires. Buttons: Try again, Continue browsing.

Not reachable on a device: Needs a network fault, crash, race or code change to show

Stage unknown after 5 s

Errorfrom step 2

Wireframe

Account gate

Offline

Servers unreachable copy

Body says servers could not be reached; Try again shows a spinner while retrying.

Not reachable on a device: Needs a network fault, crash, race or code change to show

Servers unreachable wording

Edgefrom step 2

Wireframe

Home

Offline

Offline skeletons persist

No offline state or timeout; skeletons stay indefinitely

Not reachable on a device: Needs a network fault, crash, race or code change to show

Continue browsing: degraded Home

Account gate, Closed account signed out silently (iOS) — Closed account: silent sign-out

Account gate, Closed account signed out silently (Android) — Closed account: silent sign-out

Home, Signed out (iOS) — Closed account lands on guest Home

Home, Signed out (Android) — Closed account lands on guest Home

Flow diagram

App update prompt

Step 1

Wireframe

Update available

Edge

Update available

Installed version is below the minimum supported (1.7.0) and not dismissed.

Needs data: Capture audit 2026-10-30. ios: Release build required; __DEV__ disables update prompt. android: Release build required; __DEV__ disables update prompt.

Modal says the installed version is below the minimum

Tap Later

Branches and edge cases

Edgefrom step 1

Wireframe

Update available

Edge

New version on Play Store

Android sideloaded install with prompt enabled; wins over the version update.

Needs data: Capture audit 2026-10-30. ios: Release build required; __DEV__ disables update prompt. android: Release build required; __DEV__ disables update prompt.

Sideloaded Android build

Update available, Hidden (iOS) — Up to date or no policy

Update available, Hidden (Android) — Up to date or no policy

Edgefrom step 1

Wireframe

Update available

Edge

Not a forced update

Both kinds can be dismissed for 7 days; there is no maintenance mode.

Needs data: Capture audit 2026-10-30. ios: Release build required; __DEV__ disables update prompt. android: Release build required; __DEV__ disables update prompt.

Optional update

Flow diagram

Screens and states

Splash and startup

Wireframe

Splash and startup

Not reachable on a device: Splash is a transient native overlay

Gateapp/_layout

Splash and startup

Holds the splash until session and first content are ready, then shows the app.

src/app/_layout.tsx

Entry

Cold start

Exits

Ready → Home
Session stalls 10 s → Home as guest
Uncaught crash → App Error screen

States · 4

Splash while initialising · Session still pending and app not ready; native splash is held.src/app/_layout.tsx:402

Offline

Session slow, continue as guest · Session pending for 10 s (offline or stalled); app proceeds as a guest.src/app/_layout.tsx:336

Splash cover over first screen · Overlay stays until Home reports content ready, with a 12 s backstop.src/app/_layout.tsx:365

Edge

Deep link replayed after Home · A link that arrived before Home existed is replayed once Home is built.src/app/_layout.tsx:167

Account gate

Wireframe

Account gate

Not reachable on a device: Account gate is a transient blocking splash on cold start

Gateapp/(app)/_layout

Account gate

Blocks cold start on the account stage and offers retry when the account cannot load.

src/app/(app)/_layout.tsx

Entry

Every route inside the app stack

Exits

Try again → re-check account
Continue browsing → Home, degraded
Needs details → account details sheet
Closed account → silent sign-out

States · 9

Gate

Guest, no gate · Signed-out user; the app renders immediately.src/features/auth/hooks/use-post-auth-redirect.ts:71

Blocking splash on cold start · Signed-in cold start while the account stage loads; later token refreshes never block.src/app/(app)/_layout.tsx:102

Error

Can't load your account · Profile wait gives up after 5 s or the 15 s backstop fires. Buttons: Try again, Continue browsing.src/app/(app)/_layout.tsx:155

Offline

Servers unreachable copy · Body says servers could not be reached; Try again shows a spinner while retrying.src/app/(app)/_layout.tsx:134

Edge

Unfinished sign-up reopens details · Stage needs-details pushes the account details sheet once.src/app/(app)/_layout.tsx:183

Edge

Closed account signed out silently · Deleted or suspended account is signed out and no message is shown.src/features/auth/hooks/use-post-auth-redirect.ts:114

Success

Pending sign-in action resumes · A stored onSignedIn callback runs once when the stage becomes ready.src/app/(app)/_layout.tsx:274

Edge

Home notification offer mounted · useOfferNotificationsOnHome(stage) runs in the (app) layout; only stage ready, Home focused, not yet offered and no registered token schedule the asksrc/app/(app)/_layout.tsx:287

Edge

App icon badge follows unread · useAppBadge sets the icon badge to the unread count, and 0 for a guest so sign-out clears itsrc/app/(app)/_layout.tsx:283

Captured states

Account gate, Home notification offer mounted (iOS) — Home notification offer mounted

Account gate, Home notification offer mounted (Android) — Home notification offer mounted

App root redirect

Wireframe

App root redirect

Not reachable on a device: Pure redirect with no UI to photograph

Redirectapp/(app)/index

App root redirect

Sends the bare app path to the Home tab.

src/app/(app)/index.tsx

Entry

Cold start
Sign-in sheet closed with nothing below it

Exits

Redirect → Home tab

Deep link screening

Wireframe

Deep link screening

Not reachable on a device: Pure link screening with no UI to photograph

Redirectapp/+native-intent

Deep link screening

Screens incoming links so rejected ones land on Home and valid ones open their target.

src/app/+native-intent.ts

Entry

Any OS link, cold or warm

Exits

Cold start rejected link → Home
Warm rejected link → stay on current screen
Auth callback → handled by sign-in
Valid link → target screen

States · 3

Edge

Rejected link is silent · Cold start opens Home, warm link is ignored; nothing is shown to the user.src/app/+native-intent.ts:107

Edge

Android link held until Home exists · Warm link before Home is parked and replayed; links older than 60 s are dropped.src/app/+native-intent.ts:113

Edge

Language switch restores route · Cold start after a language reload reopens the saved route.src/app/+native-intent.ts:54

Captured states

Oops!

Screenapp/+not-found

Oops!

404 fallback with a link back to Home.

src/app/+not-found.tsx

Entry

In-app push to a bad path

Exits

Go to home screen! → Home

States · 1

Error

This screen doesn't exist. · No route matched. Copy is not translated and does not use the shared empty state.src/app/+not-found.tsx:9

Update available

Wireframe

Update available

Needs data: Needs a backend min-version policy above the installed build

DialogAppUpdateModal

Update available

Dismissible prompt to update the app or install from the Play Store.

src/shared/components/update/app-update-modal.tsx

Entry

Automatic, over any screen

Exits

Update Now → store listing
Later → hidden for 7 days
Swipe or backdrop → same as Later

States · 4

Edge

Hidden · No policy yet (offline or loading), no installer info, or no platform policy.src/shared/hooks/use-app-update-gate.ts:64

Edge

Update available · Installed version is below the minimum supported (1.7.0) and not dismissed.src/shared/hooks/use-app-update-gate.ts:83

Edge

New version on Play Store · Android sideloaded install with prompt enabled; wins over the version update.src/shared/hooks/use-app-update-gate.ts:74

Edge

Not a forced update · Both kinds can be dismissed for 7 days; there is no maintenance mode.src/shared/hooks/use-app-update-gate.ts:18

Captured states

App Error

Wireframe

App Error

Not reachable on a device: Needs a render crash; code change or fault injection

ScreenAppErrorBoundary

App Error

Last-resort crash screen with retry and restart.

src/shared/components/error/app-error-boundary.tsx

Entry

Any uncaught render error

Exits

Try Again → clears the error
Retry Connection → clears the error
Restart App → sign out and reload

States · 4

Error

App Error · Uncaught render error. Body: Something went wrong, but we can try to recover.src/shared/components/error/app-error-boundary.tsx:156

Offline

No internet connection detected · Device offline; body asks the user to check the connection and offers Retry Connection.src/shared/components/error/app-error-boundary.tsx:70

Edge

Critical App Error · After 3 critical errors (chunk load, network failed); restart recommended.src/shared/components/error/app-error-boundary.tsx:32

Edge

Restart signs the user out · Restart App and automatic critical recovery sign out, then reload the app.src/shared/components/error/app-error-boundary.tsx:248

Tab bar

Screen(app)/(tabs)/_layout

Tab bar

Five tabs for guests and members, with bag and unread badges.

src/app/(app)/(tabs)/_layout.tsx

Entry

Default landing
Tab deep links

Exits

Home tab
Shop tab
My Bag tab
Loyalty tab
Profile tab

States · 3

Edge

My Bag count badge · Shows cart item count above 0, capped 99+, for guests and members.src/app/(app)/(tabs)/_layout.tsx:139

Edge

Profile unread badge · Shows unread notification count once a user id exists, capped 99+.src/app/(app)/(tabs)/_layout.tsx:180

Edge

Hidden on full-screen routes · Tab bar is hidden on pushed routes such as product.src/app/(app)/_layout.tsx:302

App shell & gates

FlowsCopy Anchor Link

Cold start as guestCopy Anchor Link

Cold start as signed-in userCopy Anchor Link

App update promptCopy Anchor Link

Screens and statesCopy Anchor Link

Splash and startupCopy Anchor Link

Splash and startup

Account gateCopy Anchor Link

Account gate

App root redirectCopy Anchor Link

App root redirect

Deep link screeningCopy Anchor Link

Deep link screening

Oops!Copy Anchor Link

Oops!

Update availableCopy Anchor Link

Update available

App ErrorCopy Anchor Link

App Error

Tab barCopy Anchor Link

Tab bar

On this page

Flows

Cold start as guest

Cold start as signed-in user

App update prompt

Screens and states

Splash and startup

Account gate

App root redirect

Deep link screening

Oops!

Update available

App Error

Tab bar