Skip to content

Routing

Tomoda uses Expo Router — a file-based router built on React Navigation. Files under frontend/app/ become routes; their on-disk shape is the URL shape.

Conventions

File / folder Meaning
app/foo.tsx Route at /foo
app/foo/index.tsx Route at /foo (folder form)
app/foo/_layout.tsx Layout wrapping every child route (renders a <Stack/>, <Tabs/>, etc.)
app/foo/[id].tsx Dynamic segment, accessible via useLocalSearchParams()
app/(group)/... Route group — folder ignored in the URL, used purely to share layout / organize
app/+html.tsx Web-only custom HTML shell (head, meta, viewport)
app/index.tsx The root route /

The root layout app/_layout.tsx wraps every screen with provider context (see State Management) and renders a single <Stack/>.

Top-level route map

app/_layout.tsx (providers + auth gate via Stack.Protected) is the parent. The consumer-facing tab sections live inside a (tomoda) group whose layout renders an <expo-router> <Tabs tabBar={() => null}> navigator with the default tab bar hidden. The chrome (mobile bottom dock + web sidebar) is painted by AppNav. Each tab keeps its own internal stack, so swipe-back and nested back navigation stay scoped to the active tab and tab swaps do not accumulate root history.

Route-agnostic screens (mount one screen under several tabs)

Because each tab owns its own stack, a screen deep-linked across tabs cannot router.back() to the origin — "back" pops the target tab's stack and lands on that tab's root, not the caller. When a screen must be reachable from more than one tab (Events and Voyages open from both the hub's horizon and the planner), put its content in one shared component and mount thin route wrappers at each path:

  • components/<domain>/<Name>Screen.tsx — the screen itself: UI, data, and its own Page + header.
  • app/(tomoda)/hub/horizon/events.tsx and app/(tomoda)/plan/events.tsx — one line each (export { default } from '.../EventsScreen', or a wrapper that passes props).

Each wrapper inherits its own stack's back behavior, so opening Events from the planner keeps the user in the plan tab and "back" returns to the planner. Prefer this to cross-tab deep-linking patched up with router.back() fallbacks.

Keep shared data in the shared layer

Because the same component mounts in more than one stack (and Expo Router keeps both tab stacks alive), its server data must live in a TanStack Query hook (keyed by a *QueryKey factory) or a context — then every mount reads one cache: fetch once, no divergence, and WS updates patch all mounts. Only genuinely per-view UI state (scroll position) stays local. A hand-rolled useState fetch loop double-fetches and drifts between mounts.

Sibling groups outside (tomoda) host the surfaces that should NOT participate in the tab navigator: auth flows, the capture flow (native-only, full-screen modal), public share targets, and the partner / Tomoda-team shells. Which authed shell mounts is chosen by account type in Stack.Protected. The full inventory is below.

Route prefix Type Purpose Children
/ (index.tsx) screen Public landing (web) and redirect target. Authed users bounce to /discover (standard), /partner/dashboard (partner), or /backstage (Tomoda accounts). —
/auth/* stack Sign-in, sign-up, recovery, onboarding. Mounted while !isAuthenticated \|\| profileIncomplete. login.tsx, register.tsx, forgot-password.tsx, complete-profile.tsx
(tomoda)/ group Consumer app shell. Layout renders <Tabs tabBar={() => null}> with animation: 'none'. Mounted for standard / synthetic accounts. Chrome painted by AppNav. discover/, plan/, search.tsx, connect/, notifications.tsx, hub/
/discover ((tomoda)/discover/) stack Discover tab. /discover renders the home view (greeting + feed); /discover/map renders the full map. The mobile center nav button morphs into a capture shutter while on either route (native-only). index.tsx, map.tsx
/plan/* ((tomoda)/plan/) stack Plan tab: the stash + plan canvas (index.tsx), plus in-tab Events / Voyages that render the same shared screens as horizon (route-agnostic, so back returns to the planner). index.tsx, events.tsx, voyages.tsx
/search ((tomoda)/search.tsx) screen Unified search tab (events, locations, people, NL intent) backed by the /discovery/search* endpoints. —
/connect/* ((tomoda)/connect/) stack Messaging / DMs / new-chat flow. /connect redirects to /connect/inbox. index.tsx, inbox.tsx, new.tsx, [userId].tsx, chat/[id].tsx, chat/draft/[userId].tsx
/notifications ((tomoda)/notifications.tsx) screen Inbox of activity notifications. —
/hub/* ((tomoda)/hub/) stack Profile + settings hub, plus the personal timeline (horizon) and friends / security sub-trees. index.tsx, profile.tsx, profile-edit.tsx, appearance.tsx, preferences.tsx, account.tsx, friends/, security/, horizon/
(capture)/* group Capture flow (no URL prefix), native-only. The layout Redirects to /discover on web, so the routes are unreachable from the web bundle. Entered by tapping the shutter the center dock button morphs into on /discover and /discover/map. camera.tsx, checkin.tsx, compose-moment.tsx, place.tsx, preview.tsx
(social)/* group Public share targets, available regardless of auth state for OG previews and direct deep links. events/[id].tsx, u/[handle].tsx, m/[id].tsx (moment), plans/[id].tsx, plans/join/[token].tsx
(legal)/* group Public policy pages, the account-deletion explainer and the help center, always mounted and rendered in PublicPageShell with no app nav, signed in or not. privacy.tsx, terms.tsx, cookies.tsx, guidelines.tsx, refunds.tsx, child-safety.tsx, delete-account.tsx, help/
/partner/* (partner/) stack Partner-account shell, a real URL segment so its routes never collide with the consumer shell. Mounted when account_type === 'partner'; the layout renders <Tabs tabBar={() => null}>. AppNav switches to the partner nav. Partners use a linked standard account to reach the consumer app (see Authentication architecture → Linked accounts). dashboard/, members/, events/, hub/
(backstage)/* group Backstage, the Backstage shell. Mounted only while a Tomoda accounts (tomoda) session is active, entered from the linked personal account. Sections show by capability. backstage/index.tsx
+html.tsx web-only Custom <html> shell for the web bundle. —

auth/

auth/
├── _layout.tsx
├── login.tsx              -> /auth/login (password, passkey, or the emailed code step; a suspended account sees the review sheet)
├── register.tsx           -> /auth/register
├── forgot-password.tsx    -> /auth/forgot-password
└── complete-profile.tsx   -> /auth/complete-profile

Supports Email/Password, Google, Apple, Passkey, and OTP-based flows (driven from contexts/AuthContext.tsx).

connect/

connect/
├── _layout.tsx
├── index.tsx                 -> /connect            (redirects to /connect/inbox)
├── inbox.tsx                 -> /connect/inbox
├── new.tsx                   -> /connect/new
├── [userId].tsx              -> /connect/:userId     (DM resolver: opens or drafts a room)
└── chat/
    ├── [id].tsx              -> /connect/chat/:id    (active room)
    └── draft/[userId].tsx    -> /connect/chat/draft/:userId

Chat rooms open via the dynamic chat/[id].tsx route; the per-room WebSocket connection is established in that screen. See Real-time. /connect/:userId resolves an existing room for that friend (or spins a draft) and redirects into the chat route.

hub/

The settings/profile hub, which also hosts the personal timeline (horizon) and the friends / security sub-trees:

hub/
├── _layout.tsx
├── index.tsx                 -> /hub
├── profile.tsx               -> /hub/profile
├── profile-edit.tsx          -> /hub/profile-edit
├── appearance.tsx            -> /hub/appearance       (theme picker)
├── preferences.tsx           -> /hub/preferences
├── account.tsx               -> /hub/account
├── legal/
│   ├── index.tsx             -> /hub/legal            (Terms & policies list, reached from Hub → Account)
│   └── [doc].tsx             -> /hub/legal/:doc       (one policy, rendered in-app)
├── help/
│   ├── index.tsx             -> /hub/help             (searchable help center, reached from Hub → Account)
│   └── [slug].tsx            -> /hub/help/:slug       (one help article)
├── friends/
│   ├── index.tsx             -> /hub/friends
│   └── close.tsx             -> /hub/friends/close    (close-friends list)
├── security/
│   ├── index.tsx             -> /hub/security
│   ├── change-email.tsx      -> /hub/security/change-email
│   └── change-password.tsx   -> /hub/security/change-password
└── horizon/
    ├── events.tsx            -> /hub/horizon/events   (wraps components/horizon/EventsScreen)
    └── voyages.tsx           -> /hub/horizon/voyages  (wraps components/horizon/VoyagesScreen)

events.tsx / voyages.tsx here are thin wrappers around the shared components/horizon/{EventsScreen,VoyagesScreen} — the same screens plan/events.tsx / plan/voyages.tsx mount (see Route-agnostic screens).

(social)/ — public share targets

(social)/
├── events/[id].tsx        -> /events/:id       (no group prefix)
├── u/[handle].tsx         -> /u/:handle         (wraps components/profile/ProfileScreen)
├── m/[id].tsx             -> /m/:id             (moment)
├── moments-viewer.tsx     -> /moments-viewer    (a profile's moments, full screen)
├── places/[id].tsx        -> /places/:id        (redirects to /place-map)
├── plans/[id].tsx         -> /plans/:id         (shared plan)
├── plans/join/[token].tsx -> /plans/join/:token (share-link join)
└── profile/edit.tsx       -> /profile/edit

These routes are public, reachable without authentication so they can render share previews and OG metadata. The auth gate keeps index and (social) always mounted.

For a signed-in member these pages open on the root stack above (tomoda): the tab navigator stays mounted underneath, AppNav stays painted, and back returns to the screen that opened them. In-app links to them go through NavPressable or useAppNavigation, which navigate client-side on web.

/u/:handle accepts either a username or a UUID. The backend resolves either form; the screen canonicalizes a UUID landing to the username path via router.setParams once the profile loads so the address bar shows the pretty link. userPath (utils/userPath.ts) adds ?id=<uuid> to a username link when the caller knows the id. With that param, or a UUID handle, the screen fetches the profile and moments in parallel with the handle lookup.

Share pages tell a missing resource from a failed request with isNotFoundError (utils/apiErrors.ts). A 400, 403, 404 or 410 shows the not-available state: NotFoundScreen for signed-out visitors, an in-page empty state for members. A network error, timeout or 5xx shows an error state with Retry and keeps the user on the page. The reserved username list (backend/internal/utils/username.go::IsReservedUsername) keeps usernames from colliding with top-level route segments (u, discover, hub, etc.).

(legal)/
├── privacy.tsx        -> /privacy         (LegalDocScreen doc="privacy")
├── terms.tsx          -> /terms
├── cookies.tsx        -> /cookies
├── guidelines.tsx     -> /guidelines
├── refunds.tsx        -> /refunds
├── child-safety.tsx   -> /child-safety    (Child Safety Standards)
├── delete-account.tsx -> /delete-account  (DeleteAccountScreen)
└── help/
    ├── index.tsx      -> /help            (HelpCenter; the store support URL)
    └── [slug].tsx     -> /help/:slug      (one help article)

Each policy route renders the bundled Markdown in frontend/content/legal/ (imported as text through metro.transformer.js) with components/legal/LegalMarkdown.tsx. Signed-in users read the same documents in-app at /hub/legal/:doc (Hub → Account → Terms & policies), so the public pages serve signed-out visitors, the stores and the web footer. The signup clickwrap links call utils/legalLinks.ts::openLegalPage: a new tab on web, the in-app browser at EXPO_PUBLIC_WEB_URL on native. The root layout exempts (legal) from the complete-profile redirect so those links work mid-onboarding. On the public pages the header swaps Sign up / Sign in for Open Tomoda when the visitor is signed in.

The help center content is bundled Markdown in frontend/content/help/ (one file per article, manifest.json for categories, titles, summaries and search keywords, and one optional file per translated language in i18n/, loaded by hooks/useHelpCatalog.ts; see Localization). components/help/HelpCenter.tsx renders search and a grid of topic tiles that expand in place to list their articles (utils/helpSearch.ts, client-side ranking over title, keywords, summary and body) for both /help and /hub/help. The web footer links Help, Privacy, Terms and Cookies; the other policies and account deletion are reached from Help.

Open in the app from a phone browser

On a phone browser, public pages offer the native app. Landing, profile and event pages carry their own "Open in Tomoda app" button; every other public page (auth, (legal) including help, and the remaining (social) pages) shows components/public/OpenInAppBar.tsx, a slim dismissible bar above the page (snoozed for 14 days in local storage). Both go through utils/appLinks.ts::appPathForWebPath: a shared item (profile, event, moment, place, plan, check-in) opens that item in the app, every other page opens the app home. Android uses an intent:// link with the Play Store as fallback. iOS fires the tomoda:// scheme behind the system "Open in Tomoda?" prompt; if the page is still showing after 2.5 seconds (prompt cancelled or app not installed) the control switches to "Get the app" instead of navigating away. Desktop browsers and the native app show neither.

/delete-account sends a signed-out visitor to /auth/login?next=/hub/account. utils/postAuthRedirect.ts allowlists next values; the root layout honors one when it bounces a standard account out of the auth group (web only).

(capture)/

(capture)/
├── _layout.tsx            -> wraps in CaptureProvider; Redirects to /discover on web
├── camera.tsx             -> capture camera
├── place.tsx              -> nearby-location picker
├── checkin.tsx            -> check-in composer
├── compose-moment.tsx     -> moment composer
└── preview.tsx            -> capture preview / confirm

The group is native-only: the layout Redirects to /discover on web, so these routes never render in the web bundle. CaptureContext (provided in (capture)/_layout.tsx) holds the in-flight publish (picked location, companions, rating, captured media) so back-navigation preserves state; it resets on publish or cancel.

The check-in publish path additionally calls POST /events/:id/checkin for a nearby active event, which proximity-checks the user's active event RSVPs and stamps the participant row on a match. Best-effort; never fails the publish. See Events service.

(backstage)/

(backstage)/backstage/index.tsx         -> /backstage              (Today)
(backstage)/backstage/people/index.tsx  -> /backstage/people
(backstage)/backstage/people/[id].tsx   -> /backstage/people/:id
(backstage)/backstage/reports/index.tsx -> /backstage/reports    (triage)
(backstage)/backstage/reports/[id].tsx  -> /backstage/reports/:id
(backstage)/backstage/reports/reviews/index.tsx -> /backstage/reports/reviews
(backstage)/backstage/ops.tsx           -> /backstage/ops
(backstage)/backstage/announcements.tsx -> /backstage/announcements
(backstage)/backstage/switches.tsx      -> /backstage/switches
(backstage)/backstage/covers/index.tsx  -> /backstage/covers      (cover photo review queue)
(backstage)/backstage/covers/[id].tsx   -> /backstage/covers/:id
(backstage)/backstage/audit.tsx         -> /backstage/audit
(backstage)/backstage/accounts.tsx        -> /backstage/accounts (Tomoda and Partners tabs)

Backstage, the Backstage shell, mounted only for a tomoda session (see Backstage). Each screen wraps components/backstage/BackstageScreen, which shows a not-available state when useBackstageMe() lacks the section's capability; the nav (navConfig.ts) hides those sections too. Switching into a linked account runs from the personal account at /hub/switch/{id}, and invites are accepted at the public /invite?token=, signed in or out. Today shows "Link your personal account" to a Tomoda account with no link (a sheet: a fresh step-up, then any normal sign-in of the personal account: password, Google or Apple) and "Unlink personal account" to a linked one (a fresh step-up). Backstage strings are English-only (i18n/backstage.json). The cover review screens use the reports capabilities and are linked from the reports queue. Report triage shows one group at a time: on native, swipe left to dismiss (never for urgent groups) and right to skip; on the web, single keys run the same commands (components/backstage/triage/). Support lives in the member shell: Contact us at /hub/help/contact, My requests at /hub/support and /hub/support/:id, and the public form at /help/contact; Backstage answers at /backstage/cases; /backstage/crashes lists crashes; /backstage/data is the data console (a table with select-all on wide web, cards on phones) and /backstage/data/changes its change log; /backstage/insights is the dashboard and /backstage/insights/member/:id one member's engagement, opened from People; /backstage/ops shows queues and failed tasks, /backstage/announcements writes the notices members see at the top of the Hub, and /backstage/switches turns registered features off. Public switches reach the app through hooks/useSwitch.ts. A problem report opens from anywhere in the member shell (contexts/ProblemReportContext.tsx): shaking the phone, Report on an error toast, or the help center. Members see an action taken on them at /hub/moderation/:id, opened only from its notification (Notifications is the one place notices live). A warning, hidden content or removed content offers one Ask for a review; a suspension shows the support email.

Auth gate

The root layout (frontend/app/_layout.tsx) uses Stack.Protected to declaratively choose which top-level groups exist at any given moment. When a guard flips (login, logout, profile completion), the navigator auto-navigates to the first available screen in the newly-mounted branch, so no manual router.replace is required for the broad transitions.

const profileIncomplete = !!user && (!user.username || !user.date_of_birth);

<Stack>
  {/* Always available, public surfaces */}
  <Stack.Screen name="index" />
  <Stack.Screen name="(social)" />

  {/* Unauth / onboarding shell */}
  <Stack.Protected guard={!isAuthenticated || profileIncomplete}>
    <Stack.Screen name="auth" />
  </Stack.Protected>

  {/* Authed shells, chosen by account type. Standard/synthetic accounts
    * get the consumer surface plus the capture flow; partner and Tomoda
    * accounts each mount their own shell instead. */}
  <Stack.Protected guard={authed && (accountType === 'standard' || accountType === 'synthetic')}>
    <Stack.Screen name="(tomoda)" options={{ animation: 'none' }} />
    <Stack.Screen name="(capture)" options={{ presentation: 'fullScreenModal' }} />
  </Stack.Protected>

  <Stack.Protected guard={authed && accountType === 'partner'}>
    <Stack.Screen name="partner" options={{ animation: 'none' }} />
  </Stack.Protected>

  <Stack.Protected guard={authed && accountType === 'tomoda'}>
    <Stack.Screen name="(backstage)" options={{ animation: 'none' }} />
  </Stack.Protected>
</Stack>

Stack.Protected rewrites a URL the current auth state can't open to /. One effect in the root layout recovers the intent behind that / by applying decideRootRedirect (utils/rootRedirect.ts), a pure function covered by scenario tests in __tests__/utils/rootRedirect.test.ts:

  • Signed out on a members-only deep link: /auth/login?next=<path>. After sign-in, or social sign-up through /auth/complete-profile, the user lands on that path. /auth/login also takes ?email=<address> to prefill the identifier, which sign-up's Sign in instead passes for an address that already has an account.
  • Signed in on a deep link the guard rewrote: the original URL replays.
  • Signed in on / or /auth/*: their shell's home (/discover for standard, /partner/dashboard for partner, /backstage for Tomoda), so the marketing landing never sticks for a signed-in user.
  • Profile incomplete: /auth/complete-profile, carrying any pending destination. The policy pages stay reachable.

A destination is used only when the account's shell serves it (shellServesPath in utils/accountLanding.ts); otherwise the user goes to their home. next accepts same-site paths only (safeNextPath in utils/postAuthRedirect.ts). The loaded URL is read once, so a later logout or logo tap never replays it.

Caller state Mounted shell Default screen
Unauthenticated index, (social), (legal), auth /auth/login
Authed, profile incomplete index, (social), (legal), auth /auth/complete-profile
Authed standard / synthetic index, (social), (legal), (tomoda), (capture) /discover
Authed partner index, (social), (legal), partner /partner/dashboard
Authed tomoda index, (social), (legal), (backstage) /backstage

Partner and Tomoda-team members reach the consumer surface through a linked standard account (separate JWT, re-auth on switch). See Authentication architecture → Frontend authorization shell for the multi-shell pattern, role-based screen gating, and account switching.

Default landing

The signed-in landing route is /discover. It renders the discovery home view. The full map lives at /discover/map and is reached via the "Open map" affordance on the home view or the segmented control in the page header. Both routes are treated as the Discover tab in AppNav, so the mobile center button morphs into the capture shutter on either one.

Where to go next