wasla_mobile

Mobile app starter for Wasla, built with Expo + React Native.

This setup is intentionally minimal in app code, but opinionated in tooling so interns can focus on product features.

Preferred stack and why

• tamagui + @tamagui/config + @tamagui/lucide-icons Why: modern look, strong theming/tokens, reusable UI primitives, better visual ceiling than basic default UI.
• @tanstack/react-query + axios Why: reliable async state, caching, retries, and predictable API layer.
• zustand Why: lightweight global state without boilerplate.
• react-hook-form + zod + @hookform/resolvers Why: fast forms with strict validation and clear type safety.
• react-native-reanimated + moti + @gorhom/bottom-sheet Why: smooth, premium interactions for mobile UX patterns.
• socket.io-client Why: real-time booking updates from backend sockets.
• expo-camera + react-native-qrcode-svg Why: QR scanning and ticket QR rendering.
• expo-web-browser + react-native-webview Why: payment redirect/checkout flows.
• expo-secure-store Why: secure token/session storage on device.
• expo-notifications Why: booking/ticket push notifications.
• dayjs Why: simple date/time handling for ETD and schedule logic.

Run

pnpm run start
pnpm run android
pnpm run ios
pnpm run web

If Metro cache causes stale warnings:

pnpm run start -- --clear

Central Server Realtime (Socket.IO)

The app initializes a persistent Socket.IO connection to the central backend once the app bootstraps.

Environment:

• EXPO_PUBLIC_CENTRAL_SERVER_URL (required; set it to your backend URL)

Connection details:

• Socket.IO namespace: /realtime
• Events in: ping
• Events out: ready, pong

To verify locally:

1. Start the backend: pnpm -C central-server start:dev
2. Start the app: pnpm -C wasla_mobile start
3. Confirm the app connects and receives ready, then pong (the app sends ping automatically after ready).

Note for interns:

• Android emulator: use http://10.0.2.2:4000 when the backend runs on your machine.
• iOS simulator: use http://localhost:4000 when the backend runs on your machine.
• Physical device: replace with the dev machine LAN IP (or use an Expo tunnel), because localhost points to the phone itself.

Connection state is available via useRealtimeStore (status, lastReadyAt, lastPongAt, lastPong, lastError).

Tests / Release

• pnpm run test:unit — compiles tsconfig.unit.json helpers and runs node --test test/*.test.cjs.
• pnpm run verify:maestro-ids — ensures .maestro/smoke_login_booking.yaml still matches testIDs in source (CI-friendly guard).
• CI: .github/workflows/mobile-ci.yml runs those on main.
• Sessions (no refresh API yet): docs/auth-sessions.md.
• iOS HTTP in dev only: EXPO_PUBLIC_ALLOW_INSECURE_HTTP=true (see app.config.js); prefer HTTPS otherwise.
• E2E smoke (Maestro device): .maestro/smoke_login_booking.yaml + docs/release-checklist.md.
• Sentry (optional): docs/observability.md.