Trainee app overview

The trainee app is the Expo project in mobile/. Trainees sign in with a phone number and a WhatsApp code, then follow workouts, log meals, fill forms, read studio content and track their body metrics. The app talks only to the core API under /v1/trainee/* with a bearer token. The same source also builds for the web. That export is embedded in the coach dashboard as a read-only live preview of a trainee’s app.

Stack and versions

Versions come from mobile/package.json on the dev branch.

Concern	Package	Version
App version	`version` in `package.json` and `app.json`	`1.0.7`
Framework	`expo`	`~57.0.2`
Runtime	`react-native`	`0.86.0`
React	`react`, `react-dom`	`19.2.3`
Routing	`expo-router`	`~57.0.3`
Server state	`@tanstack/react-query`	`^5.100.14`
Client state	`zustand`	`^5.0.14`
Animation	`react-native-reanimated` with `react-native-worklets`	`4.5.1`, `0.10.1`
Gestures	`react-native-gesture-handler`	`~2.32.0`
Secure storage	`expo-secure-store`	`~57.0.0`
Push and local notifications	`expo-notifications`	`~57.0.3`
OTA	`expo-updates`	`~57.0.6`
Widgets and Live Activity	`expo-widgets`, `@expo/ui`	`~57.0.2`, `~57.0.3`
Apple Health	`@kingstinct/react-native-healthkit`	`^14.0.2`
Nitro runtime	`react-native-nitro-modules`	`^0.36.1`
Health Connect	`react-native-health-connect`	`^3.5.3`
Sharing	`react-native-share`, `react-native-view-shot`, `expo-sharing`, `expo-media-library`	`^12.3.1`, `5.1.0`
Web target	`react-native-web`	`~0.21.0`
Language	`typescript`	`~6.0.3`
Package manager	`pnpm`	`10.28.2`
Node	`.nvmrc`	`24.14.0`

Expo experiments enabled in app.json: typedRoutes and reactCompiler.

Folder map

mobile/
├── app.json                 Static Expo config: ids, permissions, plugins, widgets, runtime version
├── app.config.js            Adds the web preview base path and API URL from env
├── eas.json                 EAS build and submit profiles
├── metro.config.js          SVG transformer and web / Expo Go module shims
├── babel.config.js          babel-preset-expo only
├── tsconfig.json            strict, "@/*" to "src/*", "@/assets/*" to "assets/*"
├── eslint.config.js         eslint-config-expo flat config
├── pnpm-workspace.yaml      patchedDependencies and the @types/react override
├── patches/                 pnpm patches for four native packages
├── plugins/                 Two local config plugins for Health Connect
├── modules/                 Local Expo native module (Android cardio notification)
├── scripts/                 OTA, web preview export, LAN IP helper, node:test suites
├── assets/                  brand images, SVG icons, story intro assets
└── src/
    ├── app/                 Expo Router tree. Route files only render a screen
    ├── features/            One folder per product area
    ├── components/          ui kit, glass primitives, phone field parts, splash
    ├── lib/                 api client, storage, i18n, rtl, time, media, notifications
    ├── theme/               colors, spacing, typography, theme store
    ├── constants/           strings and locale dictionaries, assets, preview constants
    └── types/               svg module declaration

ios/ and android/ are generated by prebuild and are in .gitignore. Native configuration is only durable when it lives in app.json, a config plugin, a patch or modules/.

Features

Folder	What it owns
`auth`	OTP sign in, session store, studio choice, frozen access screen
`branding`	Studio brand store, skin backgrounds, widget logo cache
`home`	Home screen in four skins, home widgets, banner
`workouts`	Programs, workout day screen, session store, rest timer, Live Activity
`movement`	Cardio requirement, cardio log, the live cardio timer
`share-story`	Workout complete screen and story share cards
`nutrition`	Menu, day log, meal screens, portions, barcode, AI meal logging, water
`plans`	Plan kind helpers and the file plan viewer
`shopping`	Shopping list
`food-preferences`	Foods the trainee excludes
`forms`	Form rendering, conditions, drafts
`content`	Studio content library
`calendar`	Meeting booking
`tracking`	Measurements log, steps
`progress`	Progress overview
`health`	Apple Health and Health Connect step sync
`notification-preferences`	Trainee notification groups
`app-update`	Store update prompt
`profile`	Profile tab
`onboarding`	Three step welcome carousel

Where to start reading

Route tree

Every route file and the gates in the layouts.

Feature modules

The folder convention with a worked example.

API client

Headers, retries, errors and the bearer token.

State management

Zustand stores, React Query, and what is persisted where.

Environment variables

Name	Read by	Purpose
`EXPO_PUBLIC_API_URL`	`src/lib/api/config.ts`	API root with no `/v1` suffix. Optional in development
`EXPO_PUBLIC_FB_APP_ID`	share to story	Attributes Instagram story shares to the app. Optional
`APP_ENV`	EAS profiles	`preview` or `production`
`PREVIEW_BASE_PATH`	`app.config.js`	Sets `experiments.baseUrl` for the web export
`PREVIEW_API_URL`	`app.config.js`	Sets `extra.apiUrl` for the web export
`EXPO_GO_SHIMS`	`metro.config.js`	When `1`, swaps `expo-widgets` for its shim on native

.env and .env.production are ignored by Git. .env.example is the committed template.

Run it locally

cd mobile
pnpm install
pnpm start          # Expo dev server
pnpm ios            # expo run:ios, builds the dev client
pnpm android        # expo run:android
pnpm web            # react-native-web

In development the API base URL is detected from the Metro host, so a phone on the same network reaches the backend on port 3031 without any env file. See API client.

What the old notes get wrong

mobile/README.md and mobile/docs/*.md were written for an early scaffold. The code has moved on in these places.

Old note	Current code
Screens render mock data from `Promise.resolve`	Every feature calls the real API through `apiClient`
Four tabs: Home, Workouts, Nutrition, Progress	Five tabs: Home, Workouts, Nutrition, Content, Profile. Progress is a stack route
Auth is a better-auth bearer token on `/v1/<module>`	Auth is the trainee OTP flow on `/v1/trainee/auth/` and every call uses `/v1/trainee/`
`MANUAL_RTL = true`, native direction pinned to LTR	`MANUAL_RTL = false`. Native RTL follows the app language
`supportsRTL` is set in `app.json`	`app.json` must pass neither `supportsRTL` nor `forcesRTL`
Package manager is npm	pnpm 10 with a lockfile and patches
`SplashView` covers loading	`SplashGate` plus `IconLoader`
`authToken.ts` manages SecureStore	`authToken.ts` is an in-memory holder. `secureStore.ts` persists
”No `expo-blur` dependency yet” in `liquid-glass.md`	`expo-blur` is installed and `GlassSurface` uses `BlurView` as the fallback
Live workout route is `workout/[id].tsx`	It is `workout/[id]/index.tsx` and renders `WorkoutDayScreen`
Pre-push runs typecheck and lint	`.husky/pre-push` runs `npm run lint` only
CI runs `npm install`	CI runs `pnpm install --frozen-lockfile`
Only Hebrew, Inter font	Six languages, with IBM Plex Sans Arabic for Arabic and extra families for the home skins and story cards

​Stack and versions

​Folder map

​Features

​Where to start reading