as-app/cline_docs/systemPatterns.md

System Patterns

Architecture Overview

• React Native mobile application
• GraphQL with Hasura backend
  • Federation of remote schemas
  • Real-time subscriptions support
  • Custom business logic through remote schemas
• Firebase for FCM push notifications
• Component-based architecture

Key Technical Patterns

GraphQL Subscription Management

1. Subscription Lifecycle:

   • Unique subscriptionKey for each subscription instance
   • Unconditional cleanup in useEffect hooks
   • Proper cleanup on:
     • Component unmount
     • Variables change
     • Skip condition change
   • Detailed logging for debugging

2. Cache Management:

   • Isolated cache contexts:
     • Alert-specific: alert:${alertId}
     • Aggregate view: aggregate-messages
   • Cache cleanup on:
     • Component mount
     • Component unmount
     • Variables change
   • Strict message filtering by alertId

3. Message Handling:

   • Alert-specific filtering
   • Aggregate view with oneAlert field
   • Optimistic updates per cache context

State Management

• Apollo Client for GraphQL state management
• Local stores for app state
• Loading states tied to specific actions (e.g., SMS type)

Component Structure

1. Components (src/components/)

   • Reusable UI components
   • Presentational components
   • Theme-aware components (e.g., LittleLoader)

2. Containers (src/containers/)

   • Business logic components
   • Data-fetching components
   • Feature-specific implementations

3. Chat Components:

   • MessagesFetcher:
     • Data fetching and subscription setup
     • Cache context management
     • Message filtering
   • ChatMessages:
     • Message display and UI logic
     • Scroll position management
     • New message indicators
   • AggregateMessages:
     • Cross-alert message display
     • Alert context integration
     • Navigation handling

Authentication Flow

1. SMS Authentication:

   • Registration SMS (type "R")
   • Connection SMS (type "C")
   • Loading states specific to SMS type
   • 3-minute timeout for loading states
   • Automatic clearing on login request

2. Account Management:

   • Modal-based interface
   • Support for both phone and email
   • Loading states based on action type
   • Login request handling

Data Flow

• GraphQL queries and mutations
• Real-time subscriptions
• Event system
• Login request monitoring

Navigation & Deep Linking

• Custom navigation implementation
• Parameter passing for state management
• Modal coordination
• Deep Linking Configuration:

  1. iOS URL Types:

     • Custom scheme (com.alertesecours.alertesecours://)
     • Expo scheme (exp+alerte-secours://)
     • HTTPS scheme for Universal Links
     • Each URL type has proper CFBundleURLName configuration

  2. Universal Links:

     • Associated Domains capability enabled
     • apple-app-site-association file configuration:
       • Proper app ID format (TeamID.BundleID)
       • Wildcard paths pattern
       • Hosted at /.well-known/apple-app-site-association

  3. Deep Link Handling:

     • Expo Linking module integration
     • Initial URL handling
     • Runtime URL event listening
     • Custom handleDeepLink implementation

Error Handling

• Sentry integration for error tracking
• Custom error boundaries and components
• Timeout handling for loading states
• Graceful subscription error handling
• Clear error logging for debugging

UI/UX Patterns

1. Loading States:

   • Action-specific loading indicators
   • Timeout mechanisms
   • Clear loading state triggers

2. Modal Management:

   • Contextual modal opening
   • State preservation
   • Loading state coordination

3. Theme Support:

   • Dark/light theme compatibility
   • Dynamic color filters for animations
   • Consistent styling across components

Testing

• E2E testing with Detox
• Component-level testing
• Flow-specific testing scenarios

Build & Deployment

• Fastlane integration
• Custom build scripts
• Environment-specific configurations

Best Practices

1. Loading State Management:

   • Tie loading states to specific actions
   • Implement timeouts for all loading states
   • Clear loading states on relevant events
   • Keep loading states focused and contextual

2. Component Design:

   • Clear separation of concerns
   • Consistent prop patterns
   • Theme awareness
   • Proper hook usage
   • Form state management:
     • Use react-hook-form for form handling
     • Track form changes via formState.isDirty
     • Disable submit buttons when no changes
     • Consistent disabled state styling (50% opacity)

3. Navigation:

   • Clear parameter passing
   • State management through navigation
   • Modal coordination

4. Authentication:

   • Type-specific SMS handling
   • Clear loading feedback
   • Proper timeout handling
   • Login request monitoring

5. Subscription Management:

   • Always provide cleanup functions in useEffect, even for effects that don't seem to need cleanup
   • Use proper cache isolation between views
   • Implement strict message filtering
   • Add detailed logging for debugging
   • Handle optimistic updates carefully
   • Clean up subscriptions before setting up new ones
   • Track component lifecycle with refs instead of let variables
   • Ensure consistent hook behavior across all effects
   • Maintain proper cleanup order in effects

6. Hook Usage Rules:

   • All useEffect hooks must return cleanup functions consistently
   • Use refs for mutable state that persists across renders
   • Track mounted state through refs, not variables
   • Clean up all subscriptions and side effects on unmount
   • Keep hook dependencies accurate and complete
   • Handle async operations safely with mounted checks
   • Ensure proper cleanup order when multiple effects interact