AquaX Mobile Architecture

Owner: Mobile & Architecture
Reviewers: Backend, Product Design, QA, Security, DevOps
Status: Draft - Current-Code Baseline
Version: 0.1
Last Updated: 2026-09-17
Review Cycle: Per mobile navigation, auth, API, storage, notification or release change

1. Purpose And Scope

This document describes the current AquaX mobile architecture as implemented in mobile/. It focuses on runtime composition, role-based navigation, state management, API integration, authentication/session storage, notifications, feature boundaries, design-system usage, build/release behavior and known mobile risks.

This document covers the Expo React Native mobile app only. Web frontend architecture is documented in docs/04-architecture/FE_Architecture.md.

Sources reviewed:

• mobile/package.json
• mobile/app.json
• mobile/babel.config.js
• mobile/tsconfig.json
• mobile/src/main.tsx
• mobile/src/App.tsx
• mobile/src/core/components/**
• mobile/src/core/config/**
• mobile/src/core/navigation/**
• mobile/src/core/store/**
• mobile/src/core/hooks/**
• mobile/src/core/services/**
• mobile/src/core/types/**
• mobile/src/features/**
• mobile/scripts/deploy_android_playstore.sh
• docs/current/architecture/mobile-architecture.md
• docs/07_Design System.md

2. High-Level Mobile Context

AquaX mobile is an Expo React Native app for role-based farm operations. It supports public auth flows and authenticated role surfaces for ADMIN, MANAGER, TECHNICIAN and OWNER.

Current stack:

Primary runtime flow:

AppProviders
  -> RootNavigator
    -> AuthNavigator or MainNavigator
      -> role navigator
        -> feature screen
          -> domain hook
            -> API service
              -> apiClient
                -> backend /api

3. Source Layout

Current source layout:

mobile/src/
  core/
    components/
    config/
    constants/
    hooks/
    libs/
    navigation/
    services/
    store/
    theme/
    types/
  features/
    admin/
    auth/
    manager/
    owner/
    shared/
    technician/
  App.tsx
  main.tsx

Boundaries:

Important alignment note:

• Older docs described a flatter navigation/ and screens/ root layout. Current code uses core/ plus features/.
• Current code uses role OWNER, not VIEWER, for owner/viewer mobile flows.

4. App Bootstrap

mobile/src/main.tsx registers the Expo root component.

registerRootComponent(App)

mobile/src/App.tsx composes:

AppProviders
  -> RootNavigator

AppProviders composes:

GestureHandlerRootView
  -> QueryClientProvider
    -> SafeAreaProvider
      -> ThemeProvider
        -> Ant Design Provider
          -> app children
          -> AppToast

It also loads Ant Design icon fonts and shows a custom branded launch loading screen while fonts are loading.

5. Build And Runtime Configuration

5.1 Expo App Config

mobile/app.json confirms:

5.2 Environment

core/config/env.ts uses:

Android emulator behavior:

• When running on Android, localhost is rewritten to 10.0.2.2.

5.3 Module Resolution

babel.config.js and tsconfig.json define:

@/* -> ./src/*

TypeScript is strict and uses bundler module resolution.

6. Navigation Architecture

6.1 Root Navigation

RootNavigator owns auth restoration and top-level routing.

Flow:

isRestoring
  -> show ActivityIndicator
else accessToken exists
  -> MainNavigator
else
  -> AuthNavigator

Session restoration:

1. Calls authAPI.restoreSession().
2. restoreSession() calls refresh flow using SecureStore refresh token.
3. On success, Zustand setSession() stores access token/user and refresh token.
4. On failure, Zustand clearSession() clears session.

Deep link reset password:

6.2 Auth Navigator

Auth stack screens:

6.3 Main Navigator

MainNavigator selects a role navigator from the authenticated user's role:

MainNavigator also starts:

• push notification token registration;
• notification realtime stream.

6.4 Shared Role Tab Navigator

RoleTabNavigator provides:

• bottom tab navigation;
• shared app header;
• role-specific tabs;
• hidden screens for stack-like flows;
• safe-area-aware tab bar sizing;
• notification bell for OWNER and TECHNICIAN.

7. Role Navigation Map

7.1 ADMIN

Visible tabs:

Hidden screens:

• AdminAddUser
• AdminDetailUser
• AdminEditUser

7.2 MANAGER

Visible tabs:

7.3 OWNER

Visible tabs:

Hidden screens:

• FarmingLog
• Notifications
• PondDetail
• CreateProblem
• ProblemDetail
• TodoForm

7.4 TECHNICIAN

Visible tabs:

Hidden screens:

• TechIncidentDetail
• TechIncidentAccept
• Notifications
• PondDetail

8. State Management Architecture

8.1 Zustand Auth Store

core/store/auth.store.ts owns authenticated session state.

State:

Actions:

8.2 Token Storage

Refresh token storage:

expo-secure-store key: auth.refreshToken

General storage abstraction:

AsyncStorage JSON get/set/remove

Security rule:

• Refresh token must stay in SecureStore.
• Access token is kept in Zustand state and attached by the API client.

8.3 TanStack Query

queryClient defaults:

Domain hooks use Query Client invalidation after mutations.

9. API Integration Architecture

9.1 API Client

core/config/api-client.ts creates the Axios client.

Current config:

9.2 Refresh Flow

When a request receives 401:

1. Login and refresh requests are excluded from retry.
2. If refresh token is missing, session is cleared.
3. If a refresh is already in progress, requests wait in a queue.
4. Refresh uses SecureStore refresh token.
5. Refresh request sends:
   • body { refreshToken };
   • x-client-type: mobile;
   • x-refresh-token: <refreshToken>.
6. On success, setSession() updates auth store and refresh token.
7. Queued requests replay with the new access token.
8. On failure, queue rejects and session is cleared.

Mobile refresh flow is intentionally different from web because native clients do not rely on browser httpOnly cookie behavior.

9.3 API Services

Current domain API services:

10. Domain Hooks Architecture

Hooks live in core/hooks and are the preferred screen-facing API.

Current hook areas:

Architecture rule:

• Screens should call hooks, not raw API services, when a hook exists.
• Hooks should own cache keys, invalidation and toast side effects.

11. Feature Modules

Current feature grouping:

12. Notifications Architecture

Mobile notifications have three layers:

1. REST list/stats/read/delete APIs.
2. SSE realtime stream.
3. Expo push token registration.

Realtime stream:

• Starts when authenticated.
• Uses fetch with Accept: text/event-stream.
• Sends Authorization: Bearer <accessToken>.
• Sends x-client-type: mobile.
• Listens for event type notification.created.
• Invalidates notification queries on matching event.
• Reconnect delay is 5 seconds.
• Stops when AppState is not active and reconnects when active.

Push registration:

• Ensures Android notification channel.
• Requests notification permission.
• Uses Expo project ID from app config.
• Registers Expo push token with backend.
• Failures are swallowed because REST/SSE remains source of truth.

13. Theme And Design System Integration

Theme provider:

ThemeProvider -> useTheme()

Theme tokens:

Current reusable components:

Current design-system gap:

• Core theme primary color is blue, while many production screens use AquaX teal hardcoded values such as #00796B, #006B5F, #005D4E.
• Future cleanup should align core theme tokens with the AquaX teal palette before expanding token usage.

14. File Upload And Native Capabilities

Confirmed native capabilities:

FormData behavior:

• API client removes Content-Type when request body is FormData.
• Ticket and farming-log attachment services append native file objects.

15. Build, CI And Release Considerations

Package scripts:

Android release script:

mobile/scripts/deploy_android_playstore.sh

Confirmed release flow:

1. Load mobile/secrets/build_config.env if present.
2. Detect Android keystore from mobile/secrets.
3. Require Google Play service account JSON.
4. Run npm install.
5. Run npx expo prebuild --platform android --clean.
6. Set Android versionCode.
7. Run Gradle bundleRelease.
8. Upload AAB with Fastlane supply.

Supported tracks:

• internal
• alpha
• beta
• production

Release gaps:

• iOS TestFlight/App Store release process is not documented in repo.
• Mobile CI/CD is not wired into GitHub Actions.
• Android release script mutates app.json versionCode during release; this should be handled carefully in release branches.

16. Performance And UX Considerations

Current confirmed patterns:

• TanStack Query caches server state.
• Infinite query is used for activity logs.
• Pond detail loads multiple tab queries in parallel.
• Device tab and water timeseries poll while viewing pond detail.
• Notification stream suspends when app is not active.
• Keyboard-aware helper exists for long forms.
• Safe-area-aware layout is used in Screen and tab/header UI.

Current gaps:

• No mobile performance budget is documented.
• No crash/error monitoring provider is confirmed.
• Large screens contain substantial local styles and may need decomposition as features grow.

17. Security And Privacy Considerations

Confirmed controls:

• Refresh token stored in Expo SecureStore.
• API client sends x-client-type: mobile.
• Access token is attached only through Axios interceptor.
• Refresh queue prevents parallel refresh storms.
• Session restore clears local state when refresh fails.

Risks:

18. Architecture Risks And Action Items

19. Change Rules

When changing mobile architecture:

1. Add route types to core/types/navigation.types.ts.
2. Register screens in the correct role navigator.
3. Add endpoint constants in core/constants/apiURL.constants.ts.
4. Add or update API service wrapper in core/services/api.
5. Add or update domain hook in core/hooks.
6. Keep refresh token handling inside SecureStore-backed auth store.
7. Keep server-state cache/invalidation in hooks.
8. Update docs/08_API Specification.md for contract changes.
9. Update this file when navigation, auth, storage, notification or release architecture changes.
10. Run npm run lint and npm run typecheck for mobile code changes.

20. Traceability