Mobile Architecture

The mobile app is built with Expo (React Native) and TypeScript. It targets iOS and Android from a single codebase.

Expo Router (File-Based Routing)

Screens are defined by their file path in the app/ directory:

app/
  _layout.tsx              → Root layout (auth redirect logic)
  (auth)/
    login.tsx              → /login
    signup.tsx             → /signup
  (tabs)/
    _layout.tsx            → Tab bar layout
    index.tsx              → Home tab
    tasks.tsx              → Tasks tab
    calendar.tsx           → Calendar tab
    settings.tsx           → Settings tab
  tasks/
    new.tsx                → New task screen
    [id].tsx               → Task detail
    ai-preview.tsx         → AI parse preview
  settings/
    household.tsx          → Household management
  subscription/
    index.tsx              → Paywall
  templates.tsx            → Life templates browser
  first-task.tsx           → Onboarding
  reset-password.tsx       → Deep link password reset

The root _layout.tsx checks auth state and redirects unauthenticated users to (auth)/login.

React Query for Server State

All API data fetching uses React Query (TanStack Query). This provides:

Automatic caching -- Data is cached by query key and revalidated on focus
Optimistic updates -- Task completion updates the UI immediately, then syncs with the server
Background refetch -- Stale data is refreshed when the app returns to foreground
Query invalidation -- After mutations, related queries are invalidated to trigger re-fetch

The API client is Axios, configured in services/api.ts with an interceptor for JWT token refresh.

Contexts

Context	Purpose
`AuthContext`	Manages auth state, tokens, user object. Provides `login`, `logout`, `refreshUser`
`TasksFilterContext`	Manages active filter state (status, category, search) across the tasks tab

These are lightweight contexts for UI state. Server state lives in React Query.

Component Patterns

Screen components live in app/ (Expo Router convention)
Reusable components live in components/
Business logic lives in services/ (API calls, notification scheduling, RevenueCat, etc.)
Constants live in constants/ (theme colors, level definitions)

Key components:

Component	Purpose
`HomeV2`	Home screen with dashboard stats, suggestions, quick actions
`SwipeableTaskRow`	Swipeable row with complete (right) and delete (left)
`CategoryFilter`	Horizontal pill filter for categories
`VoiceInput`	Voice recording with Deepgram streaming or native fallback
`QuickEditBar`	Natural language edit input (Pro only)
`ConfettiOverlay`	Celebration animation on task completion
`WeekCompleteCard`	Celebration when all weekly tasks are done
`LevelBadge` / `LevelJourneySheet`	Gamification UI
`SuggestionsCard`	AI task suggestions on the home screen

Offline Behavior

The app is offline-tolerant:

React Query cache persists across app restarts
When offline, cached data is displayed with a connection banner
Mutations are queued and retried when connectivity returns
Local notifications work fully offline

Root Layout
├── (auth) — Login, Signup, Onboarding
└── (tabs) — Main app
    ├── Home — Dashboard, suggestions
    ├── Tasks — Task list with filters
    ├── Calendar — Monthly view with stats
    └── Settings — Profile, household, subscription

Mobile Architecture ​

Expo Router (File-Based Routing) ​

React Query for Server State ​

Contexts ​

Component Patterns ​

Offline Behavior ​