Sauci/apps/mobile/agents.md

Mobile App - Agent Guidelines

STRICT RULES - DO NOT VIOLATE

Architecture

This is an Expo React Native app using:

• Routing: expo-router with file-based routing in app/ directory
• State: Zustand stores in src/store/index.ts
• Backend: Supabase client in src/lib/supabase.ts
• UI: Glass-morphism themed components in src/components/ui/
• Theme: Centralized theme in src/theme/index.ts

Directory Structure

app/                    # Expo Router routes
  (auth)/               # Authentication screens
  (app)/                # Protected app screens (tabs)
src/
  components/           # Reusable components
    ui/                 # Base UI components (GlassCard, GlassButton, etc.)
  lib/                  # Utilities (supabase, analytics, revenuecat)
  store/                # Zustand stores (index.ts)
  theme/                # Theme constants (colors, gradients, spacing, etc.)
  types/                # TypeScript types

Critical Rules

Tab Bar - NEVER CHANGE

NEVER set backgroundColor: 'transparent' on the tab bar.

Always use:

backgroundColor: 'rgba(18, 18, 18, 0.85)',

The BlurView in tabBarBackground is unreliable. The solid rgba background acts as a fallback.

Location: app/(app)/_layout.tsx - tabBarStyle

State Management

• Use existing Zustand stores: useAuthStore, useMatchStore, usePacksStore, useMessageStore, useSubscriptionStore
• Access cross-store state via getState() (e.g., useAuthStore.getState().user)
• Clear related stores on sign out (see signOut in useAuthStore)

Supabase Queries

• Always use .maybeSingle() instead of .single() when the row might not exist
• .single() throws an error if 0 or >1 rows are returned
• Check for null before performing operations

UI Components

Use existing UI primitives from src/components/ui/:

• GlassCard - Glass-morphism card container
• GlassButton - Glass-styled button
• GlassInput - Glass-styled input field
• GradientBackground - Screen background gradient
• ShimmerEffect - Loading shimmer animation

Theme Usage

Import from src/theme/index.ts:

import { colors, gradients, spacing, radius, typography, shadows } from '@/theme';

DO NOT hardcode colors. Always use theme values.

Response Handling

• Responses use UPSERT with onConflict: "user_id,question_id"
• Match detection happens in submit-response edge function

Typing

• Import shared types from @/types
• Import Supabase types from @/types/supabase

RevenueCat

• RevenueCat service in src/lib/revenuecat.ts
• Does not work in Expo Go - check revenueCatService.isAvailable() first
• Initialize with user ID after auth

Analytics

• Use Events from src/lib/analytics for tracking
• Track: packEnabled, packDisabled, signOut, etc.

Forbidden Actions

1. DO NOT change tab bar background to transparent
2. DO NOT use .single() for queries that might return 0 rows
3. DO NOT hardcode colors - use theme values
4. DO NOT create new stores without integrating with auth sign-out cleanup
5. DO NOT bypass RevenueCat availability checks
6. DO NOT add navigation logic outside of expo-router