Mobile App Architecture

Why This Matters

The mobile app is the primary consumer touchpoint for Nous. It handles:

Daily self-discovery (photo prompts, video reflections)
AI-powered conversations (Vicky wingman)
Discovery and matching
Relationship tools (Caring Moments, Official Flag)

A well-structured architecture ensures the team can iterate quickly while maintaining code quality across iOS and Android.

Directory Structure

apps/mobile — Expo React Native application app/ — Expo Router file-based routing

_layout.tsx — Root layout with native navigation
capture.tsx — Video moment capture flow
user-settings.tsx — User profile settings
app-modal.tsx — Modal presentation

app/(onboarding)/ — First-time user onboarding

_layout.tsx, onboarding-splash.tsx, onboarding-philosophy.tsx
camera-permission.tsx, notification-permission.tsx

app/(tabs)/ — Main tab navigation (Home, Discover, Messages)

_layout.tsx — Tab bar configuration
index.tsx — Home (daily content + LMS)
discover.tsx — Map + activities discovery
messages.tsx — Matches list
profile.tsx — User profile (standalone route, not a tab)

app/ — Standalone routes

design-system.tsx — Design system preview (standalone route, not a tab)

app/chat/ — Chat routes

[id].tsx — Individual match conversation
vicky.tsx — Direct Vicky AI wingman chat

app/moment/ — Moment detail

[id].tsx — Single moment view

components/ — Reusable UI components

ui/ — Primitive components
home/ — Home screen components
chat/ — Chat UI components
discover/ — Discovery feature components
messages/ — Messages list components
features/ — Feature-specific components
shared/ — Cross-feature shared components

hooks/ — Custom React hooks lib/ — Services and utilities services/ — API service layers constants/ — App-wide constants types/ — TypeScript type definitions data/ — Static data and mock data assets/ — Images, fonts, etc.

The backend (Hono/tRPC) and frontend (Next.js) services were removed from this repo in May 2026. The mobile app communicates directly with the Mastra AI runtime for all features.

Root Layout (`app/_layout.tsx`)

The root layout wraps the entire app with native navigation primitives and providers. Main navigation uses Expo Router’s native tab trigger system:

Tab	File	Icon	Purpose
Home	`index.tsx`	House icon	Daily content, LMS courses
Discover	`discover.tsx`	Sparkles icon	Activities discovery
Messages	`messages.tsx`	Chat icon	Match conversations, Vicky AI
Search	—	Magnifying glass	Not yet implemented

The Assistant tab was removed — Vicky AI is accessed via the Messages tab header. User settings are accessed via app/user-settings.tsx. A Search tab trigger exists in the tab layout but search.tsx has not been implemented (no corresponding route file).

Onboarding Flow (`app/(onboarding)/`)

First-time users experience a curated onboarding:

Splash — Brand introduction
Philosophy — App values and approach
Camera Permission — Required for self-discovery features
Notification Permission — For matches and messages

Chat Routes

Route	File	Purpose
Chat	`chat/[id].tsx`	Individual match conversation
Vicky Chat	`chat/vicky.tsx`	Direct Vicky AI wingman chat

Custom Hooks

AI & Chat Hooks

Hook	Purpose
`use-vicky-chat.ts`	Vicky AI wingman chat (streams from Mastra agent)
`use-chat-stream.ts`	Nous AI chat (streams from Mastra `/api/chat/stream`)
`use-conversation-starter.ts`	AI-generated conversation openers

Data & State Hooks

Hook	Purpose
`use-color-scheme.ts`	System color scheme (light/dark)
`use-color-scheme-web.ts`	Web-specific color scheme
`use-theme-color.ts`	App theme color management
`use-discover-data.ts`	Discovery feed data
`use-moments.ts`	User moments/video timeline

Key Services

LMS Service (`services/lms-service.ts`)

Direct fetch calls to Mastra LMS endpoints. Used in app/(tabs)/index.tsx for the home screen courses list.

const MASTRA_URL =
  process.env.EXPO_PUBLIC_MASTRA_URL ?? 'https://nous-mastra.curlynguyen95.workers.dev'

export async function getPublishedCourses(): Promise<Course[]>
export async function getCourseById(courseId: string): Promise<CourseDetail>
export async function getUserEnrollments(userId: string): Promise<unknown[]>
export async function enrollInCourse(userId: string, courseId: string): Promise<void>
export async function updateLessonProgress(
  userId: string,
  lessonId: string,
  watchedSeconds: number
): Promise<void>

lib/api-client.ts contains TanStack Query hooks for the same LMS endpoints, but these are not yet integrated into the app — services/lms-service.ts is currently used directly.

Matches Service (`services/matches-service.ts`)

Match and conversation management:

export async function getMatches(userId: string): Promise<Match[]>
export async function getMatchById(matchId: string): Promise<Match | null>
export async function getMessages(matchId: string): Promise<MessageData[]>
export async function sendMessage(matchId: string, content: string, userId: string): Promise<void>

Utilities (`lib/utils.ts`)

Standard utility functions including cn() for Tailwind class merging.

API Client (`lib/api-client.ts`)

TanStack Query hooks wrapping LMS API with caching and state management. Defined but not yet integrated into app components.

export function useCourses() // Fetch all published courses
export function useCourse(courseId) // Fetch single course with lessons
export function useEnroll() // Enroll in a course
export function useEnrollments(userId) // Get user's enrolled courses
export function useUpdateProgress() // Update lesson progress
export function useVideoUrl(lessonId) // Get video streaming URL

Cloudflare Stream (`lib/cloudflare-stream.ts`)

Video upload and streaming via Cloudflare Stream:

export class CloudflareStream {
  async listVideos(): Promise<StreamVideo[]>
  async getVideo(uid: string): Promise<StreamVideo | null>
  async createUploadUrl(videoName: string, description?: string): Promise<StreamUploadResponse>
  async uploadVideo(
    filePath: string,
    videoName: string,
    description?: string,
    onProgress?: (progress: number) => void
  ): Promise<StreamVideo>
  async deleteVideo(uid: string): Promise<boolean>
}

Mobile API (`lib/mobile-api.ts`)

Mobile-specific API client for match and conversation operations.

Mobile Polyfills (`lib/mobile-polyfills.ts`)

Platform-specific polyfills for React Native compatibility.

Memory (`lib/memory/`)

AI SDK + Mastra memory integration documentation and setup:

2026-04-23-ai-sdk-mastra-first.md — Initial integration notes

UI Components

Primitive UI (`components/ui/`)

Core reusable components:

Component	Purpose
`button.tsx`	Primary button with variants
`card.tsx`	Card container
`gradient-background.tsx`	App-wide gradient theming
`iconSymbol.tsx`	SF Symbols / Material Icons mapping
`loading-dots.tsx`	Loading indicator
`error-boundary.tsx`	Error catching and display
`section-title.tsx`	Section heading component
`icon-button.tsx`	Icon-only button

Home Components (`components/home/`)

Component	Purpose
`home-header.tsx`	Header with date and greeting
`daily-content.tsx`	Daily prompt and inspirational content
`capture-button.tsx`	Video capture trigger
`moments-timeline.tsx`	User’s video moments feed
`timeline.tsx`	Timeline view component

Chat Components (`components/chat/`)

Component	Purpose
`chat-header.tsx`	Chat screen header with back button
`message-item.tsx`	Individual message bubble
`message-input.tsx`	Text input with send button
`suggestion-chips.tsx`	AI-suggested responses
`schedule-message.tsx`	Date/event scheduling card
`text-bubble.tsx`	Text message bubble
`image-message.tsx`	Image attachment message
`ai-toggle-pill.tsx`	AI enable/disable toggle
`ai-button.tsx`	AI action button
`avatar.tsx`	User/match avatar
`bento-grid.tsx`	Bento-style layout grid
`bento-image-wrapper.tsx`	Image wrapper for bento grid
`chat-back-button.tsx`	Back navigation
`gift-message.tsx`	Gift/caring moment message
`gradient-message.tsx`	Gradient-styled message
`grain-overlay.tsx`	Grain texture overlay
`poke-message.tsx`	Poke notification message
`schedule-date-row.tsx`	Date row in schedule
`schedule-location-row.tsx`	Location row in schedule
`send-button.tsx`	Message send button
`suggestion-chip.tsx`	Individual suggestion chip
`suggestion-error.tsx`	Suggestion error state
`suggestion-header.tsx`	Suggestion section header
`suggestion-loading.tsx`	Suggestion loading state
`chat-input-accessory.tsx`	Input accessory view

Messages Components (`components/messages/`)

Component	Purpose
`nous-button.tsx`	Nous action button
`connection-avatar.tsx`	Connection avatar
`connection-content.tsx`	Connection content
`connection-divider.tsx`	Connection list divider
`connection-online-dot.tsx`	Online status indicator
`connection-row.tsx`	Connection list item
`messages-header.tsx`	Messages list header
`connection-actions.tsx`	Connection action buttons

Discover Components (`components/discover/` and `components/features/discover/`)

components/discover/ — Top-level discover components:

Component	Purpose
`discover-header.tsx`	Discovery screen header

components/features/discover/ — Feature-specific discover components:

Component	Purpose
`category-pill.tsx`	Category filter pill
`category-pills-row.tsx`	Horizontal category pills scroll
`detail-sheet.tsx`	Event detail bottom sheet
`event-card-badge.tsx`	Event card badge
`event-card-host.tsx`	Event host info
`event-card-meta.tsx`	Event metadata (date, time, price)
`event-card-price.tsx`	Event price display
`event-card.tsx`	Event card component
`events-section.tsx`	Events list section
`host-card.tsx`	Host information card
`invitation-card.tsx`	Invitation card
`invitations-section.tsx`	Invitations list section
`map-marker.tsx`	Map marker component
`map-section.tsx`	Map view section
`meta-item.tsx`	Metadata item

Profile Components (`components/features/profile/`)

Component	Purpose
`premium-badge.tsx`	Premium tier badge
`profile-avatar.tsx`	Profile avatar with status
`profile-header.tsx`	Profile screen header
`profile-hero-overlay.tsx`	Hero image overlay
`profile-hero.tsx`	Profile hero section
`profile-stats-row.tsx`	Stats row (matches, etc.)
`settings-row.tsx`	Settings list item
`settings-section.tsx`	Settings group section
`stat-card.tsx`	Stat display card

Home Feature Components (`components/features/home/`)

Component	Purpose
`empty-day.tsx`	Empty state for no content
`day-header.tsx`	Day/section header
`fullscreen-viewer.tsx`	Fullscreen media viewer
`moment-bento-grid.tsx`	Bento grid for moments
`video-card.tsx`	Video content card

Settings Components (`components/settings/`)

Component	Purpose
`settings-section.tsx`	Settings group section
`settings-header.tsx`	Settings page header
`settings-row.tsx`	Settings list item

Shared Components (`components/shared/`)

Component	Purpose
`haptic-tab.tsx`	Tab with haptic feedback
`themed-text.tsx`	Theme-aware text
`themed-view.tsx`	Theme-aware view

Design System Components (`components/design-system/`)

Component	Purpose
`button-demo.tsx`	Button component demo
`color-row.tsx`	Color palette row
`swatch.tsx`	Color swatch display
`typography-demo.tsx`	Typography showcase

State Management

TanStack Query

Data fetching and caching uses TanStack Query:

Courses and enrollments cached automatically
Optimistic updates for enrollments
Background refetch on focus

React Context

Navigation and global state via React Context:

Theme colors and styling constants
Safe area insets for notch handling
Auth state via Clerk

Key Dependencies

expo-router

File-based routing

@tanstack/react-query

Server state management

ai

AI SDK for streaming chat

expo-image-picker

Camera and gallery access

expo-sensors

Accelerometer for shake-to-capture

expo-haptics

Tactile feedback

expo-image

Optimized image loading

react-native-safe-area-context

Safe area handling

Last Updated: 2026-05-13

​Mobile App Architecture

​Why This Matters

​Directory Structure

​Navigation Architecture

​Root Layout (app/_layout.tsx)

​Tab Navigation (app/(tabs)/_layout.tsx)

​Onboarding Flow (app/(onboarding)/)

​Chat Routes

​Custom Hooks

​AI & Chat Hooks

​Data & State Hooks

​Key Services

​LMS Service (services/lms-service.ts)

​Matches Service (services/matches-service.ts)

​Utilities (lib/utils.ts)

​API Client (lib/api-client.ts)

​Cloudflare Stream (lib/cloudflare-stream.ts)

​Mobile API (lib/mobile-api.ts)

​Mobile Polyfills (lib/mobile-polyfills.ts)

​Memory (lib/memory/)

​UI Components

​Primitive UI (components/ui/)

​Home Components (components/home/)

​Chat Components (components/chat/)

​Messages Components (components/messages/)

​Discover Components (components/discover/ and components/features/discover/)

​Profile Components (components/features/profile/)

​Home Feature Components (components/features/home/)

​Settings Components (components/settings/)

​Shared Components (components/shared/)

​Design System Components (components/design-system/)

​State Management

​TanStack Query

​React Context

​Key Dependencies

expo-router

@tanstack/react-query

ai

expo-image-picker

expo-sensors

expo-haptics

expo-image

react-native-safe-area-context

Mobile App Architecture

Why This Matters

Directory Structure

Navigation Architecture

Root Layout (`app/_layout.tsx`)

Tab Navigation (`app/(tabs)/_layout.tsx`)

Onboarding Flow (`app/(onboarding)/`)

Chat Routes

Custom Hooks

AI & Chat Hooks

Data & State Hooks

Key Services

LMS Service (`services/lms-service.ts`)

Matches Service (`services/matches-service.ts`)

Utilities (`lib/utils.ts`)

API Client (`lib/api-client.ts`)

Cloudflare Stream (`lib/cloudflare-stream.ts`)

Mobile API (`lib/mobile-api.ts`)

Mobile Polyfills (`lib/mobile-polyfills.ts`)

Memory (`lib/memory/`)

UI Components

Primitive UI (`components/ui/`)

Home Components (`components/home/`)

Chat Components (`components/chat/`)

Messages Components (`components/messages/`)

Discover Components (`components/discover/` and `components/features/discover/`)

Profile Components (`components/features/profile/`)

Home Feature Components (`components/features/home/`)

Settings Components (`components/settings/`)

Shared Components (`components/shared/`)

Design System Components (`components/design-system/`)

State Management

TanStack Query

React Context

Key Dependencies