# uta-ecosystem: UTA Ecosystem Overview
URL: https://dev.updatetheapp.com/docs/uta-ecosystem
Documentation: https://dev.updatetheapp.com/docs/uta-ecosystem

Understanding how the UTA ecosystem components work together to accelerate React Native development while maintaining platform independence.
        
***

title: UTA Ecosystem Overview
description: Understanding how the UTA ecosystem components work together to accelerate React Native development while maintaining platform independence.
---------------------------------------------------------------------------------------------------------------------------------------------------------

import { Callout } from 'fumadocs-ui/components/callout';
import { Steps, Step } from 'fumadocs-ui/components/steps';
import { Card, Cards } from 'fumadocs-ui/components/card';
import { Tabs, Tab } from 'fumadocs-ui/components/tabs';

# UTA Ecosystem Overview

## Overview

The UTA ecosystem provides standardized React Native development patterns and deployment solutions that work independently or together. Rather than creating vendor lock-in, UTA offers proven architectural patterns that enhance any React Native project, regardless of your chosen deployment strategy.

This approach eliminates architectural decision fatigue while maintaining complete freedom in your deployment choices. Whether you use Expo Updates, CodePush, updatetheapp.com, or any other solution, UTA patterns provide the foundation for scalable, maintainable applications.

<Callout type="info">
  **What Makes UTA Different**

  UTA provides architectural guidance that works with **any** deployment solution. The patterns stand on their own merit and can be adopted independently of any specific platform or service.
</Callout>

## Purpose & Scope

This document explains how UTA's components work together while maintaining independence, helping you understand how to adopt UTA patterns regardless of your deployment choices.

**Target Audience**: Architects, technical leads, and development teams evaluating standardized development approaches for React Native projects.

## Prerequisites

To get the most out of this architectural overview, we recommend you first understand these key areas and review the related guides:

* Basic familiarity with React Native development patterns and common challenges
* Understanding of modern JavaScript/TypeScript development workflows and tooling
* Awareness of over-the-air (OTA) update concepts and deployment options in the React Native ecosystem

For implementation-specific guidance and step-by-step instructions, see the [UI Development Getting Started](/docs/ui-development/getting-started) guide after understanding the ecosystem foundations.

## Core Ecosystem Components

<Tabs items={["Overview", "Template Architecture", "Deployment Flexibility", "Documentation System"]}>
  <Tab value="Overview">
    ### Independent Yet Complementary Components

    UTA consists of three independent components that can work together or separately:

    <Cards>
      <Card title="react-native-uta" description="Platform-agnostic React Native template with proven architectural patterns">
        Works with any deployment solution
      </Card>

      <Card title="updatetheapp.com Platform" description="Optional deployment platform for teams who want instant OTA updates">
        One deployment option among many
      </Card>

      <Card title="UTA DevHub" description="Comprehensive development documentation for platform-agnostic development patterns">
        Educational resource for any React Native project
      </Card>
    </Cards>

    **Key Principle**: Each component provides independent value while working well together when combined.
  </Tab>

  <Tab value="Template Architecture">
    ### Platform-Agnostic Development Foundation

    **Purpose**: A production-ready React Native template with battle-tested architectural patterns

    **Core Principles**:

    * **Deployment Neutral**: Works with Expo Updates, CodePush, updatetheapp.com, or any OTA solution
    * **Proven Patterns**: Pre-selected architectural approaches that have been tested across different projects
    * **Immediate Productivity**: Fork, setup, and start building features from day one

    **What's Included**:

    * Feature-Domain Hybrid architecture (UI organization + business logic separation)
    * Standardized state management patterns with Zustand
    * API integration patterns using TanStack Query
    * Comprehensive testing strategies and utilities
    * AI-optimized code patterns for better development assistance

    **Benefits for Your Team**:

    * Eliminates architectural decision paralysis across projects
    * Ensures consistent code patterns regardless of deployment choice
    * Dramatically reduces onboarding time for new developers
    * Provides immediate AI assistance with high accuracy
  </Tab>

  <Tab value="Deployment Flexibility">
    ### Choose Your Deployment Strategy

    **Purpose**: UTA patterns work with any React Native deployment approach

    **Supported Deployment Options**:

    * **Expo Updates**: Native integration with Expo's OTA update system
    * **CodePush**: Microsoft's OTA update solution for React Native
    * **updatetheapp.com**: UTA's own deployment platform with advanced features
    * **Custom Solutions**: Any deployment strategy that supports JavaScript bundle updates

    **Platform-Specific Optimizations**:

    * Configuration templates for popular deployment services
    * Environment-specific build scripts and configurations
    * Deployment workflow examples for different platforms
    * Migration guides between deployment solutions

    **No Vendor Lock-in**:

    * Template code remains independent of deployment choice
    * Switch deployment platforms without architectural changes
    * Test different deployment strategies without code modifications
  </Tab>

  <Tab value="Documentation System">
    ### Educational Resource Architecture

    **Purpose**: Comprehensive documentation that serves development needs regardless of deployment choice

    **Documentation Strategy**:

    * **Development Patterns**: Architectural guidance that applies to any React Native project
    * **Deployment Examples**: Show multiple deployment options, not just one platform
    * **AI Training Context**: Machine-readable patterns optimized for AI assistance

    **Key Benefits**:

    * Learn patterns that transfer to any React Native project
    * Compare different deployment strategies with real examples
    * Access consistent architectural guidance regardless of your platform choices
    * Get AI assistance that understands modern React Native patterns

    **Educational Philosophy**:

    * Explain the "why" behind architectural decisions
    * Show multiple implementation approaches when relevant
    * Provide migration paths between different solutions
    * Focus on long-term maintainability over vendor-specific features
  </Tab>
</Tabs>

## How the Components Work Together

The UTA ecosystem creates value through **independent excellence** rather than forced integration:

**Template** → **Documentation** → **Deployment Choice**

* **react-native-uta template** provides proven architectural patterns that work anywhere
* **UTA DevHub documentation** offers comprehensive guidance for any React Native project
* **Your deployment choice** can be any solution that fits your needs (Expo, CodePush, updatetheapp.com, custom)

This independent approach ensures that adopting UTA patterns doesn't lock you into any specific deployment platform, while providing examples of how these patterns work well with various deployment strategies.

## Documentation Strategy: Platform-Neutral Guidance

UTA documentation focuses on architectural patterns that work with any deployment solution, while providing specific examples for popular platforms.

### Development Focus: UTA DevHub (This Site)

**Purpose**: UTA DevHub - comprehensive development guide for platform-agnostic React Native patterns\
**Target Audience**: Developers building applications with modern React Native patterns

**What You'll Find Here**:

* Architecture patterns and design decisions with detailed explanations
* UI component development guidelines and best practices
* State management implementation using modern patterns
* API integration approaches with TanStack Query
* Development workflows that work with any deployment platform

### Platform-Specific Examples

**Purpose**: Show how UTA patterns work with different deployment solutions\
**Target Audience**: Teams evaluating or implementing specific deployment strategies

**Deployment Examples Covered**:

* Expo Updates configuration and workflow
* CodePush integration and release management
* updatetheapp.com deployment and monitoring
* Custom deployment pipeline setup

<Callout type="info">
  **Educational Approach**

  * **How to architect** → UTA DevHub patterns (platform-neutral)
  * **How to deploy** → Multiple examples showing different platforms
  * **How to choose** → Decision frameworks for evaluating deployment options
</Callout>

## Complete Developer Journey

Understanding how UTA works in practice, regardless of your deployment choice:

<Steps>
  <Step>
    ### Foundation: Start with Proven Architecture

    Begin with the react-native-uta template that provides battle-tested patterns:

    **What Happens**:

    * Fork a production-ready template with established architectural patterns
    * Run automated setup that configures your development environment
    * Access comprehensive documentation and AI-optimized patterns

    **Immediate Benefits**:

    * Day one productivity with zero architectural decisions required
    * Consistent patterns that work with any deployment strategy
    * AI assistance that understands your codebase from the start

    **Why This Matters**: Instead of spending weeks debating state management libraries or folder structures, your team starts building features immediately with patterns that work everywhere.
  </Step>

  <Step>
    ### Development: Build with Proven Patterns

    Develop features using pre-established, deployment-agnostic architectural patterns:

    **Standardized Patterns**:

    * **State Management**: Zustand for predictable, scalable state handling
    * **API Layer**: TanStack Query for robust data fetching and caching
    * **UI Architecture**: Feature-Domain Hybrid system for maintainable organization
    * **Testing Strategy**: Comprehensive testing patterns built into the template

    **Key Principle**: Follow proven patterns that enhance maintainability regardless of your deployment platform.

    **Team Benefits**: Code reviews become faster, onboarding becomes easier, and everyone writes code that works consistently across different deployment environments.
  </Step>

  <Step>
    ### Deployment: Choose Your Strategy

    Deploy using whichever solution best fits your needs:

    **Popular Options**:

    ```bash
    # Expo Updates
    expo publish --channel production

    # CodePush
    appcenter codepush release-react MyApp-iOS

    # updatetheapp.com
    uta deploy --production

    # Custom solution
    npm run build:release && ./deploy-script.sh
    ```

    **Business Impact**: Ship updates using the deployment strategy that best matches your team's needs and constraints.

    <Callout type="success">
      **Real-World Flexibility**: Teams have successfully used UTA patterns with Expo Updates for rapid prototyping, CodePush for enterprise deployment, updatetheapp.com for managed deployment, and custom solutions for specialized requirements.
    </Callout>
  </Step>

  <Step>
    ### Iteration: Maintain Development Velocity

    Maintain momentum with your chosen deployment approach:

    **Continuous Improvement**:

    * Monitor application performance and user behavior
    * Push feature updates using your preferred deployment method
    * Switch deployment platforms if needs change (architectural patterns remain the same)
    * All operations work independently of UTA-specific services

    **Long-term Benefits**: Your team maintains high velocity because architectural patterns remain consistent even if deployment strategies evolve.
  </Step>
</Steps>

## Why This Ecosystem Approach Works

<Tabs items={["For Developers", "For Teams", "For Business"]}>
  <Tab value="For Developers">
    ### Individual Developer Benefits

    **Platform-Independent Productivity**:

    * **(Do ✅) Day 1 Productivity**: Fork and start building immediately with any deployment target
    * **(Do ✅) Eliminate Decision Fatigue**: Proven patterns work consistently across platforms
    * **(Do ✅) AI-Assisted Development**: Achieve high accuracy with standardized patterns
    * **(Do ✅) Deployment Flexibility**: Ship updates using the platform that best fits your project

    **Learning & Growth**:

    * Learn industry-standard patterns that transfer to any React Native project
    * Focus on business logic instead of architectural plumbing
    * Get immediate feedback through consistent, predictable development patterns
    * Build confidence with patterns that work regardless of deployment choice
  </Tab>

  <Tab value="For Teams">
    ### Team Collaboration Benefits

    **Organizational Efficiency**:

    * **(Do ✅) Reduced Context Switching**: Standardized patterns mean less time debating approaches
    * **(Do ✅) Faster Onboarding**: New developers become productive within days, not weeks
    * **(Do ✅) Streamlined Code Reviews**: Everyone follows consistent patterns and conventions
    * **(Do ✅) Deployment Flexibility**: Team can evaluate and switch deployment platforms without architectural changes

    **Collaboration Improvements**:

    * Shared vocabulary and patterns reduce miscommunication
    * Standardized architecture makes it easy to work on any part of the codebase
    * Consistent testing patterns ensure reliable quality across all deployment targets
    * Documentation that everyone can contribute to and benefit from
  </Tab>

  <Tab value="For Business">
    ### Strategic Business Advantages

    **Competitive Benefits**:

    * **(Do ✅) Ship Faster**: From code to production using your preferred deployment method
    * **(Do ✅) Risk Reduction**: Proven patterns reduce architectural risks across platforms
    * **(Do ✅) Platform Independence**: Avoid vendor lock-in with deployment-agnostic patterns
    * **(Do ✅) Strategic Flexibility**: Evaluate and adopt different deployment strategies as needs evolve

    **Operational Efficiency**:

    * Reduced development costs through faster onboarding and fewer architectural mistakes
    * Lower maintenance overhead with standardized, well-documented patterns
    * Improved reliability through battle-tested architectural decisions
    * Better resource allocation since teams spend time on features, not infrastructure decisions

    **Important Considerations**:

    * **(Be Aware ❗) Learning Investment**: Teams need time to adapt to standardized patterns initially
    * **(Be Aware ❗) Platform Evaluation**: Teams should evaluate deployment options based on their specific needs
    * **(Consider 🤔) Deployment Strategy**: Choose deployment platforms based on requirements, not architectural constraints
  </Tab>
</Tabs>

## Implementation Considerations

### Performance & Scalability

**Deployment-Agnostic Optimization**:

* Monitor bundle size to ensure fast updates regardless of deployment platform
* Implement code splitting patterns that work with any OTA update system
* Balance update frequency with user experience across different deployment strategies

**Application Performance**:

* Built-in performance monitoring through standardized template patterns
* Established patterns for code splitting and lazy loading
* Proven state management patterns that scale with application complexity

### Security & Reliability

**Platform-Independent Security**:

* Secure coding patterns that work with any deployment strategy
* Authentication and authorization patterns that don't depend on specific platforms
* Data protection strategies that remain consistent across deployment environments

**Operational Security**:

* Template includes security best practices for any deployment platform
* Audit trail capabilities that work with multiple deployment solutions
* Monitoring and alerting patterns that adapt to different platforms

### Scalability Aspects

**Team Scaling**:

* Standardized patterns support teams from 1 to 100+ developers
* Consistent architecture reduces coordination overhead as teams grow
* Documentation and AI assistance provide self-service onboarding

**Technical Scaling**:

* Architecture patterns proven to work at scale with real-world applications
* Built-in performance patterns and optimization strategies
* Deployment infrastructure patterns designed for enterprise-scale applications

## Getting Started

<Cards>
  <Card title="Explore Architecture" href="/docs/architecture">
    Understand UTA's architectural principles and design decisions
  </Card>

  <Card title="Start Building" href="/docs/ui-development/getting-started">
    Get hands-on with the react-native-uta template
  </Card>
</Cards>

## Related Documents

For deeper technical implementation details, explore these related resources:

* [UI Development Getting Started](/docs/ui-development/getting-started) - Hands-on guide to building with UTA patterns
* [State Management Architecture](/docs/state-management/state-management-architecture) - Comprehensive guide to modern state management patterns
* [API Client Architecture](/docs/api/client-architecture) - TanStack Query implementation patterns and best practices
* [Team Onboarding Checklist](/docs/guides/team-onboarding-checklist) - Step-by-step guide for new team members

<Callout type="success">
  **The UTA Philosophy**

  UTA represents proven React Native architectural patterns that enhance any project, regardless of deployment choice. By standardizing on battle-tested approaches, your team can focus on what matters most: building exceptional features for your users.
</Callout>


# UTA Architecture: Architecture Documentation
URL: https://dev.updatetheapp.com/docs/architecture
Documentation: https://dev.updatetheapp.com/docs/architecture

Core architectural patterns and design philosophy of the UTA mobile application template
        
***

title: Architecture Documentation
description: Core architectural patterns and design philosophy of the UTA mobile application template
-----------------------------------------------------------------------------------------------------

import { Card, Cards } from 'fumadocs-ui/components/card';
import { ChevronRightIcon } from 'lucide-react';

# Architecture Documentation

## Overview

The UTA mobile application architecture follows a modular, domain-driven design that emphasizes separation of concerns, testability, and maintainability. Our architecture is designed to scale with your application's complexity while providing clear boundaries between different parts of your system.

Our architecture is organized into several interconnected layers:

* **Core Framework** provides fundamental infrastructure and utilities
* **Domain Modules** encapsulate business logic and domain-specific functionality
* **Feature Modules** implement complete user-facing features
* **UI Components** create the visual interface and user interactions

These layers interact with state management systems and external integrations to form a cohesive application architecture.

## Key Architecture Documents

<Cards>
  <Card icon={<ChevronRightIcon />} title="Design Philosophy & Tradeoffs" description="Comprehensive evaluation of architectural strengths, limitations, and decision-making framework for adoption." href="/docs/architecture/design-philosophy-and-tradeoffs" />

  <Card icon={<ChevronRightIcon />} title="Core Architecture" description="Understand the foundational principles, patterns, and structure of the UTA mobile application template." href="/docs/architecture/core-architecture" />

  <Card icon={<ChevronRightIcon />} title="Project Structure" description="Learn about the file and folder organization, and how different parts of the codebase relate to each other." href="/docs/architecture/project-structure" />

  <Card icon={<ChevronRightIcon />} title="Domain Architecture" description="Explore our domain-driven design approach that creates clear boundaries between different parts of your application." href="/docs/architecture/domain-architecture" />
</Cards>

## Architecture Philosophy

Our architecture is built around these core principles:

1. **Separation of Concerns** - Each module has a single responsibility and clear boundaries
2. **Domain-Driven Design** - Business logic is organized into cohesive domains
3. **Unidirectional Data Flow** - Predictable state management with clear update patterns
4. **Feature-First Organization** - Code organized by feature rather than technical layer
5. **Testability** - Architecture designed to facilitate comprehensive testing strategies

## Related Areas

The architecture works together with these other important aspects of the application:

<Cards>
  <Card icon={<ChevronRightIcon />} title="API Architecture" description="Learn how our API clients integrate with backend services, including authentication and error handling." href="/docs/api" />

  <Card icon={<ChevronRightIcon />} title="State Management" description="Understand our approach to managing application state, both globally and locally." href="/docs/state-management" />

  <Card icon={<ChevronRightIcon />} title="Feature Implementation" description="Discover patterns for implementing features in a consistent way across the application." href="/docs/features" />
</Cards>


# UTA Architecture: Design Philosophy & Tradeoffs
URL: https://dev.updatetheapp.com/docs/architecture/design-philosophy-and-tradeoffs
Documentation: https://dev.updatetheapp.com/docs/architecture/design-philosophy-and-tradeoffs

Honest evaluation of UTA's architectural patterns, design decisions, and guidance for teams considering adoption of our Feature-Domain Hybrid approach.
        
***

title: Design Philosophy & Tradeoffs
description: Honest evaluation of UTA's architectural patterns, design decisions, and guidance for teams considering adoption of our Feature-Domain Hybrid approach.
--------------------------------------------------------------------------------------------------------------------------------------------------------------------

import { Card, Cards } from 'fumadocs-ui/components/card';
import { Callout } from 'fumadocs-ui/components/callout';
import { Tab, Tabs } from 'fumadocs-ui/components/tabs';

# Design Philosophy & Tradeoffs

## Overview

This document provides an honest evaluation of our UTA design philosophy and the specific architectural patterns we've chosen. We believe in transparency about both the benefits and costs of our approach, helping you understand when our Feature-Domain Hybrid strategy aligns with your project needs.

Rather than claiming our architecture fits every scenario, we examine real-world tradeoffs, learning investments, and situations where simpler approaches might be more appropriate. This balanced perspective helps teams make informed decisions about whether our architectural patterns match their specific context and goals.

## Purpose & Scope

**Target Audience**: Technical decision-makers, senior developers, and team leads evaluating architectural approaches for React Native projects, particularly those considering domain-driven design patterns.

**What This Document Addresses**:

* Our core architectural decisions and the problems they solve
* Honest assessment of learning investment and complexity costs
* Decision framework for evaluating if our patterns fit your project
* Team readiness considerations and adoption strategies
* Alternative architectural approaches for different project types

**What This Document Does NOT Cover**:

* Step-by-step implementation details (see our [Implementation Guides](/docs/guides))
* Specific API documentation (see [API Reference](/docs/api))
* Development workflow specifics (see [Getting Started Guide](/docs/guides/getting-started) and [Team Onboarding](/docs/guides/team-onboarding-checklist))

## Prerequisites

To get the most value from this document, we recommend first exploring these foundational resources:

* **[Core Architecture Reference](/docs/architecture/core-architecture)** - This will help you understand our technology stack and foundational patterns
* **[Domain Architecture Guide](/docs/architecture/domain-architecture)** - Essential for understanding our domain-driven design approach
* **[Project Structure](/docs/architecture/project-structure)** - Useful for seeing how our file organization philosophy works in practice

**Technical Background**: You'll get more from the architectural discussions if you're familiar with React Native development, TypeScript, and modern state management concepts (like the difference between server state and client state).

**Technical Foundation**: Our architectural patterns work with any modern React Native setup - whether you're using Expo Router + CNG, React Native CLI, or custom configurations. The patterns focus on code organization and business logic, not the underlying technical foundation.

## UTA Architectural Design Philosophy

### Core Organizational Strategy: Feature-Domain Hybrid

After working with various React Native project structures, we've developed a **Feature-Domain Hybrid** approach that addresses common pain points we've encountered. This strategy combines the intuitive nature of feature-first organization with the business logic clarity of domain-driven design.

**Why We Chose This Approach**: Traditional feature-only organization works great initially, but as business logic becomes complex, you end up with logic scattered across UI components. Pure domain-driven approaches can feel abstract for mobile apps. Our hybrid approach gives you the best of both worlds:

<Mermaid
  chart={`
flowchart TD
subgraph Features[Feature Layer]
  Auth[Authentication]
  Profile[User Profile]
  Shopping[Shopping Cart]
  Analytics[Analytics]
end

subgraph Domains[Domain Layer]
  UserDomain[User Domain]
  ProductDomain[Product Domain]
  OrderDomain[Order Domain]
  AnalyticsDomain[Analytics Domain]
end

subgraph Infrastructure[Infrastructure Layer]
  API[API Clients]
  Storage[Storage Services]
  Navigation[Navigation]
  UI[UI Components]
end

Features --> Domains
Domains --> Infrastructure

style Features fill:#e3f2fd
style Domains fill:#f3e5f5
style Infrastructure fill:#e8f5e8
`}
/>

**Understanding the Layers**:

* **Features** handle everything users see and interact with (screens, navigation, UI state)
* **Domains** contain pure business logic that could work in any UI context
* **Infrastructure** provides shared services that both layers can use

This separation means you can change how features look and behave without touching business rules, and you can modify business logic without breaking UI components.

### Key Architectural Decisions & Their Benefits

We've made several opinionated decisions based on real-world React Native development challenges we've encountered. Each decision addresses specific pain points that teams commonly face as projects grow:

<Tabs items={["Organization", "State Management", "Type Safety", "Testing"]}>
  <Tab>
    #### Feature-Domain Hybrid Organization

    * **Features for UI**: Screen components, navigation, and user-facing logic grouped by user workflow
    * **Domains for Business Logic**: Pure business rules and data models isolated from UI concerns
    * **Predictable Structure**: Teams know exactly where to find and place different types of code
    * **Scaling Benefits**: New features don't require restructuring existing code organization
  </Tab>

  <Tab>
    #### Separated State Management Strategy

    * **Server State**: TanStack Query handles API data, caching, and synchronization
    * **Client State**: Zustand manages application-specific UI state and user preferences
    * **No State Confusion**: Clear boundaries eliminate debates about where state belongs
    * **Performance Optimized**: Right tool for each type of state management need
  </Tab>

  <Tab>
    #### TypeScript-First Design

    * **Domain Types**: Business entities defined as TypeScript interfaces/types
    * **API Contracts**: Full type safety from backend responses to UI components
    * **Component Props**: Comprehensive typing for all React Native components
    * **Developer Experience**: IDE support, refactoring safety, and runtime error prevention
  </Tab>

  <Tab>
    #### Testability by Design

    * **Pure Business Logic**: Domain functions are easily unit tested without UI dependencies
    * **Dependency Injection**: Services can be mocked and replaced for testing
    * **Component Isolation**: UI components tested independently from business logic
    * **Integration Testing**: Clear boundaries make integration testing more focused and reliable
  </Tab>
</Tabs>

### Problems This Architecture Solves

These patterns emerged from real challenges we've faced in React Native projects. Understanding these pain points helps explain why we've made specific architectural choices:

<Cards>
  <Card title="State Management Confusion" description="We separate server state (TanStack Query) from client state (Zustand) because mixing them leads to unnecessary complexity, poor performance, and bugs that are hard to debug." />

  <Card title="Code Organization Chaos" description="Our Feature-Domain hybrid provides a predictable structure that team members can understand quickly and that scales naturally as features are added without requiring major refactoring." />

  <Card title="Business Logic Coupling" description="By isolating business rules in domain layers, we ensure that important logic can be tested independently, reused across features, and modified without breaking UI components." />

  <Card title="Team Collaboration Friction" description="Clear, opinionated patterns reduce time spent debating architecture in code reviews and help team members know where to find and place different types of code." />
</Cards>

<Callout type="info">
  **Why This Matters**: These aren't theoretical problems - they're based on real experiences from teams scaling React Native applications. Each pattern we've chosen addresses specific pain points that become critical as projects grow beyond initial prototypes.
</Callout>

### Architectural Principles

Building on the CNG foundation, the UTA architecture is guided by these principles:

<Mermaid
  chart={`
flowchart TD
subgraph Principles[Core Architectural Principles]
  SoC[Separation of Concerns]
  DDD[Domain-Driven Design]
  UDF[Unidirectional Data Flow]
  FTO[Feature-First Organization]
  Test[Testability by Design]
end

subgraph Benefits[Resulting Benefits]
  Scalable[Scalable Codebase]
  Maintainable[Maintainable Code]
  Predictable[Predictable Behavior]
  Collaborative[Team Collaboration]
  Quality[Code Quality]
end

SoC --> Scalable
DDD --> Maintainable
UDF --> Predictable
FTO --> Collaborative
Test --> Quality

style SoC fill:#e1f5fe
style DDD fill:#f3e5f5
style UDF fill:#e8f5e8
style FTO fill:#fff3e0
style Test fill:#fce4ec
`}
/>

#### 1. Separation of Concerns

* **Business Logic**: Isolated in domain modules, independent of UI
* **Presentation Logic**: Contained within feature modules and components
* **Infrastructure**: Shared utilities and configuration separated from business rules

#### 2. Domain-Driven Design

* **Business-Centric Organization**: Code structure reflects business domains
* **Bounded Contexts**: Clear boundaries prevent domain logic bleeding
* **Ubiquitous Language**: Consistent terminology across code and documentation

#### 3. Unidirectional Data Flow

* **Predictable State Changes**: Clear patterns for state mutations
* **Server State Management**: TanStack Query handles API interactions
* **Client State Isolation**: Zustand manages application-specific state

#### 4. Feature-First Organization

* **User-Centric Structure**: Features organized around user workflows
* **Colocated Code**: Related components, screens, and navigation grouped together
* **Encapsulation**: Features contain their own state and navigation logic

#### 5. Testability by Design

* **Dependency Injection**: Services can be easily mocked for testing
* **Pure Functions**: Business logic written as testable pure functions
* **Component Isolation**: UI components testable independently of business logic

### When This Architecture Excels

<Cards>
  <Card title="Complex Business Logic" description="Domain layer patterns shine when you have sophisticated business rules, calculations, or workflows that need to be consistent across multiple UI contexts." />

  <Card title="Growing Development Teams" description="Clear boundaries and patterns prevent 'stepping on each other's toes' as teams scale from 3-4 developers to 10+ developers working simultaneously." />

  <Card title="Long-Term Product Evolution" description="Feature-Domain hybrid structure accommodates major product pivots and feature additions without requiring large-scale code reorganization." />

  <Card title="API-Heavy Applications" description="TanStack Query patterns excel with complex server state requirements - multiple endpoints, caching strategies, and real-time updates." />

  <Card title="Cross-Platform Consistency" description="Domain layer ensures business logic behaves identically across iOS, Android, and web platforms when using universal React Native approaches." />

  <Card title="High Testing Requirements" description="Clear separation of concerns makes comprehensive testing achievable - unit tests for business logic, integration tests for features." />
</Cards>

## Honest Assessment of Architectural Tradeoffs

### When Our Patterns Create Overhead

<Callout type="warn">
  **Honest Reality**: Our architecture is optimized for projects that will grow in complexity over time. If you're building a simple app that will stay simple, this approach may feel like overkill.
</Callout>

#### Learning Investment You Should Expect

We believe in being upfront about the learning curve. Here's what your team should be prepared for:

* **Domain-Driven Design Concepts**: Understanding business logic separation is a mindset shift that takes time to internalize
* **State Management Patterns**: Learning when to use TanStack Query vs. Zustand requires understanding the difference between server and client state
* **TypeScript Discipline**: Our approach relies heavily on TypeScript for safety, so team members need to be comfortable with comprehensive typing
* **Architectural Thinking**: Success requires embracing layered architecture concepts rather than putting everything in components

#### Complexity Considerations

<Mermaid
  chart={`
flowchart LR
subgraph Simple[Simple Projects]
  QuickStart[Quick Prototypes]
  MVPs[Basic MVPs]
  Personal[Personal Projects]
end

subgraph Complex[Complex Projects]
  Enterprise[Enterprise Apps]
  MultiTeam[Multi-Team Development]
  LongTerm[Long-Term Maintenance]
end

Simple --> |May be overkill| Architecture[UTA Architecture]
Complex --> |Well-suited| Architecture

Architecture --> Overhead[Setup Overhead]
Architecture --> Benefits[Long-term Benefits]

style Simple fill:#ffebee
style Complex fill:#e8f5e8
style Architecture fill:#e3f2fd
style Overhead fill:#fff3e0
style Benefits fill:#f1f8e9
`}
/>

### When NOT to Use This Architecture

<Callout type="info">
  **Key Insight**: No architecture fits every scenario. Here's when alternatives might be better choices.
</Callout>

#### Project Types Where Simpler Approaches Excel

<Tabs items={["Quick Prototypes", "Simple Apps", "Learning Projects", "Tight Deadlines"]}>
  <Tab>
    #### Rapid Prototyping & MVPs

    * **Timeline**: Projects with 2-4 week development cycles
    * **Scope**: Single-feature or proof-of-concept applications
    * **Alternative**: Expo Router with simple folder structure
    * **Why**: Setup overhead exceeds project duration
  </Tab>

  <Tab>
    #### Small-Scale Applications

    * **Team Size**: 1-2 developers
    * **Feature Count**: Fewer than 5 major features
    * **Complexity**: Simple CRUD operations
    * **Alternative**: Standard React Native CLI with basic organization
    * **Why**: Architectural benefits don't justify complexity
  </Tab>

  <Tab>
    #### Educational Projects

    * **Purpose**: Learning React Native fundamentals
    * **Focus**: Understanding core concepts rather than architecture
    * **Timeline**: Short-term learning exercises
    * **Alternative**: Tutorial-based structures
    * **Why**: Architecture concepts can distract from core learning
  </Tab>

  <Tab>
    #### Emergency Projects

    * **Constraints**: Extremely tight deadlines
    * **Resources**: No time for team training
    * **Scope**: Single-purpose applications
    * **Alternative**: Framework defaults with minimal customization
    * **Why**: Training time conflicts with delivery requirements
  </Tab>
</Tabs>

#### Technical Constraints

* **Legacy Integration**: Heavy integration with legacy systems that conflict with modern patterns
* **Extreme Performance**: Real-time applications with microsecond requirements (rare in mobile apps)

### Known Tradeoffs & Their Impact

#### Development Velocity Tradeoffs

<Mermaid
  chart={`
flowchart TD
subgraph Timeline[Development Timeline]
  Week1[Week 1-2: Setup & Learning]
  Week3[Week 3-4: Pattern Adoption]
  Week5[Week 5+: Productivity Gains]
end

subgraph Velocity[Development Velocity]
  Slow[Slower than Simple Approach]
  Breaking[Breaking Even Point]
  Fast[Faster than Simple Approach]
end

Week1 --> Slow
Week3 --> Breaking
Week5 --> Fast

style Week1 fill:#ffebee
style Week3 fill:#fff3e0
style Week5 fill:#e8f5e8
style Slow fill:#ffcdd2
style Breaking fill:#fff9c4
style Fast fill:#c8e6c9
`}
/>

#### Performance Considerations

* **Bundle Size**: Additional dependencies increase application size
* **Memory Usage**: Multiple state management solutions consume more memory
* **Initialization Time**: Complex setup can slow application startup
* **Runtime Overhead**: Abstraction layers introduce minimal performance cost

#### Team Requirements

* **Skill Level**: Requires developers comfortable with TypeScript and modern React patterns
* **Onboarding Time**: New team members need 1-2 weeks to become productive
* **Maintenance Expertise**: Long-term success requires understanding architectural principles
* **Decision Making**: Teams must commit to following established patterns consistently

## Decision Framework

### Evaluation Criteria

We've created this framework to help you honestly assess whether our architectural approach makes sense for your specific situation. Rather than advocating for our approach in every case, we want to help you make the right choice for your project:

<Tabs items={["Project Assessment", "Team Evaluation", "Technical Requirements", "Business Factors"]}>
  <Tab>
    #### Project Characteristics

    **Strong Fit Indicators** ✅

    * Development timeline exceeding 3 months
    * Expected feature count above 10 major features
    * Multiple user roles and workflows
    * Plans for ongoing feature development
    * Integration with multiple backend services

    **Weak Fit Indicators** ❌

    * One-time prototype or proof of concept
    * Simple CRUD application
    * Single-purpose utility app
    * Fixed scope with no planned expansion
    * Minimal business logic complexity
  </Tab>

  <Tab>
    #### Team Capabilities

    **Strong Fit Indicators** ✅

    * 3+ developers on the team
    * Experience with TypeScript and modern React
    * Commitment to learning new patterns
    * Plans for team growth
    * Emphasis on code quality and maintainability

    **Weak Fit Indicators** ❌

    * Solo developer or pair programming only
    * Beginner-level React Native experience
    * Tight deadlines preventing learning time
    * High team turnover expected
    * Preference for minimal abstractions
  </Tab>

  <Tab>
    #### Technical Needs

    **Strong Fit Indicators** ✅

    * Complex state management requirements
    * Multiple API integrations
    * Need for comprehensive testing
    * Performance optimization important
    * Platform-specific customization needed

    **Weak Fit Indicators** ❌

    * Simple local data storage
    * Single API endpoint integration
    * Minimal testing requirements
    * Basic performance needs
    * Standard platform behaviors sufficient
  </Tab>

  <Tab>
    #### Business Context

    **Strong Fit Indicators** ✅

    * Long-term product vision (1+ years)
    * Multiple stakeholders and requirements
    * Plans for feature iteration and evolution
    * Importance of maintainability
    * Budget for proper development practices

    **Weak Fit Indicators** ❌

    * Short-term tactical solution
    * Single stakeholder with simple needs
    * Fixed requirements unlikely to change
    * Time-to-market prioritized over quality
    * Limited development budget
  </Tab>
</Tabs>

### Decision Tree

<Mermaid
  chart={`
flowchart TD
Start([Project Evaluation]) --> TeamSize{Team Size &gt; 2?}

TeamSize -->|No| Simple[Consider Simpler Architecture]
TeamSize -->|Yes| Timeline{Timeline &gt; 3 months?}

Timeline -->|No| Simple
Timeline -->|Yes| Features{Features &gt; 10?}

Features -->|No| Evaluate[Evaluate Other Factors]
Features -->|Yes| Complex{Complex Business Logic?}

Complex -->|No| Evaluate
Complex -->|Yes| UTA[UTA Architecture Recommended]

Evaluate --> Experience{Team TypeScript Experience?}
Experience -->|Low| Training{Training Time Available?}
Experience -->|High| Maintenance{Long-term Maintenance?}

Training -->|No| Simple
Training -->|Yes| UTA

Maintenance -->|No| Simple
Maintenance -->|Yes| UTA

style UTA fill:#c8e6c9
style Simple fill:#ffcdd2
style Evaluate fill:#fff3e0
`}
/>

### Questions to Discuss with Your Team

<Callout>
  **Team Alignment**: These questions can help facilitate productive discussions about whether our approach fits your team's needs and constraints.
</Callout>

#### Technical Assessment

1. How comfortable is our team with TypeScript and modern React patterns?
2. Are we planning to integrate with multiple backend services or APIs?
3. Do we expect significant growth in features and complexity over time?
4. How important is comprehensive testing for this project?

#### Project Context

1. What are our realistic development timeline and team size constraints?
2. How do we balance long-term maintainability with time-to-market pressures?
3. Do we have stakeholder support for investing in architectural patterns?
4. Are we prepared to invest time in team onboarding and learning?

#### Risk Assessment

1. What are the real consequences if our architectural choice doesn't work out?
2. How difficult would it be to migrate to a different approach later?
3. Do we have the expertise to adapt these patterns to our specific needs?
4. How will we maintain architectural consistency as the team grows?

## Migration Considerations

### Adoption Strategies

<Tabs items={["Greenfield Projects", "Existing Projects", "Hybrid Approaches"]}>
  <Tab>
    #### New Project Implementation

    **Recommended Approach**: Full adoption from project start

    **Timeline**: 1-2 weeks for initial setup and team training

    **Steps**:

    1. Clone template and configure for your project
    2. Conduct team training sessions on architectural patterns
    3. Implement first feature following established patterns
    4. Establish code review processes for pattern compliance
    5. Create project-specific documentation additions

    **Success Factors**:

    * Dedicated time for learning and setup
    * Team commitment to following patterns
    * Clear communication about architectural decisions
  </Tab>

  <Tab>
    #### Migrating Existing Codebases

    **Recommended Approach**: Gradual migration by feature

    **Timeline**: 2-6 months depending on codebase size

    **Steps**:

    1. Assess current architecture and identify pain points
    2. Create migration plan prioritizing high-value features
    3. Implement new features using UTA patterns
    4. Gradually refactor existing features during maintenance
    5. Update team processes and documentation

    **Challenges**:

    * Maintaining consistency during transition
    * Managing technical debt during migration
    * Team adoption of new patterns while maintaining old code
  </Tab>

  <Tab>
    #### Selective Pattern Adoption

    **Recommended Approach**: Adopt specific architectural patterns without full migration

    **Use Cases**:

    * Teams wanting domain organization without full template
    * Projects requiring only state management improvements
    * Gradual architectural evolution

    **Considerations**:

    * May miss benefits of integrated architectural approach
    * Requires deeper understanding of individual patterns
    * Risk of inconsistent implementation
  </Tab>
</Tabs>

### Team Preparation Requirements

#### Technical Skills Development

* **TypeScript Proficiency**: Essential for taking advantage of type safety
* **Modern React Patterns**: Hooks, context, and state management
* **TanStack Query**: Server state management and caching strategies
* **Testing Practices**: Component testing and integration testing approaches

#### Process Adaptations

* **Code Review Guidelines**: Establishing architectural pattern compliance
* **Documentation Habits**: Maintaining up-to-date architectural documentation
* **Feature Planning**: Incorporating domain and feature analysis into planning
* **Onboarding Processes**: Training new team members on architectural patterns

### Success Metrics

#### Short-term Indicators (First 3 months)

* Team comfort level with architectural patterns
* Consistency of pattern implementation across features
* Reduction in time spent on code organization decisions
* Quality of code reviews and architectural discussions

#### Long-term Indicators (6+ months)

* Developer velocity for new feature implementation
* Reduced time for new team member onboarding
* Decreased bug rates related to state management
* Improved test coverage and reliability

## Alternative Architectural Approaches

<Callout type="info">
  **UTA's Role**: UTA provides architectural patterns that can be applied on top of any React Native technical foundation (Expo Router + CNG, React Native CLI, or custom setups).
</Callout>

### When to Consider Different Architectural Strategies

<Mermaid
  chart={`
flowchart LR
subgraph ProjectNeeds[Project Requirements]
  Simple[Simple Structure Needs]
  Custom[Custom Requirements]
  Rapid[Rapid Development]
  Enterprise[Enterprise Complexity]
end

subgraph Approaches[Architectural Approaches]
  Minimal[Minimal Organization]
  UTA[UTA Patterns]
  CustomArch[Custom Architecture]
end

Simple --> Minimal
Rapid --> Minimal
Custom --> CustomArch
Enterprise --> UTA

style Simple fill:#e8f5e8
style Enterprise fill:#e3f2fd
style UTA fill:#c8e6c9
`}
/>

#### Simple Project Organization (Framework Defaults)

* **Best For**: Prototypes, MVPs, small teams (1-3 developers)
* **Benefits**: Minimal setup, fast initial development, easy to understand
* **Tradeoffs**: Limited scalability, no architectural guidance for complexity

#### Custom Domain-Driven Architecture

* **Best For**: Enterprise teams with specific architectural requirements, existing DDD expertise
* **Benefits**: Complete control over patterns, tailored to business context
* **Tradeoffs**: Requires significant architectural expertise, longer standardization time

#### UTA's Position as Architectural Layer

<Callout type="info">
  **Key Understanding**: UTA architectural patterns sit **above** the technical foundation. Whether you use Expo Router + CNG, React Native CLI, or custom configurations, UTA provides the business logic organization and state management strategies.
</Callout>

**When UTA Architectural Patterns Are Most Valuable**:

* Teams building complex applications that will scale beyond simple CRUD operations
* Projects requiring clear separation between UI logic and business logic
* Organizations prioritizing long-term maintainability and team collaboration
* Applications with sophisticated state management needs (multiple APIs, complex caching)

**When Simpler Architectural Approaches Are Better**:

* Rapid prototypes and proof-of-concept projects
* Small teams (1-3 developers) building straightforward applications
* Projects with extremely tight deadlines where architectural investment isn't justified
* Teams with strong existing architectural expertise who prefer custom solutions

## Related Documents

This document provides the foundation for architectural decision-making. For implementation details and specific guidance, explore these related resources:

<Cards>
  <Card title="Core Architecture Reference" description="Deep dive into the technical implementation of the UTA architecture patterns and technology stack." href="/docs/architecture/core-architecture" />

  <Card title="Domain Architecture Guide" description="Comprehensive guide to implementing domain-driven design patterns for business logic organization." href="/docs/architecture/domain-architecture" />

  <Card title="Project Structure Guide" description="Detailed explanation of file organization, naming conventions, and folder hierarchy." href="/docs/architecture/project-structure" />

  <Card title="Feature Implementation Patterns" description="Practical patterns for building features that integrate with the architectural foundation." href="/docs/features" />

  <Card title="State Management Architecture" description="Guide to managing both server state and client state within the architectural framework." href="/docs/state-management" />

  <Card title="API Integration Patterns" description="Best practices for integrating with backend services while maintaining architectural boundaries." href="/docs/api" />
</Cards>

***

*This document represents our current understanding of architectural tradeoffs based on real-world experience. As we continue to evolve the architecture based on feedback and new requirements, we'll update this assessment to reflect new insights and learnings.*


# UTA Architecture: Core Architecture
URL: https://dev.updatetheapp.com/docs/architecture/core-architecture
Documentation: https://dev.updatetheapp.com/docs/architecture/core-architecture

Reference guide to the core architecture of the React Native app, covering patterns, component interactions, and technology stack.
        
***

title: Core Architecture
description: Reference guide to the core architecture of the React Native app, covering patterns, component interactions, and technology stack.
-----------------------------------------------------------------------------------------------------------------------------------------------

# Core Architecture

## Overview

This document outlines the core architecture for our React Native mobile application. It defines the fundamental patterns, structures, and frameworks that support all features and functionality. Our architecture employs a hybrid approach combining feature-based UI organization with domain-based business logic for optimal scalability and maintainability.

## Purpose & Scope

This document provides a comprehensive reference for understanding the overall application architecture. It's intended for all developers working on the project, particularly those who need to understand how different system components interact and the distinction between shared utilities and domain-specific code.

## Core Architecture Components

### 1. Architectural Overview

<Mermaid
  chart={`
flowchart TD
App[App Container] --> QueryProvider[TanStack Query Provider]
App --> StoreProvider[State Store Provider]
App --> Navigation[Navigation Container]

QueryProvider --> Features[Feature Modules]
StoreProvider --> Features
Navigation --> Features

Features --> Domains[Domain Services]
Features --> SharedUtils[Shared Utilities]
Features --> UI[Shared UI Components]

Domains --> ApiClient[API Client]
SharedUtils --> ApiClient
Domains --> SharedUtils

ApiClient --> Backend[Backend Services]
`}
/>

Our application follows a hybrid architecture that combines:

* **Feature-based organization** for UI/UX concerns
* **Domain-based organization** for business logic and data
* **Clear separation** between shared utilities and domain-specific code

### 2. Technology Stack

| Category     | Technology                          | Purpose                                                              |
| ------------ | ----------------------------------- | -------------------------------------------------------------------- |
| Framework    | React Native                        | Cross-platform mobile application development                        |
| Language     | TypeScript                          | Static typing and improved developer productivity                    |
| Server State | TanStack Query                      | Data fetching, caching, synchronization, and server state management |
| Client State | Zustand                             | Global application state management                                  |
| Navigation   | React Navigation                    | Screen routing and navigation management                             |
| HTTP Client  | Axios                               | Promise-based HTTP requests, integrated with TanStack Query          |
| Styling      | React Native StyleSheet / Unistyles | Native styling with performance optimization and theme support       |
| Testing      | Jest & React Testing Library        | Unit and integration testing                                         |
| E2E Testing  | Detox                               | End-to-end testing for mobile applications                           |

### 3. Hybrid Architecture: Features + Domains

Our architecture employs a dual approach for optimal organization:

#### Domain-Based Business Logic

* **Purpose**: Organize business logic by domain entities
* **Location**: `core/domains/[domain]/`
* **Contents**: API services, types, hooks, query keys
* **Examples**: Products, Users, Auth, Orders

#### Feature-Based UI Organization

* **Purpose**: Organize user-facing functionality by features
* **Location**: `features/[feature]/`
* **Contents**: Screens, components, navigation
* **Examples**: Shopping Cart, Product Catalog, User Profile

#### Shared Utilities

* **Purpose**: Cross-cutting concerns used everywhere
* **Location**: `core/shared/`
* **Contents**: Generic hooks, utilities, types
* **Examples**: useDebounce, formatDate, ApiResponse

### 4. Core Infrastructure

The core infrastructure is divided into domain-specific and shared components:

```
core/
├── domains/                   # Domain-based business logic
│   ├── products/              # Product domain
│   │   ├── api.ts            # Product API service
│   │   ├── types.ts          # Product type definitions
│   │   ├── hooks.ts          # Product query hooks
│   │   └── queryKeys.ts      # Product query keys
│   ├── users/                # User domain
│   ├── auth/                 # Authentication domain
│   │   ├── api.ts
│   │   ├── types.ts
│   │   ├── hooks.ts
│   │   ├── store.ts          # Auth state management
│   │   ├── tokenService.ts   # Token management
│   │   └── events.ts         # Auth events
│   └── [other-domains]/
│
└── shared/                    # Truly shared utilities
    ├── api/
    │   ├── client.ts         # Axios instance with interceptors
    │   └── interceptors.ts   # Request/response interceptors
    ├── query/
    │   └── queryClient.ts    # TanStack Query client config
    ├── hooks/                # Generic React hooks
    ├── utils/                # General utility functions
    ├── types/                # Cross-domain types
    └── styles/               # Global styling
```

### 5. Shared vs Domain Guidelines

Clear separation between shared and domain-specific code is crucial:

#### What Goes in Shared Folders

* **core/shared/hooks/**: Generic React hooks (useDebounce, useLocalStorage)
* **core/shared/utils/**: General utilities (formatDate, capitalizeString)
* **core/shared/types/**: Cross-domain types (ApiResponse, AsyncState, ErrorResponse)

#### What Stays in Domain Folders

* **core/domains/\[domain]/hooks.ts**: Domain queries (useProducts, useUser)
* **core/domains/\[domain]/types.ts**: Domain models (Product, User)
* **core/domains/\[domain]/api.ts**: Domain services

### 6. Feature Module Structure

Each feature module is a self-contained unit focused on user-facing functionality:

```
features/
├── product-catalog/           # Product browsing feature
│   ├── components/            # Feature components
│   ├── screens/               # Screen components
│   ├── navigation.tsx         # Feature navigation
│   └── state/                 # Feature-specific state
└── [other-features]/          # Other feature modules
```

### 7. State Management Architecture

<Mermaid
  chart={`
flowchart LR
UI[UI Components] <--> ServerState[Server State]
UI <--> ClientState[Client State]

subgraph TanStack Query
  ServerState --> Cache[(Cache)]
  Cache --> Hooks[Domain Query Hooks]
end

subgraph Zustand
  ClientState <--> Stores[(State Stores)]
  Stores <--> StateHooks[State Hooks]
end

Hooks --> DomainServices[Domain Services]
DomainServices --> Backend[Backend]
`}
/>

Our application clearly separates different types of state:

* **Server State**: Managed by TanStack Query through domain hooks
* **Client State**: Managed by Zustand for global application state
* **Component State**: Local state for UI-specific concerns

### 8. Navigation System

The navigation system provides type-safe routing:

* **Navigation Container**: Central React Navigation setup
* **Feature-Based Navigation**: Each feature defines its screens
* **Deep Linking**: Support for external app opening
* **Type Safety**: Full TypeScript integration

### 9. Communication Patterns

<Mermaid
  chart={`
flowchart TD
subgraph "Feature A"
  ComponentA[Component A]
end

subgraph "Feature B"
  ComponentB[Component B]
end

ComponentA -->|"Domain Service"| DomainService[Domain Service]
DomainService --> ComponentB

ComponentA -->|"Events"| EventBus[Event Bus]
EventBus --> ComponentB

ComponentA -->|"Shared State"| SharedState[Shared State]
SharedState --> ComponentB

ComponentA -->|"Navigation"| Navigation[Navigation]
Navigation --> ComponentB
`}
/>

Features communicate through several patterns:

* **Domain Services**: Shared data access through domain hooks
* **Event Bus**: Publish-subscribe for loose coupling
* **Shared State**: Query cache and global state
* **Navigation**: Parameter passing between screens

### 10. Authentication Architecture

Authentication is handled as a special domain with additional concerns:

```
core/domains/auth/
├── api.ts                    # Auth API calls
├── types.ts                  # Auth types
├── hooks.ts                  # Auth query hooks
├── store.ts                  # Auth state management
├── tokenService.ts           # Token storage and refresh
└── events.ts                 # Auth events (session expired)
```

Key features:

* Automatic token refresh through interceptors
* Session management with event-driven updates
* Secure token storage abstraction

## Design Principles

### 1. Feature-Based Modularity

We organize UI/UX by features rather than technical concerns to create clear user journey mapping and better team ownership.

**(Do ✅) Group related UI components by feature**

* This approach makes it easier to understand the complete user journey within a feature.
* Example: All components related to product browsing are grouped in `features/product-catalog/`.

**(Consider 🤔) When a feature becomes too large, consider breaking it into sub-features**

* Large features (>15-20 components) can become difficult to maintain.
* Use a subdirectory structure to organize related components within large features.

### 2. Domain-Driven Design

We organize business logic by domains for better scalability and maintainability. This separation has proven to significantly reduce complexity as applications grow.

**(Do ✅) Identify clear domain boundaries based on business entities**

* Group related business logic, types, and API calls by domain entity.
* Example: Everything related to products is in `core/domains/products/`.

**(Don't ❌) Mix domain concerns within a single domain module**

* Avoid including user-related functionality in the product domain.
* Each domain should have a single, well-defined responsibility.

### 3. Clear Separation of Concerns

Our architecture maintains clear boundaries between different responsibilities:

**(Do ✅) Use appropriate tools for different state needs**

* **Server State vs. Client State**: TanStack Query for server data, Zustand for client-only state
* **Shared vs. Domain**: Place truly shared utilities in `core/shared`, domain-specific code in domains
* **UI vs. Business Logic**: Features handle UI/UX, domains handle data and business rules

### 4. Type Safety

Comprehensive TypeScript throughout the application improves reliability and developer experience:

**(Do ✅) Define complete type interfaces for all data structures**

* **API Types**: Full request/response typing with proper documentation
* **State Types**: Typed stores and hooks for compile-time safety
* **Navigation Types**: Type-safe routes and parameters

**(Don't ❌) Use `any` types or ignore TypeScript warnings**

* Type safety is only effective when consistently applied throughout the codebase.
* If you find yourself using `any`, it might indicate a design issue that needs addressing.

### 5. Performance First

We prioritize performance considerations in our architecture design:

**(Do ✅) Implement performance optimizations from the start**

* **Optimized Rendering**: Strategic memoization of components and callbacks
* **Query Optimization**: Smart caching strategies for data fetching
* **Code Splitting**: Domain-based lazy loading for faster initial load

**(Consider 🤔) Adding performance monitoring to identify bottlenecks**

* Implement basic performance tracking to identify areas for improvement.
* Regular performance audits help maintain a fast application experience.

### 6. Developer Experience

Our architecture is designed to enhance developer productivity:

**(Do ✅) Maintain consistent patterns across the codebase**

* **Consistent Patterns**: Predictable organization makes onboarding easier
* **Clear Boundaries**: Obvious where code belongs reduces decision fatigue
* **Self-Documenting**: Structure reveals intent and guides development

## Implementation Considerations

### 1. Adding New Domains

Domains represent business entities and contain related business logic. When creating a new domain, follow these steps:

<Steps>
  <Step>
    #### Create domain folder

    Create a new directory in `core/domains/` with a descriptive name representing the business entity (e.g., `products`, `orders`, `payments`).
  </Step>

  <Step>
    #### Add required files

    At minimum, every domain needs these three files:

    ```typescript
    // api.ts - API service methods
    class NewDomainApi {
      public readonly public = { /* public endpoints */ };
      public readonly protected = { /* auth-required endpoints */ };
    }
    export const newDomainApi = new NewDomainApi();

    // types.ts - TypeScript interfaces
    export interface NewDomainEntity {
      id: string;
      // other properties
    }

    // hooks.ts - React Query hooks
    export function useNewDomainEntities() {
      return useQuery({
        queryKey: ['newDomain', 'list'],
        queryFn: () => newDomainApi.public.getAll()
      });
    }
    ```
  </Step>

  <Step>
    #### Add optional files as needed

    Consider adding these files for more complex domains:

    * `queryKeys.ts` - For consistent query key management
    * `events.ts` - For pub/sub communication
    * `store.ts` - For domain-specific UI state
    * `utils.ts` - For domain-specific utility functions
  </Step>

  <Step>
    #### Create barrel exports

    Add an `index.ts` file that exports the public API of your domain:

    ```typescript
    // index.ts
    export * from './api';
    export * from './types';
    export * from './hooks';
    // export other files as needed
    ```
  </Step>
</Steps>

**(Do ✅) Follow the established domain structure consistently**

* A consistent structure makes the codebase more predictable and easier to navigate.
* Each domain should have the same basic file organization.

**(Don't ❌) Mix domain logic with feature-specific UI code**

* Domains should contain only business logic, data fetching, and types.
* Feature-specific UI components should stay in feature folders.

### 2. Creating New Features

Features represent user-facing functionality and organize related UI components. To create a new feature:

<Steps>
  <Step>
    #### Create feature folder

    Add a new directory in `features/` with a name describing the user-facing functionality (e.g., `product-catalog`, `shopping-cart`, `checkout`).
  </Step>

  <Step>
    #### Add screens and components

    Create subdirectories for organization:

    ```
    features/new-feature/
    ├── components/       # Feature-specific components
    ├── screens/          # Screen components
    ├── navigation.tsx    # Feature navigation
    └── index.ts          # Barrel exports
    ```
  </Step>

  <Step>
    #### Connect to domains

    Import and use domain hooks to access data and business logic:

    ```typescript
    // features/product-catalog/screens/ProductListScreen.tsx
    import { useProducts } from '@/core/domains/products';

    export function ProductListScreen() {
      const { data: products, isLoading } = useProducts();
      // Render UI using the products data
    }
    ```
  </Step>

  <Step>
    #### Add feature-specific state if needed

    For UI state that's specific to the feature but doesn't belong in a domain:

    ```typescript
    // features/product-catalog/state/filters.ts
    import { create } from 'zustand';

    export const useProductFiltersStore = create((set) => ({
      viewMode: 'grid',
      setViewMode: (mode) => set({ viewMode: mode }),
    }));
    ```
  </Step>
</Steps>

**(Do ✅) Keep features focused on user-facing functionality**

* Features should primarily contain UI components and layout logic.
* The API for a feature should be clean and limited to what's necessary for other parts of the app.

**(Be Aware ❗) Features can get complex - consider sub-features**

* For very large features, consider creating sub-feature folders.
* Use the same organizational patterns within sub-features.

### 3. Shared vs Domain Decision

Deciding where code belongs is critical for maintaining the architecture. Use this decision tree:

<Mermaid
  chart={`
flowchart TD
Start["New Code: Where does it belong?"] --> Q1{"Is it specific to\none business domain?"}

Q1 -->|"Yes"| Domain["Place in domain folder\ncore/domains/[domain-name]/"]
Q1 -->|"No"| Q2{"Is it a reusable\nutility or hook?"}

Q2 -->|"Yes"| Shared["Place in shared folder\ncore/shared/[appropriate-subfolder]/"]
Q2 -->|"No"| Q3{"Is it UI-related?"}

Q3 -->|"Yes"| UI["Is it feature-specific?"]
Q3 -->|"No"| Q4{"Is it infrastructure?"}

UI -->|"Yes"| Feature["Place in feature folder\nfeatures/[feature-name]/"]
UI -->|"No"| UILib["Place in UI library\nui/[component-type]/"]

Q4 -->|"Yes"| Config["Place in app config\ncore/config/"]
Q4 -->|"No"| Reconsider["Reconsider the design"]

classDef decision fill:#f9f,stroke:#333;
classDef location fill:#bfb,stroke:#333;
classDef reconsider fill:#fbb,stroke:#333;

class Q1,Q2,Q3,Q4,UI decision;
class Domain,Shared,Feature,UILib,Config location;
class Reconsider reconsider;
`}
/>

**(Do ✅) Ask critical questions when deciding placement**

* "Is this specific to one business domain?" → Domain folder
* "Is it a reusable utility used across domains?" → Shared folder
* "Is it a UI component specific to one feature?" → Feature folder

**(Don't ❌) Create ambiguous or overlapping responsibilities**

* Avoid creating utilities that do the same thing in different places.
* Don't add business logic to UI components.

### 4. Cross-Feature Communication

Features should never directly import from other features. Instead, use these patterns:

**(Do ✅) Use domain hooks for shared data access**

```typescript
// Both features use the same domain hook
// features/product-catalog/screens/ProductList.tsx
// features/product-detail/screens/ProductDetail.tsx
import { useProduct } from '@/core/domains/products';
```

**(Do ✅) Use events for loose coupling**

```typescript
// features/shopping-cart/screens/CartScreen.tsx
import { cartEvents } from '@/core/domains/cart';

// Emit event when item added
cartEvents.emit('cart:itemAdded', { productId, quantity });

// features/product-detail/components/AddedNotification.tsx
// Listen for cart events
cartEvents.on('cart:itemAdded', handleItemAdded);
```

**(Do ✅) Pass parameters through navigation**

```typescript
// features/product-catalog/components/ProductCard.tsx
import { useNavigation } from '@react-navigation/native';

const navigation = useNavigation();
navigation.navigate('ProductDetail', { productId: product.id });
```

**(Don't ❌) Import directly between features**

```typescript
// AVOID THIS - creates tight coupling
import { ProductCard } from '@/features/product-catalog/components/ProductCard';
```

**(Consider 🤔) Using Signals for real-time updates**

* For real-time updates that need to flow across features, consider using a signals library or reactive state.
* This provides a performance benefit for frequently changing values.

## Related Documents

* [Project Structure Reference](/docs/architecture/project-structure)
* [Domain Architecture Guide](/docs/architecture/domain-architecture)
* [Shared Utilities Guide](/docs/features/shared-utilities)
* [File Naming Conventions](/docs/coding-standards/file-naming-conventions)
* [Communication Patterns](/docs/features/communication-patterns)
* [Authentication Architecture](/docs/api/authentication)
* [State Management](/docs/state-management)
* [API Architecture](/docs/api)


# UTA Architecture: Project Structure
URL: https://dev.updatetheapp.com/docs/architecture/project-structure
Documentation: https://dev.updatetheapp.com/docs/architecture/project-structure

Comprehensive reference for the project's directory structure, file organization, and module boundaries with clear shared/domain separation.
        
***

title: Project Structure
description: Comprehensive reference for the project's directory structure, file organization, and module boundaries with clear shared/domain separation.
---------------------------------------------------------------------------------------------------------------------------------------------------------

# Project Structure

## Overview

This document provides a comprehensive reference for the project's directory structure, file organization, and module boundaries. It outlines how code is organized following a hybrid architecture that combines feature-based UI organization with domain-based business logic, emphasizing the clear separation between shared utilities and domain-specific code.

## Purpose & Scope

This reference is intended for all developers working on the project to understand how code should be organized and where different types of code should be placed. It serves as the definitive guide for project organization with clear rules for shared versus domain-specific code placement.

## Directory Structure

### Root Structure

```
project-root/
├── src/                       # Source code
│   ├── core/                  # Domain logic & shared utilities
│   ├── features/              # Feature modules (UI/UX)
│   ├── ui/                    # Shared UI components
│   ├── navigation/            # Navigation configuration
│   ├── App.tsx               # Application entry with providers
│   └── index.js              # Root file
├── assets/                    # Static assets (project root level)
├── android/                   # Android platform files
├── ios/                       # iOS platform files
└── package.json              # Project configuration
```

#### High-Level Architecture Relationships

<Mermaid
  chart={`
flowchart TD
subgraph src[Source Code]
  Features[features/ - Feature modules]
  Core[core/ - Domain logic & shared]
  UI[ui/ - Shared UI components]
  Nav[navigation/ - Navigation config]
  App[App.tsx - Entry point]
end

Features --> Core
Features --> UI
Features --> Nav

App --> Features
App --> Core
App --> UI
App --> Nav

style Features fill:#f9f,stroke:#333
style Core fill:#bfb,stroke:#333
style UI fill:#bbf,stroke:#333
style Nav fill:#fbb,stroke:#333
`}
/>

### Core Directory

The `core` directory is divided into two main sections: domain-based business logic and truly shared utilities:

<Mermaid
  chart={`
flowchart TD
subgraph core[Core Directory]
  subgraph domains[Domain Modules]
    Products[products/]
    Users[users/]
    Auth[auth/]
    Other[other domains...]
  end
  
  subgraph shared[Shared Utilities]
    API[api/]
    Query[query/]
    Hooks[hooks/]
    Utils[utils/]
    Types[types/]
    Styles[styles/]
  end
end

%% Domain internals
subgraph domain_internals[Domain Internal Structure]
  Types_D[types.ts]
  API_D[api.ts]
  Hooks_D[hooks.ts]
  Query_D[queryKeys.ts]
  Store_D[store.ts - optional]
end

domains --> domain_internals

style domains fill:#f9f,stroke:#333
style shared fill:#bfb,stroke:#333
style domain_internals fill:#ddd,stroke:#333
`}
/>

```
core/
├── domains/                   # Domain-based business logic
│   ├── products/              # Product domain
│   │   ├── api.ts            # Product API service
│   │   ├── types.ts          # Product types (Product, ProductCategory)
│   │   ├── hooks.ts          # Product hooks (useProducts, useProduct)
│   │   └── queryKeys.ts      # Product query keys
│   │
│   ├── users/                # User domain
│   │   ├── api.ts            # User API service
│   │   ├── types.ts          # User types (User, UserProfile)
│   │   ├── hooks.ts          # User hooks (useUser, useUpdateUser)
│   │   └── queryKeys.ts      # User query keys
│   │
│   ├── auth/                 # Authentication domain
│   │   ├── api.ts            # Auth API service
│   │   ├── types.ts          # Auth types (AuthState, LoginRequest)
│   │   ├── hooks.ts          # Auth hooks (useAuth, useLogin)
│   │   ├── store.ts          # Auth state management
│   │   ├── tokenService.ts   # Token management service
│   │   ├── events.ts         # Auth events (sessionExpired)
│   │   └── queryKeys.ts      # Auth query keys
│   │
│   └── [other-domains]/      # Additional domains (orders, payments, etc.)
│
└── shared/                    # Truly shared, non-domain utilities
    ├── api/
    │   ├── client.ts         # Axios instance with interceptors
    │   └── interceptors.ts   # Request/response interceptors
    │
    ├── query/
    │   └── queryClient.ts    # TanStack Query client config
    │
    ├── hooks/                # Generic React hooks (NO domain logic)
    │   ├── useDebounce.ts    # Debounce hook
    │   ├── useLocalStorage.ts # Local storage hook
    │   ├── useMediaQuery.ts  # Media query hook
    │   └── useTimeout.ts     # Timeout hook
    │
    ├── utils/                # General utilities (NO domain logic)
    │   ├── date.ts           # Date formatting utilities
    │   ├── string.ts         # String manipulation utilities
    │   ├── validation.ts     # Generic validation helpers
    │   └── number.ts         # Number formatting utilities
    │
    ├── types/                # Cross-domain types  
    │   ├── ui.ts             # Cross-domain UI patterns (BaseComponentProps, LoadingState)
    │   ├── global.ts         # Global app types (AppState, Theme)
    │   └── api.ts            # Generic API types (ErrorResponse, Pagination)
    │
    └── styles/               # Global styling
        ├── theme.ts          # Theme constants (colors, spacing)
        ├── typography.ts     # Text styles and fonts
        ├── layout.ts         # Layout utilities
        ├── shadows.ts        # Shadow styles
        └── mixins.ts         # Reusable style patterns
```

For detailed information on domain-based business logic organization and implementation patterns, see the [Domain Architecture Guide](/docs/architecture/domain-architecture).

### Features Directory

Features contain UI/UX code organized by user-facing functionality:

```
features/
├── product-catalog/           # Product browsing feature
│   ├── components/            # Feature-specific components
│   │   └── ProductCard/
│   │       ├── ProductCard.tsx
│   │       ├── styles.ts
│   │       └── index.ts
│   ├── screens/               # Feature screens
│   │   └── ProductListScreen/
│   │       ├── ProductListScreen.tsx
│   │       ├── styles.ts
│   │       └── index.ts
│   ├── navigation.tsx         # Feature navigation setup
│   └── state/                 # Feature-specific UI state
│       └── filterStore.ts     # UI filters state
│
├── shopping-cart/             # Shopping cart feature
│   ├── components/
│   ├── screens/
│   ├── navigation.tsx
│   └── state/
│       └── cartUIStore.ts     # Cart UI state (drawer open/close)
│
└── [other-features]/          # Additional features
```

For more information on implementing features and communication between features and domains, see the [Communication Patterns](/docs/features/communication-patterns) guide.

### UI Directory

Shared UI components used across features:

```
ui/
├── Button/                    # Generic button component
│   ├── Button.tsx
│   ├── styles.ts
│   └── index.ts
├── Card/                      # Generic card component
│   ├── Card.tsx
│   ├── styles.ts
│   └── index.ts
├── Input/                     # Generic input component
│   ├── Input.tsx
│   ├── styles.ts
│   └── index.ts
└── [other-components]/        # Other shared UI components
```

For UI component best practices and implementation details, refer to the UI Development guides.

### Navigation Directory

Navigation configuration for the entire app:

```
navigation/
├── RootNavigator.tsx          # Main navigation setup
├── AuthNavigator.tsx          # Auth flow navigation
├── MainNavigator.tsx          # Main app navigation
└── types.ts                   # Navigation type definitions
```

For more information on navigation configuration and routing strategies, see the related sections in the [Core Architecture Reference](/docs/architecture/core-architecture).

### Assets Directory

Static assets organization for brand assets, fonts, animations, and other media:

```
assets/                        # Project root level
├── brand/                     # Brand assets (logos, illustrations)
│   ├── logos/                 # Company/product logos
│   │   ├── company-logo.svg   # SVG for scalability
│   │   ├── product-logo.svg   # SVG for scalability
│   │   └── partner-logo.png   # PNG with @2x, @3x variants
│   ├── illustrations/         # Marketing/onboarding graphics
│   │   ├── onboarding/
│   │   └── empty-states/
│   └── backgrounds/           # Hero banners, splash screens
├── fonts/                     # Custom font files
│   ├── OpenSans-Regular.ttf
│   ├── OpenSans-Bold.ttf
│   └── OpenSans-Italic.ttf
└── animations/                # Lottie and other animations
    └── loading.json           # Loading animation
```

**Important**: UI icons (navigation, actions, status) are managed separately in the UI component system. See the [Icon Management Guide](/docs/ui-development/assets/icon-management) for UI icons and the [Assets Management Guide](/docs/ui-development/assets/assets-management) for brand assets.

### Reference Implementations Directory

Working examples and demonstrations that mirror the main project structure:

<Mermaid
  chart={`
flowchart TD
subgraph main[Main Project]
  MainSrc[src/]
  MainCore[core/]
  MainFeatures[features/]
  MainUI[ui/]
end

subgraph ref[Reference Implementations]
  RefCore[core/]
  RefFeatures[features/]
  RefUI[ui/]
  RefDocs[docs/]
end

MainSrc -.->|"mirrors"| ref
MainCore -.->|"examples"| RefCore
MainFeatures -.->|"patterns"| RefFeatures
MainUI -.->|"components"| RefUI

style main fill:#f9f,stroke:#333
style ref fill:#bfb,stroke:#333
`}
/>

```
reference-implementations/        # Project root level
├── README.md                    # Overview and usage guide
├── core/                        # Domain and shared utilities examples
│   ├── domains/                 # Business logic implementations
│   │   ├── products/            # Product domain examples
│   │   │   ├── api.example.ts   # Product API service patterns
│   │   │   ├── hooks.example.ts # Product hooks implementations
│   │   │   ├── types.example.ts # Product type definitions
│   │   │   └── README.md        # Domain implementation guide
│   │   ├── users/               # User domain examples
│   │   ├── auth/                # Authentication examples
│   │   └── [other-domains]/     # Additional domain examples
│   │
│   └── shared/                  # Shared utilities examples
│       ├── api/                 # API client patterns
│       │   ├── client.example.ts        # Configured API client
│       │   ├── interceptors.example.ts  # Request/response handling
│       │   └── README.md                # API integration guide
│       ├── hooks/               # Generic hook implementations
│       │   ├── useDebounce.example.ts   # Debounce hook pattern
│       │   ├── useLocalStorage.example.ts # Storage hook pattern
│       │   └── README.md                # Hook development guide
│       ├── utils/               # Utility function examples
│       │   ├── validation.example.ts    # Validation patterns
│       │   ├── formatting.example.ts    # Data formatting
│       │   └── README.md                # Utility development guide
│       └── types/               # Cross-domain type examples
│           ├── api.example.ts           # Generic API types
│           ├── ui.example.ts            # UI pattern types
│           └── README.md                # Type architecture guide
│
├── features/                    # Feature implementation examples
│   ├── product-catalog/         # Product browsing feature example
│   │   ├── components/          # Feature-specific components
│   │   ├── screens/             # Feature screen implementations
│   │   ├── navigation.example.tsx # Feature navigation patterns
│   │   ├── state.example.ts     # Feature state management
│   │   └── README.md            # Feature implementation guide
│   ├── shopping-cart/           # Shopping cart feature example
│   ├── user-authentication/     # Auth flow feature example
│   └── [other-features]/        # Additional feature patterns
│
├── ui/                          # UI component implementations
│   ├── foundation/              # Basic building blocks
│   │   ├── Button/              # Button component examples
│   │   │   ├── Button.example.tsx       # Main implementation
│   │   │   ├── Button.variants.tsx      # All visual variants
│   │   │   ├── Button.playground.tsx    # Interactive examples
│   │   │   ├── Button.test.tsx          # Testing patterns
│   │   │   └── README.md                # Component guide
│   │   ├── Input/               # Input component examples
│   │   ├── Card/                # Card component examples
│   │   └── [other-foundation]/  # Additional foundation components
│   │
│   ├── patterns/                # Composed UI patterns
│   │   ├── Modal/               # Modal pattern implementations
│   │   │   ├── Modal.example.tsx        # Basic modal usage
│   │   │   ├── Modal.complex.tsx        # Advanced patterns
│   │   │   ├── Modal.accessibility.tsx  # A11y implementation
│   │   │   └── README.md                # Pattern guide
│   │   ├── Form/                # Form pattern examples
│   │   ├── DataTable/           # Data table implementations
│   │   └── [other-patterns]/    # Additional pattern components
│   │
│   └── business/                # Domain-aware components
│       ├── ProductCard/         # Product display examples
│       │   ├── ProductCard.example.tsx  # Basic implementation
│       │   ├── ProductCard.loading.tsx  # Loading states
│       │   ├── ProductCard.error.tsx    # Error handling
│       │   └── README.md                # Business component guide
│       ├── UserAvatar/          # User display examples
│       └── [other-business]/    # Additional business components
│
└── docs/                        # Documentation examples
    ├── guides/                  # Implementation guides
    ├── patterns/                # Code pattern examples
    └── best-practices/          # Best practice implementations
```

#### Purpose and Benefits

**Documentation → Examples → Implementation Flow**:

1. **Learn**: Read comprehensive documentation
2. **Study**: Examine working reference implementations
3. **Implement**: Build production features with confidence

**Key Benefits**:

* **Working Code**: All examples are tested and functional
* **Mirror Structure**: 1:1 mapping with main project architecture
* **Progressive Learning**: From simple examples to complex patterns
* **Template Ready**: Copy-paste starting points for new features
* **Best Practices**: Demonstrates recommended patterns and approaches

**Cross-References**: Each implementation includes:

* Links back to relevant documentation sections
* GitHub source links for the actual production code
* Testing examples and patterns
* Performance considerations
* Accessibility implementations

For detailed information on using reference implementations effectively, see the [Reference Implementation Guide](/docs/reference-implementations).

## Module Boundaries

### Shared vs Domain Rules

<Mermaid
  chart={`
flowchart TD
subgraph Shared[core/shared - Generic Utilities]
  SharedHooks[Generic Hooks<br/>useDebounce, useLocalStorage]
  SharedUtils[Generic Utils<br/>formatDate, capitalizeString]
  SharedTypes[Cross-domain Types<br/>ApiResponse, AsyncState]
end

subgraph Domains[core/domains - Business Logic]
  ProductDomain[products/<br/>API, types, hooks]
  UserDomain[users/<br/>API, types, hooks]
  AuthDomain[auth/<br/>API, types, hooks, store]
end

subgraph Features[features/ - UI Layer]
  ProductCatalog[product-catalog]
  ShoppingCart[shopping-cart]
end

Features --> Shared
Features --> Domains
Domains --> Shared
Domains -.->|"Allowed but minimize"| Domains
Features -.-|"❌ NEVER"| Features

style Domains fill:#f9f,stroke:#333,stroke-width:2px
style Shared fill:#9ff,stroke:#333,stroke-width:2px
style Features fill:#ff9,stroke:#333,stroke-width:2px
`}
/>

### Import Rules

<Callout type="info">
  **Why Import Rules Matter**

  Clear import boundaries help maintain a clean architecture by preventing circular dependencies,
  ensuring proper separation of concerns, and making the codebase more maintainable and testable.
</Callout>

#### Allowed Import Patterns

* **Features** can import from:
  * Core domains (`core/domains/*`) for business logic
  * Shared utilities (`core/shared/*`) for common functions
  * UI components (`ui/*`) for shared interface elements
  * Navigation (`navigation/*`) for routing functions

* **Core domains** can import from:
  * Shared utilities (`core/shared/*`) only

* **UI components** can import from:
  * Shared utilities (`core/shared/*`) only

* **Navigation** can import from:
  * Shared utilities (`core/shared/*`) only

#### Prohibited Import Patterns

* **Features** cannot import from:
  * Other features (to prevent feature coupling)

* **Core domains** cannot import from:
  * Features (to prevent business logic depending on UI)
  * Other domains (to maintain domain independence)

* **Shared utilities** cannot import from:
  * Features (to maintain utility independence)
  * Domains (to keep utilities truly shared and reusable)

<Mermaid
  chart={`
flowchart TD
subgraph Allowed[Allowed Import Patterns]
  Features[features/*]
  UI[ui/*]
  Navigation[navigation/*]
  Domains[core/domains/*]
  Shared[core/shared/*]
  
  Features -->|✓ can import| Domains
  Features -->|✓ can import| Shared
  Features -->|✓ can import| UI
  Features -->|✓ can import| Navigation
  
  Domains -->|✓ can import| Shared
  
  UI -->|✓ can import| Shared
  Navigation -->|✓ can import| Shared
end

subgraph Prohibited[Prohibited Import Patterns]
  Features2[features/*]
  Domains2[core/domains/*]
  Shared2[core/shared/*]
  
  Features2 -->|❌ cannot import| Features2
  Domains2 -->|❌ cannot import| Features2
  Domains2 -->|❌ cannot import| Domains2
  Shared2 -->|❌ cannot import| Domains2
  Shared2 -->|❌ cannot import| Features2
end

style Allowed fill:#f8f8f8,stroke:#333
style Prohibited fill:#fff8f8,stroke:#333

style Features fill:#f9f,stroke:#333
style UI fill:#bbf,stroke:#333
style Navigation fill:#fbb,stroke:#333
style Domains fill:#bfb,stroke:#333
style Shared fill:#dfd,stroke:#333

style Features2 fill:#f9f,stroke:#333
style Domains2 fill:#bfb,stroke:#333
style Shared2 fill:#dfd,stroke:#333
`}
/>

#### Common Import Violations to Avoid

* **Cross-feature imports**: Features should not directly import from each other
* **Domain-to-domain imports**: Domains should remain independent of each other
* **Shared importing domains**: Shared utilities must not depend on domain-specific code
* **Circular dependencies**: No module should directly or indirectly depend on itself

### Decision Tree for Code Placement

```
Is this code specific to one business domain?
├─ YES → Place in core/domains/[domain]/
│   ├─ API calls? → api.ts
│   ├─ Data types? → types.ts
│   ├─ React hooks? → hooks.ts
│   └─ Query keys? → queryKeys.ts
│
└─ NO → Is it used across multiple domains?
    ├─ YES → Place in core/shared/
    │   ├─ React hook? → shared/hooks/
    │   ├─ Utility function? → shared/utils/
    │   └─ Type definition? → shared/types/
    │
    └─ NO → Is it UI-specific?
        ├─ YES → Place in features/[feature]/
        └─ NO → Reconsider architecture
```

## Component Structure

All components follow this consistent structure:

```
ComponentName/
├── ComponentName.tsx          # Component implementation
├── styles.ts                  # Component-specific styles
├── types.ts                   # Component-specific types (optional)
├── __tests__/                 # Tests directory
│   └── ComponentName.test.tsx # Unit tests
└── index.ts                   # Exports component
```

## File Naming Conventions

This project follows strict file naming conventions to ensure consistency:

* **Components**: PascalCase (e.g., `Button.tsx`, `ProductCard.tsx`)
* **Hooks**: camelCase with "use" prefix (e.g., `useAuth.ts`, `useDebounce.ts`)
* **Domain files**: lowercase descriptive (e.g., `api.ts`, `types.ts`)
* **Utilities**: lowercase by category (e.g., `date.ts`, `string.ts`)
* **Features**: kebab-case folders (e.g., `product-catalog/`)
* **Tests**: `.test.ts` or `.test.tsx` suffix

For complete naming guidelines, see the [File Naming Conventions](/docs/coding-standards/file-naming-conventions).

## Do's and Don'ts

### Shared Folders Guidelines

* (Do ✅) Place **generic, reusable** hooks like `useDebounce` in `core/shared/hooks/`
* (Don't ❌) Put **domain-specific** hooks like `useProducts` in shared hooks
* (Do ✅) Keep **general utilities** like `formatDate` in `core/shared/utils/`
* (Don't ❌) Put **domain utilities** like `calculateProductDiscount` in shared utils
* (Do ✅) Store **cross-domain types** like `ApiResponse` and `AsyncState` in `core/shared/types/`
* (Don't ❌) Put **component-specific types** like `ButtonProps` in shared types - these belong co-located with components per the [Feature Implementation Decision Tree](/docs/guides/feature-implementation-decision-tree)
* (Don't ❌) Duplicate **domain types** like `Product` in shared types

### Domain Folders Guidelines

* (Do ✅) Keep **domain queries** like `useProducts` in `core/domains/products/hooks.ts`
* (Do ✅) Store **domain models** like `Product` in `core/domains/products/types.ts`
* (Do ✅) Place **domain API calls** in `core/domains/products/api.ts`
* (Consider 🤔) Creating `utils.ts` in domain if needed for domain-specific helpers
* (Consider 🤔) Adding `queryKeys.ts` only if you have > 3 query keys

### Feature Folders Guidelines

* (Do ✅) Import data from **domain hooks** (`core/domains/*/hooks.ts`)
* (Do ✅) Use **shared utilities** from `core/shared/*`
* (Do ✅) Keep **UI state** local to features
* (Don't ❌) Import from **other features**
* (Don't ❌) Implement **business logic** in features

### General Guidelines

* (Do ✅) Use **index.ts** files for clean exports
* (Do ✅) Maintain **consistent naming** conventions
* (Do ✅) Write **tests** alongside components
* (Don't ❌) Create **circular dependencies**
* (Don't ❌) Mix **concerns** (UI with business logic)

## Examples

### Correct Import Patterns

```typescript
// In features/product-catalog/screens/ProductList.tsx
import { useProducts } from '@/core/domains/products'; // ✅ Domain hook
import { formatCurrency } from '@/core/shared/utils'; // ✅ Shared utility  
import { Button } from '@/ui/foundation/Button'; // ✅ Shared UI component

// In core/domains/products/api.ts
import { apiClient } from '@/core/shared/api'; // ✅ Shared API client
import type { Product } from './types'; // ✅ Same domain type

// In core/shared/hooks/useDebounce.ts
import { useState, useEffect } from 'react'; // ✅ Only React imports
// No domain imports! ✅
```

### Incorrect Import Patterns

```typescript
// In features/product-catalog/screens/ProductList.tsx
import { CartItem } from '@/features/shopping-cart/components'; // ❌ Cross-feature

// In core/shared/utils/product.ts
import { Product } from '@/core/domains/products'; // ❌ Domain in shared

// In core/domains/products/hooks.ts
import { useDebounce } from '@/core/shared/hooks'; // ✅ Fixed: Use shared hook
```

## Implementation Considerations

### Adding New Domains

1. Create folder: `core/domains/[domain-name]/`
2. Add required files:
   * `api.ts` - API service methods
   * `types.ts` - TypeScript interfaces
   * `hooks.ts` - Query/mutation hooks
3. Add optional files as needed:
   * `queryKeys.ts` - If many query keys
   * `store.ts` - If client state needed
   * `events.ts` - If event system needed
4. Update barrel exports

### Adding New Features

1. Create folder: `features/[feature-name]/`
2. Add standard structure:
   * `screens/` - Feature screens
   * `components/` - Feature components
   * `navigation.tsx` - Feature routing
3. Import from domains for data
4. Keep business logic in domains

### Migration Strategy

When refactoring existing code:

1. **Identify domain boundaries**
   * Group related API calls
   * Extract business types

2. **Move to appropriate locations**
   * Domain logic → `core/domains/`
   * Generic utilities → `core/shared/`
   * UI components → Features or `ui/`

3. **Update imports**
   * Fix all import paths
   * Remove circular dependencies

4. **Test thoroughly**
   * Ensure no regressions
   * Verify module boundaries

## Related Documents

* [](/docs/architecture/core-architecture)
* [](/docs/architecture/domain-architecture)
* [](/docs/features/shared-utilities)
* [](/docs/coding-standards/file-naming-conventions)
* [](/docs/features/communication-patterns)
* [](/docs/ui-development/assets)


# UTA Architecture: Domain Architecture Guide
URL: https://dev.updatetheapp.com/docs/architecture/domain-architecture
Documentation: https://dev.updatetheapp.com/docs/architecture/domain-architecture

Guide to implementing domain-based architecture for business logic organization.
        
***

title: Domain Architecture Guide
description: Guide to implementing domain-based architecture for business logic organization.
---------------------------------------------------------------------------------------------

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';

# Domain Architecture Guide

## Overview

This guide explains our approach to domain-based architecture, which we've implemented in the `core/domains/` directory. In our experience, organizing business logic by entity (such as products, users, authentication) rather than by technical concern creates clearer boundaries and significantly improves scalability as applications grow.

Domain-based architecture helps solve several common challenges in React Native development:

* **Code organization** as applications scale beyond a handful of features
* **Maintainability** by creating logical boundaries between business entities
* **Team collaboration** by enabling parallel work with minimal conflicts
* **Testing** by isolating business logic from UI concerns

By following these patterns, we've found teams can work more efficiently and produce more robust applications.

## Purpose & Scope

This document is designed to help developers at all experience levels:

<Tabs items={["What You'll Learn", "Who This Is For", "Prerequisites"]}>
  <Tab>
    * When and why to create separate domains for business logic
    * How to structure domain folders for consistency and discoverability
    * Patterns for implementing domain services, hooks, and types
    * Best practices for maintaining proper boundaries between domains
    * Techniques for cross-domain communication without tight coupling
  </Tab>

  <Tab>
    * **New team members** wanting to understand our architecture
    * **Feature developers** needing to integrate with domain services
    * **Domain maintainers** responsible for implementing business logic
    * **Technical leads** making architectural decisions
  </Tab>

  <Tab>
    To get the most from this guide, you should be familiar with:

    * Basic React and React Native concepts
    * TypeScript fundamentals (interfaces, types)
    * [Core Architecture Reference](/docs/architecture/core-architecture) (recommended first)
    * [API Integration](/docs/api) (helpful for understanding API services)
  </Tab>
</Tabs>

## Domain Boundaries

### Key Principles

1. **Domain Independence**: Domains should be self-contained and not directly import from each other
2. **Shared Interface**: Domains expose public APIs through hooks and types
3. **Feature Integration**: Features compose multiple domains for UI

<Mermaid
  chart={`
flowchart TD
subgraph Features[Feature Modules]
  ProductList[Product List Feature]
  ShoppingCart[Shopping Cart Feature]
  Checkout[Checkout Feature]
end

subgraph Domains[Domain Modules]
  ProductDomain[Products Domain]
  CartDomain[Cart Domain]
  UserDomain[User Domain]
  OrderDomain[Orders Domain]
end

ProductList --> ProductDomain
ShoppingCart --> ProductDomain
ShoppingCart --> CartDomain
Checkout --> CartDomain
Checkout --> UserDomain
Checkout --> OrderDomain

style Features fill:#f8f8f8,stroke:#333
style Domains fill:#f0f0f0,stroke:#333

style ProductList fill:#bbf,stroke:#333
style ShoppingCart fill:#bbf,stroke:#333
style Checkout fill:#bbf,stroke:#333

style ProductDomain fill:#bfb,stroke:#333
style CartDomain fill:#bfb,stroke:#333
style UserDomain fill:#bfb,stroke:#333
style OrderDomain fill:#bfb,stroke:#333
`}
/>

### Cross-Domain Communication

<Mermaid
  chart={`
flowchart TD
subgraph Feature[Feature Component]
  FeatureUI[Checkout Screen]
end

subgraph Domains[Domain Communication Patterns]
  subgraph Orders[Orders Domain]
    OrdersAPI[Orders API]
    OrdersHooks[Orders Hooks]
  end
  
  subgraph Products[Products Domain]
    ProductsAPI[Products API]
    ProductsHooks[Products Hooks]
  end
  
  subgraph User[User Domain]
    UserAPI[User API]
    UserHooks[User Hooks]
  end
  
  subgraph Auth[Auth Domain]
    AuthAPI[Auth API]
    AuthEvents[Auth Events]
  end
end

%% Feature consuming multiple domains
FeatureUI --> OrdersHooks
FeatureUI --> ProductsHooks
FeatureUI --> UserHooks

%% Domain-to-domain communication
OrdersHooks --> ProductsAPI
OrdersHooks --> UserAPI

%% Event-based communication
AuthEvents --> Orders
AuthEvents --> Products
AuthEvents --> User

style FeatureUI fill:#bbf,stroke:#333

style OrdersHooks fill:#f9f,stroke:#333
style ProductsHooks fill:#f9f,stroke:#333
style UserHooks fill:#f9f,stroke:#333

style OrdersAPI fill:#bfb,stroke:#333
style ProductsAPI fill:#bfb,stroke:#333
style UserAPI fill:#bfb,stroke:#333
style AuthEvents fill:#fbb,stroke:#333
style AuthAPI fill:#bfb,stroke:#333
`}
/>

#### Communication Patterns

1. **Direct Hook Usage**: Features import and use hooks from multiple domains simultaneously
2. **Cross-Domain API Calls**: Domain services can access other domain services through their public APIs
3. **Event-Based Communication**: Domains can broadcast events that other domains listen for
4. **Shared State Access**: Domains can share data through centralized state stores

## What is a Domain?

A domain represents a distinct business entity or area of functionality:

* **Products**: Everything related to product data and operations
* **Users**: User management and profile functionality
* **Auth**: Authentication and authorization logic
* **Orders**: Order processing and management
* **Payments**: Payment processing logic

## Domain Structure

### Standard Domain Anatomy

Every domain follows this structure:

```
core/domains/[domain-name]/
├── api.ts          # API service methods (required)
├── types.ts        # TypeScript interfaces (required)
├── hooks.ts        # React Query hooks (required)
├── queryKeys.ts    # Query key factory (optional)
├── store.ts        # Client state if needed (optional)
├── events.ts       # Event definitions (optional)
├── utils.ts        # Domain utilities (optional)
└── index.ts        # Barrel exports (required)
```

<Mermaid
  chart={`
flowchart TD
subgraph DomainModule[Domain Module Structure]
  API[api.ts - API Service]
  Types[types.ts - Type Definitions]
  Hooks[hooks.ts - Query Hooks]
  QueryKeys[queryKeys.ts - Query Keys]
  Store[store.ts - Client State]
  Events[events.ts - Domain Events]
  Utils[utils.ts - Domain Utils]
  Index[index.ts - Exports]
end

Index --> API
Index --> Types
Index --> Hooks
Index --> QueryKeys
Index --> Store
Index --> Events
Index --> Utils

Hooks --> API
Hooks --> QueryKeys
Hooks --> Types

API --> Types

classDef required fill:#f9f,stroke:#333
classDef optional fill:#bfb,stroke:#333

class API,Types,Hooks,Index required
class QueryKeys,Store,Events,Utils optional
`}
/>

### Required Files

All domain files follow our [File Naming Conventions](/docs/coding-standards/file-naming-conventions). Each file has a specific purpose:

#### 1. `api.ts` - API Service Methods

Contains all API calls for the domain, following the **mandatory** public/protected pattern:

```typescript
// core/domains/products/api.ts
import { publicApi, authenticatedApi } from '@/core/shared/api/client';
import type { Product, CreateProductDto, UpdateProductDto } from './types';

class ProductApi {
  // Public endpoints (no auth required)
  public readonly public = {
    getAll: async (): Promise<Product[]> => {
      const { data } = await publicApi.get('/products');
      return data;
    },

    getById: async (id: string): Promise<Product> => {
      const { data } = await publicApi.get(`/products/${id}`);
      return data;
    },

    search: async (query: string): Promise<Product[]> => {
      const { data } = await publicApi.get('/products/search', {
        params: { q: query }
      });
      return data;
    },
  };

  // Protected endpoints (auth required)
  public readonly protected = {
    create: async (product: CreateProductDto): Promise<Product> => {
      const { data } = await authenticatedApi.post('/products', product);
      return data;
    },

    update: async (id: string, updates: UpdateProductDto): Promise<Product> => {
      const { data } = await authenticatedApi.put(`/products/${id}`, updates);
      return data;
    },

    delete: async (id: string): Promise<void> => {
      await authenticatedApi.delete(`/products/${id}`);
    },

    getUserProducts: async (userId: string): Promise<Product[]> => {
      const { data } = await authenticatedApi.get(`/users/${userId}/products`);
      return data;
    },
  };
}

export const productApi = new ProductApi();
```

**This pattern is required for all domain APIs**. Benefits:

* Clear separation of public vs authenticated endpoints
* No runtime flags or configuration needed
* Type-safe API calls
* Better developer experience with IntelliSense

<Mermaid
  chart={`
flowchart LR
subgraph DomainAPI[Domain API Service]
  Public[Public Endpoints]
  Protected[Protected Endpoints]
end

subgraph APIClients[API Clients]
  PublicClient[Public API Client]
  AuthClient[Authenticated API Client]
end

Public --> PublicClient
Protected --> AuthClient

PublicClient --> Backend
AuthClient --> Backend

Backend[Backend API]

style Public fill:#bfb,stroke:#333
style Protected fill:#f9f,stroke:#333
`}
/>

#### 2. `types.ts` - TypeScript Interfaces

Defines all types for the domain:

```typescript
// core/domains/products/types.ts
export interface Product {
  id: string;
  name: string;
  description: string;
  price: number;
  category: string;
  inStock: boolean;
  createdAt: Date;
  updatedAt: Date;
}

export interface CreateProductDto {
  name: string;
  description: string;
  price: number;
  category: string;
  inStock?: boolean;
}

export interface UpdateProductDto {
  name?: string;
  description?: string;
  price?: number;
  category?: string;
  inStock?: boolean;
}

export interface ProductFilters {
  category?: string;
  minPrice?: number;
  maxPrice?: number;
  inStock?: boolean;
}
```

#### 3. `hooks.ts` - React Query Hooks

Implements data fetching hooks using TanStack Query, following the public/protected pattern:

```typescript
// core/domains/products/hooks.ts
import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
import { productApi } from './api';
import { productQueryKeys } from './queryKeys';
import type { Product, CreateProductDto, UpdateProductDto, ProductFilters } from './types';

// Public query hooks (no auth required)
export function useProducts(filters?: ProductFilters) {
  return useQuery({
    queryKey: productQueryKeys.list(filters),
    queryFn: () => productApi.public.getAll(filters),
  });
}

export function useProduct(id: string) {
  return useQuery({
    queryKey: productQueryKeys.detail(id),
    queryFn: () => productApi.public.getById(id),
    enabled: !!id,
  });
}

export function useProductSearch(query: string) {
  return useQuery({
    queryKey: productQueryKeys.search(query),
    queryFn: () => productApi.public.search(query),
    enabled: query.length > 2,
  });
}

// Protected mutation hooks (auth required)
export function useCreateProduct() {
  const queryClient = useQueryClient();

  return useMutation({
    mutationFn: productApi.protected.create,
    onSuccess: () => {
      queryClient.invalidateQueries({ 
        queryKey: productQueryKeys.lists() 
      });
    },
  });
}

export function useUpdateProduct() {
  const queryClient = useQueryClient();

  return useMutation({
    mutationFn: ({ id, updates }: { id: string; updates: UpdateProductDto }) => 
      productApi.protected.update(id, updates),
    onSuccess: (data, { id }) => {
      queryClient.setQueryData(productQueryKeys.detail(id), data);
      queryClient.invalidateQueries({ 
        queryKey: productQueryKeys.lists() 
      });
    },
  });
}

export function useDeleteProduct() {
  const queryClient = useQueryClient();

  return useMutation({
    mutationFn: productApi.protected.delete,
    onSuccess: (_, id) => {
      queryClient.removeQueries({ 
        queryKey: productQueryKeys.detail(id) 
      });
      queryClient.invalidateQueries({ 
        queryKey: productQueryKeys.lists() 
      });
    },
  });
}

// Protected query hooks (auth required)
export function useUserProducts(userId: string) {
  return useQuery({
    queryKey: productQueryKeys.userProducts(userId),
    queryFn: () => productApi.protected.getUserProducts(userId),
    enabled: !!userId,
  });
}
```

#### Domain Data Flow Pattern

<Mermaid
  chart={`
flowchart LR
subgraph Application[Application Flow]
  UI[UI Component]
  Hooks[Domain Hooks]
  API[API Service]
  Backend[Backend]
end

UI --> Hooks
Hooks --> API
API --> Backend
Backend --> API
API --> Hooks
Hooks --> UI

style UI fill:#bbf,stroke:#333
style Hooks fill:#f9f,stroke:#333
style API fill:#bfb,stroke:#333
style Backend fill:#fbb,stroke:#333
`}
/>

#### Data Flow Steps

1. UI Component calls domain hook (e.g., `useProducts()`)
2. Domain hook calls API service
3. API service makes HTTP request to backend
4. Backend responds with data
5. API service returns typed data to hook
6. Hook returns cached data to UI

### Optional Files

#### 4. `queryKeys.ts` - Query Key Factory

Use when you have > 3 query keys:

```typescript
// core/domains/products/queryKeys.ts
export const productQueryKeys = {
  all: ['products'] as const,
  lists: () => [...productQueryKeys.all, 'list'] as const,
  list: (filters?: ProductFilters) => 
    [...productQueryKeys.lists(), { filters }] as const,
  details: () => [...productQueryKeys.all, 'detail'] as const,
  detail: (id: string) => [...productQueryKeys.details(), id] as const,
  byCategory: (category: string) => 
    [...productQueryKeys.all, 'category', category] as const,
};
```

#### 5. `store.ts` - Client State

For domain-specific UI state:

```typescript
// core/domains/products/store.ts
import { create } from 'zustand';

interface ProductsUIState {
  selectedCategory: string | null;
  viewMode: 'grid' | 'list';
  sortBy: 'name' | 'price' | 'date';
  setSelectedCategory: (category: string | null) => void;
  setViewMode: (mode: 'grid' | 'list') => void;
  setSortBy: (sort: 'name' | 'price' | 'date') => void;
}

export const useProductsUIStore = create<ProductsUIState>((set) => ({
  selectedCategory: null,
  viewMode: 'grid',
  sortBy: 'name',
  setSelectedCategory: (category) => set({ selectedCategory: category }),
  setViewMode: (mode) => set({ viewMode: mode }),
  setSortBy: (sort) => set({ sortBy: sort }),
}));
```

#### 6. `events.ts` - Event Definitions

For pub/sub communication:

```typescript
// core/domains/products/events.ts
import { EventEmitter } from '@/core/shared/utils/events';

export type ProductEvents = {
  'product:created': { productId: string };
  'product:updated': { productId: string; changes: Record<string, any> };
  'product:deleted': { productId: string };
  'product:stockLow': { productId: string; quantity: number };
};

export const productEvents = new EventEmitter<ProductEvents>();

// Usage example
productEvents.on('product:stockLow', ({ productId, quantity }) => {
  console.log(`Product ${productId} has low stock: ${quantity}`);
});
```

#### 7. `index.ts` - Barrel Exports

Clean public API for the domain:

```typescript
// core/domains/products/index.ts
export * from './api';
export * from './types';
export * from './hooks';
export * from './queryKeys';
export { productEvents } from './events';
export { useProductsUIStore } from './store';
```

## Real-World Examples

### Authentication Domain

The auth domain has special requirements:

```typescript
// core/domains/auth/tokenService.ts
import { storage } from '@/core/shared/utils/storage';

export const tokenService = {
  getAccessToken: () => storage.get('accessToken'),
  getRefreshToken: () => storage.get('refreshToken'),
  setTokens: (access: string, refresh: string) => {
    storage.set('accessToken', access);
    storage.set('refreshToken', refresh);
  },
  clearTokens: () => {
    storage.remove('accessToken');
    storage.remove('refreshToken');
  },
};
```

```typescript
// core/domains/auth/events.ts
import { EventEmitter } from '@/core/shared/utils/events';

export type AuthEvents = {
  'auth:login': { userId: string };
  'auth:logout': void;
  'auth:sessionExpired': void;
  'auth:tokenRefreshed': { accessToken: string };
};

export const authEvents = new EventEmitter<AuthEvents>();
```

### User Domain

```typescript
// core/domains/users/hooks.ts
export function useCurrentUser() {
  return useQuery({
    queryKey: userQueryKeys.current(),
    queryFn: userApi.getCurrentUser,
  });
}

export function useUpdateProfile() {
  const queryClient = useQueryClient();

  return useMutation({
    mutationFn: (updates: UpdateProfileDto) => 
      userApi.updateProfile(updates),
    onSuccess: (data) => {
      queryClient.setQueryData(userQueryKeys.current(), data);
    },
  });
}
```

## Communication Between Domains

### Preferred: Through Shared Cache

```typescript
// In products domain
export function useProductWithUser(productId: string) {
  const { data: product } = useProduct(productId);
  const { data: user } = useUser(product?.ownerId);
  
  return { product, owner: user };
}
```

### Alternative: Through Events

```typescript
// In orders domain
import { productEvents } from '@/core/domains/products';

export function useCreateOrder() {
  return useMutation({
    mutationFn: orderApi.create,
    onSuccess: (order) => {
      // Notify product domain about stock changes
      order.items.forEach(item => {
        productEvents.emit('product:stockLow', {
          productId: item.productId,
          quantity: item.remainingStock,
        });
      });
    },
  });
}
```

## Domain Creation Checklist

When creating a new domain:

### 1. Identify the Domain

* [ ] Clear business entity (e.g., products, users)
* [ ] Has distinct API endpoints
* [ ] Contains related types and operations

### 2. Create the Structure

* [ ] Create folder: `core/domains/[domain-name]/`
* [ ] Add required files: `api.ts`, `types.ts`, `hooks.ts`
* [ ] Add optional files as needed
* [ ] Create barrel export: `index.ts`

### 3. Implement Core Functionality

* [ ] Define types in `types.ts`
* [ ] Implement API methods in `api.ts`
* [ ] Create query/mutation hooks in `hooks.ts`
* [ ] Add query keys if > 3 queries

### 4. Handle Special Cases

* [ ] Add client state if needed (`store.ts`)
* [ ] Implement events if needed (`events.ts`)
* [ ] Add domain utilities if needed (`utils.ts`)

### 5. Update Documentation

* [ ] Add domain to architecture docs
* [ ] Document special behaviors
* [ ] Update team guidelines

## Best Practices

<Callout type="info">
  **Why These Practices Matter**

  These patterns have evolved through our experience building and maintaining large-scale React Native applications. They help ensure consistency, maintainability, and scalability as your application grows and as team members come and go.
</Callout>

### 1. API Service Patterns

**(Do ✅) Use the public/protected pattern for all domain APIs**

This pattern creates a clear separation between endpoints that require authentication and those that don't, which helps prevent security mistakes and improves developer experience:

```typescript
class ProductApi {
  public readonly public = {
    // Endpoints that don't require authentication
    getAll: async (): Promise<Product[]> => {
      const { data } = await publicApi.get('/products');
      return data;
    },
  };
  
  public readonly protected = {
    // Endpoints that require authentication
    create: async (product: CreateProductDto): Promise<Product> => {
      const { data } = await authenticatedApi.post('/products', product);
      return data;
    },
  };
}
```

The benefits of this approach include:

* Clear visual distinction between authenticated and unauthenticated endpoints
* Compile-time safety through TypeScript's property access checking
* Better IntelliSense support with grouped methods
* No runtime checks or flags needed for auth requirements

**(Don't ❌) Use API clients directly or rely on configuration flags**

Avoid approaches that mix authentication concerns or rely on flags:

```typescript
// DON'T do this
export const productApi = {
  // Unclear which endpoints need authentication
  getAll: () => apiClient.get('/products', { skipAuth: true }),
  create: (data) => apiClient.post('/products', data),
};
```

This approach creates several problems:

* Authentication requirements are not obvious from the code structure
* Easy to forget the `skipAuth` flag and cause runtime errors
* No compile-time safety for authentication requirements
* Harder to maintain consistency as the codebase grows

### 2. Domain Boundaries and Focus

**(Do ✅) Keep domains focused on a single business entity**

A well-designed domain should represent a single business concept with clear boundaries:

```typescript
// core/domains/products/api.ts
class ProductApi {
  public readonly public = {
    getAll: async (): Promise<Product[]> => {
      const { data } = await publicApi.get('/products');
      return data;
    },
    getById: async (id: string): Promise<Product> => {
      const { data } = await publicApi.get(`/products/${id}`);
      return data;
    },
  };
  
  public readonly protected = {
    create: async (product: CreateProductDto): Promise<Product> => {
      const { data } = await authenticatedApi.post('/products', product);
      return data;
    },
    update: async (id: string, updates: UpdateProductDto): Promise<Product> => {
      const { data } = await authenticatedApi.put(`/products/${id}`, updates);
      return data;
    },
    delete: async (id: string): Promise<void> => {
      await authenticatedApi.delete(`/products/${id}`);
    },
  };
}
```

By keeping domains focused, you gain several benefits:

* **Easier maintenance**: Each domain is smaller and more manageable
* **Better code organization**: Logical grouping of related functionality
* **Clearer ownership**: Teams can own specific domains
* **More targeted testing**: Domain-specific test suites

**(Don't ❌) Mix multiple business entities in a single domain**

Mixing responsibilities creates confusion and maintenance challenges:

```typescript
// DON'T do this
class ProductAndUserApi {
  public readonly public = {
    // Product methods
    getProducts: async (): Promise<Product[]> => {
      const { data } = await publicApi.get('/products');
      return data;
    },
    getProductById: async (id: string): Promise<Product> => {
      const { data } = await publicApi.get(`/products/${id}`);
      return data;
    },
    
    // User methods - should be in users domain
    getUsers: async (): Promise<User[]> => {
      const { data } = await publicApi.get('/users');
      return data;
    },
    getUserById: async (id: string): Promise<User> => {
      const { data } = await publicApi.get(`/users/${id}`);
      return data;
    },
  };
};
```

This approach creates several problems:

* **Unclear domain boundaries**: Where does one entity end and another begin?
* **Harder to maintain**: Changes to one entity might affect the other
* **Difficult testing**: Tests for different entities are mixed together
* **Poor code organization**: Code for different business concepts is intermingled
* **Challenges for team ownership**: Hard to assign ownership to different teams

### 3. Use Consistent Naming

<Callout type="info">
  Consistent naming patterns significantly improve developer experience by making code more predictable and easier to navigate. They also reduce the cognitive load when switching between different parts of the codebase.
</Callout>

**(Do ✅) Follow established naming conventions for all domain artifacts**

These conventions make code more predictable and discoverable:

| Type           | Pattern                 | Examples                                              |
| -------------- | ----------------------- | ----------------------------------------------------- |
| API instances  | `[domain]Api`           | `productApi`, `userApi`, `orderApi`                   |
| Query hooks    | `use[Resource]`         | `useProducts`, `useUser`, `useOrder`                  |
| Mutation hooks | `use[Action][Resource]` | `useCreateProduct`, `useUpdateUser`, `useDeleteOrder` |
| State stores   | `use[Domain]Store`      | `useProductStore`, `useCartStore`                     |
| Events         | `[domain]Events`        | `productEvents`, `authEvents`                         |
| Query keys     | `[domain]QueryKeys`     | `productQueryKeys`, `userQueryKeys`                   |

**(Consider 🤔) Creating a domain naming cheat sheet for your team**

As your application grows, consider documenting naming patterns in a quick-reference format for new team members.

**(Don't ❌) Mix naming conventions or create inconsistent patterns**

Inconsistent naming creates confusion and slows down development:

```typescript
// DON'T do this - inconsistent naming

// Different naming styles for similar concepts
export const productApiService = new ProductApiService(); // Too verbose
export const userApiClient = new UserApiClient();  // Different suffix
export const orderService = new OrderService();  // Missing "Api"

// Inconsistent hook naming
export function useGetProducts() { /* ... */ }  // "Get" is redundant
export function fetchUsers() { /* ... */ }      // Missing "use" prefix
export function orderQueryHook() { /* ... */ }  // Unclear purpose
```

Consistent naming provides several benefits:

* **Predictability**: Developers can guess file and export names correctly
* **Clarity**: The purpose of each artifact is immediately clear
* **Maintainability**: Easier to implement tooling and linting rules
* **Onboarding**: New team members learn patterns more quickly

### 4. Separate Public and Protected Hooks

<Callout type="info">
  The authentication requirements of your hooks should match the authentication requirements of the underlying API methods they use. This creates a consistent security model throughout your application.
</Callout>

**(Do ✅) Match hook authentication requirements to API authentication requirements**

When creating hooks, ensure their authentication requirements align with the API methods they call:

```typescript
// Public hooks (no auth required) call public API methods
export function useProducts() {
  return useQuery({
    queryKey: productQueryKeys.list(),
    queryFn: () => productApi.public.getAll(),
  });
}

// Protected hooks (auth required) call protected API methods
export function useCreateProduct() {
  const queryClient = useQueryClient();
  return useMutation({
    mutationFn: productApi.protected.create,
    onSuccess: () => {
      queryClient.invalidateQueries({ queryKey: productQueryKeys.lists() });
    },
  });
}
```

This alignment provides several benefits:

* **Security consistency**: Authentication requirements are clear at every level
* **Predictable behavior**: Hooks fail in expected ways when auth is missing
* **Better developer experience**: API structure guides hook organization

**(Don't ❌) Mix authentication requirements or add unnecessary authentication**

These approaches create confusion and security risks:

```typescript
// DON'T do this

// Public data shouldn't require authentication
export function usePublicProducts() {
  // Wrong: Using protected API for public data
  return useQuery({
    queryKey: ['products'],
    queryFn: () => protectedApiClient.get('/public-products'),
  });
}

// Don't add conditional authentication
export function useProducts(requireAuth = false) {
  // Wrong: Dynamic authentication creates unpredictable behavior
  const client = requireAuth ? protectedApiClient : publicApiClient;
  return useQuery({
    queryKey: ['products', { auth: requireAuth }],
    queryFn: () => client.get('/products'),
  });
}
```

**(Consider 🤔) Adding explicit documentation about authentication requirements**

For larger teams, consider adding JSDoc comments that explicitly state authentication requirements:

```typescript
/**
 * Hook to fetch products list - no authentication required
 */
export function useProducts() { /* ... */ }

/**
 * Hook to create a new product - requires authentication
 * @throws {UnauthorizedError} When user is not authenticated
 */
export function useCreateProduct() { /* ... */ }
```

### 5. Handle Errors Gracefully

<Callout type="info">
  Error handling is a critical aspect of domain hooks. Well-designed error handling improves the user experience and makes debugging easier.
</Callout>

**(Do ✅) Implement consistent error handling in all query hooks**

```typescript
export function useProduct(id: string) {
  return useQuery({
    queryKey: productQueryKeys.detail(id),
    queryFn: async () => {
      try {
        return await productApi.public.getById(id);
      } catch (error) {
        // Transform API errors to more user-friendly format
        if (error.status === 404) {
          throw new ProductNotFoundError(id);
        }
        throw error; // Re-throw other errors
      }
    },
    enabled: !!id,
    retry: (failureCount, error) => {
      // Only retry for network errors, not for 404s
      if (error instanceof ProductNotFoundError) return false;
      return failureCount < 3;
    },
  });
}
```

### 6. Optimize Query Patterns

```typescript
// Use query options effectively
export function useProducts(options?: UseQueryOptions<Product[]>) {
  return useQuery({
    queryKey: productQueryKeys.all(),
    queryFn: productApi.public.getAll,
    staleTime: 5 * 60 * 1000, // 5 minutes
    ...options,
  });
}
```

## Anti-Patterns to Avoid

### 1. Direct State Mutation

❌ **Wrong**: Mutating cache directly

```typescript
const queryClient = useQueryClient();
const products = queryClient.getQueryData(['products']);
products.push(newProduct); // Don't do this!
```

✅ **Correct**: Use proper mutations

```typescript
const createProduct = useCreateProduct();
createProduct.mutate(newProduct);
```

### 2. Circular Dependencies

❌ **Wrong**: Domains importing each other

```typescript
// core/domains/products/api.ts
import { userApi } from '@/core/domains/users/api'; // Avoid!
```

✅ **Correct**: Use shared hooks or events

```typescript
// In feature component
const { data: product } = useProduct(id);
const { data: user } = useUser(product?.ownerId);
```

### 3. Business Logic in Features

❌ **Wrong**: Calculate in features

```typescript
// features/product-catalog/components/ProductCard.tsx
const discountPrice = product.price * 0.9; // Business logic!
```

✅ **Correct**: Domain handles logic

```typescript
// core/domains/products/utils.ts
export function calculateDiscount(product: Product): number {
  return product.price * 0.9;
}
```

## Related Documents

* [Core Architecture Reference](/docs/architecture/core-architecture)
* [Project Structure Reference](/docs/architecture/project-structure)
* [Shared Utilities Guide](/docs/features/shared-utilities)
* [File Naming Conventions](/docs/coding-standards/file-naming-conventions)
* [Communication Patterns](/docs/features/communication-patterns)
* [API Integration Guide](/docs/api)
* [State Management Guide](/docs/guides/state-management)


# UTA Architecture: Architecture Decision Record Template
URL: https://dev.updatetheapp.com/docs/architecture/adr-template
Documentation: https://dev.updatetheapp.com/docs/architecture/adr-template

Template for documenting architectural decisions with emphasis on explaining rationale and context
        
***

title: Architecture Decision Record Template
description: Template for documenting architectural decisions with emphasis on explaining rationale and context
---------------------------------------------------------------------------------------------------------------

import { Callout } from 'fumadocs-ui/components/callout';
import { Tabs, Tab } from 'fumadocs-ui/components/tabs';

# Architecture Decision Record (ADR) Template

## Overview

Architecture Decision Records (ADRs) help our team document important architectural choices, their context, and most importantly, the reasoning behind them. This creates a valuable knowledge base that helps current and future team members understand not just *what* we decided, but *why* we made those choices.

<Callout type="info">
  **Why ADRs Matter**: ADRs prevent "archaeology" - the need to dig through old code and commits to understand why things are the way they are. They capture the context and constraints that influenced our decisions, which often gets lost over time.
</Callout>

## ADR Structure

<Tabs items={["Template", "Filled Example", "Writing Tips"]}>
  <Tab>
    ### ADR-\[NUMBER]: \[Descriptive Title]

    **Date**: \[YYYY-MM-DD]\
    **Status**: \[Proposed | Accepted | Deprecated | Superseded]\
    **Deciders**: \[List of people involved in the decision]\
    **Technical Story**: \[Ticket/Issue reference if applicable]

    ### Context and Problem Statement

    \[Describe the situation that necessitates this decision. What challenge are we facing? What opportunity are we addressing? Write this in 2-3 clear sentences that someone new to the project could understand.]

    ### Why is this decision necessary?

    \[Explain the importance and urgency of making this decision. What happens if we don't address this? What pain points does it solve? This section helps readers understand the motivation.]

    ### Decision Drivers

    Key factors influencing our decision:

    * \[Driver 1 - e.g., Performance requirements]
    * \[Driver 2 - e.g., Team expertise]
    * \[Driver 3 - e.g., Time constraints]
    * \[Additional drivers as needed]

    ### Considered Options

    We evaluated the following approaches:

    1. **\[Option 1 Name]** - \[Brief description]
    2. **\[Option 2 Name]** - \[Brief description]
    3. **\[Option 3 Name]** - \[Brief description]

    ### Decision Outcome

    **Chosen option**: "\[Selected Option]"

    We selected this option because \[provide clear justification linking back to the decision drivers].

    #### Why this option?

    \[Provide detailed explanation of why this option best addresses our needs. Include:

    * How it satisfies our key requirements
    * What trade-offs we're accepting
    * Why other options were less suitable]

    ### Consequences

    #### Positive Outcomes

    * \[Benefit 1 - e.g., Improved developer experience]
    * \[Benefit 2 - e.g., Better performance]
    * \[Additional benefits]

    #### Trade-offs and Considerations

    * \[Trade-off 1 - e.g., Increased complexity in certain areas]
    * \[Trade-off 2 - e.g., Additional learning curve]
    * \[Other considerations]

    ### Implementation Details

    #### File Structure Impact

    ```
    # Show how this decision affects project organization
    src/
    ├── core/
    │   └── [new/modified structure]
    └── features/
        └── [affected areas]
    ```

    #### Code Examples

    <Tabs items={["Before", "After"]}>
      <Tab>
        ```typescript
        // Current implementation approach
        [Show existing pattern or structure]
        ```
      </Tab>

      <Tab>
        ```typescript
        // New implementation following this decision
        [Show new pattern with helpful comments]
        ```
      </Tab>
    </Tabs>

    ### Validation

    How we'll measure success:

    * \[Metric 1 - e.g., 50% reduction in related bugs]
    * \[Metric 2 - e.g., New developer onboarding time under 2 days]
    * \[Metric 3 - e.g., Decreased "where does this go?" questions]

    ### Related Resources

    * \[Link to related ADRs]
    * \[Link to implementation documentation]
    * \[Link to example implementations]
  </Tab>

  <Tab>
    ### ADR-001: Three-Layer UI Architecture

    **Date**: 2024-01-15\
    **Status**: Accepted\
    **Deciders**: Tech Lead, Senior UI Engineers, Frontend Team\
    **Technical Story**: JIRA-1234

    ### Context and Problem Statement

    Our UI components have grown organically without clear categorization guidelines. Developers spend significant time deciding where to place new components, and we're seeing duplication because existing components are hard to discover. We need a clear, scalable approach to organizing our UI layer.

    ### Why is this decision necessary?

    Without clear component organization:

    * Developers waste 15-30 minutes per component deciding placement
    * We've found 23 duplicate button variations across features
    * Business logic is leaking into what should be presentational components
    * Component reusability is suffering, increasing bundle size

    If we don't address this now, these issues will compound as the team grows.

    ### Decision Drivers

    Key factors influencing our decision:

    * **Clarity**: Need unambiguous rules for component placement
    * **Reusability**: Must maximize component sharing across features
    * **Separation of Concerns**: Keep business logic separate from presentation
    * **Team Scalability**: System must work for both junior and senior developers
    * **Migration Path**: Solution must allow incremental adoption

    ### Considered Options

    We evaluated four architectural approaches:

    1. **Three-layer architecture** (foundation/patterns/business)
       * Clear separation between atomic, composed, and domain-aware components

    2. **Two-layer architecture** (components/containers)
       * Simple split between presentational and container components

    3. **Feature-first organization** (all UI in features)
       * Co-locate all UI with its feature code

    4. **Atomic design** (atoms/molecules/organisms/templates/pages)
       * Industry-standard five-level hierarchy

    ### Decision Outcome

    **Chosen option**: "Three-layer architecture"

    We selected this approach because it provides the optimal balance of clarity and flexibility while addressing all our key requirements.

    #### Why this option?

    The three-layer architecture best serves our needs because:

    * **Foundation layer** (atoms) enforces zero business logic in basic components, ensuring maximum reusability
    * **Patterns layer** (molecules) allows sophisticated UI composition without domain coupling
    * **Business layer** (organisms) provides a clear home for domain-aware components shared across features

    This approach is superior to alternatives because:

    * Clearer than atomic design's 5 levels (which often confuse developers)
    * More flexible than the rigid container/component split
    * Better for reusability than feature-first organization
    * Maps naturally to how our team already thinks about components

    ### Consequences

    #### Positive Outcomes

    * Clear, memorable rules reduce decision time to under 2 minutes
    * Improved component discovery through logical organization
    * Better code reuse (estimated 40% reduction in duplicate components)
    * Easier onboarding - new developers understand the system in hours, not days
    * Natural enforcement of separation of concerns

    #### Trade-offs and Considerations

    * Initial migration effort (estimated 2 sprints for full adoption)
    * Some components may sit at layer boundaries (we'll document edge cases)
    * Team training required (planned lunch-and-learn sessions)
    * Need to update build tools for new structure

    ### Implementation Details

    #### File Structure Impact

    ```
    src/ui/
    ├── foundation/          # Atomic components (no business logic)
    │   ├── Button/
    │   ├── Input/
    │   ├── Card/
    │   └── Icon/
    ├── patterns/           # Composed UI patterns (domain-agnostic)
    │   ├── Modal/
    │   ├── Form/
    │   ├── DataTable/
    │   └── SearchBox/
    └── business/          # Domain-aware components (3+ features)
        ├── ProductCard/
        ├── UserAvatar/
        └── OrderStatus/
    ```

    #### Code Examples

    <Tabs items={["Foundation Example", "Pattern Example", "Business Example"]}>
      <Tab>
        ```typescript
        // ui/foundation/Button/Button.tsx
        import { theme } from '@/core/shared/styles/theme';

        interface ButtonProps {
          variant?: 'primary' | 'secondary';
          size?: 'small' | 'medium' | 'large';
          onPress: () => void;
          children: React.ReactNode;
        }

        // Pure presentational component - no business logic
        export function Button({ variant = 'primary', size = 'medium', onPress, children }: ButtonProps) {
          return (
            <TouchableOpacity 
              style={[styles.base, styles[variant], styles[size]]}
              onPress={onPress}
            >
              <Text style={styles.text}>{children}</Text>
            </TouchableOpacity>
          );
        }
        ```
      </Tab>

      <Tab>
        ```typescript
        // ui/patterns/Modal/Modal.tsx
        import { Button } from '@/ui/foundation/Button';
        import { Card } from '@/ui/foundation/Card';

        interface ModalProps {
          visible: boolean;
          onClose: () => void;
          title: string;
          children: React.ReactNode;
        }

        // Composed from foundation components, handles UI behavior only
        export function Modal({ visible, onClose, title, children }: ModalProps) {
          if (!visible) return null;
          
          return (
            <View style={styles.overlay}>
              <Card style={styles.modal}>
                <Text style={styles.title}>{title}</Text>
                {children}
                <Button onPress={onClose}>Close</Button>
              </Card>
            </View>
          );
        }
        ```
      </Tab>

      <Tab>
        ```typescript
        // ui/business/ProductCard/ProductCard.tsx
        import { Card } from '@/ui/foundation/Card';
        import { Button } from '@/ui/foundation/Button';
        import { PriceTag } from '@/ui/patterns/PriceTag';
        import { useProduct } from '@/core/domains/products/hooks';
        import { useCart } from '@/core/domains/cart/hooks';

        interface ProductCardProps {
          productId: string;
        }

        // Domain-aware component that uses business logic
        export function ProductCard({ productId }: ProductCardProps) {
          const { data: product, isLoading } = useProduct(productId);
          const { addToCart } = useCart();
          
          if (isLoading) return <ProductCardSkeleton />;
          if (!product) return null;
          
          return (
            <Card>
              <Image source={{ uri: product.imageUrl }} style={styles.image} />
              <Text style={styles.name}>{product.name}</Text>
              <PriceTag price={product.price} discount={product.discount} />
              <Button onPress={() => addToCart(product)}>
                Add to Cart
              </Button>
            </Card>
          );
        }
        ```
      </Tab>
    </Tabs>

    ### Validation

    We'll measure success through:

    * **Placement Decision Time**: Target \< 2 minutes (from current 15-30 min)
    * **Component Duplication**: 40% reduction within 3 months
    * **Developer Satisfaction**: Survey scores > 4/5 on component organization
    * **Onboarding Efficiency**: New developers productive within 1 week
    * **Code Review Mentions**: 80% reduction in component placement discussions

    ### Related Resources

    * [UI Architecture Guide](/docs/architecture/ui-architecture) - Detailed implementation guide
    * [Component Development Guide](/docs/guides/component-development) - Best practices
    * [Migration Guide](/docs/guides/ui-migration) - Step-by-step migration plan
  </Tab>

  <Tab>
    ### Writing Effective ADRs

    <Callout type="tip">
      **Remember**: ADRs are written for future readers, including yourself in 6 months. Be kind to your future self!
    </Callout>

    #### Key Principles

    1. **Be Concise but Complete**
       * Include enough context for understanding
       * Don't write a novel - aim for 2-3 pages max
       * Focus on the "why" more than the "how"

    2. **Consider Your Audience**
       * Write for developers who might join the team later
       * Avoid assuming deep knowledge of current context
       * Define project-specific terms

    3. **Make it Discoverable**
       * Use descriptive titles
       * Include relevant keywords
       * Link from related documentation

    #### Common Pitfalls to Avoid

    * **Too Technical**: Balance technical accuracy with readability
    * **Missing Context**: Always explain the problem before the solution
    * **No Alternatives**: Show that you considered multiple options
    * **Vague Consequences**: Be specific about trade-offs

    #### When to Write an ADR

    Create an ADR when:

    * Choosing between architectural patterns
    * Adopting new technologies or libraries
    * Making changes that affect multiple teams/features
    * Decisions that are expensive to reverse
    * Team debates indicate lack of clarity

    <Callout type="info">
      **Pro Tip**: If you find yourself explaining the same decision multiple times, it probably needs an ADR!
    </Callout>
  </Tab>
</Tabs>

## Related Documents

* [Project Structure](/docs/architecture/project-structure) - Understanding our codebase organization
* [Domain Architecture](/docs/architecture/domain-architecture) - How we structure business logic


# UTA State Management: State Management Architecture
URL: https://dev.updatetheapp.com/docs/state-management/state-management-architecture
Documentation: https://dev.updatetheapp.com/docs/state-management/state-management-architecture

Overview of our state management approach and the golden rule for separating server and client state
        
***

title: State Management Architecture
description: Overview of our state management approach and the golden rule for separating server and client state
-----------------------------------------------------------------------------------------------------------------

import { File, Folder, Files } from 'fumadocs-ui/components/files';

# State Management Architecture

## Overview

This document outlines our application's state management architecture, built around the **Golden Rule** - our fundamental principle for state separation. This architecture optimizes for performance, maintainability, and developer experience by ensuring each type of state (server, client, and component) is handled by the tool best suited for its characteristics. By following a clear separation of concerns, we reduce complexity and improve both runtime performance and developer productivity.

## Purpose & Scope

* **Target Audience**: React Native developers working on this application who need to understand when and how to use different state management tools
* **Problems Addressed**: State management complexity, prop drilling, unnecessary re-renders, and data synchronization challenges
* **Scope Boundaries**: Covers the three primary state management patterns and their integration, but does not cover persistence strategies or offline capabilities in depth

## The Golden Rule

> **Server state belongs in TanStack Query, Client state belongs in Zustand, Component state belongs in React**

This foundational principle guides all state management decisions in our application:

<Mermaid
  chart={`flowchart TD
  subgraph "State Types"
      ServerState[Server State<br/>Remote Data]
      ClientState[Client State<br/>UI State]
      ComponentState[Component State<br/>Local State]
  end
  
  subgraph "Management Tools"
      TanStack[TanStack Query]
      Zustand[Zustand]
      React[React useState/useReducer]
  end
  
  ServerState --> TanStack
  ClientState --> Zustand
  ComponentState --> React
  
  style ServerState fill:#bbf,stroke:#333,stroke-width:2px
  style ClientState fill:#ff9,stroke:#333,stroke-width:2px
  style ComponentState fill:#f9f,stroke:#333,stroke-width:2px
  style TanStack fill:#bbf,stroke:#333,stroke-width:2px
  style Zustand fill:#ff9,stroke:#333,stroke-width:2px
  style React fill:#f9f,stroke:#333,stroke-width:2px
`}
/>

### When to Apply the Golden Rule

* **(Do ✅)** Use TanStack Query when the data comes from an API or remote source
* **(Do ✅)** Use Zustand when state needs to be shared across components or persisted
* **(Do ✅)** Use React state when the state is only relevant to a single component

## Core Components/Architecture

### Component Types

| Component       | Responsibility               | Implementation            |
| --------------- | ---------------------------- | ------------------------- |
| Server State    | Remote data from APIs        | TanStack Query            |
| Client State    | Application-wide UI state    | Zustand                   |
| Component State | Local component interactions | React useState/useReducer |

### When to Apply Each Component

* **(Do ✅)** Use TanStack Query when the data comes from an API
* **(Do ✅)** Use Zustand when state needs to be shared across components or persisted
* **(Do ✅)** Use React state when the state is only relevant to a single component

### Communication Patterns

<Mermaid
  chart={`flowchart TD
  Component[UI Component] --> Query[TanStack Query Hooks]
  Component --> Store[Zustand Store]
  Component --> Local[React useState]
  
  Query --> QueryClient[Query Client]
  QueryClient --> API[API Layer]
  API --> Backend[Backend Server]
  
  Store --> PersistLayer[Optional Persist Layer]
  PersistLayer --> Storage[AsyncStorage]
  
  style Component fill:#f5f5f5,stroke:#333,stroke-width:2px
  style Query fill:#bbf,stroke:#333,stroke-width:2px
  style Store fill:#ff9,stroke:#333,stroke-width:2px
  style Local fill:#f9f,stroke:#333,stroke-width:2px
`}
/>

## Design Principles

### Core Architectural Principles

* **(Do ✅)** Maintain a clear separation of concerns between server and client state
  * Server state and client state have fundamentally different characteristics and should be treated differently
  * Mixing concerns leads to unnecessary complexity and performance issues

* **(Do ✅)** Use specialized tools optimized for each state type
  * TanStack Query handles caching, invalidation, and refetching
  * Zustand provides a simple API for global state with minimal boilerplate
  * React state is perfect for component-level concerns

* **(Do ✅)** Keep components pure and focused on rendering
  * Components should primarily transform props into UI
  * Delegate state management logic to hooks and stores

### Trade-offs and Design Decisions

| Decision                        | Benefits                                          | Trade-offs                  | Why We Chose It             |
| ------------------------------- | ------------------------------------------------- | --------------------------- | --------------------------- |
| Separate server & client state  | Better performance, clearer code                  | Learning multiple tools     | Benefits outweigh costs     |
| TanStack Query for server state | Automatic caching, refetching, optimistic updates | More code than simple fetch | Drastically improves UX     |
| Zustand for global state        | Simple API, minimal boilerplate                   | Another dependency          | Less complex than Redux     |
| React state for component state | Built-in, familiar                                | No persistence              | Perfect for ephemeral state |

## Implementation Considerations

### Performance Implications

* **Query Caching**: Server state is automatically cached by TanStack Query, reducing unnecessary network requests
* **Zustand Selectors**: Use selectors to prevent unnecessary re-renders by only subscribing to relevant slices of state
* **Component Memoization**: Leverage React.memo and useMemo to prevent wasteful re-renders

### Scaling Considerations

* **Query Client Configuration**: Set up appropriate staleTime and cacheTime based on data volatility
* **Store Slicing**: Break down Zustand stores by domain as the application grows
* **Persistence Strategy**: Configure storage persistence only for critical state to avoid bloat

## Related Documents

* [Server State Management](/docs/state-management/server-state) - Detailed guide on TanStack Query implementation
* [Client State Management](/docs/state-management/client-state) - Zustand patterns and best practices
* [Component State](/docs/state-management/component-state) - React state management techniques
* [State Integration Patterns](/docs/state-management/integration-patterns) - How different state types work together


# UTA State Management: Server State Management
URL: https://dev.updatetheapp.com/docs/state-management/server-state
Documentation: https://dev.updatetheapp.com/docs/state-management/server-state

Comprehensive guide for managing server state with TanStack Query in our React Native application
        
***

title: Server State Management
description: Comprehensive guide for managing server state with TanStack Query in our React Native application
--------------------------------------------------------------------------------------------------------------

import { File, Folder, Files } from 'fumadocs-ui/components/files';
import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Accordion, Accordions } from 'fumadocs-ui/components/accordion';

# Server State Management

## Overview

This document outlines our approach to managing server state - data that originates from external APIs and requires caching, synchronization, and complex loading states. Our architecture implements TanStack Query (React Query) as the dedicated solution for all server state management, following our application's **Golden Rule**: "Server state belongs in TanStack Query, not in Zustand or Redux". This approach optimizes for performance, developer experience, and data consistency across the application.

## Purpose & Scope

* **Target Audience**: React Native developers implementing features that require API data fetching, caching, or state synchronization
* **Problems Addressed**: API data management, caching strategies, loading/error states, and data synchronization challenges
* **Scope Boundaries**: Covers TanStack Query implementation, query patterns, mutation strategies, and caching approaches but does not cover API service implementation details or authentication token management

## Core Components/Architecture

<Mermaid
  chart={`flowchart TD
  Component[UI Component] --> QueryHook[Query Hook]
  Component --> MutationHook[Mutation Hook]
  
  QueryHook --> QueryClient[Query Client]
  MutationHook --> QueryClient
  
  QueryClient --> Cache[(Query Cache)]
  QueryClient --> API[API Layer]
  API --> Backend[Backend Server]
  
  subgraph "Server State Layer"
      QueryHook
      MutationHook
      QueryClient
      Cache
  end
  
  style QueryHook fill:#bbf,stroke:#333,stroke-width:2px
  style MutationHook fill:#bbf,stroke:#333,stroke-width:2px
  style QueryClient fill:#bbf,stroke:#333,stroke-width:2px
  style Cache fill:#bbf,stroke:#333,stroke-width:2px
`}
/>

### Component Types

| Component      | Responsibility                        | Implementation                |
| -------------- | ------------------------------------- | ----------------------------- |
| Query Hooks    | Data fetching and caching             | Feature-specific custom hooks |
| Mutation Hooks | Data updating and optimistic updates  | Feature-specific custom hooks |
| Query Client   | Central management and configuration  | Globally configured instance  |
| Query Cache    | In-memory data storage                | Managed by Query Client       |
| Query Keys     | Cache identification and organization | Structured array patterns     |

### When to Use Server State

TanStack Query should be used for any data that meets these criteria:

* **(Do ✅)** Use for data fetched from external APIs or backend services
* **(Do ✅)** Use for data that requires caching and deduplication
* **(Do ✅)** Use for data with complex loading or error states
* **(Do ✅)** Use for data that needs synchronization across components
* **(Do ✅)** Use for real-time data that requires polling or refetching

## Design Principles

### Core Architectural Principles

* **(Do ✅)** Keep server state separate from client state
  * Server state should be managed by TanStack Query
  * Client state should be managed by Zustand
  * Mixing these concerns leads to unnecessary complexity

* **(Do ✅)** Create focused, reusable query hooks
  * Each query hook should serve a specific data need
  * Hooks should be feature-specific and located in the appropriate feature directory
  * Abstract complex query logic into custom hooks

* **(Don't ❌)** Store server data in Zustand or React context
  * Avoid creating duplicate copies of server state
  * Let TanStack Query handle caching and synchronization

### Data Access Patterns

| Pattern            | Used For                           | Implementation                             |
| ------------------ | ---------------------------------- | ------------------------------------------ |
| Basic Queries      | Simple data fetching               | `useQuery` with query keys                 |
| Dependent Queries  | Data that depends on other queries | `useQuery` with `enabled` option           |
| Paginated Queries  | Lists with pagination              | `useQuery` with pagination params          |
| Infinite Queries   | Endless scrolling lists            | `useInfiniteQuery` with `getNextPageParam` |
| Mutations          | Creating, updating, deleting data  | `useMutation` with callbacks               |
| Optimistic Updates | Immediate UI feedback              | `useMutation` with `onMutate`              |

### Query Key Strategies

<Mermaid
  chart={`flowchart LR
  Root["Root Key"] --> Entity["Entity Type"]  
  Entity --> Collection["Collection/Detail"] 
  Collection --> Params["Parameters"] 

  style Root fill:#bbf,stroke:#333,stroke-width:2px
  style Entity fill:#bbf,stroke:#333,stroke-width:2px
  style Collection fill:#bbf,stroke:#333,stroke-width:2px
  style Params fill:#bbf,stroke:#333,stroke-width:2px
`}
/>

Query keys should follow a consistent structure:

```typescript
// Pattern for detail queries
['entity', 'detail', entityId, ...params]

// Pattern for list queries
['entity', 'list', { filters }] 
```

### Trade-offs and Design Decisions

**Centralized vs. Distributed Query Hooks**

| Approach              | Benefits                                    | Drawbacks                                 | Best For             |
| --------------------- | ------------------------------------------- | ----------------------------------------- | -------------------- |
| Centralized API hooks | Consistency, single source of truth         | Potential for large files, tight coupling | Small to medium apps |
| Feature-based hooks   | Better code organization, feature isolation | Potential duplication                     | Medium to large apps |

**Our Decision**: We use a feature-based organization for query hooks while sharing common functionality through a factory pattern, giving us both organization and reusability.

## Implementation Considerations

### Performance Implications

* **(Do ✅)** Configure appropriate staleTime based on data volatility
  * More static data (e.g., product details): Longer staleTime (5-10 minutes)
  * More dynamic data (e.g., cart): Shorter staleTime (0-30 seconds)

* **(Do ✅)** Use the `select` option to transform and minimize data
  * Transform and filter data on selection to minimize re-renders
  * Extract only the needed fields from larger response objects

* **(Don't ❌)** Fetch the same data in multiple components
  * Create reusable query hooks to share data between components
  * Let TanStack Query handle the caching and deduplication

### Security Considerations

* **(Do ✅)** Validate all data from server responses
  * Use TypeScript interfaces to enforce data shape
  * Consider runtime validation with libraries like Zod or Yup

* **(Do ✅)** Properly handle authentication errors
  * Set up global error handling for 401 responses
  * Redirect to login page or refresh tokens as needed

* **(Don't ❌)** Store sensitive data in the query cache without encryption
  * Be cautious when persisting the query cache to storage
  * Consider what data should be excluded from persistence

### Scalability Aspects

* **(Do ✅)** Implement structured query keys for efficient invalidation
  * Create a query key factory for consistent key structure
  * Use parent keys to invalidate related queries

* **(Consider 🤔)** Setting up query cache persistence
  * Improves offline experience and reduces initial loading
  * Balance with cache size management and potential staleness

* **(Be Aware ❗)** Of memory usage with large datasets
  * Implement pagination or infinite queries for large lists
  * Consider data normalization for frequently used entities

## Implementation Examples

### Setting Up TanStack Query

```typescript
// core/query/queryClient.ts
import { QueryClient } from '@tanstack/react-query';

export const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      staleTime: 5 * 60 * 1000, // 5 minutes
      cacheTime: 10 * 60 * 1000, // 10 minutes
      retry: 3,
      retryDelay: (attemptIndex) => Math.min(1000 * 2 ** attemptIndex, 30000),
      refetchOnWindowFocus: false,
      refetchOnMount: true,
    },
    mutations: {
      retry: 1,
    },
  },
});

// App.tsx
import { QueryClientProvider } from '@tanstack/react-query';
import { queryClient } from '@/core/query';

export function App() {
  return (
    <QueryClientProvider client={queryClient}>
      {/* Your app components */}
    </QueryClientProvider>
  );
}
```

### Query Key Factory

```typescript
// core/query/queryKeys.ts
export const queryKeys = {
  all: ['queries'] as const,
  users: {
    all: ['users'] as const,
    lists: () => [...queryKeys.users.all, 'list'] as const,
    list: (filters: string) => [...queryKeys.users.lists(), { filters }] as const,
    details: () => [...queryKeys.users.all, 'detail'] as const,
    detail: (id: string) => [...queryKeys.users.details(), id] as const,
  },
  products: {
    all: ['products'] as const,
    lists: () => [...queryKeys.products.all, 'list'] as const,
    list: (filters: any) => [...queryKeys.products.lists(), { filters }] as const,
    details: () => [...queryKeys.products.all, 'detail'] as const,
    detail: (id: string) => [...queryKeys.products.details(), id] as const,
  },
  cart: {
    all: ['cart'] as const,
    current: () => [...queryKeys.cart.all, 'current'] as const,
  },
};
```

### Query Patterns

<Tabs items={['Basic Query', 'With Transformation', 'Dependent Queries']}>
  <Tab>
    ```typescript
    // features/products/api/productHooks.ts
    import { useQuery } from '@tanstack/react-query';
    import { productService } from '@/core/api/services';
    import { queryKeys } from '@/core/query';

    export const useProductsQuery = (filters = {}) => {
      return useQuery({
        queryKey: queryKeys.products.list(filters),
        queryFn: () => productService.getProducts(filters),
        staleTime: 5 * 60 * 1000, // 5 minutes
      });
    };

    export const useProductQuery = (productId: string) => {
      return useQuery({
        queryKey: queryKeys.products.detail(productId),
        queryFn: () => productService.getProduct(productId),
        enabled: !!productId,
      });
    };
    ```
  </Tab>

  <Tab>
    ```typescript
    // features/users/api/userHooks.ts
    interface UserResponse {
      id: string;
      first_name: string;
      last_name: string;
      email_address: string;
    }

    interface User {
      id: string;
      name: string;
      email: string;
    }

    export const useUserQuery = (userId: string) => {
      return useQuery({
        queryKey: queryKeys.users.detail(userId),
        queryFn: () => userService.getUser(userId),
        select: (data: UserResponse): User => ({
          id: data.id,
          name: `${data.first_name} ${data.last_name}`,
          email: data.email_address,
        }),
      });
    };
    ```
  </Tab>

  <Tab>
    ```typescript
    // features/orders/api/orderHooks.ts
    export const useOrderWithDetailsQuery = (orderId: string) => {
      const orderQuery = useQuery({
        queryKey: queryKeys.orders.detail(orderId),
        queryFn: () => orderService.getOrder(orderId),
      });

      const orderItemsQuery = useQuery({
        queryKey: queryKeys.orders.items(orderId),
        queryFn: () => orderService.getOrderItems(orderId),
        enabled: !!orderQuery.data,
      });

      return {
        order: orderQuery.data,
        items: orderItemsQuery.data,
        isLoading: orderQuery.isLoading || orderItemsQuery.isLoading,
        error: orderQuery.error || orderItemsQuery.error,
      };
    };
    ```
  </Tab>
</Tabs>

### Mutation Patterns

<Tabs items={['Basic Mutation', 'Optimistic Updates', 'Sequential Mutations']}>
  <Tab>
    ```typescript
    // features/products/api/productMutations.ts
    import { useMutation, useQueryClient } from '@tanstack/react-query';
    import { productService } from '@/core/api/services';
    import { queryKeys } from '@/core/query';

    export const useCreateProductMutation = () => {
      const queryClient = useQueryClient();

      return useMutation({
        mutationFn: productService.createProduct,
        onSuccess: (newProduct) => {
          // Invalidate and refetch products list
          queryClient.invalidateQueries({ queryKey: queryKeys.products.lists() });
          
          // Add the new product to the cache
          queryClient.setQueryData(
            queryKeys.products.detail(newProduct.id),
            newProduct
          );
        },
      });
    };
    ```
  </Tab>

  <Tab>
    ```typescript
    // features/cart/api/cartMutations.ts
    export const useUpdateCartItemMutation = () => {
      const queryClient = useQueryClient();

      return useMutation({
        mutationFn: cartService.updateCartItem,
        onMutate: async ({ itemId, quantity }) => {
          // Cancel any outgoing refetches
          await queryClient.cancelQueries({ queryKey: queryKeys.cart.current() });

          // Snapshot the previous value
          const previousCart = queryClient.getQueryData(queryKeys.cart.current());

          // Optimistically update
          queryClient.setQueryData(queryKeys.cart.current(), (old: Cart) => ({
            ...old,
            items: old.items.map(item =>
              item.id === itemId ? { ...item, quantity } : item
            ),
          }));

          // Return a context with the previous value
          return { previousCart };
        },
        onError: (err, variables, context) => {
          // If the mutation fails, use the context to roll back
          if (context?.previousCart) {
            queryClient.setQueryData(queryKeys.cart.current(), context.previousCart);
          }
        },
        onSettled: () => {
          // Always refetch after error or success
          queryClient.invalidateQueries({ queryKey: queryKeys.cart.current() });
        },
      });
    };
    ```
  </Tab>

  <Tab>
    ```typescript
    // features/checkout/api/checkoutMutations.ts
    export const useCheckoutMutation = () => {
      const queryClient = useQueryClient();
      const createOrderMutation = useMutation({
        mutationFn: orderService.createOrder,
      });
      
      const processPaymentMutation = useMutation({
        mutationFn: paymentService.processPayment,
      });

      return useMutation({
        mutationFn: async (checkoutData: CheckoutData) => {
          // Create order first
          const order = await createOrderMutation.mutateAsync({
            items: checkoutData.items,
            shippingAddress: checkoutData.shippingAddress,
          });

          // Then process payment
          const payment = await processPaymentMutation.mutateAsync({
            orderId: order.id,
            paymentMethod: checkoutData.paymentMethod,
            amount: order.total,
          });

          return { order, payment };
        },
        onSuccess: () => {
          // Clear cart and invalidate related queries
          queryClient.invalidateQueries({ queryKey: queryKeys.cart.all });
          queryClient.invalidateQueries({ queryKey: queryKeys.orders.all });
        },
      });
    };
    ```
  </Tab>
</Tabs>

### Advanced Patterns

<Tabs items={['Infinite Queries', 'Real-time Updates', 'Prefetching']}>
  <Tab>
    ```typescript
    // features/feed/api/feedHooks.ts
    import { useInfiniteQuery } from '@tanstack/react-query';

    export const useFeedQuery = () => {
      return useInfiniteQuery({
        queryKey: queryKeys.feed.all,
        queryFn: ({ pageParam = 1 }) => feedService.getFeedItems({ page: pageParam }),
        getNextPageParam: (lastPage, pages) => {
          return lastPage.hasMore ? lastPage.nextPage : undefined;
        },
        initialPageParam: 1,
      });
    };

    // Component usage
    const FeedList = () => {
      const {
        data,
        fetchNextPage,
        hasNextPage,
        isFetchingNextPage,
      } = useFeedQuery();

      const items = data?.pages.flatMap(page => page.items) ?? [];

      return (
        <FlatList
          data={items}
          renderItem={({ item }) => <FeedItem item={item} />}
          onEndReached={() => {
            if (hasNextPage && !isFetchingNextPage) {
              fetchNextPage();
            }
          }}
          ListFooterComponent={() =>
            isFetchingNextPage ? <ActivityIndicator /> : null
          }
        />
      );
    };
    ```
  </Tab>

  <Tab>
    ```typescript
    // features/notifications/api/notificationHooks.ts
    export const useNotificationsQuery = () => {
      return useQuery({
        queryKey: queryKeys.notifications.unread,
        queryFn: notificationService.getUnreadNotifications,
        refetchInterval: 30 * 1000, // Poll every 30 seconds
        refetchIntervalInBackground: true,
      });
    };

    // App state change refetching
    import { useEffect } from 'react';
    import { AppState, AppStateStatus } from 'react-native';
    import { useQueryClient } from '@tanstack/react-query';

    export const useAppStateRefetch = () => {
      const queryClient = useQueryClient();

      useEffect(() => {
        const handleAppStateChange = (nextAppState: AppStateStatus) => {
          if (nextAppState === 'active') {
            // Refetch all queries when app comes to foreground
            queryClient.invalidateQueries();
          }
        };

        const subscription = AppState.addEventListener('change', handleAppStateChange);
        return () => subscription.remove();
      }, [queryClient]);
    };
    ```
  </Tab>

  <Tab>
    ```typescript
    // features/products/screens/ProductListScreen.tsx
    export const ProductListScreen = () => {
      const queryClient = useQueryClient();
      const { data: products } = useProductsQuery();

      const handleProductPress = async (productId: string) => {
        // Prefetch product details before navigation
        await queryClient.prefetchQuery({
          queryKey: queryKeys.products.detail(productId),
          queryFn: () => productService.getProduct(productId),
        });
        
        navigation.navigate('ProductDetail', { productId });
      };

      return (
        <FlatList
          data={products}
          renderItem={({ item }) => (
            <ProductItem
              product={item}
              onPress={() => handleProductPress(item.id)}
            />
          )}
        />
      );
    };
    ```
  </Tab>
</Tabs>

### Error Handling Strategies

<Tabs items={['Global Configuration', 'Custom Error Handler', 'Component-Level Handling']}>
  <Tab>
    ```typescript
    // core/query/queryClient.ts
    export const queryClient = new QueryClient({
      defaultOptions: {
        queries: {
          staleTime: 5 * 60 * 1000,
          retry: 3,
          retryDelay: (attemptIndex) => Math.min(1000 * 2 ** attemptIndex, 30000),
          onError: (error) => {
            // Log the error
            console.error('Query error:', error);
            
            // You could trigger a global notification here
          },
        },
        mutations: {
          retry: 1,
          onError: (error, variables, context) => {
            // Log mutation errors
            console.error('Mutation error:', error, variables);
            
            // Show a toast message
            Toast.show({
              type: 'error',
              text1: 'Operation failed',
              text2: getErrorMessage(error),
            });
          },
        },
      },
    });
    ```
  </Tab>

  <Tab>
    ````typescript
    // core/hooks/useErrorHandler.ts
    import { useCallback } from 'react';
    import { Toast } from 'react-native-toast-message';
    import { isAxiosError } from 'axios';

    export const useErrorHandler = () => {
      const handleError = useCallback((error: unknown, fallbackMessage = 'An error occurred') => {
        let message = fallbackMessage;

        if (isAxiosError(error)) {
          if (error.response) {
            // Server responded with an error status
            const serverMessage = error.response.data?.message;
            message = serverMessage || `Error ${error.response.status}: ${error.response.statusText}`;
            
            // Handle specific status codes
            if (error.response.status === 401) {
              // Trigger auth refresh or logout workflow
              // ...
              return;
            }
          } else if (error.request) {
            // Request was made but no response
            message = 'No response from server. Please check your connection.';
          }
        } else if (error instanceof Error) {
          message = error.message;
        }

    ## Caching Strategies

    <Tabs items={['Baseline Configuration', 'Selective Caching', 'Cache Invalidation']}>
    <Tab>
    ```typescript
    // core/query/queryClient.ts
    export const queryClient = new QueryClient({
      defaultOptions: {
        queries: {
          // How long until the data is considered stale
          staleTime: 5 * 60 * 1000, // 5 minutes
          
          // How long to keep data in cache while unused
          cacheTime: 10 * 60 * 1000, // 10 minutes
          
          // Whether to refetch when window regains focus
          refetchOnWindowFocus: true,
          
          // Whether to refetch when component remounts
          refetchOnMount: true,
          
          // Whether to refetch when reconnecting
          refetchOnReconnect: true,
        },
      },
    });
    ````

    Default settings establish baseline behavior for all queries. Adjust these settings based on app needs:

    * **Short-lived data**: Low staleTime (30s)
    * **Relatively stable data**: Medium staleTime (5-10min)
    * **Rarely changing data**: Higher staleTime (30min-1hr)
  </Tab>

  <Tab>
    ```typescript
    // features/products/api/productHooks.ts

    // Frequently changing data - short staleTime
    export const useProductInventoryQuery = (productId: string) => {
      return useQuery({
        queryKey: queryKeys.products.inventory(productId),
        queryFn: () => productService.getInventory(productId),
        staleTime: 30 * 1000, // 30 seconds
        refetchInterval: 60 * 1000, // Poll every minute
      });
    };

    // Stable reference data - long staleTime
    export const useProductCategoriesQuery = () => {
      return useQuery({
        queryKey: queryKeys.products.categories(),
        queryFn: productService.getCategories,
        staleTime: 24 * 60 * 60 * 1000, // 24 hours
        cacheTime: 7 * 24 * 60 * 60 * 1000, // 7 days
      });
    };

    // Critical user data - always refetch on mount
    export const useUserProfileQuery = (userId: string) => {
      return useQuery({
        queryKey: queryKeys.users.detail(userId),
        queryFn: () => userService.getUser(userId),
        staleTime: 0, // Always considered stale
        refetchOnMount: 'always',
      });
    };
    ```
  </Tab>
</Tabs>

## Advanced Usage Patterns

<Tabs items={['Smart Invalidation', 'Optimistic Updates', 'Prefetching']}>
  <Tab>
    ```typescript
    // features/products/api/productMutations.ts
    export const useUpdateProductMutation = () => {
      const queryClient = useQueryClient();

      return useMutation({
        mutationFn: productService.updateProduct,
        onSuccess: (updatedProduct) => {
          // Update specific product in cache
          queryClient.setQueryData(
            queryKeys.products.detail(updatedProduct.id),
            updatedProduct
          );

          // Update product in any lists that might contain it
          queryClient.setQueriesData(
            { queryKey: queryKeys.products.lists() },
            (old: { products: Product[] }) => {
              if (!old) return old;
              return {
                ...old,
                products: old.products.map(product =>
                  product.id === updatedProduct.id ? updatedProduct : product
                ),
              };
            }
          );
        },
      });
    };
    ```
  </Tab>

  <Tab>
    ```typescript
    // features/cart/api/cartMutations.ts
    export const useRemoveCartItemMutation = () => {
      const queryClient = useQueryClient();
      
      return useMutation({
        mutationFn: cartService.removeItem,
        onMutate: async (itemId) => {
          // Cancel any outgoing refetches
          await queryClient.cancelQueries({
            queryKey: queryKeys.cart.current(),
          });
          
          // Snapshot the current cart
          const previousCart = queryClient.getQueryData(queryKeys.cart.current());
          
          // Optimistically update the cart
          queryClient.setQueryData(queryKeys.cart.current(), (old) => ({
            ...old,
            items: old.items.filter(item => item.id !== itemId),
            totalItems: old.totalItems - 1,
            totalPrice: old.totalPrice - (old.items.find(i => i.id === itemId)?.price || 0),
          }));
          
          return { previousCart };
        },
        onError: (_, __, context) => {
          // Rollback on error
          if (context?.previousCart) {
            queryClient.setQueryData(queryKeys.cart.current(), context.previousCart);
          }
        },
        onSettled: () => {
          // Refetch to ensure data consistency
          queryClient.invalidateQueries({ queryKey: queryKeys.cart.current() });
        },
      });
    };
    ```
  </Tab>

  <Tab>
    ```typescript
    // features/navigation/navigationHelpers.ts
    import { queryClient } from '@/core/query';
    import { queryKeys } from '@/core/query';
    import { productService } from '@/core/api/services';

    export const navigateToProductDetail = async (navigation, productId) => {
      // Prefetch product details before navigation
      await queryClient.prefetchQuery({
        queryKey: queryKeys.products.detail(productId),
        queryFn: () => productService.getProduct(productId),
      });
      
      // Prefetch related data in parallel
      await Promise.all([
        queryClient.prefetchQuery({
          queryKey: queryKeys.products.reviews(productId),
          queryFn: () => productService.getProductReviews(productId),
        }),
        queryClient.prefetchQuery({
          queryKey: queryKeys.products.related(productId),
          queryFn: () => productService.getRelatedProducts(productId),
        }),
      ]);
      
      // Navigate after data is in cache
      navigation.navigate('ProductDetail', { productId });
    };
    ```
  </Tab>
</Tabs>

## Testing Server State

<Tabs items={['Query Hooks', 'Mocking QueryClient', 'Integration Tests']}>
  <Tab>
    ```typescript
    // features/products/api/__tests__/productHooks.test.ts
    import { renderHook, waitFor } from '@testing-library/react-native';
    import { useProductsQuery } from '../productHooks';
    import { productService } from '@/core/api/services';
    import { createWrapper } from '@/test/utils';

    jest.mock('@/core/api/services');

    describe('useProductsQuery', () => {
      it('should fetch products successfully', async () => {
        const mockProducts = [{ id: '1', name: 'Test Product' }];
        (productService.getProducts as jest.Mock).mockResolvedValue(mockProducts);

        const { result } = renderHook(() => useProductsQuery(), {
          wrapper: createWrapper(),
        });

        expect(result.current.isLoading).toBe(true);

        await waitFor(() => {
          expect(result.current.isSuccess).toBe(true);
        });

        expect(result.current.data).toEqual(mockProducts);
      });

      it('should handle errors', async () => {
        const error = new Error('Failed to fetch');
        (productService.getProducts as jest.Mock).mockRejectedValue(error);

        const { result } = renderHook(() => useProductsQuery(), {
          wrapper: createWrapper(),
        });

        await waitFor(() => {
          expect(result.current.isError).toBe(true);
        });

        expect(result.current.error).toEqual(error);
      });
    });
    ```
  </Tab>

  <Tab>
    ```typescript
    // test/utils/createWrapper.tsx
    import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
    import { PropsWithChildren } from 'react';

    export function createWrapper() {
      const queryClient = new QueryClient({
        defaultOptions: {
          queries: {
            retry: false,
            cacheTime: 0,
          },
        },
        logger: {
          log: console.log,
          warn: console.warn,
          error: () => {}, // Silent errors in tests
        },
      });

      return ({ children }: PropsWithChildren<{}>) => (
        <QueryClientProvider client={queryClient}>
          {children}
        </QueryClientProvider>
      );
    }
    ```
  </Tab>

  <Tab>
    ```typescript
    // features/products/screens/__tests__/ProductListScreen.test.tsx
    import { render, screen, fireEvent, waitFor } from '@testing-library/react-native';
    import { ProductListScreen } from '../ProductListScreen';
    import { useProductsQuery } from '../../api/productHooks';
    import { createWrapper } from '@/test/utils';

    jest.mock('../../api/productHooks');

    describe('ProductListScreen', () => {
      it('should render products and handle item press', async () => {
        const mockProducts = [
          { id: '1', name: 'Product 1', price: '$10' },
          { id: '2', name: 'Product 2', price: '$20' },
        ];

        (useProductsQuery as jest.Mock).mockReturnValue({
          data: mockProducts,
          isLoading: false,
          isError: false,
        });

        const mockNavigate = jest.fn();
        jest.mock('@react-navigation/native', () => ({
          useNavigation: () => ({
            navigate: mockNavigate,
          }),
        }));

        const { getByText } = render(<ProductListScreen />, {
          wrapper: createWrapper(),
        });

        expect(getByText('Product 1')).toBeTruthy();
        expect(getByText('Product 2')).toBeTruthy();

        fireEvent.press(getByText('Product 1'));
        
        await waitFor(() => {
          expect(mockNavigate).toHaveBeenCalledWith('ProductDetail', { productId: '1' });
        });
      });
    });
    ```
  </Tab>
</Tabs>

## Troubleshooting

<Accordions>
  <Accordion title="Common Issues with TanStack Query">
    1. **Stale Data Persisting**: If stale data persists longer than expected, check your `staleTime` configuration. You might need to adjust it for your specific use case.

    2. **Multiple Network Requests**: If you're seeing duplicate requests, check the query key construction. Ensure keys are consistent and deterministic across renders.

    3. **Memory Leaks**: When working with infinite queries or large data sets, monitor memory usage. Consider implementing pagination or windowing for large lists.

    4. **Background Refetching Issues**: If background refetching isn't working as expected, verify `refetchOnWindowFocus` and `refetchOnMount` settings.
  </Accordion>

  <Accordion title="Debugging Query Behavior">
    The React Query Devtools are essential for debugging queries in development:

    ```typescript
    import { QueryClientProvider } from '@tanstack/react-query';
    import { ReactQueryDevtools } from '@tanstack/react-query-devtools/build/web';

    function App() {
      return (
        <QueryClientProvider client={queryClient}>
          {/* Your application */}
          {__DEV__ && <ReactQueryDevtools />}
        </QueryClientProvider>
      );
    }
    ```

    For React Native, consider using a custom logging middleware or Flipper plugin for TanStack Query.
  </Accordion>

  <Accordion title="Performance Issues">
    If you encounter performance issues:

    1. **Enable Selective Updates**: Use the `select` option to transform and filter data, reducing component re-renders.

    2. **Use Query Cancellation**: Cancel pending queries when they're no longer needed.

    3. **Optimize Query Keys**: Structure keys appropriately to maximize cache hits.

    4. **Analyze QueryClient Configuration**: Review `cacheTime`, `staleTime`, and garbage collection settings.
  </Accordion>
</Accordions>

## Related Documents

<Cards num={3}>
  <Card title="State Management Overview" href="/docs//architecture/state-management">
    Overview of our complete state management approach including client, server, and component state.
  </Card>

  <Card title="Client State Management" href="/docs//architecture/state-management/client-state">
    Companion documentation for handling client-specific state with Zustand.
  </Card>

  <Card title="Integration Patterns" href="/docs//architecture/state-management/integration-patterns">
    Patterns for integrating server and client state effectively.
  </Card>
</Cards>

<div className="mt-8 border-t pt-8">
  <h3>External Resources</h3>

  <ul>
    <li><a href="https://tanstack.com/query/latest/docs/react/overview" target="_blank" rel="noopener noreferrer">TanStack Query Official Documentation</a></li>
    <li><a href="https://tkdodo.eu/blog/practical-react-query" target="_blank" rel="noopener noreferrer">Practical React Query by TkDodo</a></li>
    <li><a href="https://codebycorey.com/blog/react-query-authorization" target="_blank" rel="noopener noreferrer">React Query Authorization Guide</a></li>
  </ul>
</div>


# UTA State Management: Client State Management
URL: https://dev.updatetheapp.com/docs/state-management/client-state
Documentation: https://dev.updatetheapp.com/docs/state-management/client-state

Comprehensive guide for managing client state with Zustand in our React Native application
        
***

title: Client State Management
description: Comprehensive guide for managing client state with Zustand in our React Native application
-------------------------------------------------------------------------------------------------------

import { File, Folder, Files } from 'fumadocs-ui/components/files';
import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Accordion, Accordions } from 'fumadocs-ui/components/accordion';
import { Cards, Card } from 'fumadocs-ui/components/card';

# Client State Management

## Overview

This document outlines our approach to managing client-side state - data that exists exclusively within the application and doesn't need to be synchronized with external servers. Our architecture implements Zustand as the dedicated solution for all client state management, following our application's **Golden Rule**: "Client state belongs in Zustand, not in TanStack Query or Redux". This approach optimizes for simplicity, developer experience, and performance across the application.

## Purpose & Scope

* **Target Audience**: React Native developers implementing features that require global state management, UI state coordination, or persistent local settings
* **Problems Addressed**: Simplifying state management, reducing boilerplate, improving TypeScript integration, and providing performance optimizations
* **Scope Boundaries**: Covers Zustand implementation, store patterns, performance optimization, and testing but does not cover server state management or data fetching strategies

## Core Components/Architecture

<Mermaid
  chart={`flowchart TD
  Component[React Component] --Subscribe--> Store[Zustand Store]
  Component --Call Actions--> Store
  
  subgraph "Client State Layer"
      Store --Update--> State[(Application State)]
      State --Notify--> Store
  end
  
  subgraph "Middleware"
      Store <--> Persist[Persistence]
      Store <--> Immer[Immer]
      Store <--> DevTools[DevTools]
  end
  
  State <-.Optional Persistence.-> LocalStorage[(AsyncStorage)]
  
  style Component fill:#bbf,stroke:#333,stroke-width:2px
  style Store fill:#bbf,stroke:#333,stroke-width:2px
  style State fill:#bbf,stroke:#333,stroke-width:2px
`}
/>

### Component Types

| Component     | Responsibility                                 | Implementation                       |
| ------------- | ---------------------------------------------- | ------------------------------------ |
| Zustand Store | State container and update logic               | Feature-specific store files         |
| Store Actions | Methods that modify state                      | Defined within store creation        |
| Selectors     | Extract and subscribe to specific state slices | Used in components via hooks         |
| Middleware    | Add functionality to stores                    | Persistence, immutability, debugging |
| Store Hooks   | Encapsulate store access patterns              | Feature-specific custom hooks        |

### When to Use Client State

Zustand should be used for any data that meets these criteria:

* **(Do ✅)** Use for UI state like modals, drawers, and navigation state

* **(Do ✅)** Use for user preferences and settings that persist across sessions

* **(Do ✅)** Use for temporary form data or wizard flows

* **(Do ✅)** Use for cached data that doesn't require server synchronization

* **(Do ✅)** Use for cross-component communication

* **(Don't ❌)** Use for server data that requires synchronization

* **(Don't ❌)** Use for form state in individual components

* **(Don't ❌)** Use for ephemeral UI state in single components

## Design Principles

### Core Architectural Principles

* **(Do ✅)** Keep stores small and focused
  * Create separate stores for distinct concerns
  * Avoid monolithic stores that handle multiple domains

* **(Do ✅)** Use TypeScript interfaces for store definitions
  * Define explicit types for all state and actions
  * Leverage TypeScript for autocompletion and error checking

* **(Do ✅)** Create selectors for performance optimization
  * Select only the specific state slices components need
  * Use stable references for selectors when appropriate

* **(Don't ❌)** Mix server and client state in the same store
  * Server state belongs in TanStack Query
  * Client state belongs in Zustand

### Store Organization Patterns

| Pattern           | Used For                            | Implementation                         |
| ----------------- | ----------------------------------- | -------------------------------------- |
| Global Stores     | Application-wide settings, UI state | Located in `core/store/`               |
| Feature Stores    | Feature-specific state              | Located in `features/[feature]/state/` |
| Transient Stores  | Temporary workflow state            | Created and destroyed with features    |
| Persistent Stores | Settings, auth tokens, preferences  | Implemented with persist middleware    |

## Implementation Examples

### Basic Store Structure

```typescript
// core/store/uiStore.ts
import { create } from 'zustand';
import { devtools } from 'zustand/middleware';

interface UIState {
  // State
  theme: 'light' | 'dark';
  sidebarOpen: boolean;
  activeModal: string | null;
  
  // Actions
  setTheme: (theme: 'light' | 'dark') => void;
  toggleSidebar: () => void;
  openModal: (modalId: string) => void;
  closeModal: () => void;
}

export const useUIStore = create<UIState>()(
  devtools(
    (set) => ({
      // Initial state
      theme: 'light',
      sidebarOpen: false,
      activeModal: null,
      
      // Actions
      setTheme: (theme) => set({ theme }),
      toggleSidebar: () => set((state) => ({ sidebarOpen: !state.sidebarOpen })),
      openModal: (modalId) => set({ activeModal: modalId }),
      closeModal: () => set({ activeModal: null }),
    }),
    {
      name: 'ui-store',
    }
  )
);
```

<Tabs items={['Feature Store', 'Persistent Store', 'Store with Computed Values']}>
  <Tab>
    ```typescript
    // features/auth/state/authStore.ts
    import { create } from 'zustand';
    import { devtools, persist } from 'zustand/middleware';
    import AsyncStorage from '@react-native-async-storage/async-storage';

    interface AuthState {
      user: User | null;
      token: string | null;
      isAuthenticated: boolean;
      setUser: (user: User | null) => void;
      setToken: (token: string | null) => void;
      logout: () => void;
    }

    export const useAuthStore = create<AuthState>()(
      devtools(
        persist(
          (set) => ({
            user: null,
            token: null,
            isAuthenticated: false,
            
            setUser: (user) => set({ user, isAuthenticated: !!user }),
            setToken: (token) => set({ token }),
            logout: () => set({ user: null, token: null, isAuthenticated: false }),
          }),
          {
            name: 'auth-storage',
            storage: AsyncStorage,
            partialize: (state) => ({ token: state.token }), // Only persist token
          }
        )
      )
    );
    ```
  </Tab>

  <Tab>
    ```typescript
    // core/store/settingsStore.ts
    import { create } from 'zustand';
    import { devtools, persist } from 'zustand/middleware';
    import AsyncStorage from '@react-native-async-storage/async-storage';

    interface SettingsState {
      theme: 'light' | 'dark';
      language: string;
      notifications: boolean;
      setTheme: (theme: 'light' | 'dark') => void;
      setLanguage: (language: string) => void;
      toggleNotifications: () => void;
    }

    export const useSettingsStore = create<SettingsState>()(
      devtools(
        persist(
          (set) => ({
            theme: 'light',
            language: 'en',
            notifications: true,
            
            setTheme: (theme) => set({ theme }),
            setLanguage: (language) => set({ language }),
            toggleNotifications: () => set((state) => ({ notifications: !state.notifications })),
          }),
          {
            name: 'settings-storage',
            storage: AsyncStorage,
          }
        )
      )
    );
    ```
  </Tab>

  <Tab>
    ```typescript
    // features/cart/state/cartStore.ts
    import { create } from 'zustand';
    import { immer } from 'zustand/middleware/immer';

    interface CartItem {
      id: string;
      productId: string;
      quantity: number;
      price: number;
    }

    interface CartState {
      items: CartItem[];
      
      // Actions
      addItem: (item: CartItem) => void;
      removeItem: (itemId: string) => void;
      updateQuantity: (itemId: string, quantity: number) => void;
      clearCart: () => void;
      
      // Computed values as functions
      totalItems: () => number;
      totalPrice: () => number;
    }

    export const useCartStore = create<CartState>()(
      immer((set, get) => ({
        items: [],
        
        addItem: (item) => set((state) => {
          const existingItem = state.items.find(i => i.id === item.id);
          if (existingItem) {
            existingItem.quantity += item.quantity;
          } else {
            state.items.push(item);
          }
        }),
        
        removeItem: (itemId) => set((state) => {
          state.items = state.items.filter(item => item.id !== itemId);
        }),
        
        updateQuantity: (itemId, quantity) => set((state) => {
          const item = state.items.find(i => i.id === itemId);
          if (item) item.quantity = quantity;
        }),
        
        clearCart: () => set({ items: [] }),
        
        totalItems: () => get().items.reduce((sum, item) => sum + item.quantity, 0),
        
        totalPrice: () => get().items.reduce((sum, item) => sum + (item.price * item.quantity), 0)
      }))
    );
    ```
  </Tab>
</Tabs>

## Advanced Usage Patterns

<Tabs items={['Performance Optimization', 'Middleware Composition', 'Custom Hooks']}>
  <Tab>
    ```typescript
    // Poor performance - re-renders on any state change
    const Component = () => {
      const store = useCartStore();
      return <Text>{store.items.length}</Text>;
    };

    // Better performance - only re-renders when relevant state changes
    const Component = () => {
      const itemCount = useCartStore((state) => state.items.length);
      return <Text>{itemCount}</Text>;
    };

    // Best practice - reusable selector
    export const useCartItemCount = () => useCartStore((state) => state.items.length);

    const Component = () => {
      const itemCount = useCartItemCount();
      return <Text>{itemCount}</Text>;
    };

    // Advanced - stable selector functions with shallow comparison
    import { shallow } from 'zustand/shallow';

    const Component = () => {
      const { add, remove } = useCartStore(
        (state) => ({ add: state.addItem, remove: state.removeItem }),
        shallow
      );
      
      return (
        <View>
          <Button onPress={() => add(newItem)} title="Add" />
          <Button onPress={() => remove(itemId)} title="Remove" />
        </View>
      );
    };
    ```
  </Tab>

  <Tab>
    ```typescript
    // Composing multiple middleware
    import { create } from 'zustand';
    import { persist, devtools, immer } from 'zustand/middleware';
    import AsyncStorage from '@react-native-async-storage/async-storage';

    // Order matters! Apply from inside out
    const useStore = create(
      devtools(
        persist(
          immer((set) => ({
            count: 0,
            increment: () => set((state) => { state.count += 1 }),
            decrement: () => set((state) => { state.count -= 1 }),
          })),
          { name: 'count-store', storage: AsyncStorage }
        )
      )
    );

    // Custom middleware for logging
    const logger = (config) => (set, get, api) => config(
      (...args) => {
        console.log('  applying', args);
        set(...args);
        console.log('  new state', get());
      },
      get,
      api
    );

    const useLoggedStore = create(
      logger((set) => ({
        bears: 0,
        increase: () => set((state) => ({ bears: state.bears + 1 }))
      }))
    );
    ```
  </Tab>

  <Tab>
    ```typescript
    // features/counter/hooks/useCounter.ts
    import { create } from 'zustand';

    const useCounterStore = create((set) => ({
      count: 0,
      increment: () => set((state) => ({ count: state.count + 1 })),
      decrement: () => set((state) => ({ count: state.count - 1 })),
      reset: () => set({ count: 0 }),
    }));

    // Custom hook composition with additional functionality
    export const useCounter = () => {
      const { count, increment, decrement, reset } = useCounterStore();
      
      // Derived state
      const isPositive = count > 0;
      const isNegative = count < 0;
      
      // Additional functions not in the store
      const incrementBy = (amount) => {
        for (let i = 0; i < amount; i++) {
          increment();
        }
      };
      
      // Return enhanced API
      return {
        count,
        increment,
        decrement,
        reset,
        incrementBy,
        isPositive,
        isNegative,
      };
    };

    // Usage in component
    const CounterComponent = () => {
      const { count, increment, isPositive } = useCounter();
      return (
        <View>
          <Text style={{ color: isPositive ? 'green' : 'black' }}>{count}</Text>
          <Button onPress={increment} title="+" />
        </View>
    ```
  </Tab>
</Tabs>

## Testing Zustand Stores

<Tabs items={['Basic Store Testing', 'Testing with Middleware', 'Testing Async Actions']}>
  <Tab>
    ```typescript
    // __tests__/core/store/uiStore.test.ts
    import { renderHook, act } from '@testing-library/react-hooks';
    import { useUIStore } from '@/core/store/uiStore';

    describe('UIStore', () => {
      // Reset store before each test
      beforeEach(() => {
        useUIStore.setState({ 
          theme: 'light',
          sidebarOpen: false,
          activeModal: null 
        });
      });
      
      it('should toggle sidebar', () => {
        const { result } = renderHook(() => useUIStore());
        
        expect(result.current.sidebarOpen).toBe(false);
        
        act(() => {
          result.current.toggleSidebar();
        });
        
        expect(result.current.sidebarOpen).toBe(true);
      });
      
      it('should set theme', () => {
        const { result } = renderHook(() => useUIStore());
        
        expect(result.current.theme).toBe('light');
        
        act(() => {
          result.current.setTheme('dark');
        });
        
        expect(result.current.theme).toBe('dark');
      });
    });
    ```
  </Tab>

  <Tab>
    ```typescript
    // __tests__/features/auth/state/authStore.test.ts
    import { renderHook, act } from '@testing-library/react-hooks';
    import { useAuthStore } from '@/features/auth/state/authStore';
    import AsyncStorage from '@react-native-async-storage/async-storage';

    // Mock AsyncStorage
    jest.mock('@react-native-async-storage/async-storage', () => ({
      getItem: jest.fn(),
      setItem: jest.fn(),
      removeItem: jest.fn(),
    }));

    describe('AuthStore with persist middleware', () => {
      beforeEach(() => {
        // Clear store and mocks
        useAuthStore.setState({ user: null, token: null, isAuthenticated: false });
        AsyncStorage.getItem.mockClear();
        AsyncStorage.setItem.mockClear();
      });
      
      it('should update user and authentication status', async () => {
        const { result } = renderHook(() => useAuthStore());
        const testUser = { id: '1', name: 'Test User' };
        
        act(() => {
          result.current.setUser(testUser);
        });
        
        expect(result.current.user).toEqual(testUser);
        expect(result.current.isAuthenticated).toBe(true);
        
        // Verify persistence middleware was called
        expect(AsyncStorage.setItem).toHaveBeenCalled();
      });
      
      it('should clear state on logout', async () => {
        const { result } = renderHook(() => useAuthStore());
        
        // Set initial state
        act(() => {
          result.current.setUser({ id: '1', name: 'Test User' });
          result.current.setToken('test-token');
        });
        
        // Perform logout
        act(() => {
          result.current.logout();
        });
        
        // Verify state is cleared
        expect(result.current.user).toBeNull();
        expect(result.current.token).toBeNull();
        expect(result.current.isAuthenticated).toBe(false);
      });
    });
    ```
  </Tab>

  <Tab>
    ```typescript
    // __tests__/features/user/userStore.test.ts
    import { renderHook, act, waitFor } from '@testing-library/react-hooks';
    import { useUserStore } from '@/features/user/state/userStore';
    import { userService } from '@/core/api/services/userService';

    jest.mock('@/core/api/services/userService');

    describe('UserStore with async actions', () => {
      beforeEach(() => {
        useUserStore.setState({ profile: null, loading: false, error: null });
        jest.clearAllMocks();
      });
      
      it('should fetch user profile successfully', async () => {
        // Mock API response
        const mockProfile = { id: '1', name: 'John Doe', email: 'john@example.com' };
        userService.getProfile.mockResolvedValue(mockProfile);
        
        const { result } = renderHook(() => useUserStore());
        
        // Call the async action
        await act(async () => {
          await result.current.fetchProfile();
        });
        
        // Verify state updates
        expect(result.current.loading).toBe(false);
        expect(result.current.profile).toEqual(mockProfile);
        expect(result.current.error).toBeNull();
        expect(userService.getProfile).toHaveBeenCalledTimes(1);
      });
      
      it('should handle errors when fetching profile', async () => {
        // Mock API error
        const mockError = new Error('Failed to fetch profile');
        userService.getProfile.mockRejectedValue(mockError);
        
        const { result } = renderHook(() => useUserStore());
        
        // Call the async action
        await act(async () => {
          await result.current.fetchProfile();
        });
        
        // Verify error handling
        expect(result.current.loading).toBe(false);
        expect(result.current.profile).toBeNull();
        expect(result.current.error).toBe(mockError.message);
      });
    });
    ```
  </Tab>
</Tabs>

## Troubleshooting

<Accordions>
  <Accordion title="Common Issues with Zustand">
    1. **State Not Updating in Components**: This often happens when you're not using selectors correctly.

    ```typescript
    // ❌ Bad - Component won't update when other parts of store change
    const Component = () => {
      const store = useStore(); // Gets entire store
      return <Text>{store.count}</Text>;
    };

    // ✅ Good - Component only updates when count changes
    const Component = () => {
      const count = useStore(state => state.count);
      return <Text>{count}</Text>;
    };
    ```

    2. **Circular Dependencies**: When stores depend on each other, it can create hard-to-debug issues.

    ```typescript
    // ❌ Bad - Circular dependency
    // storeA.js
    import { useStoreB } from './storeB';
    export const useStoreA = create(() => ({
      getDataFromB: () => useStoreB.getState().data
    }));

    // storeB.js
    import { useStoreA } from './storeA';
    export const useStoreB = create(() => ({
      getDataFromA: () => useStoreA.getState().data
    }));

    // ✅ Good - Use a third store or lift state up
    export const useSharedStore = create(() => ({
      dataA: {},
      dataB: {}
    }));
    ```

    3. **Middleware Order Matters**: When combining middleware, order is critical.

    ```typescript
    // ❌ Bad - persist won't save immer's draft state correctly
    const useStore = create(
      persist(
        immer((set) => ({
          // store implementation
        })),
        { name: 'store' }
      )
    );

    // ✅ Good - correct order: innermost → outermost
    const useStore = create(
      immer(
        persist((set) => ({
          // store implementation
        }),
        { name: 'store' })
      )
    );
    ```
  </Accordion>

  <Accordion title="Performance Optimization Tips">
    1. **Use Selectors to Prevent Unnecessary Renders**

    ```typescript
    // ❌ Bad - Causes re-renders when any part of the store changes
    const { items, count } = useStore();

    // ✅ Good - Only re-renders when these specific values change
    const items = useStore(state => state.items);
    const count = useStore(state => state.count);

    // ✅ Better - Use the shallow comparison for object selection
    import { shallow } from 'zustand/shallow';
    const { items, count } = useStore(
      state => ({ items: state.items, count: state.count }),
      shallow
    );
    ```

    2. **Memoize Selectors for Complex Derivations**

    ```typescript
    import { useMemo } from 'react';

    const Component = () => {
      const items = useStore(state => state.items);
      
      // ✅ Good - Expensive computation only runs when items change
      const processedItems = useMemo(() => {
        return items.map(item => expensiveComputation(item));
      }, [items]);
      
      return <ItemList items={processedItems} />;
    };
    ```

    3. **Break Up Large Stores**

    ```typescript
    // ❌ Bad - One large store for everything
    const useAppStore = create(() => ({
      // UI state
      theme: 'light',
      sidebar: false,
      
      // User state
      user: null,
      settings: {},
      
      // Feature state
      products: [],
      cart: [],
    }));

    // ✅ Good - Separate stores by domain
    const useUIStore = create(() => ({
      theme: 'light',
      sidebar: false,
    }));

    const useUserStore = create(() => ({
      user: null,
      settings: {},
    }));

    const useProductStore = create(() => ({
      products: [],
    }));
    ```
  </Accordion>

  <Accordion title="Debugging Zustand State">
    1. **Enable Redux DevTools** for visualizing state changes:

    ```typescript
    import { devtools } from 'zustand/middleware';

    const useStore = create(
      devtools(
        (set) => ({
          counter: 0,
          increase: () => set((state) => ({ counter: state.counter + 1 })),
        }),
        {
          name: 'Counter Store',
          trace: true, // enables stack traces for actions
        }
      )
    );
    ```

    2. **Add Custom Logging** for tracking specific changes:

    ```typescript
    const useStore = create((set, get) => ({
      counter: 0,
      increase: () => {
        const prevCount = get().counter;
        set((state) => ({ counter: state.counter + 1 }));
        console.log(`Counter changed from ${prevCount} to ${get().counter}`);
      },
    }));
    ```

    3. **Inspect State from Outside Components**:

    ```typescript
    // Anywhere in your code
    console.log('Current state:', useStore.getState());

    // Subscribe to changes outside of React
    const unsubscribe = useStore.subscribe(
      (state) => console.log('New state:', state)
    );

    // Later: clean up subscription
    unsubscribe();
    ```
  </Accordion>
</Accordions>

## Related Documents

<Cards num={3}>
  <Card title="State Management Overview" href="/docs//architecture/state-management">
    Overview of our complete state management approach including client, server, and component state.
  </Card>

  <Card title="Server State Management" href="/docs//architecture/state-management/server-state">
    Companion documentation for handling server-specific state with TanStack Query.
  </Card>

  <Card title="Integration Patterns" href="/docs//architecture/state-management/integration-patterns">
    Patterns for integrating server and client state effectively.
  </Card>
</Cards>

<div className="mt-8 border-t pt-8">
  <h3>External Resources</h3>

  <ul>
    <li><a href="https://github.com/pmndrs/zustand" target="_blank" rel="noopener noreferrer">Zustand Official Documentation</a></li>
    <li><a href="https://tkdodo.eu/blog/working-with-zustand" target="_blank" rel="noopener noreferrer">Working with Zustand by TkDodo</a></li>
    <li><a href="https://react-native.dev/docs/react-devtools" target="_blank" rel="noopener noreferrer">React Native DevTools Integration</a></li>
  </ul>
</div>


# UTA State Management: Component State Management
URL: https://dev.updatetheapp.com/docs/state-management/component-state
Documentation: https://dev.updatetheapp.com/docs/state-management/component-state

Guide for managing local component state with React's built-in state management
        
***

title: Component State Management
description: Guide for managing local component state with React's built-in state management
--------------------------------------------------------------------------------------------

import { File, Folder, Files } from 'fumadocs-ui/components/files';
import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Accordion, Accordions } from 'fumadocs-ui/components/accordion';
import { Cards, Card } from 'fumadocs-ui/components/card';

# Component State Management

## Overview

This document outlines our approach to managing component-level state in our React Native application. Component state represents local state that is specific to a single component or a small component tree. We implement React's built-in state management hooks (useState and useReducer) for managing ephemeral UI state, form data, and other localized concerns. This follows our application's **Golden Rule**: "Component state belongs in React's built-in hooks, not in Zustand or TanStack Query". This approach optimizes for simplicity, performance, and proper separation of concerns.

## Purpose & Scope

* **Target Audience**: React Native developers implementing UI components that require local state management
* **Problems Addressed**: Proper state isolation, form management, UI interactions, and temporary state that doesn't belong in global stores
* **Scope Boundaries**: Covers React's built-in state management hooks, common patterns, performance optimization, and custom hooks, but does not cover global state or server data management

## Core Components/Architecture

<Mermaid
  chart={`flowchart TD
  Component[React Component] --useState/useReducer--> LocalState[(Local State)]
  LocalState --Re-renders--> Component
  
  subgraph "Component State Layer"
      LocalState
      CustomHooks[Custom Hooks] --Abstraction--> LocalState
  end
  
  Component --Props--> ChildComponent[Child Component]
  
  LocalState --"Context (when needed)"--> ChildComponent
  
  style LocalState fill:#f9f,stroke:#333,stroke-width:2px
  style Component fill:#bbf,stroke:#333,stroke-width:2px
  style ChildComponent fill:#bbf,stroke:#333,stroke-width:2px
  style CustomHooks fill:#dfd,stroke:#333,stroke-width:2px
`}
/>

## When to Use Component State

Use React's built-in state management for:

* Form inputs before submission
* UI toggles (dropdowns, modals specific to one component)
* Temporary values during user interaction
* Animation states
* Local component configuration
* Any state that doesn't need to be shared beyond a small component tree

## Basic Component State

<Tabs items={['useState', 'useReducer']}>
  <Tab value="useState">
    ### Simple State with useState

    The `useState` hook is ideal for managing simple, independent state values in a component.

    ```typescript
    import React, { useState } from 'react';
    import { View, TextInput, Button, Text } from 'react-native';

    const ContactForm: React.FC = () => {
      const [name, setName] = useState('');
      const [email, setEmail] = useState('');
      const [message, setMessage] = useState('');
      const [isSubmitting, setIsSubmitting] = useState(false);
      
      const handleSubmit = async () => {
        setIsSubmitting(true);
        try {
          await submitContact({ name, email, message });
          // Reset form
          setName('');
          setEmail('');
          setMessage('');
        } finally {
          setIsSubmitting(false);
        }
      };
      
      return (
        <View>
          <TextInput
            value={name}
            onChangeText={setName}
            placeholder="Name"
          />
          <TextInput
            value={email}
            onChangeText={setEmail}
            placeholder="Email"
            keyboardType="email-address"
          />
          <TextInput
            value={message}
            onChangeText={setMessage}
            placeholder="Message"
            multiline
          />
          <Button
            title="Submit"
            onPress={handleSubmit}
            disabled={isSubmitting}
          />
        </View>
      );
    };
    ```

    #### When to use useState:

    * For independent state variables
    * When state logic is simple
    * For primitive values or simple objects
    * When you don't need derived state
  </Tab>

  <Tab value="useReducer">
    ### Complex State with useReducer

    The `useReducer` hook is better for managing complex state logic, especially when state values are interdependent.

    ```typescript
    import React, { useReducer } from 'react';
    import { View, Text, Button, TextInput } from 'react-native';

    interface FormState {
      values: {
        username: string;
        password: string;
      };
      errors: {
        username?: string;
        password?: string;
      };
      isSubmitting: boolean;
      submitCount: number;
    }

    type FormAction =
      | { type: 'SET_FIELD'; field: string; value: string }
      | { type: 'SET_ERROR'; field: string; error: string }
      | { type: 'SUBMIT_START' }
      | { type: 'SUBMIT_SUCCESS' }
      | { type: 'SUBMIT_ERROR'; errors: Record<string, string> };

    const formReducer = (state: FormState, action: FormAction): FormState => {
      switch (action.type) {
        case 'SET_FIELD':
          return {
            ...state,
            values: { ...state.values, [action.field]: action.value },
            errors: { ...state.errors, [action.field]: undefined },
          };
        case 'SET_ERROR':
          return {
            ...state,
            errors: { ...state.errors, [action.field]: action.error },
          };
        case 'SUBMIT_START':
          return { ...state, isSubmitting: true };
        case 'SUBMIT_SUCCESS':
          return {
            ...state,
            isSubmitting: false,
            submitCount: state.submitCount + 1,
            values: { username: '', password: '' },
          };
        case 'SUBMIT_ERROR':
          return {
            ...state,
            isSubmitting: false,
            errors: action.errors,
          };
        default:
          return state;
      }
    };

    const LoginForm: React.FC = () => {
      const [state, dispatch] = useReducer(formReducer, {
        values: { username: '', password: '' },
        errors: {},
        isSubmitting: false,
        submitCount: 0,
      });
      
      const handleSubmit = async () => {
        dispatch({ type: 'SUBMIT_START' });
        
        try {
          await login(state.values);
          dispatch({ type: 'SUBMIT_SUCCESS' });
        } catch (error) {
          dispatch({ type: 'SUBMIT_ERROR', errors: error.errors });
        }
      };
      
      return (
        <View>
          <TextInput
            value={state.values.username}
            onChangeText={(value) => 
              dispatch({
                type: 'SET_FIELD',
                field: 'username',
                value,
              })
            }
            placeholder="Username"
          />
          {state.errors.username && (
            <Text style={{ color: 'red' }}>{state.errors.username}</Text>
          )}
          
          <TextInput
            value={state.values.password}
            onChangeText={(value) =>
              dispatch({
                type: 'SET_FIELD',
                field: 'password',
                value,
              })
            }
            placeholder="Password"
            secureTextEntry
          />
          {state.errors.password && (
            <Text style={{ color: 'red' }}>{state.errors.password}</Text>
          )}
          
          <Button
            title="Login"
            onPress={handleSubmit}
            disabled={state.isSubmitting}
          />
          
          {state.submitCount > 0 && (
            <Text>Form submitted {state.submitCount} times</Text>
          )}
        </View>
      );
    };
    ```

    #### When to use useReducer:

    * For complex state logic with multiple sub-values
    * When state transitions depend on previous state
    * When testing state logic separately from components
    * For handling complex validation or multi-step processes
  </Tab>

  <Tab value="Collapsible UI">
    ### Toggle States

    Components that need to show/hide content based on user interaction use toggle state.

    ```typescript
    const CollapsibleSection: React.FC<{ title: string; children: ReactNode }> = ({
      title,
      children,
    }) => {
      const [isExpanded, setIsExpanded] = useState(false);
      
      return (
        <View>
          <TouchableOpacity onPress={() => setIsExpanded(!isExpanded)}>
            <View style={styles.header}>
              <Text>{title}</Text>
              <Text>{isExpanded ? '−' : '+'}</Text>
            </View>
          </TouchableOpacity>
          {isExpanded && <View style={styles.content}>{children}</View>}
        </View>
      );
    };
    ```

    #### Common Toggle Use Cases:

    * Expandable panels and accordions
    * Show/hide password fields
    * Modal dialogs and popovers
    * Theme switching (light/dark mode)
  </Tab>

  <Tab>
    ### Temporary UI State

    State that's only needed during specific user interactions like loading, confirmation, or error states.

    ```typescript
    const ListItem: React.FC<{ item: Item; onDelete: (id: string) => void }> = ({
      item,
      onDelete,
    }) => {
      const [isDeleting, setIsDeleting] = useState(false);
      
      const handleDelete = async () => {
        setIsDeleting(true);
        try {
          await onDelete(item.id);
        } catch (error) {
          setIsDeleting(false);
          // Handle error
        }
      };
      
      return (
        <View style={[styles.item, isDeleting && styles.deleting]}>
          <Text>{item.name}</Text>
          <Button
            title="Delete"
            onPress={handleDelete}
            disabled={isDeleting}
          />
        </View>
      );
    };
    ```

    #### Common Temporary State Types:

    * Loading indicators
    * Validation states
    * Confirmation dialogs
    * Error messages
    * Success notifications
  </Tab>

  <Tab>
    ### Multi-Step Forms

    Complex forms split into multiple steps, often with validation between steps.

    ```typescript
    interface Step1Data {
      firstName: string;
      lastName: string;
    }

    interface Step2Data {
      email: string;
      phone: string;
    }

    const MultiStepForm: React.FC = () => {
      const [currentStep, setCurrentStep] = useState(1);
      const [step1Data, setStep1Data] = useState<Step1Data>({
        firstName: '',
        lastName: '',
      });
      const [step2Data, setStep2Data] = useState<Step2Data>({
        email: '',
        phone: '',
      });
      
      const goToNext = () => setCurrentStep(currentStep + 1);
      const goToPrevious = () => setCurrentStep(currentStep - 1);
      
      const handleSubmit = async () => {
        const formData = { ...step1Data, ...step2Data };
        await submitForm(formData);
      };
      
      return (
        <View>
          {currentStep === 1 && (
            <Step1
              data={step1Data}
              onChange={setStep1Data}
              onNext={goToNext}
            />
          )}
          {currentStep === 2 && (
            <Step2
              data={step2Data}
              onChange={setStep2Data}
              onPrevious={goToPrevious}
              onSubmit={handleSubmit}
            />
          )}
        </View>
      );
    };
    ```

    #### Best Practices:

    * Keep step data in separate state objects for clarity
    * Validate each step before allowing progress
    * Consider useReducer for complex multi-step forms
    * Persist state if there's a risk of navigation away (optional)
  </Tab>
</Tabs>

## Common Patterns

<Tabs items={['Controlled Components', 'Collapsible UI', 'Temporary UI State', 'Multi-Step Forms']}>
  <Tab value="Controlled Components">
    ### Controlled Components

    Controlled components are React components where form data is handled by the component's state.

    ```typescript
    import React, { useState, useEffect } from 'react';
    import { View, TextInput, Text } from 'react-native';

    const SearchBar: React.FC = () => {
      const [searchTerm, setSearchTerm] = useState('');
      const [suggestions, setSuggestions] = useState<string[]>([]);
      
      useEffect(() => {
        // Debounce logic could be added here
        if (searchTerm.length > 2) {
          fetchSuggestions(searchTerm).then(setSuggestions);
        } else {
          setSuggestions([]);
        }
      }, [searchTerm]);
      
      return (
        <View>
          <TextInput
            value={searchTerm}
            onChangeText={setSearchTerm}
            placeholder="Search..."
          />
          {suggestions.length > 0 && (
            <View>
              {suggestions.map((suggestion) => (
                <Text key={suggestion}>{suggestion}</Text>
              ))}
            </View>
          )}
        </View>
      );
    };
    ```

    #### Benefits:

    * Predictable flow of data
    * Single source of truth
    * Easier to validate or transform input
    * Enables immediate UI responses to user input
  </Tab>

  <Tab>
    ### Collapsible UI Elements

    Toggle-based UI elements like accordions, expandable panels, and dropdown menus are common patterns that use local state.

    ```typescript
    import React, { useState } from 'react';
    import { View, Text, TouchableOpacity, StyleSheet } from 'react-native';

    const Accordion: React.FC<{ title: string; children: React.ReactNode }> = ({
      title,
      children,
    }) => {
      const [isExpanded, setIsExpanded] = useState(false);
      
      const toggleExpand = () => setIsExpanded(!isExpanded);
      
      return (
        <View style={styles.container}>
          <TouchableOpacity onPress={toggleExpand}>
            <View style={styles.header}>
              <Text style={styles.title}>{title}</Text>
              <Text>{isExpanded ? '−' : '+'}</Text>
            </View>
          </TouchableOpacity>
          {isExpanded && (
            <View style={styles.content}>
              {children}
            </View>
          )}
        </View>
      );
    };

    const styles = StyleSheet.create({
      container: {
        borderWidth: 1,
        borderColor: '#ccc',
        borderRadius: 4,
        marginBottom: 10,
      },
      header: {
        flexDirection: 'row',
        justifyContent: 'space-between',
        padding: 15,
        backgroundColor: '#f5f5f5',
      },
      title: {
        fontWeight: 'bold',
      },
      content: {
        padding: 15,
      },
    });
    ```

    #### Implementation Notes:

    * Keep toggle state close to where it's used
    * For multiple accordion items, consider an array of expanded states or IDs
    * For complex cases, useReducer may be more appropriate
  </Tab>

  <Tab>
    ### Temporary UI State

    Temporary UI states like loading indicators, confirmation dialogs, and error states are perfect for component state.

    ```typescript
    import React, { useState } from 'react';
    import { View, Text, Button, ActivityIndicator } from 'react-native';

    const ListItem: React.FC<{ item: Item; onDelete: (id: string) => void }> = ({
      item,
      onDelete,
    }) => {
      const [isDeleting, setIsDeleting] = useState(false);
      const [showConfirm, setShowConfirm] = useState(false);
      const [error, setError] = useState<string | null>(null);
      
      const handleDeleteRequest = () => setShowConfirm(true);
      const cancelDelete = () => setShowConfirm(false);
      
      const handleConfirmedDelete = async () => {
        setIsDeleting(true);
        setError(null);
        try {
          await onDelete(item.id);
          setShowConfirm(false);
        } catch (err) {
          setError(err.message || 'Failed to delete');
        } finally {
          setIsDeleting(false);
        }
      };
      
      return (
        <View style={{ padding: 10, borderBottomWidth: 1, borderColor: '#eee' }}>
          <Text style={{ fontSize: 16 }}>{item.title}</Text>
          
          {error && <Text style={{ color: 'red' }}>{error}</Text>}
          
          {!showConfirm ? (
            <Button
              title="Delete"
              onPress={handleDeleteRequest}
              disabled={isDeleting}
            />
          ) : (
            <View style={{ flexDirection: 'row', marginTop: 10 }}>
              <Text>Are you sure?</Text>
              {isDeleting ? (
                <ActivityIndicator size="small" />
              ) : (
                <>
                  <Button title="Yes" onPress={handleConfirmedDelete} />
                  <Button title="No" onPress={cancelDelete} />
                </>
              )}
            </View>
          )}
        </View>
      );
    };
    ```

    #### Key Considerations:

    * Use boolean flags for UI states (loading, open/closed, etc.)
    * Keep error states locally when they apply to a specific interaction
    * Reset temporary states when the interaction completes
  </Tab>

  <Tab>
    ### Multi-Step Forms

    Forms with multiple steps or wizard interfaces manage state about the current step and form data.

    ```typescript
    import React, { useState } from 'react';
    import { View, TextInput, Button, Text, StyleSheet } from 'react-native';

    interface Step1Data {
      firstName: string;
      lastName: string;
    }

    interface Step2Data {
      email: string;
      phone: string;
    }

    const MultiStepForm: React.FC = () => {
      const [currentStep, setCurrentStep] = useState(1);
      const [step1Data, setStep1Data] = useState<Step1Data>({
        firstName: '',
        lastName: '',
      });
      const [step2Data, setStep2Data] = useState<Step2Data>({
        email: '',
        phone: '',
      });
      
      const nextStep = () => setCurrentStep((prev) => prev + 1);
      const prevStep = () => setCurrentStep((prev) => prev - 1);
      
      const handleSubmit = async () => {
        await submitForm({ ...step1Data, ...step2Data });
        // Reset form or navigate away
      };
      
      const isStep1Valid = () => (
        step1Data.firstName.trim() !== '' && 
        step1Data.lastName.trim() !== ''
      );
      
      return (
        <View style={styles.container}>
          <View style={styles.stepIndicator}>
            <Text>Step {currentStep} of 2</Text>
            <View style={styles.progressBar}>
              <View 
                style={[styles.progress, { width: `${(currentStep / 2) * 100}%` }]} 
              />
            </View>
          </View>
          
          {currentStep === 1 && (
            <View style={styles.step}>
              <Text style={styles.stepTitle}>Personal Information</Text>
              <TextInput
                style={styles.input}
                value={step1Data.firstName}
                onChangeText={(value) =>
                  setStep1Data({ ...step1Data, firstName: value })
                }
                placeholder="First Name"
              />
              <TextInput
                style={styles.input}
                value={step1Data.lastName}
                onChangeText={(value) =>
                  setStep1Data({ ...step1Data, lastName: value })
                }
                placeholder="Last Name"
              />
              <Button 
                title="Next" 
                onPress={nextStep} 
                disabled={!isStep1Valid()}
              />
            </View>
          )}
          
          {currentStep === 2 && (
            <View style={styles.step}>
              <Text style={styles.stepTitle}>Contact Information</Text>
              <TextInput
                style={styles.input}
                value={step2Data.email}
                onChangeText={(value) =>
                  setStep2Data({ ...step2Data, email: value })
                }
                placeholder="Email"
                keyboardType="email-address"
              />
              <TextInput
                style={styles.input}
                value={step2Data.phone}
                onChangeText={(value) =>
                  setStep2Data({ ...step2Data, phone: value })
                }
                placeholder="Phone"
                keyboardType="phone-pad"
              />
              <View style={styles.buttonRow}>
                <Button title="Back" onPress={prevStep} />
                <Button title="Submit" onPress={handleSubmit} />
              </View>
            </View>
          )}
        </View>
      );
    };

    const styles = StyleSheet.create({
      container: {
        padding: 20,
      },
      stepIndicator: {
        marginBottom: 20,
      },
      progressBar: {
        height: 10,
        backgroundColor: '#e0e0e0',
        borderRadius: 5,
        marginTop: 10,
      },
      progress: {
        height: 10,
        backgroundColor: '#007AFF',
        borderRadius: 5,
      },
      step: {
        marginBottom: 20,
      },
      stepTitle: {
        fontSize: 18,
        fontWeight: 'bold',
        marginBottom: 15,
      },
      input: {
        borderWidth: 1,
        borderColor: '#ddd',
        padding: 10,
        marginBottom: 15,
        borderRadius: 4,
      },
      buttonRow: {
        flexDirection: 'row',
        justifyContent: 'space-between',
      },
    });
    ```

    #### Best Practices:

    * Keep step data in separate state objects for clarity
    * Validate each step before allowing progress
    * Consider useReducer for complex multi-step forms
    * Persist state if there's a risk of navigation away (optional)
  </Tab>
</Tabs>

## Custom Hooks for Reusable Component State

<Tabs items={['useToggle', 'useForm', 'useDebounce', 'usePrevious']}>
  <Tab value="useToggle">
    ### Toggle State Hook

    A simple hook for boolean toggle state that's commonly used in UI components.

    ```typescript
    import { useState, useCallback } from 'react';

    /**
     * A hook for managing boolean toggle state with a single function
     * 
     * @param initialValue - Initial boolean state value
     * @returns [value, toggleFunction]
     */
    const useToggle = (initialValue: boolean = false): [boolean, () => void] => {
      const [value, setValue] = useState(initialValue);
      const toggle = useCallback(() => setValue((v) => !v), []);
      return [value, toggle];
    };
    ```

    #### Usage Example

    ```typescript
    const ExpandablePanel: React.FC<{ title: string; children: React.ReactNode }> = ({
      title,
      children
    }) => {
      const [isExpanded, toggleExpanded] = useToggle(false);
      
      return (
        <View style={styles.container}>
          <TouchableOpacity onPress={toggleExpanded}>
            <View style={styles.header}>
              <Text>{title}</Text>
              <Text>{isExpanded ? '−' : '+'}</Text>
            </View>
          </TouchableOpacity>
          {isExpanded && (
            <View style={styles.content}>{children}</View>
          )}
        </View>
      );
    };
    ```
  </Tab>

  <Tab value="useForm">
    ### Form State Hook

    A hook for managing form state, field changes, errors, and touched states.

    ```typescript
    import { useState } from 'react';

    /**
     * A hook for managing form state with validation support
     * 
     * @param initialValues - Initial form values object
     * @returns Form state management utilities
     */
    const useForm = <T extends Record<string, any>>(initialValues: T) => {
      const [values, setValues] = useState<T>(initialValues);
      const [errors, setErrors] = useState<Partial<Record<keyof T, string>>>({});
      const [touched, setTouched] = useState<Partial<Record<keyof T, boolean>>>({});
      const [isSubmitting, setIsSubmitting] = useState(false);
      
      const handleChange = (field: keyof T, value: any) => {
        setValues((prev) => ({ ...prev, [field]: value }));
        
        // Clear error when field is modified
        if (errors[field]) {
          setErrors((prev) => ({ ...prev, [field]: undefined }));
        }
        
        // Mark as touched
        if (!touched[field]) {
          setTouched((prev) => ({ ...prev, [field]: true }));
        }
      };
      
      const handleBlur = (field: keyof T) => {
        setTouched((prev) => ({ ...prev, [field]: true }));
      };
      
      const reset = () => {
        setValues(initialValues);
        setErrors({});
        setTouched({});
        setIsSubmitting(false);
      };
      
      return { 
        values, 
        errors, 
        touched, 
        isSubmitting, 
        handleChange, 
        handleBlur,
        setErrors, 
        setIsSubmitting,
        reset 
      };
    };
    ```
  </Tab>

  <Tab value="useDebounce">
    ### Debounced Value Hook

    A hook that delays updating a value until a specified delay has passed without changes.

    ```typescript
    import { useState, useEffect } from 'react';

    /**
     * A hook that provides a debounced version of a value
     * 
     * @param value - The value to debounce
     * @param delay - Debounce delay in milliseconds
     * @returns The debounced value
     */
    const useDebounce = <T>(value: T, delay: number): T => {
      const [debouncedValue, setDebouncedValue] = useState<T>(value);
      
      useEffect(() => {
        const handler = setTimeout(() => {
          setDebouncedValue(value);
        }, delay);
        
        return () => {
          clearTimeout(handler);
        };
      }, [value, delay]);
      
      return debouncedValue;
    };
    ```
  </Tab>

  <Tab value="usePrevious">
    ### Previous Value Hook

    A hook that keeps track of the previous value of a state or prop.

    ```typescript
    import { useRef, useEffect } from 'react';

    /**
     * Hook to access the previous value of a state or prop
     * 
     * @param value - Current value to track
     * @returns The previous value (undefined on first render)
     */
    function usePrevious<T>(value: T): T | undefined {
      const ref = useRef<T>();
      
      useEffect(() => {
        ref.current = value;
      }, [value]);
      
      return ref.current;
    }
    ```
  </Tab>
</Tabs>

## When to Elevate State

<Tabs items={['Shared Access', 'Persistence Needs', 'Complex Interactions']}>
  <Tab value="Shared Access">
    ### Multiple Components Need Access

    When state needs to be shared across components that aren't directly related, you should elevate to global state.

    ```typescript
    // ❌ Prop drilling through multiple components
    const App = () => {
      const [user, setUser] = useState(null);
      return (
        <Layout user={user}>
          <MainContent user={user}>
            <Sidebar user={user} />
            <Feed user={user} />
          </MainContent>
          <Footer user={user} />
        </Layout>
      );
    };

    // ✅ Shared state with Zustand
    const useUserStore = create((set) => ({
      user: null,
      setUser: (user) => set({ user })
    }));

    const UserAvatar = () => {
      const user = useUserStore((state) => state.user);
      return <Avatar user={user} />;
    };

    const UserSettings = () => {
      const user = useUserStore((state) => state.user);
      return <Settings user={user} />;
    };
    ```
  </Tab>

  <Tab>
    ### Persistence Across Navigation

    When state needs to survive component unmounting or navigation events.

    ```typescript
    // ❌ Lost state on navigation
    const ProfileScreen = () => {
      const [filters, setFilters] = useState({ sortBy: 'date', showArchived: false });
      // State is lost when user navigates away
      
      return <UserList filters={filters} onFilterChange={setFilters} />;
    };

    // ✅ Persistent state with Zustand
    const useFiltersStore = create((set) => ({
      filters: { sortBy: 'date', showArchived: false },
      setFilters: (filters) => set({ filters })
    }));

    const ProfileScreen = () => {
      const { filters, setFilters } = useFiltersStore();
      // State persists even if user navigates away
      
      return <UserList filters={filters} onFilterChange={setFilters} />;
    };
    ```
  </Tab>

  <Tab>
    ### Complex Interactions Between Components

    When multiple components need to interact with the same state in complex ways.

    ```typescript
    // ❌ Complex state coordination
    const CartPage = () => {
      const [items, setItems] = useState([]);
      const [total, setTotal] = useState(0);
      const [discounts, setDiscounts] = useState([]);
      const [shipping, setShipping] = useState({});
      
      // Need to coordinate updates across components
      const updateQuantity = (id, qty) => { /* complex logic */ };
      const applyDiscount = (code) => { /* more complex logic */ };
      
      return (
        <>
          <CartItems items={items} onUpdateQuantity={updateQuantity} />
          <CartSummary total={total} discounts={discounts} />
          <ShippingOptions shipping={shipping} setShipping={setShipping} />
          <CheckoutButton /* ... */ />
        </>
      );
    };

    // ✅ Unified global state
    const useCartStore = create((set, get) => ({
      items: [],
      shipping: {},
      discounts: [],
      updateQuantity: (id, qty) => { /* centralized logic */ },
      applyDiscount: (code) => { /* centralized logic */ },
      get total() { /* computed property */ }
    }));

    // Components only use what they need
    const CartItems = () => {
      const { items, updateQuantity } = useCartStore();
      return /* ... */;
    };
    ```
  </Tab>
</Tabs>

## Performance Considerations

### 1. Minimize Re-renders

```typescript
// ❌ Bad: New object on every render
const Component: React.FC = () => {
  const [form, setForm] = useState({ name: '', email: '' });
  
  return (
    <ChildComponent 
      config={{ form, extra: 'data' }} // New object every render
    />
  );
};

// ✅ Good: Stable references
const Component: React.FC = () => {
  const [form, setForm] = useState({ name: '', email: '' });
  const config = useMemo(
    () => ({ form, extra: 'data' }),
    [form]
  );
  
  return <ChildComponent config={config} />;
};
```

### 2. Use Callbacks Appropriately

```typescript
// ❌ Bad: New function on every render
const Component: React.FC = () => {
  const [count, setCount] = useState(0);
  
  return (
    <Button 
      onPress={() => setCount(count + 1)} // New function every render
    />
  );
};

// ✅ Good: Stable callback
const Component: React.FC = () => {
  const [count, setCount] = useState(0);
  const increment = useCallback(() => setCount(c => c + 1), []);
  
  return <Button onPress={increment} />;
};
```

## Testing Component State

<Tabs items={['Testing Hooks', 'Testing Components', 'Mocking State Logic']}>
  <Tab>
    ### Testing Custom Hooks

    Use `@testing-library/react-hooks` to test custom hooks.

    ```typescript
    // __tests__/hooks/useToggle.test.ts
    import { renderHook, act } from '@testing-library/react-hooks';
    import { useToggle } from '@/hooks/useToggle';

    describe('useToggle', () => {
      it('should initialize with default value', () => {
        const { result } = renderHook(() => useToggle());
        expect(result.current[0]).toBe(false);
      });
      
      it('should initialize with provided value', () => {
        const { result } = renderHook(() => useToggle(true));
        expect(result.current[0]).toBe(true);
      });
      
      it('should toggle the value', () => {
        const { result } = renderHook(() => useToggle(false));
        
        act(() => {
          const toggle = result.current[1];
          toggle();
        });
        
        expect(result.current[0]).toBe(true);
        
        act(() => {
          const toggle = result.current[1];
          toggle();
        });
        
        expect(result.current[0]).toBe(false);
      });
    });
    ```
  </Tab>

  <Tab>
    ### Testing State in Components

    Use `@testing-library/react-native` to test component state behavior.

    ```typescript
    // __tests__/components/Counter.test.tsx
    import React from 'react';
    import { render, fireEvent } from '@testing-library/react-native';
    import Counter from '@/components/Counter';

    describe('Counter', () => {
      it('should display initial count', () => {
        const { getByText } = render(<Counter initialCount={5} />);
        expect(getByText('Count: 5')).toBeTruthy();
      });
      
      it('should increment count when + button is pressed', () => {
        const { getByText } = render(<Counter initialCount={5} />);
        
        const incrementButton = getByText('+');
        fireEvent.press(incrementButton);
        
        expect(getByText('Count: 6')).toBeTruthy();
      });
      
      it('should decrement count when - button is pressed', () => {
        const { getByText } = render(<Counter initialCount={5} />);
        
        const decrementButton = getByText('-');
        fireEvent.press(decrementButton);
        
        expect(getByText('Count: 4')).toBeTruthy();
      });
    });
    ```
  </Tab>

  <Tab>
    ### Mocking State Dependencies

    Mock dependencies to isolate component state logic in tests.

    ```typescript
    // __tests__/components/UserProfile.test.tsx
    import React from 'react';
    import { render, act, waitFor } from '@testing-library/react-native';
    import UserProfile from '@/components/UserProfile';
    import { useUserQuery } from '@/api/userApi';

    // Mock the server state hook
    jest.mock('@/api/userApi', () => ({
      useUserQuery: jest.fn(),
    }));

    describe('UserProfile', () => {
      it('should render loading state', () => {
        // Setup mock to return loading state
        useUserQuery.mockReturnValue({
          data: null,
          isLoading: true,
          error: null,
          refetch: jest.fn(),
        });
        
        const { getByTestId } = render(<UserProfile userId="123" />);
        
        expect(getByTestId('loading-indicator')).toBeTruthy();
      });
      
      it('should render error state', () => {
        // Setup mock to return error state
        useUserQuery.mockReturnValue({
          data: null,
          isLoading: false,
          error: new Error('Failed to load user'),
          refetch: jest.fn(),
        });
        
        const { getByText } = render(<UserProfile userId="123" />);
        
        expect(getByText('Error: Failed to load user')).toBeTruthy();
      });
    });
    ```
  </Tab>
</Tabs>

## Troubleshooting

<Accordions>
  <Accordion title="Common Issues with useState">
    1. **Stale Closures**: Functions defined in render use stale state values

    ```typescript
    // ❌ Problem: onClick uses stale count
    function Counter() {
      const [count, setCount] = useState(0);
      
      // This function captures the value of count at render time
      const handleClick = () => {
        setTimeout(() => {
          alert(count); // Will show stale value
        }, 1000);
      };
      
      return (
        <>
          <p>Count: {count}</p>
          <button onClick={() => setCount(count + 1)}>Increment</button>
          <button onClick={handleClick}>Show alert</button>
        </>
      );
    }

    // ✅ Solution: Use functional updates or useRef
    function Counter() {
      const [count, setCount] = useState(0);
      const countRef = useRef(count);
      
      // Update ref when count changes
      useEffect(() => {
        countRef.current = count;
      }, [count]);
      
      const handleClick = () => {
        setTimeout(() => {
          alert(countRef.current); // Always shows current value
        }, 1000);
      };
      
      return (
        <>
          <p>Count: {count}</p>
          <button onClick={() => setCount(c => c + 1)}>Increment</button>
          <button onClick={handleClick}>Show alert</button>
        </>
      );
    }
    ```

    2. **Batched Updates**: Multiple state updates in event handlers are batched

    ```typescript
    // ❌ Problem: Both setState calls only trigger one re-render
    function Counter() {
      const [count, setCount] = useState(0);
      
      const handleClick = () => {
        setCount(count + 1); // count is 0
        setCount(count + 1); // count is still 0, so this sets it to 1 again
      };
      
      return <button onClick={handleClick}>Count: {count}</button>;
    }

    // ✅ Solution: Use functional updates
    function Counter() {
      const [count, setCount] = useState(0);
      
      const handleClick = () => {
        setCount(c => c + 1); // c is 0, sets to 1
        setCount(c => c + 1); // c is 1, sets to 2
      };
      
      return <button onClick={handleClick}>Count: {count}</button>;
    }
    ```
  </Accordion>

  <Accordion title="useEffect Cleanup Issues">
    1. **Memory Leaks**: Not cleaning up effects properly

    ```typescript
    // ❌ Problem: No cleanup causes memory leaks
    function UserStatus() {
      const [isOnline, setIsOnline] = useState(false);
      
      useEffect(() => {
        const subscription = subscribeToUserStatus(userId, (status) => {
          setIsOnline(status.isOnline);
        });
        // No cleanup, subscription stays active after unmount
      }, [userId]);
      
      return <div>{isOnline ? 'Online' : 'Offline'}</div>;
    }

    // ✅ Solution: Proper cleanup function
    function UserStatus() {
      const [isOnline, setIsOnline] = useState(false);
      
      useEffect(() => {
        const subscription = subscribeToUserStatus(userId, (status) => {
          setIsOnline(status.isOnline);
        });
        
        // Cleanup function that runs before next effect or on unmount
        return () => {
          subscription.unsubscribe();
        };
      }, [userId]);
      
      return <div>{isOnline ? 'Online' : 'Offline'}</div>;
    }
    ```
  </Accordion>

  <Accordion title="Performance Optimization">
    1. **Unnecessary Re-renders**: Components re-render when props or state haven't changed

    ```typescript
    // ❌ Problem: New function reference on every render
    function ParentComponent() {
      const [count, setCount] = useState(0);
      
      // This creates a new function reference every render
      const handleClick = () => {
        console.log('Clicked');
      };
      
      return <ChildComponent onClick={handleClick} />;
    }

    // ✅ Solution: Memoize function with useCallback
    function ParentComponent() {
      const [count, setCount] = useState(0);
      
      // Stable function reference between renders
      const handleClick = useCallback(() => {
        console.log('Clicked');
      }, []); // Only changes if dependencies change
      
      return <ChildComponent onClick={handleClick} />;
    }
    ```
  </Accordion>
</Accordions>

## Related Documents

<Cards num={3}>
  <Card title="State Management Overview" href="/docs//architecture/state-management">
    Overview of our complete state management approach including client, server, and component state.
  </Card>

  <Card title="Client State Management" href="/docs//architecture/state-management/client-state">
    Companion documentation for handling global client state with Zustand.
  </Card>

  <Card title="Server State Management" href="/docs//architecture/state-management/server-state">
    Companion documentation for handling server state with TanStack Query.
  </Card>
</Cards>

<div className="mt-8 border-t pt-8">
  <h3>External Resources</h3>

  <ul>
    <li><a href="https://react.dev/reference/react" target="_blank" rel="noopener noreferrer">React Hooks Documentation</a></li>
    <li><a href="https://react.dev/learn/you-might-not-need-an-effect" target="_blank" rel="noopener noreferrer">You Might Not Need an Effect</a></li>
    <li><a href="https://kentcdodds.com/blog/application-state-management-with-react" target="_blank" rel="noopener noreferrer">Application State Management with React by Kent C. Dodds</a></li>
  </ul>
</div>


# UTA State Management: State Integration Patterns
URL: https://dev.updatetheapp.com/docs/state-management/integration-patterns
Documentation: https://dev.updatetheapp.com/docs/state-management/integration-patterns

Common patterns for integrating server and client state in React Native applications
        
***

title: State Integration Patterns
description: Common patterns for integrating server and client state in React Native applications
-------------------------------------------------------------------------------------------------

# State Integration Patterns

## Overview

This document outlines architectural patterns for effectively integrating different types of state management in React Native applications. It focuses on the coordination between server state (TanStack Query), client state (Zustand), and component state (React), providing solutions for common state integration challenges while maintaining a clean separation of concerns.

## Purpose & Scope

* **Target Audience**: React Native developers implementing features that require coordination between multiple state management approaches
* **Problems Addressed**: Complex state interactions, synchronization challenges, and maintaining data consistency
* **Scope**: Covers integration patterns specifically for authentication flows, shopping carts, forms with drafts, real-time updates, and filter/search functionality

## Authentication Flow Pattern

A complete authentication flow demonstrates how to coordinate between different state types:

<Mermaid
  chart={`sequenceDiagram
  participant UI as Login Screen
  participant CS as Component State
  participant ZS as Zustand Store
  participant TQ as TanStack Query
  participant API as Auth API
  
  Note over CS: Form inputs (email, password)
  
  UI->>CS: User enters credentials
  UI->>API: Login request
  API-->>UI: Returns tokens & user data
  
  UI->>ZS: Save tokens to Zustand
  UI->>TQ: Update user cache
  UI->>TQ: Invalidate protected queries
  
  Note over ZS: Tokens persisted to AsyncStorage
  Note over TQ: User data cached
`}
/>

```typescript
// features/auth/state/authStore.ts (Client State)
interface AuthState {
  token: string | null;
  refreshToken: string | null;
  setTokens: (token: string, refreshToken: string) => void;
  clearTokens: () => void;
}

export const useAuthStore = create<AuthState>()(
  persist(
    (set) => ({
      token: null,
      refreshToken: null,
      setTokens: (token, refreshToken) => set({ token, refreshToken }),
      clearTokens: () => set({ token: null, refreshToken: null }),
    }),
    {
      name: 'auth-storage',
      storage: AsyncStorage,
    }
  )
);

// features/auth/api/authHooks.ts (Server State)
export const useCurrentUser = () => {
  const token = useAuthStore((state) => state.token);
  
  return useQuery({
    queryKey: ['user', 'me'],
    queryFn: userService.getCurrentUser,
    enabled: !!token,
  });
};

export const useLogin = () => {
  const queryClient = useQueryClient();
  const { setTokens } = useAuthStore();
  
  return useMutation({
    mutationFn: authService.login,
    onSuccess: (data) => {
      // Update client state with tokens
      setTokens(data.token, data.refreshToken);
      
      // Update server state cache
      queryClient.setQueryData(['user', 'me'], data.user);
      
      // Invalidate protected queries
      queryClient.invalidateQueries({ 
        predicate: (query) => query.queryKey[0] === 'protected' 
      });
    },
  });
};

export const useLogout = () => {
  const queryClient = useQueryClient();
  const { clearTokens } = useAuthStore();
  
  return useMutation({
    mutationFn: authService.logout,
    onSuccess: () => {
      // Clear client state
      clearTokens();
      
      // Clear all cached data
      queryClient.clear();
    },
  });
};

// features/auth/components/LoginScreen.tsx (Component State)
const LoginScreen = () => {
  const [email, setEmail] = useState('');
  const [password, setPassword] = useState('');
  const [rememberMe, setRememberMe] = useState(false);
  
  const loginMutation = useLogin();
  const navigation = useNavigation();
  
  const handleLogin = async () => {
    try {
      await loginMutation.mutateAsync({ 
        email, 
        password, 
        rememberMe 
      });
      navigation.navigate('Home');
    } catch (error) {
      // Handle error
    }
  };
  
  return (
    // UI implementation
  );
};
```

## Shopping Cart with Sync Pattern

Managing a shopping cart that syncs with the server:

<Mermaid
  chart={`flowchart TD
  Guest[Guest User] --> LocalCart[Local Cart - Zustand]
  LocalCart --> Login{User Logs In}
  
  Login -->|Yes| SyncProcess[Sync Process]
  Login -->|No| StayLocal[Continue Local]
  
  SyncProcess --> MergeCart[Merge Local + Server Cart]
  MergeCart --> ServerUpdate[Update Server Cart]
  ServerUpdate --> ClearLocal[Clear Local Cart]
  ClearLocal --> UseServer[Use Server Cart]
  
  LoggedIn[Logged In User] --> ServerCart[Server Cart - TanStack Query]
  ServerCart --> Updates[Direct Server Updates]
  
  style LocalCart fill:#ff9,stroke:#333,stroke-width:2px
  style ServerCart fill:#bbf,stroke:#333,stroke-width:2px
`}
/>

<Mermaid
  chart={`sequenceDiagram
  participant U as User
  participant LC as Local Cart (Zustand)
  participant SC as Server Cart (TQ)
  participant API as Cart API
  
  Note over U,LC: Guest adds items
  U->>LC: Add item to cart
  LC-->>U: Update UI count
  
  U->>U: Login
  U->>SC: Check server cart
  SC->>API: Get server cart
  API-->>SC: Return cart data
  
  SC->>LC: Get local items
  SC->>API: Sync carts
  API-->>SC: Return merged cart
  SC->>LC: Clear local cart
  
  Note over U,SC: Now using server cart
`}
/>

```typescript
// features/cart/state/cartStore.ts (Client State)
interface CartState {
  localItems: CartItem[];
  addItem: (item: CartItem) => void;
  removeItem: (itemId: string) => void;
  updateQuantity: (itemId: string, quantity: number) => void;
  clearLocalCart: () => void;
}

export const useCartStore = create<CartState>((set) => ({
  localItems: [],
  
  addItem: (item) => set((state) => {
    const existing = state.localItems.find(i => i.id === item.id);
    if (existing) {
      return {
        localItems: state.localItems.map(i =>
          i.id === item.id 
            ? { ...i, quantity: i.quantity + item.quantity }
            : i
        ),
      };
    }
    return { localItems: [...state.localItems, item] };
  }),
  
  removeItem: (itemId) => set((state) => ({
    localItems: state.localItems.filter(item => item.id !== itemId),
  })),
  
  updateQuantity: (itemId, quantity) => set((state) => ({
    localItems: state.localItems.map(item =>
      item.id === itemId ? { ...item, quantity } : item
    ),
  })),
  
  clearLocalCart: () => set({ localItems: [] }),
}));

// features/cart/api/cartHooks.ts (Server State)
export const useCart = () => {
  const { data: user } = useCurrentUser();
  
  return useQuery({
    queryKey: ['cart', user?.id],
    queryFn: () => cartService.getCart(),
    enabled: !!user,
  });
};

export const useSyncCart = () => {
  const queryClient = useQueryClient();
  const localItems = useCartStore((state) => state.localItems);
  const { clearLocalCart } = useCartStore();
  const { data: user } = useCurrentUser();
  
  const syncMutation = useMutation({
    mutationFn: (items: CartItem[]) => cartService.syncCart(items),
    onSuccess: (data) => {
      // Update server state
      queryClient.setQueryData(['cart', user?.id], data);
      
      // Clear local cart after successful sync
      clearLocalCart();
    },
  });
  
  // Sync local cart with server when user logs in
  useEffect(() => {
    if (user && localItems.length > 0) {
      syncMutation.mutate(localItems);
    }
  }, [user]);
  
  return syncMutation;
};

// features/cart/components/CartButton.tsx
const CartButton = () => {
  const { data: serverCart } = useCart();
  const localItems = useCartStore((state) => state.localItems);
  const { data: user } = useCurrentUser();
  
  // Show server cart count for logged-in users, local cart for guests
  const itemCount = user 
    ? serverCart?.items.length || 0 
    : localItems.length;
  
  return (
    <Button>
      <Text>Cart ({itemCount})</Text>
    </Button>
  );
};
```

## Form with Draft Saving Pattern

Complex form with local state and server persistence:

<Mermaid
  chart={`stateDiagram-v2
  [*] --> FormInit: Load Form
  
  FormInit --> CheckDraft: Check for draft
  FormInit --> LoadServer: Load existing post
  
  CheckDraft --> PopulateForm: Draft exists
  LoadServer --> PopulateForm: Server data exists
  PopulateForm --> Editing: User edits
  
  Editing --> AutoSave: On change
  AutoSave --> SaveDraft: After 1s delay
  SaveDraft --> Editing: Continue editing
  
  Editing --> Submit: User saves
  Submit --> ServerSave: Save to server
  ServerSave --> ClearDraft: Success
  ServerSave --> ShowError: Error
  ClearDraft --> [*]
  ShowError --> Editing
`}
/>

<Mermaid
  chart={`flowchart LR
  CS[Component State] --> |Auto-save| DS[Draft Store - Zustand]
  CS --> |Submit| API[Server API]
  API --> |Success| TQ[TanStack Query Cache]
  API --> |Success| DS
  DS --> |Delete draft| X[Clear]
  
  subgraph "Form State Flow"
      CS -.-> |Initialize| DS
      CS -.-> |Initialize| TQ
  end
  
  style CS fill:#f9f,stroke:#333,stroke-width:2px
  style DS fill:#ff9,stroke:#333,stroke-width:2px
  style TQ fill:#bbf,stroke:#333,stroke-width:2px
`}
/>

```typescript
// features/posts/state/postDraftStore.ts (Client State)
interface DraftState {
  drafts: Record<string, PostDraft>;
  saveDraft: (id: string, draft: PostDraft) => void;
  getDraft: (id: string) => PostDraft | undefined;
  deleteDraft: (id: string) => void;
}

export const useDraftStore = create<DraftState>()(
  persist(
    (set, get) => ({
      drafts: {},
      
      saveDraft: (id, draft) => set((state) => ({
        drafts: { ...state.drafts, [id]: draft },
      })),
      
      getDraft: (id) => get().drafts[id],
      
      deleteDraft: (id) => set((state) => {
        const { [id]: _, ...rest } = state.drafts;
        return { drafts: rest };
      }),
    }),
    {
      name: 'post-drafts',
      storage: AsyncStorage,
    }
  )
);

// features/posts/components/PostEditor.tsx (Component State + Integration)
const PostEditor = ({ postId }: { postId?: string }) => {
  const queryClient = useQueryClient();
  const { saveDraft, getDraft, deleteDraft } = useDraftStore();
  
  // Server state for existing post
  const { data: existingPost } = useQuery({
    queryKey: ['post', postId],
    queryFn: () => postService.getPost(postId!),
    enabled: !!postId,
  });
  
  // Component state for form
  const [title, setTitle] = useState('');
  const [content, setContent] = useState('');
  const [isDirty, setIsDirty] = useState(false);
  
  // Initialize from server data or draft
  useEffect(() => {
    if (existingPost) {
      setTitle(existingPost.title);
      setContent(existingPost.content);
    } else {
      const draft = getDraft(postId || 'new');
      if (draft) {
        setTitle(draft.title);
        setContent(draft.content);
      }
    }
  }, [existingPost, postId]);
  
  // Auto-save draft
  useEffect(() => {
    if (isDirty) {
      const timeoutId = setTimeout(() => {
        saveDraft(postId || 'new', { title, content });
        setIsDirty(false);
      }, 1000);
      
      return () => clearTimeout(timeoutId);
    }
  }, [title, content, isDirty]);
  
  // Save to server
  const saveMutation = useMutation({
    mutationFn: (data: PostData) => 
      postId ? postService.updatePost(postId, data) : postService.createPost(data),
    onSuccess: (savedPost) => {
      // Clear draft after successful save
      deleteDraft(postId || 'new');
      
      // Update cache
      queryClient.setQueryData(['post', savedPost.id], savedPost);
      queryClient.invalidateQueries({ queryKey: ['posts', 'list'] });
      
      // Navigate to saved post
      navigation.navigate('PostDetail', { postId: savedPost.id });
    },
  });
  
  const handleSave = () => {
    saveMutation.mutate({ title, content });
  };
  
  return (
    <View>
      <TextInput
        value={title}
        onChangeText={(text) => {
          setTitle(text);
          setIsDirty(true);
        }}
        placeholder="Post title"
      />
      <TextInput
        value={content}
        onChangeText={(text) => {
          setContent(text);
          setIsDirty(true);
        }}
        placeholder="Post content"
        multiline
      />
      <Button
        title="Save"
        onPress={handleSave}
        disabled={saveMutation.isLoading}
      />
    </View>
  );
};
```

## Real-time Updates with Polling Pattern

Combining server polling with optimistic client updates:

<Mermaid
  chart={`sequenceDiagram
  participant U as User
  participant UI as Chat UI
  participant PS as Pending Store (Zustand)
  participant TQ as TanStack Query
  participant API as Chat API
  
  Note over TQ,API: Polling every 5s
  
  loop Every 5 seconds
      TQ->>API: Poll messages
      API-->>TQ: Return messages
      TQ-->>UI: Update message list
  end
  
  U->>UI: Send message
  UI->>PS: Add to pending
  UI-->>U: Show pending message
  UI->>API: Send to server
  
  alt Success
      API-->>UI: Message sent
      UI->>PS: Remove from pending
      UI->>TQ: Update cache
  else Failure
      API-->>UI: Error
      UI->>PS: Mark as failed
      UI-->>U: Show retry option
  end
`}
/>

<Mermaid
  chart={`flowchart TD
  User[User Types Message] --> AddPending[Add to Pending Messages]
  AddPending --> ShowOptimistic[Show in UI Immediately]
  AddPending --> SendAPI[Send to Server]
  
  SendAPI --> Success{Success?}
  Success -->|Yes| RemovePending[Remove from Pending]
  Success -->|Yes| UpdateCache[Update TQ Cache]
  Success -->|No| MarkFailed[Mark as Failed]
  MarkFailed --> ShowRetry[Show Retry Button]
  
  Polling[TQ Polling] --> FetchNew[Fetch New Messages]
  FetchNew --> MergeMessages[Merge with Local]
  
  UpdateCache --> DisplayFinal[Display Final List]
  MergeMessages --> DisplayFinal
  
  style AddPending fill:#ff9,stroke:#333,stroke-width:2px
  style UpdateCache fill:#bbf,stroke:#333,stroke-width:2px
  style Polling fill:#bbf,stroke:#333,stroke-width:2px
`}
/>

```typescript
// features/chat/api/chatHooks.ts (Server State)
export const useMessages = (chatId: string) => {
  return useQuery({
    queryKey: ['messages', chatId],
    queryFn: () => chatService.getMessages(chatId),
    refetchInterval: 5000, // Poll every 5 seconds
  });
};

// features/chat/state/chatStore.ts (Client State)
interface ChatState {
  pendingMessages: Map<string, Message>;
  addPendingMessage: (tempId: string, message: Message) => void;
  removePendingMessage: (tempId: string) => void;
}

export const useChatStore = create<ChatState>((set) => ({
  pendingMessages: new Map(),
  
  addPendingMessage: (tempId, message) => set((state) => {
    const newMap = new Map(state.pendingMessages);
    newMap.set(tempId, message);
    return { pendingMessages: newMap };
  }),
  
  removePendingMessage: (tempId) => set((state) => {
    const newMap = new Map(state.pendingMessages);
    newMap.delete(tempId);
    return { pendingMessages: newMap };
  }),
}));

// features/chat/components/ChatScreen.tsx
const ChatScreen = ({ chatId }: { chatId: string }) => {
  const queryClient = useQueryClient();
  const { data: messages = [] } = useMessages(chatId);
  const { pendingMessages, addPendingMessage, removePendingMessage } = useChatStore();
  
  const sendMessageMutation = useMutation({
    mutationFn: chatService.sendMessage,
    onMutate: async (newMessage) => {
      const tempId = Date.now().toString();
      const optimisticMessage = {
        ...newMessage,
        id: tempId,
        status: 'pending',
        timestamp: new Date().toISOString(),
      };
      
      // Add to pending messages
      addPendingMessage(tempId, optimisticMessage);
      
      return { tempId };
    },
    onSuccess: (data, variables, context) => {
      // Remove from pending
      removePendingMessage(context.tempId);
      
      // Update cache
      queryClient.setQueryData(['messages', chatId], (old: Message[] = []) => {
        return [...old, data];
      });
    },
    onError: (error, variables, context) => {
      // Mark message as failed
      const failed = pendingMessages.get(context.tempId);
      if (failed) {
        addPendingMessage(context.tempId, { ...failed, status: 'failed' });
      }
    },
  });
  
  // Combine server messages with pending client messages
  const allMessages = [
    ...messages,
    ...Array.from(pendingMessages.values()),
  ].sort((a, b) => new Date(a.timestamp).getTime() - new Date(b.timestamp).getTime());
  
  return (
    <FlatList
      data={allMessages}
      renderItem={({ item }) => (
        <MessageItem 
          message={item} 
          isPending={pendingMessages.has(item.id)}
        />
      )}
    />
  );
};
```

## Filter and Search State Pattern

Managing complex filter state with server queries:

<Mermaid
  chart={`flowchart TD
  UI[Filter UI] --> FS[Filter Store - Zustand]
  
  FS --> |Category| QK[Query Key]
  FS --> |Price Range| QK
  FS --> |Sort By| QK
  FS --> |Search| Debounce[Debounce 500ms]
  
  Debounce --> QK
  QK --> TQ[TanStack Query]
  TQ --> API[Product API]
  API --> Cache[Query Cache]
  Cache --> Results[Product Results]
  
  subgraph "Filter State"
      FS
  end
  
  subgraph "Server State"
      TQ
      Cache
  end
  
  style FS fill:#ff9,stroke:#333,stroke-width:2px
  style TQ fill:#bbf,stroke:#333,stroke-width:2px
`}
/>

<Mermaid
  chart={`sequenceDiagram
  participant U as User
  participant FUI as Filter UI
  participant FS as Filter Store (Zustand)
  participant CS as Component State
  participant TQ as TanStack Query
  participant API as Product API
  
  U->>FUI: Change filter
  FUI->>FS: Update filter state
  
  U->>FUI: Type search query
  FUI->>CS: Update search input
  CS->>CS: Debounce 500ms
  CS->>FS: Update search state
  
  FS->>TQ: Trigger new query
  Note over TQ: Query key includes all filters
  
  TQ->>API: Fetch filtered products
  API-->>TQ: Return results
  TQ-->>FUI: Update product list
  
  Note over TQ: Keep previous data while fetching
`}
/>

```typescript
// features/products/state/productFiltersStore.ts (Client State)
interface FilterState {
  category: string | null;
  priceRange: [number, number];
  sortBy: 'price' | 'rating' | 'newest';
  searchQuery: string;
  
  setCategory: (category: string | null) => void;
  setPriceRange: (range: [number, number]) => void;
  setSortBy: (sort: 'price' | 'rating' | 'newest') => void;
  setSearchQuery: (query: string) => void;
  resetFilters: () => void;
}

export const useProductFiltersStore = create<FilterState>((set) => ({
  category: null,
  priceRange: [0, 1000],
  sortBy: 'newest',
  searchQuery: '',
  
  setCategory: (category) => set({ category }),
  setPriceRange: (priceRange) => set({ priceRange }),
  setSortBy: (sortBy) => set({ sortBy }),
  setSearchQuery: (searchQuery) => set({ searchQuery }),
  resetFilters: () => set({
    category: null,
    priceRange: [0, 1000],
    sortBy: 'newest',
    searchQuery: '',
  }),
}));

// features/products/api/productHooks.ts (Server State)
export const useFilteredProducts = () => {
  const filters = useProductFiltersStore();
  const debouncedSearch = useDebounce(filters.searchQuery, 500);
  
  return useQuery({
    queryKey: ['products', 'filtered', {
      category: filters.category,
      priceRange: filters.priceRange,
      sortBy: filters.sortBy,
      search: debouncedSearch,
    }],
    queryFn: () => productService.getProducts({
      category: filters.category,
      minPrice: filters.priceRange[0],
      maxPrice: filters.priceRange[1],
      sortBy: filters.sortBy,
      search: debouncedSearch,
    }),
    keepPreviousData: true, // Show previous results while fetching
  });
};

// features/products/components/ProductListScreen.tsx
const ProductListScreen = () => {
  const { data, isLoading, isFetching } = useFilteredProducts();
  const { searchQuery, setSearchQuery } = useProductFiltersStore();
  
  return (
    <View>
      <SearchBar
        value={searchQuery}
        onChangeText={setSearchQuery}
        placeholder="Search products..."
      />
      <FilterBar />
      {isLoading ? (
        <LoadingSpinner />
      ) : (
        <FlatList
          data={data?.products}
          renderItem={({ item }) => <ProductCard product={item} />}
          ListFooterComponent={() => isFetching ? <ActivityIndicator /> : null}
        />
      )}
    </View>
  );
};
```

## Core Components/Architecture

The integration patterns involve these key components working together:

<Mermaid
  chart={`flowchart TD
  CS[Component State\nReact useState/useReducer] --> ZS[Client State\nZustand Store]
  CS --> TQ[Server State\nTanStack Query]
  ZS --> TQ
  TQ --> API[Backend API]
  
  subgraph "State Integration Layer"
      CS
      ZS
      TQ
  end
  
  style CS fill:#f9f,stroke:#333,stroke-width:2px
  style ZS fill:#ff9,stroke:#333,stroke-width:2px
  style TQ fill:#bbf,stroke:#333,stroke-width:2px`}
/>

### Component Types

| Component         | Responsibility                                        | Common Patterns                                       |
| ----------------- | ----------------------------------------------------- | ----------------------------------------------------- |
| Component State   | UI interactions, form inputs, temporary data          | Form handling, UI element state, local interactions   |
| Zustand Store     | Application-wide client state, persistent preferences | Auth state, preferences, cart data, offline support   |
| TanStack Query    | Server data fetching, caching, synchronization        | API responses, optimistic updates, background polling |
| Integration Layer | Coordinating data flow between state types            | Event handlers, useEffect hooks, side effects         |

### Communication Patterns

* **Component → Zustand**: Direct state updates via store actions
* **Component → TanStack Query**: Query invalidation, cache manipulation
* **Zustand → TanStack Query**: Query enablement, dependent queries
* **TanStack Query → API**: Data fetching, mutations with optimistic updates

## Design Principles

### Core Architectural Principles

* **(Do ✅)** Establish clear ownership for each piece of state:
  * Server data → TanStack Query
  * UI state → Zustand or Component State
  * Form data → Component State until submission

* **(Don't ❌)** Store server data in client state unnecessarily:
  * Avoid duplication between TanStack Query cache and Zustand
  * Reference server data directly in components when possible

* **(Do ✅)** Implement optimistic updates for better UX:
  * Update UI immediately for responsive feedback
  * Sync with server in background
  * Handle failures gracefully with rollback mechanisms

### Trade-offs and Decisions

| Approach                  | Benefits                                 | Drawbacks                                        | Best For                                 |
| ------------------------- | ---------------------------------------- | ------------------------------------------------ | ---------------------------------------- |
| Minimal state integration | Simpler mental model, clearer boundaries | May lead to prop drilling, more boilerplate      | Simple screens, isolated features        |
| Tightly coupled state     | Fewer lines of code, direct coordination | Harder to debug, potential circular dependencies | Complex interactions, real-time features |
| Event-based coordination  | Loose coupling, easier to test           | More complex initial setup                       | Large teams, complex state flows         |

## Implementation Considerations

### Performance Implications

* **(Do ✅)** Use selective Zustand subscriptions to prevent unnecessary renders
* **(Consider 🤔)** Configuring TanStack Query with appropriate staleTime/gcTime settings based on data volatility
* **(Do ✅)** Apply React memoization techniques (memo, useMemo, useCallback) at integration boundaries
* **(Be Aware ❗)** Integration points between state systems are common sources of render loops

### Security Considerations

* **(Do ✅)** Never store sensitive information (tokens, PII) in unencrypted client state
* **(Do ✅)** Apply appropriate validation at both client and server boundaries
* **(Don't ❌)** Trust client state for security decisions - always validate permissions on the server

### Scalability Aspects

* **(Consider 🤔)** Breaking large state stores into smaller, feature-focused ones
* **(Do ✅)** Design query key factories for consistent cache manipulation
* **(Be Aware ❗)** Complex state interactions may require dedicated middleware or effect systems

## Common Integration Patterns

The following sections detail specific integration patterns for common scenarios. Each pattern demonstrates how to effectively coordinate between different state management systems.

## Related Documents

* [State Management Architecture](/docs//architecture/state-management)
* [Server State Management](/docs//architecture/state-management/server-state)
* [Client State Management](/docs//architecture/state-management/client-state)
* [Component State Management](/docs//architecture/state-management/component-state)
* [State Management Implementation Guide](/docs/guides/client-state-management)


# UTA API Integration: API Client Architecture
URL: https://dev.updatetheapp.com/docs/api/client-architecture
Documentation: https://dev.updatetheapp.com/docs/api/client-architecture

Established patterns for API client implementation across the project
        
***

title: API Client Architecture
description: Established patterns for API client implementation across the project
----------------------------------------------------------------------------------

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';

# API Client Architecture Guide

## Overview

This guide outlines the **established API client architecture** for our project, which we **strongly recommend** for all API implementations. It employs a public/protected pattern using separate client instances. Adopting this approach is key to ensuring type safety, clear intent, and maintainability across our services. The following sections detail this pattern and the reasons for its selection.

## Purpose & Scope

This guide serves as the primary reference for understanding and implementing the standard API client architecture within our project. Its purpose is to:

* Define the core structure for `BaseApiClient`, `PublicApiClient`, and `AuthenticatedApiClient`.
* Establish the standard pattern for how domain-specific API services should be created and used.
* Explain the rationale behind these architectural choices to ensure consistency, maintainability, and type safety.

This document is intended for all developers involved in creating or interacting with API services. It covers the foundational client setup; more specialized topics like detailed authentication flows, request queueing, and multi-API configurations are detailed in subsequent related documents.

## Prerequisites

To fully grasp the concepts presented in this guide, we recommend a basic understanding of:

* **TypeScript**: Familiarity with classes, inheritance, and interfaces.
* **HTTP Clients/Axios**: Basic knowledge of how HTTP clients like Axios operate, including concepts like request/response interceptors (though interceptors are detailed further in linked documents).
* **API Design Fundamentals**: General understanding of RESTful APIs and common authentication patterns.

## Why This Pattern?

We evaluated several approaches before choosing this architecture:

### Alternative Patterns Considered

1. **Skip Auth Flag Pattern** (Not Recommended)
   ```typescript
   // Requires runtime flags
   apiClient.post('/auth/login', data, { skipAuth: true })
   ```
   * ❌ Runtime complexity
   * ❌ Easy to forget flags
   * ❌ Not type-safe

2. **URL Pattern Configuration** (Not Recommended)
   ```typescript
   // Maintains list of public endpoints
   const PUBLIC_ENDPOINTS = ['/auth/login', '/auth/register'];
   ```
   * ❌ Centralized configuration to maintain
   * ❌ Can become outdated
   * ❌ Hidden behavior

3. **Method Prefix Convention** (Not Recommended)
   ```typescript
   // Uses naming to indicate auth
   api.publicGet('/products');
   api.get('/protected-data');
   ```
   * ❌ Still mixing concerns
   * ❌ Naming conventions can be inconsistent

### Our Chosen Pattern: Type-Safe Domain API

We chose the **inheritance-based public/protected pattern** because it provides:

1. **Clear Separation**: Two distinct client classes - `PublicApiClient` and `AuthenticatedApiClient`
2. **Explicit Intent**: API structure clearly shows which endpoints are public vs authenticated
3. **Type Safety**: TypeScript ensures proper usage without runtime checks
4. **Better Organization**: Domain APIs are organized with `public` and `protected` namespaces
5. **No Magic Flags**: No need for `skipAuth` or similar runtime configurations
6. **Inheritance Benefits**: Authenticated client extends public client, avoiding duplication
7. **Scalability**: Easy to add new API clients for different services

## Our Standard API Client Architecture

### Core API Client Classes

Our core API client architecture is built upon three key classes, typically organized into separate files as shown below:

<Tabs items={["base.ts", "public.ts", "authenticated.ts"]}>
  <Tab>
    The `BaseApiClient` provides foundational properties and methods common to all API clients.

    ```typescript
    // core/shared/api/base.ts
    import axios, { AxiosInstance, AxiosRequestConfig, AxiosError, AxiosResponse } from 'axios';
    // Conceptual imports for error classes, actual imports would depend on project structure
    // import { ApiResponseError, NoInternetConnectionError, ExtendableError } from '@/core/shared/errors'; 

    export abstract class BaseApiClient {
      protected client: AxiosInstance;

      constructor(config?: AxiosRequestConfig) {
        this.client = axios.create({
          baseURL: process.env.API_BASE_URL, // Standard base URL from environment
          timeout: 30000, // Default timeout
          ...config, // Allow overrides and additional Axios config
        });
      }

      /**
       * Handles successful responses, extracting the data.
       * @param response The AxiosResponse object.
       * @returns The data from the response.
       */
      protected handleResponse<T>(response: AxiosResponse<T>): T {
        return response.data;
      }

      /**
       * Handles errors encountered during API requests.
       * This method transforms AxiosErrors into custom application errors 
       * consistent with the error handling architecture.
       * @param error The AxiosError object.
       * @throws {ApiResponseError | NoInternetConnectionError | ExtendableError} Throws a custom error.
       */
      protected handleError(error: AxiosError): never {
        if (error.response) {
          // Error with a response from the server (e.g., 4xx, 5xx)
          throw new ApiResponseError( // See "Error Handling Architecture" guide
            error.message,
            error.response.status,
            error.config?.url || 'unknown endpoint',
            error.response.data
          );
        } else if (error.request) {
          // Request was made but no response received (e.g., network error)
          throw new NoInternetConnectionError( // See "Error Handling Architecture" guide
            `Network error or no response for request to ${error.config?.url}`
          );
        } else {
          // Something else happened in setting up the request
          throw new ExtendableError(error.message, 'REQUEST_SETUP_ERROR'); // Base error, see "Error Handling Architecture" guide
        }
      }

      async get<T>(url: string, config?: AxiosRequestConfig): Promise<T> {
        try {
          const response = await this.client.get<T>(url, config);
          return this.handleResponse(response);
        } catch (error) {
          this.handleError(error as AxiosError);
        }
      }

      async post<T>(url: string, data?: any, config?: AxiosRequestConfig): Promise<T> {
        try {
          const response = await this.client.post<T>(url, data, config);
          return this.handleResponse(response);
        } catch (error) {
          this.handleError(error as AxiosError);
        }
      }

      async put<T>(url: string, data?: any, config?: AxiosRequestConfig): Promise<T> {
        try {
          const response = await this.client.put<T>(url, data, config);
          return this.handleResponse(response);
        } catch (error) {
          this.handleError(error as AxiosError);
        }
      }

      async delete<T>(url: string, config?: AxiosRequestConfig): Promise<T> {
        try {
          const response = await this.client.delete<T>(url, config);
          return this.handleResponse(response);
        } catch (error) {
          this.handleError(error as AxiosError);
        }
      }
    }
    ```
  </Tab>

  <Tab>
    The `PublicApiClient` extends `BaseApiClient` and is used for API endpoints that do not require authentication.

    ```typescript
    // core/shared/api/public.ts
    // Assuming BaseApiClient is imported if in a separate file:
    // import { BaseApiClient } from './base'; 
    // import { AxiosRequestConfig } from 'axios'; // Only if needed directly

    export class PublicApiClient extends BaseApiClient {
      // No additional authentication logic is needed for public endpoints.
      // Inherits constructor and HTTP methods from BaseApiClient.
      constructor(config?: AxiosRequestConfig) {
        super(config);
      }
    }
    ```
  </Tab>

  <Tab>
    The `AuthenticatedApiClient` extends `BaseApiClient` and incorporates interceptors for handling authentication (e.g., attaching tokens and managing token refresh).

    ```typescript
    // core/shared/api/authenticated.ts
    // Assuming BaseApiClient and tokenService are imported if in separate files:
    // import { BaseApiClient } from './base';
    // import { tokenService } from '@/core/domains/auth/tokenService'; // Actual path needs verification
    import { AxiosRequestConfig, AxiosError } from 'axios'; // AxiosError is used here
    // Note: tokenService would need to be imported or injected for this example to be complete.
    // For this example, we assume tokenService is globally available or correctly imported elsewhere.

    export class AuthenticatedApiClient extends BaseApiClient {
      constructor(config?: AxiosRequestConfig) {
        super(config);
        this.setupAuthInterceptors();
      }

      private setupAuthInterceptors() {
        // Request interceptor
        this.client.interceptors.request.use(
          async (config) => {
            const token = await tokenService.getAccessToken(); // tokenService would be imported/injected
            if (token) {
              config.headers = config.headers || {};
              config.headers.Authorization = `Bearer ${token}`;
            }
            return config;
          }
        );

        // Response interceptor for token refresh
        this.client.interceptors.response.use(
          (response) => response,
          async (error) => this.handleAuthError(error as AxiosError) // Ensure error is typed
        );
      }

      private async handleAuthError(error: AxiosError): Promise<any> {
        // This is a placeholder for handling 401 errors and token refresh.
        // The basic token refresh logic is detailed in the [Authentication Architecture](/docs/api/authentication) document.
        // For a comprehensive solution including request queueing for concurrent requests, 
        // refer to the [API Client with Request Queueing](/docs/api/request-queueing) document,
        // which enhances this AuthenticatedApiClient.
        return Promise.reject(error); // Default behavior
      }
    }
    ```
  </Tab>
</Tabs>

To make these API client classes usable, singleton instances are typically created and exported from a central module. This pattern ensures consistent client configuration and accessibility throughout the application. The example below shows how this might be structured:

```typescript
// Example: core/shared/api/client.ts (Conceptual instantiation file)
// import { PublicApiClient } from './public'; // Assuming separate files as shown in Tabs
// import { AuthenticatedApiClient } from './authenticated'; // Assuming separate files as shown in Tabs
// import { AxiosRequestConfig } from 'axios';
// import { tokenService } from '@/core/domains/auth/tokenService'; // Needed for BearerTokenStrategy if used

// Placeholder for actual BaseApiClient, PublicApiClient, AuthenticatedApiClient definitions if not using imports from above tabs
// For the sake of this isolated example, assume they are defined or imported.

const commonConfig: AxiosRequestConfig = {
  baseURL: process.env.API_BASE_URL, // Make sure this env variable is set up
  // other common configurations can be added here
};

export const publicApi = new PublicApiClient(commonConfig);
export const authenticatedApi = new AuthenticatedApiClient(commonConfig);
```

## Domain API Implementation Pattern

For consistency and to leverage the benefits of the core API clients, all domain APIs **should adhere** to the following pattern. This structure promotes clear separation of public and protected endpoints and ensures type-safe interactions:

```typescript
// core/domains/[domain]/api.ts
import { publicApi, authenticatedApi } from '@/core/shared/api/client';
import type { DomainTypes } from './types';

class DomainApi {
  // Public endpoints - no authentication required
  public readonly public = {
    methodName: async (params): Promise<ReturnType> => {
      const { data } = await publicApi.get('/endpoint', { params });
      return data;
    },
  };

  // Protected endpoints - authentication required
  public readonly protected = {
    methodName: async (params): Promise<ReturnType> => {
      const { data } = await authenticatedApi.post('/endpoint', params);
      return data;
    },
  };
}

export const domainApi = new DomainApi();
```

## Example Implementations

### Product Domain API

```typescript
// core/domains/products/api.ts
import { publicApi, authenticatedApi } from '@/core/shared/api/client';
import type { Product, CreateProductDto, UpdateProductDto } from './types';

class ProductApi {
  public readonly public = {
    // Anyone can view products
    getAll: async (): Promise<Product[]> => {
      return await publicApi.get('/products');
    },

    getById: async (id: string): Promise<Product> => {
      return await publicApi.get(`/products/${id}`);
    },

    search: async (query: string): Promise<Product[]> => {
      return await publicApi.get('/products/search', {
        params: { q: query }
      });
    },
  };

  public readonly protected = {
    // Only authenticated users can manage products
    create: async (product: CreateProductDto): Promise<Product> => {
      return await authenticatedApi.post('/products', product);
    },

    update: async (id: string, updates: UpdateProductDto): Promise<Product> => {
      return await authenticatedApi.put(`/products/${id}`, updates);
    },

    delete: async (id: string): Promise<void> => {
      await authenticatedApi.delete(`/products/${id}`);
    },

    getUserProducts: async (): Promise<Product[]> => {
      return await authenticatedApi.get('/users/me/products');
    },
  };
}

export const productApi = new ProductApi();
```

### User Domain API

```typescript
// core/domains/users/api.ts
import { publicApi, authenticatedApi } from '@/core/shared/api/client';
import type { User, UserProfile, UpdateProfileDto } from './types';

class UserApi {
  public readonly public = {
    // Public user endpoints
    getPublicProfile: async (userId: string): Promise<User> => {
      return await publicApi.get(`/users/${userId}/public`);
    },

    searchUsers: async (query: string): Promise<User[]> => {
      return await publicApi.get('/users/search', {
        params: { q: query }
      });
    },
  };

  public readonly protected = {
    // Protected user endpoints
    getCurrentUser: async (): Promise<UserProfile> => {
      return await authenticatedApi.get('/users/me');
    },

    updateProfile: async (updates: UpdateProfileDto): Promise<UserProfile> => {
      return await authenticatedApi.patch('/users/me', updates);
    },

    deleteAccount: async (): Promise<void> => {
      await authenticatedApi.delete('/users/me');
    },

    getPrivateData: async (): Promise<any> => {
      return await authenticatedApi.get('/users/me/private');
    },
  };
}

export const userApi = new UserApi();
```

## Hook Implementation Pattern

Hooks must use the appropriate API methods:

```typescript
// core/domains/products/hooks.ts
import { useQuery, useMutation } from '@tanstack/react-query';
import { productApi } from './api';

// Public data - anyone can access
export function useProducts() {
  return useQuery({
    queryKey: ['products'],
    queryFn: productApi.public.getAll,
  });
}

export function useProduct(id: string) {
  return useQuery({
    queryKey: ['products', id],
    queryFn: () => productApi.public.getById(id),
    enabled: !!id,
  });
}

// Protected actions - require authentication
export function useCreateProduct() {
  return useMutation({
    mutationFn: productApi.protected.create,
  });
}

export function useUpdateProduct() {
  return useMutation({
    mutationFn: ({ id, updates }) => 
      productApi.protected.update(id, updates),
  });
}
```

## Do's and Don'ts

### Do's ✅

```typescript
// Correct: Use the public/protected pattern
class OrderApi {
  public readonly public = {
    getOrderStatus: async (orderId: string) => {
      return await publicApi.get(`/orders/${orderId}/status`);
    },
  };
  
  public readonly protected = {
    createOrder: async (orderData) => {
      return await authenticatedApi.post('/orders', orderData);
    },
  };
}
```

### Don'ts ❌

```typescript
// Wrong: Direct API client usage
export const orderApi = {
  getOrders: () => apiClient.get('/orders'),
  createOrder: (data) => apiClient.post('/orders', data),
};

// Wrong: Using skipAuth flags
export const orderApi = {
  getPublicData: () => apiClient.get('/public', { skipAuth: true }),
  getPrivateData: () => apiClient.get('/private'),
};

// Wrong: Mixed patterns
export const orderApi = {
  public: {
    getOrders: () => apiClient.get('/orders', { skipAuth: true }),
  },
  createOrder: (data) => apiClient.post('/orders', data),
};
```

## Error Handling

Each API client handles errors appropriately:

```typescript
// core/shared/api/errors.ts
export class ApiError extends Error {
  constructor(
    message: string,
    public status: number,
    public code?: string,
    public data?: any
  ) {
    super(message);
    this.name = 'ApiError';
  }
}

// Domain-specific error handling
class ProductApi {
  public readonly protected = {
    create: async (product: CreateProductDto): Promise<Product> => {
      try {
        return await authenticatedApi.post('/products', product);
      } catch (error) {
        if (error.response?.status === 409) {
          throw new ApiError(
            'Product already exists',
            409,
            'DUPLICATE_PRODUCT'
          );
        }
        throw error;
      }
    },
  };
}
```

## Testing API Implementations

```typescript
// core/domains/products/__tests__/api.test.ts
import { productApi } from '../api';
import { publicApi, authenticatedApi } from '@/core/shared/api/client';

jest.mock('@/core/shared/api/client');

describe('Product API', () => {
  it('should use public client for public endpoints', async () => {
    const mockProducts = [{ id: '1', name: 'Product 1' }];
    (publicApi.get as jest.Mock).mockResolvedValue({ data: mockProducts });

    const result = await productApi.public.getAll();
    
    expect(publicApi.get).toHaveBeenCalledWith('/products');
    expect(result).toEqual(mockProducts);
  });

  it('should use authenticated client for protected endpoints', async () => {
    const newProduct = { name: 'New Product' };
    const createdProduct = { id: '1', ...newProduct };
    (authenticatedApi.post as jest.Mock).mockResolvedValue({ data: createdProduct });

    const result = await productApi.protected.create(newProduct);
    
    expect(authenticatedApi.post).toHaveBeenCalledWith('/products', newProduct);
    expect(result).toEqual(createdProduct);
  });
});
```

## Migration Guide

If you have existing code using different patterns, follow these steps:

1. Create domain API class with public/protected structure
2. Move public endpoints to the `public` object
3. Move authenticated endpoints to the `protected` object
4. Update all imports to use the new structure
5. Remove any `skipAuth` flags or similar workarounds
6. Update tests to mock the correct client

## Enforcement

* **Code Reviews**: Reject any PRs not following this pattern
* **Linting**: ESLint rules to prevent direct API client imports in domains
* **Architecture Tests**: Automated tests to verify pattern compliance

```javascript
// .eslintrc.js
module.exports = {
  rules: {
    'no-restricted-imports': [
      'error',
      {
        patterns: [
          {
            group: ['@/core/shared/api/client'],
            message: 'Use publicApi and authenticatedApi exports instead',
          },
        ],
      },
    ],
  },
};
```

## Scalability for Multiple APIs

This pattern scales excellently when your app needs multiple API services:

### Different Authentication Strategies

```typescript
// core/shared/api/auth-strategies.ts
export interface AuthStrategy {
  applyAuth(config: AxiosRequestConfig): Promise<AxiosRequestConfig>;
  handleAuthError(error: AxiosError): Promise<any>;
}

export class BearerTokenStrategy implements AuthStrategy {
  async applyAuth(config: AxiosRequestConfig) {
    const token = await tokenService.getAccessToken();
    if (token) {
      config.headers.Authorization = `Bearer ${token}`;
    }
    return config;
  }
}

export class ApiKeyStrategy implements AuthStrategy {
  constructor(private apiKey: string) {}

  async applyAuth(config: AxiosRequestConfig) {
    config.headers['X-API-Key'] = this.apiKey;
    return config;
  }
}
```

### Multiple Service Clients

> **Note:** This section provides a brief overview of how this architecture supports multiple API services. For a comprehensive treatment of this topic, including detailed implementation strategies, configuration approaches for different environments, and advanced authentication strategies, please refer to the [Scalable Multi-API Architecture](/docs/api/multi-api-setup) document.

```typescript
// core/shared/api/clients.ts
// Main API with bearer token auth
export const mainApi = {
  public: new PublicApiClient({
    baseURL: process.env.MAIN_API_URL,
  }),
  authenticated: new AuthenticatedApiClient(
    { baseURL: process.env.MAIN_API_URL },
    new BearerTokenStrategy(tokenService)
  ),
};

// Payment API with API key auth
export const paymentApi = new AuthenticatedApiClient(
  { baseURL: process.env.PAYMENT_API_URL },
  new ApiKeyStrategy(process.env.PAYMENT_API_KEY)
);

// Analytics API with OAuth2
export const analyticsApi = new AuthenticatedApiClient(
  { baseURL: process.env.ANALYTICS_API_URL },
  new OAuth2Strategy(oauthService)
);
```

For detailed multi-API implementation, see [Scalable Multi-API Architecture](/docs/api/multi-api-setup).

## Summary

Adhering to this API client pattern is **highly encouraged** for all API implementations in our project, as it provides significant benefits:

1. **Clear Intent**: Obvious which endpoints require authentication
2. **Type Safety**: Full TypeScript support
3. **Consistency**: Same pattern across all domains
4. **Maintainability**: Easy to add new endpoints
5. **Security**: Reduced risk of accidental auth bypasses
6. **Developer Experience**: Better IntelliSense and discoverability
7. **Scalability**: Supports multiple API services with different auth strategies

By consistently applying this established standard, we ensure our API integrations are robust, maintainable, and easier for all team members to work with.

## Related Documents

* [Authentication Architecture](/docs/api/authentication)
* [Domain Architecture Guide](/docs/architecture/domain-architecture)
* [API Client with Request Queueing](/docs/api/request-queueing)
* [Scalable Multi-API Architecture](/docs/api/multi-api-setup)
* [Core Architecture Reference](/docs/architecture/core-architecture)


# UTA API Integration: Authentication Architecture
URL: https://dev.updatetheapp.com/docs/api/authentication
Documentation: https://dev.updatetheapp.com/docs/api/authentication

Comprehensive guide to authentication implementation, token management, and session handling.
        
***

title: Authentication Architecture
description: Comprehensive guide to authentication implementation, token management, and session handling.
----------------------------------------------------------------------------------------------------------

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';

# Authentication Architecture

## Overview

This document outlines our authentication architecture, covering token management, session handling, and security best practices. It provides implementation details for authentication flows, automatic token refresh, and secure storage patterns.

## Purpose & Scope

This guide covers:

* Authentication flow implementation
* Token storage and management
* Session lifecycle handling
* Security considerations
* Integration with API client

## Prerequisites

To get the most out of this document, we recommend you first understand these key areas and review the related guides:

* **API Client Architecture**: Familiarity with the concepts and patterns outlined in the [API Client Architecture Guide](/docs/api/client-architecture) is essential, as this document builds upon the `BaseApiClient`, `PublicApiClient`, and `AuthenticatedApiClient` structures defined therein.

## Architecture Overview

<Mermaid
  chart={`
flowchart TD
subgraph Client[React Native App]
  LoginScreen[Login Screen]
  AuthDomain[Auth Domain]
  TokenService[Token Service]
  ApiClient[API Client]
  SecureStorage[Secure Storage]
end

subgraph Server[Backend Services]
  AuthAPI[Auth API]
  ProtectedAPI[Protected APIs]
end

LoginScreen --> AuthDomain
AuthDomain --> TokenService
TokenService --> SecureStorage
AuthDomain --> AuthAPI
ApiClient --> TokenService
ApiClient --> ProtectedAPI

AuthAPI -.->|tokens| AuthDomain
TokenService -.->|intercept| ApiClient
`}
/>

## Authentication Domain Structure

```
core/domains/auth/
├── api.ts              # Auth API endpoints
├── types.ts            # Auth types and interfaces
├── hooks.ts            # Auth hooks (useLogin, useLogout)
├── store.ts            # Auth state management
├── tokenService.ts     # Token management service
├── events.ts           # Auth events (sessionExpired)
├── constants.ts        # Auth constants
└── index.ts            # Public exports
```

## Core Components

### 1. Token Service

Manages token storage and retrieval without importing state:

```typescript
// core/domains/auth/tokenService.ts
import { storage } from '@/core/shared/utils/storage';

export interface TokenService {
  getAccessToken: () => Promise<string | null>;
  getRefreshToken: () => Promise<string | null>;
  setTokens: (access: string, refresh: string) => Promise<void>;
  clearTokens: () => Promise<void>;
  isAuthenticated: () => Promise<boolean>;
}

export const tokenService: TokenService = {
  async getAccessToken() {
    return storage.getSecureItem('accessToken');
  },

  async getRefreshToken() {
    return storage.getSecureItem('refreshToken');
  },

  async setTokens(access: string, refresh: string) {
    await Promise.all([
      storage.setSecureItem('accessToken', access),
      storage.setSecureItem('refreshToken', refresh),
    ]);
  },

  async clearTokens() {
    await Promise.all([
      storage.removeItem('accessToken'),
      storage.removeItem('refreshToken'),
    ]);
  },

  async isAuthenticated() {
    const token = await this.getAccessToken();
    return !!token;
  },
};
```

### 2. Secure Storage Implementation

Platform-specific secure storage:

```typescript
// core/shared/utils/storage.ts
import AsyncStorage from '@react-native-async-storage/async-storage';
import * as Keychain from 'react-native-keychain';
import { Platform } from 'react-native';

class SecureStorage {
  private readonly KEYCHAIN_SERVICE = 'com.yourapp.secure';

  async setSecureItem(key: string, value: string): Promise<void> {
    if (Platform.OS === 'ios') {
      await Keychain.setInternetCredentials(
        this.KEYCHAIN_SERVICE,
        key,
        value
      );
    } else {
      // Android: Use encrypted shared preferences
      await AsyncStorage.setItem(`@secure_${key}`, value);
    }
  }

  async getSecureItem(key: string): Promise<string | null> {
    if (Platform.OS === 'ios') {
      const credentials = await Keychain.getInternetCredentials(
        this.KEYCHAIN_SERVICE
      );
      return credentials ? credentials.password : null;
    } else {
      return AsyncStorage.getItem(`@secure_${key}`);
    }
  }

  async removeItem(key: string): Promise<void> {
    if (Platform.OS === 'ios') {
      await Keychain.resetInternetCredentials(this.KEYCHAIN_SERVICE);
    } else {
      await AsyncStorage.removeItem(`@secure_${key}`);
    }
  }
}

export const storage = new SecureStorage();
```

### 3. API Client Architecture

> **Note:** This section builds upon the core API client structure defined in the [API Client Architecture Guide](/docs/api/client-architecture). We do not redefine the base patterns here, but rather show how they are extended to support authentication specifically. Please refer to the API Client Architecture Guide for the complete definition of the foundational `BaseApiClient` class and overall API client patterns.

We use a type-safe, inheritance-based approach for handling public vs authenticated endpoints. The core classes are `BaseApiClient`, `PublicApiClient`, and `AuthenticatedApiClient`. Below, we illustrate how `PublicApiClient` and `AuthenticatedApiClient` extend the foundational `BaseApiClient`.

<Tabs items={["PublicApiClient Extension", "AuthenticatedApiClient Extension"]}>
  <Tab>
    The `PublicApiClient` extends `BaseApiClient` and is used for API endpoints that do not require authentication. It typically does not add further logic beyond what `BaseApiClient` provides for public access.

    ```typescript
    // Conceptual path: core/shared/api/public.ts
    // import { BaseApiClient } from './base'; // Assumes BaseApiClient is imported
    // import { AxiosRequestConfig, AxiosError, AxiosResponse } from 'axios';

    export class PublicApiClient extends BaseApiClient {
      constructor(config?: AxiosRequestConfig) {
        super(config);
        // No specialized interceptors needed for public client typically.
      }

      // Inherits get, post, put, delete methods from BaseApiClient.
      // These methods in BaseApiClient already include try/catch and use handleError.
      // If PublicApiClient needed to override or add specific logic, it would do so here.
      // For example, it could override handleError if public errors needed different treatment.
    }
    ```
  </Tab>

  <Tab>
    The `AuthenticatedApiClient` extends `BaseApiClient` and incorporates interceptors for handling authentication (e.g., attaching tokens and managing token refresh).

    ```typescript
    // Conceptual path: core/shared/api/authenticated.ts
    // import { BaseApiClient } from './base';
    // import { tokenService } from '@/core/domains/auth/tokenService';
    // import { authEvents } from '@/core/domains/auth/events';
    // import { PublicApiClient } from './public'; // For refreshAccessToken if done here
    import { AxiosRequestConfig, AxiosError } from 'axios'; // AxiosError is used

    export class AuthenticatedApiClient extends BaseApiClient {
      private isRefreshing = false;
      private refreshPromise: Promise<string> | null = null;

      constructor(config?: AxiosRequestConfig) {
        super(config);
        this.setupAuthInterceptors();
      }

      private setupAuthInterceptors() {
        // Request interceptor - add token
        this.client.interceptors.request.use(
          async (config) => {
            const token = await tokenService.getAccessToken();
            if (token) {
              config.headers = config.headers || {};
              config.headers.Authorization = `Bearer ${token}`;
            }
            return config;
          },
          (error) => Promise.reject(error)
        );

        // Response interceptor - handle token refresh
        this.client.interceptors.response.use(
          (response) => response,
          async (error) => this.handleAuthError(error as AxiosError)
        );
      }

      /**
       * Handles authentication errors (401) and manages the token refresh process.
       * When multiple requests fail due to token expiry, this client needs to incorporate
       * a robust request queueing mechanism.
       * 
       * Note: This is a simplified implementation focusing only on the authentication aspects.
       * 
       * For a complete implementation including request queueing during token refresh, see the
       * [API Client with Request Queueing](/docs/api/request-queueing) document, which provides
       * the full `AuthenticatedApiClientWithQueue` implementation. That implementation includes
       * properly handling concurrent requests during token refresh by adding failed requests
       * to a queue and processing them after the refresh completes.
       */
      private async handleAuthError(error: AxiosError): Promise<any> {
        const originalRequest = error.config as AxiosRequestConfig & { _retry?: boolean };

        if (!originalRequest || error.response?.status !== 401 || originalRequest._retry) {
          return Promise.reject(error);
        }

        originalRequest._retry = true;

        if (this.isRefreshing) {
          // Simplified: await existing promise. Full queueing details are in the "API Client with Request Queueing" guide.
          try {
            const token = await this.refreshPromise;
            if (token) {
              originalRequest.headers!.Authorization = `Bearer ${token}`;
              return this.client(originalRequest);
            }
            return Promise.reject(error);
          } catch (refreshError_1) {
            return Promise.reject(refreshError_1);
          }
        }

        this.isRefreshing = true;
        this.refreshPromise = this.refreshAccessToken();

        try {
          const newToken = await this.refreshPromise;
          originalRequest.headers!.Authorization = `Bearer ${newToken}`;
          return this.client(originalRequest);
        } catch (refreshError_2) {
          // The full queueing logic (detailed in the "API Client with Request Queueing" guide) would reject all queued requests here.
          return Promise.reject(refreshError_2);
        } finally {
          this.isRefreshing = false;
          this.refreshPromise = null;
        }
      }

      private async refreshAccessToken(): Promise<string> {
        try {
          const refreshToken = await tokenService.getRefreshToken();
          if (!refreshToken) {
            throw new Error('No refresh token available');
          }
          // In a real app, use the instantiated publicApi or a clean axios instance.
          const tempPublicClient = new PublicApiClient(this.client.defaults);
          const { data } = await tempPublicClient.post<any>('/auth/refresh', { // Using <any> for TokenResponse placeholder
            refreshToken,
          });

          await tokenService.setTokens(data.accessToken, data.refreshToken);
          authEvents.emit('auth:tokenRefreshed', { accessToken: data.accessToken });
          
          return data.accessToken;
        } catch (error) {
          await tokenService.clearTokens();
          authEvents.emit('auth:sessionExpired');
          throw error;
        } finally {
          this.isRefreshing = false;
          this.refreshPromise = null;
        }
      }
    }
    ```
  </Tab>
</Tabs>

To make these API client classes usable throughout the application, singleton instances are typically created and exported. This is often managed in a central API client configuration module. The following example illustrates this pattern:

```typescript
// Example: core/shared/api/client.ts (Conceptual instantiation file)
// import { PublicApiClient } from './public'; 
// import { AuthenticatedApiClient } from './authenticated';
// import { AxiosRequestConfig } from 'axios';

// Assuming PublicApiClient and AuthenticatedApiClient are defined as in the tabs above.
const commonConfig: AxiosRequestConfig = {
  baseURL: process.env.API_BASE_URL, // Ensure this env variable is set up
  // other common configurations can be added here
};

export const publicApi = new PublicApiClient(commonConfig);
export const authenticatedApi = new AuthenticatedApiClient(commonConfig);
```

This approach is the **established standard** for all API implementations in our project, as it provides several key benefits:

* Clear separation between public and authenticated endpoints
* Type safety without runtime flags
* Scalability for multiple API services
* Consistent error handling
* Automatic token refresh management

For detailed implementation patterns and multiple API support, see the [API Client Architecture Guide](/docs/api/client-architecture).

### 4. Auth API Service

Authentication endpoints following the mandatory public/protected pattern:

```typescript
// core/domains/auth/api.ts
import { publicApi, authenticatedApi } from '@/core/shared/api/client';
import type {
  LoginRequest,
  LoginResponse,
  RegisterRequest,
  RegisterResponse,
  UserProfile,
} from './types';

class AuthApi {
  // Public endpoints - no authentication required
  public readonly public = {
    login: async (credentials: LoginRequest): Promise<LoginResponse> => {
      const { data } = await publicApi.post('/auth/login', credentials);
      return data;
    },

    register: async (userData: RegisterRequest): Promise<RegisterResponse> => {
      const { data } = await publicApi.post('/auth/register', userData);
      return data;
    },

    forgotPassword: async (email: string): Promise<void> => {
      await publicApi.post('/auth/forgot-password', { email });
    },

    resetPassword: async (token: string, password: string): Promise<void> => {
      await publicApi.post('/auth/reset-password', { token, password });
    },

    verifyEmail: async (token: string): Promise<void> => {
      await publicApi.post('/auth/verify-email', { token });
    },
  };

  // Protected endpoints - require authentication
  public readonly protected = {
    getCurrentUser: async (): Promise<UserProfile> => {
      const { data } = await authenticatedApi.get('/auth/me');
      return data;
    },

    updateProfile: async (updates: Partial<UserProfile>): Promise<UserProfile> => {
      const { data } = await authenticatedApi.patch('/auth/profile', updates);
      return data;
    },

    changePassword: async (oldPassword: string, newPassword: string): Promise<void> => {
      await authenticatedApi.post('/auth/change-password', {
        oldPassword,
        newPassword,
      });
    },

    logout: async (): Promise<void> => {
      await authenticatedApi.post('/auth/logout');
    },

    deleteAccount: async (password: string): Promise<void> => {
      await authenticatedApi.delete('/auth/account', {
        data: { password },
      });
    },
  };
}

export const authApi = new AuthApi();
```

Adhering to this structure for all domain APIs is **strongly recommended** to ensure consistency and leverage the following benefits:

* Explicit separation of public vs authenticated endpoints
* Type-safe API calls
* Consistent patterns across all domains
* Better IntelliSense support

### 5. Auth Hooks

React Query hooks following the enforced API pattern:

```typescript
// core/domains/auth/hooks.ts
import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query';
import { authApi } from './api';
import { authStore } from './store';
import { tokenService } from './tokenService';
import { authEvents } from './events';
import { authQueryKeys } from './queryKeys';

export function useLogin() {
  const queryClient = useQueryClient();

  return useMutation({
    mutationFn: authApi.public.login,
    onSuccess: async (data) => {
      // Store tokens
      await tokenService.setTokens(
        data.tokens.access,
        data.tokens.refresh
      );

      // Update auth store
      authStore.getState().setUser(data.user);
      authStore.getState().setAuthenticated(true);

      // Set user data in cache
      queryClient.setQueryData(
        authQueryKeys.currentUser(),
        data.user
      );

      // Emit login event
      authEvents.emit('auth:login', {
        userId: data.user.id,
        token: data.tokens.access,
      });
    },
    onError: (error) => {
      console.error('Login failed:', error);
    },
  });
}

export function useRegister() {
  return useMutation({
    mutationFn: authApi.public.register,
    onSuccess: (data) => {
      // Handle registration success
      console.log('Registration successful', data);
    },
  });
}

export function useLogout() {
  const queryClient = useQueryClient();

  return useMutation({
    mutationFn: authApi.protected.logout,
    onSuccess: async () => {
      // Clear tokens
      await tokenService.clearTokens();

      // Clear auth store
      authStore.getState().clearAuth();

      // Clear all cached data
      queryClient.clear();

      // Emit logout event
      authEvents.emit('auth:logout');
    },
  });
}

export function useCurrentUser() {
  return useQuery({
    queryKey: authQueryKeys.currentUser(),
    queryFn: authApi.protected.getCurrentUser,
    staleTime: 5 * 60 * 1000, // 5 minutes
  });
}

export function useUpdateProfile() {
  const queryClient = useQueryClient();

  return useMutation({
    mutationFn: authApi.protected.updateProfile,
    onSuccess: (updatedUser) => {
      // Update cached user data
      queryClient.setQueryData(
        authQueryKeys.currentUser(),
        updatedUser
      );
      
      // Update auth store
      authStore.getState().setUser(updatedUser);
      
      // Emit user updated event
      authEvents.emit('auth:userUpdated', { user: updatedUser });
    },
  });
}

export function useChangePassword() {
  return useMutation({
    mutationFn: ({ oldPassword, newPassword }: {
      oldPassword: string;
      newPassword: string;
    }) => authApi.protected.changePassword(oldPassword, newPassword),
    onSuccess: () => {
      // Password changed successfully
      console.log('Password changed successfully');
    },
  });
}

export function useAuthStatus() {
  return useQuery({
    queryKey: authQueryKeys.status(),
    queryFn: async () => {
      const isAuthenticated = await tokenService.isAuthenticated();
      if (isAuthenticated) {
        const user = await authApi.protected.getCurrentUser();
        return { isAuthenticated: true, user };
      }
      return { isAuthenticated: false, user: null };
    },
    staleTime: Infinity, // Only refetch manually
  });
}
```

### 6. Auth State Store

Client-side auth state management:

```typescript
// core/domains/auth/store.ts
import { create } from 'zustand';
import { persist } from 'zustand/middleware';
import type { UserProfile } from './types';

interface AuthState {
  user: UserProfile | null;
  isAuthenticated: boolean;
  isLoading: boolean;
  
  setUser: (user: UserProfile | null) => void;
  setAuthenticated: (status: boolean) => void;
  setLoading: (status: boolean) => void;
  clearAuth: () => void;
}

export const authStore = create<AuthState>()(
  persist(
    (set) => ({
      user: null,
      isAuthenticated: false,
      isLoading: true,

      setUser: (user) => set({ user }),
      setAuthenticated: (status) => set({ isAuthenticated: status }),
      setLoading: (status) => set({ isLoading: status }),
      
      clearAuth: () => set({
        user: null,
        isAuthenticated: false,
        isLoading: false,
      }),
    }),
    {
      name: 'auth-store',
      partialize: (state) => ({
        user: state.user,
        isAuthenticated: state.isAuthenticated,
      }),
    }
  )
);
```

### 7. Auth Events

Event-driven auth state changes:

```typescript
// core/domains/auth/events.ts
import { EventEmitter } from '@/core/shared/utils/events';

export type AuthEvents = {
  'auth:login': { userId: string; token: string };
  'auth:logout': void;
  'auth:sessionExpired': void;
  'auth:tokenRefreshed': { accessToken: string };
  'auth:userUpdated': { user: UserProfile };
};

export const authEvents = new EventEmitter<AuthEvents>();

// Helper functions for common events
export const authEventHelpers = {
  notifyLogin: (userId: string, token: string) => {
    authEvents.emit('auth:login', { userId, token });
  },
  
  notifyLogout: () => {
    authEvents.emit('auth:logout');
  },
  
  notifySessionExpired: () => {
    authEvents.emit('auth:sessionExpired');
  },
  
  notifyTokenRefreshed: (accessToken: string) => {
    authEvents.emit('auth:tokenRefreshed', { accessToken });
  },
};
```

## Authentication Flows

### 1. Login Flow

<Mermaid
  chart={`
sequenceDiagram
  participant User
  participant LoginScreen
  participant AuthHooks
  participant AuthAPI
  participant TokenService
  participant AuthStore
  participant AuthEvents
  
  User->>LoginScreen: Enter credentials
  LoginScreen->>AuthHooks: useLogin()
  AuthHooks->>AuthAPI: login(credentials)
  AuthAPI->>AuthHooks: tokens + user data
  AuthHooks->>TokenService: setTokens()
  AuthHooks->>AuthStore: setUser()
  AuthHooks->>AuthEvents: emit('auth:login')
  AuthEvents-->>App: Navigate to Home
`}
/>

### 2. Token Refresh Flow

<Mermaid
  chart={`
sequenceDiagram
  participant App
  participant APIClient
  participant TokenService
  participant AuthAPI
  participant AuthEvents
  
  App->>APIClient: API request
  APIClient->>APIClient: 401 response
  APIClient->>TokenService: getRefreshToken()
  APIClient->>AuthAPI: refresh(token)
  AuthAPI->>APIClient: new tokens
  APIClient->>TokenService: setTokens()
  APIClient->>App: Retry request
  
  Note over APIClient,AuthAPI: If refresh fails
  APIClient->>TokenService: clearTokens()
  APIClient->>AuthEvents: emit('sessionExpired')
  AuthEvents-->>App: Navigate to Login
`}
/>

### 3. Logout Flow

<Mermaid
  chart={`
sequenceDiagram
  participant User
  participant App
  participant AuthHooks
  participant AuthAPI
  participant TokenService
  participant AuthStore
  participant QueryClient
  participant AuthEvents
  
  User->>App: Click logout
  App->>AuthHooks: useLogout()
  AuthHooks->>AuthAPI: logout()
  AuthHooks->>TokenService: clearTokens()
  AuthHooks->>AuthStore: clearAuth()
  AuthHooks->>QueryClient: clear()
  AuthHooks->>AuthEvents: emit('auth:logout')
  AuthEvents-->>App: Navigate to Login
`}
/>

## Implementation Examples

### 1. Login Screen

```typescript
// features/auth/screens/LoginScreen.tsx
import { useState } from 'react';
import { useLogin } from '@/core/domains/auth/hooks';
import { useNavigation } from '@react-navigation/native';

export function LoginScreen() {
  const [email, setEmail] = useState('');
  const [password, setPassword] = useState('');
  const login = useLogin();
  const navigation = useNavigation();

  const handleLogin = async () => {
    try {
      await login.mutateAsync({ email, password });
      // Navigation handled by auth event listener
    } catch (error) {
      Alert.alert('Login Failed', error.message);
    }
  };

  return (
    <View>
      <TextInput
        value={email}
        onChangeText={setEmail}
        placeholder="Email"
        autoCapitalize="none"
        keyboardType="email-address"
      />
      <TextInput
        value={password}
        onChangeText={setPassword}
        placeholder="Password"
        secureTextEntry
      />
      <Button
        title="Login"
        onPress={handleLogin}
        loading={login.isLoading}
      />
    </View>
  );
}
```

### 2. App-Level Auth Handling

```typescript
// App.tsx
import { useEffect } from 'react';
import { NavigationContainer } from '@react-navigation/native';
import { authEvents } from '@/core/domains/auth/events';
import { useAuthStatus } from '@/core/domains/auth/hooks';

export function App() {
  const { data: authStatus, isLoading } = useAuthStatus();
  const navigation = useNavigation();

  useEffect(() => {
    // Listen for auth events
    const unsubscribeExpired = authEvents.on('auth:sessionExpired', () => {
      navigation.reset({
        index: 0,
        routes: [{ name: 'Login' }],
      });
    });

    const unsubscribeLogout = authEvents.on('auth:logout', () => {
      navigation.reset({
        index: 0,
        routes: [{ name: 'Login' }],
      });
    });

    return () => {
      unsubscribeExpired();
      unsubscribeLogout();
    };
  }, [navigation]);

  if (isLoading) {
    return <SplashScreen />;
  }

  return (
    <NavigationContainer>
      {authStatus?.isAuthenticated ? (
        <AuthenticatedStack />
      ) : (
        <UnauthenticatedStack />
      )}
    </NavigationContainer>
  );
}
```

### 3. Protected API Calls

```typescript
// features/profile/screens/ProfileScreen.tsx
import { useCurrentUser } from '@/core/domains/auth/hooks';
import { useUpdateProfile } from '@/core/domains/users/hooks';

export function ProfileScreen() {
  const { data: user, isLoading } = useCurrentUser();
  const updateProfile = useUpdateProfile();

  const handleUpdate = async (updates: Partial<UserProfile>) => {
    try {
      await updateProfile.mutateAsync(updates);
      Alert.alert('Success', 'Profile updated');
    } catch (error) {
      Alert.alert('Error', 'Failed to update profile');
    }
  };

  if (isLoading) return <LoadingSpinner />;

  return (
    <View>
      <Text>{user?.name}</Text>
      <Text>{user?.email}</Text>
      <Button
        title="Edit Profile"
        onPress={() => handleUpdate({ name: 'New Name' })}
      />
    </View>
  );
}
```

## Security Considerations

### 1. Token Storage

* Use platform-specific secure storage (Keychain/Keystore)
* Never store tokens in plain text
* Clear tokens on logout
* Implement token expiration checks

### 2. API Security

* Always use HTTPS
* Implement certificate pinning for production
* Validate SSL certificates
* Use short-lived access tokens (15-30 minutes)
* Use longer-lived refresh tokens (7-30 days)

### 3. Session Management

* Implement idle timeout
* Clear sensitive data on app background
* Re-authenticate for sensitive operations
* Log security events

### 4. Error Handling

```typescript
// Secure error handling
export function sanitizeError(error: any): string {
  // Don't expose sensitive information
  if (error.response?.status === 401) {
    return 'Please log in to continue';
  }
  if (error.response?.status === 403) {
    return 'You don\'t have permission to perform this action';
  }
  // Generic error for production
  if (__DEV__) {
    return error.message || 'An error occurred';
  }
  return 'Something went wrong. Please try again.';
}
```

## Testing Authentication

### 1. Unit Tests

```typescript
// core/domains/auth/__tests__/tokenService.test.ts
import { tokenService } from '../tokenService';
import { storage } from '@/core/shared/utils/storage';

jest.mock('@/core/shared/utils/storage');

describe('TokenService', () => {
  beforeEach(() => {
    jest.clearAllMocks();
  });

  it('should store tokens', async () => {
    await tokenService.setTokens('access', 'refresh');
    
    expect(storage.setSecureItem).toHaveBeenCalledWith(
      'accessToken',
      'access'
    );
    expect(storage.setSecureItem).toHaveBeenCalledWith(
      'refreshToken',
      'refresh'
    );
  });

  it('should clear tokens', async () => {
    await tokenService.clearTokens();
    
    expect(storage.removeItem).toHaveBeenCalledWith('accessToken');
    expect(storage.removeItem).toHaveBeenCalledWith('refreshToken');
  });
});
```

### 2. Integration Tests

```typescript
// features/auth/__tests__/LoginScreen.integration.test.tsx
import { render, fireEvent, waitFor } from '@testing-library/react-native';
import { LoginScreen } from '../screens/LoginScreen';
import { authApi } from '@/core/domains/auth/api';

jest.mock('@/core/domains/auth/api');

describe('LoginScreen Integration', () => {
  it('should login successfully', async () => {
    const mockLogin = authApi.login as jest.Mock;
    mockLogin.mockResolvedValue({
      tokens: { access: 'token', refresh: 'refresh' },
      user: { id: '1', email: 'test@example.com' },
    });

    const { getByText, getByPlaceholderText } = render(<LoginScreen />);
    
    fireEvent.changeText(
      getByPlaceholderText('Email'),
      'test@example.com'
    );
    fireEvent.changeText(
      getByPlaceholderText('Password'),
      'password123'
    );
    fireEvent.press(getByText('Login'));

    await waitFor(() => {
      expect(mockLogin).toHaveBeenCalledWith({
        email: 'test@example.com',
        password: 'password123',
      });
    });
  });
});
```

## Troubleshooting

### Common Issues

1. **Token Refresh Loop**
   * Check refresh endpoint URL
   * Verify refresh token validity
   * Check for clock skew

2. **Session Not Persisting**
   * Verify secure storage implementation
   * Check persistence configuration
   * Validate token expiration

3. **401 Errors After Login**
   * Check Authorization header format
   * Verify token is being sent
   * Check API endpoint configuration

## Migration Guide

For existing apps migrating to this architecture:

1. **Phase 1: Token Service**
   * Implement token service
   * Migrate from existing storage

2. **Phase 2: API Client**
   * Add interceptors
   * Implement refresh logic

3. **Phase 3: Auth Domain**
   * Create auth domain structure
   * Migrate auth logic

4. **Phase 4: Event System**
   * Implement auth events
   * Update navigation handling

## Design Principles

### Core Architectural Principles

1. **Separation of Concerns**
   * Token management is isolated from business logic
   * API client handles authentication transparently to consumers
   * Events decouple authentication status from UI responses

2. **Defense in Depth**
   * Token storage uses platform-specific secure storage
   * Refresh tokens are handled with appropriate security measures
   * Automatic session termination on security breaches

3. **Developer Ergonomics**
   * Type-safe API client implementation
   * Consistent error handling patterns
   * Clear separation between public/authenticated endpoints

### Trade-offs and Design Decisions

| Decision                         | Benefits                                    | Drawbacks                                | Rationale                                                   |
| -------------------------------- | ------------------------------------------- | ---------------------------------------- | ----------------------------------------------------------- |
| Separate Token Service           | Modular, testable, no circular dependencies | More code to maintain                    | Enables independent testing and prevents circular imports   |
| Automatic Token Refresh          | Seamless UX, fewer session timeouts         | More complex API client                  | User experience benefits outweigh implementation complexity |
| Event-based Auth Status          | Loose coupling between components           | Asynchronous flow can be harder to debug | Allows for flexible responses to auth events across the app |
| Platform-specific Secure Storage | Uses best-available security per platform   | Requires platform-specific code          | Maximum security is critical for auth tokens                |

### Constraints and Considerations

* Authentication implementation must handle various network conditions
* Token refresh must work reliably to prevent disruption
* API error handling must account for various auth-related errors
* Deep linking and external app authentication flows must be supported

## Implementation Considerations

### Performance Implications

* **Token Validation**: Performed locally when possible to reduce network requests
* **Caching**: Auth status cached to minimize secure storage access which can be slow
* **API Design**: Authentication header injection optimized to minimize overhead

### Security Considerations

* **Token Storage**: Never store in AsyncStorage/LocalStorage unencrypted
* **XSS Protection**: Tokens never accessible to WebViews or JavaScript bridges
* **Refresh Logic**: Implements exponential backoff for failed refresh attempts
* **Biometric Integration**: Optional biometric verification for high-security operations

### Scalability Aspects

* Architecture supports multiple authentication methods (email/password, social, SSO)
* Design allows for additional auth providers without changing core implementation
* Supports multiple concurrent user profiles when needed

## Related Documents

* [API Client with Request Queueing](/docs/api/request-queueing) - Detailed implementation of request queueing during token refresh
* [API Client Architecture](/docs/api/client-architecture) - Mandatory patterns for API client implementation
* [Core Architecture](/docs/architecture/core-architecture) - Overview of the application's hybrid architecture
* [Communication Patterns](/docs/features/communication-patterns) - Inter-module communication
* [Security Guidelines](/docs/coding-standards/security) - Application security best practices
* [API Integration Guide](/docs/guides/api-integration) - Implementation guide for API integration
* [State Management Guide](/docs/guides/state-management)


# UTA API Integration: API Client with Request Queueing
URL: https://dev.updatetheapp.com/docs/api/request-queueing
Documentation: https://dev.updatetheapp.com/docs/api/request-queueing

Enhanced API client implementation with proper request queueing during token refresh
        
***

title: API Client with Request Queueing
description: Enhanced API client implementation with proper request queueing during token refresh
-------------------------------------------------------------------------------------------------

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';

# API Client with Request Queueing

## Overview

This document outlines our implementation of the request queueing pattern for API clients to handle token refresh scenarios efficiently. When multiple API requests encounter an expired access token simultaneously, our approach ensures that only one token refresh operation occurs, while other requests are queued and automatically retried upon successful token refresh, providing a seamless user experience without exposing authentication complexities to application logic.

> This document focuses on the request queueing mechanism specifically. For details about the overall authentication architecture, token management, and security considerations, see the [Authentication Architecture](/docs/api/authentication) documentation.

## Purpose & Scope

This reference targets developers implementing or maintaining API communication layers. It covers:

* The problem of concurrent API requests during token expiration
* Request queueing implementation strategies
* Handling of public vs. authenticated endpoints
* Error handling during token refresh
* Testing strategies for request queueing

## Prerequisites

To get the most out of this guide on request queueing, we recommend you first understand these core concepts and review the related architectural documents:

* **API Client Architecture**: You should be thoroughly familiar with the mandatory patterns defined in the [API Client Architecture Guide](/docs/api/client-architecture), particularly the roles of `BaseApiClient`, `PublicApiClient`, and `AuthenticatedApiClient`.
* **Authentication Architecture**: A strong grasp of the concepts in the [Authentication Architecture](/docs/api/authentication) document is crucial. This includes understanding how `tokenService` manages tokens, how `authEvents` are used, and the basic token refresh flow.
* **Axios Interceptors**: The queueing logic is implemented using Axios request and response interceptors. Familiarity with how these work is essential.
* **JavaScript Asynchronous Operations**: A good understanding of Promises, `async/await` is necessary to follow the code examples.

## The Problem

When multiple API requests are made simultaneously and the access token has expired, each request will receive a 401 response. Without proper handling, this would trigger multiple token refresh requests, causing:

* Race conditions
* Invalid refresh token errors
* Poor user experience
* Potential security issues

## Solution: Request Queue Pattern

<Mermaid
  chart={`
sequenceDiagram
participant App as Application
participant Client as API Client
participant Queue as Request Queue
participant Auth as Auth Service
participant API as Backend API

App->>Client: Request 1
App->>Client: Request 2
App->>Client: Request 3

Client->>API: Request 1 with token
API-->>Client: 401 Unauthorized (token expired)

Note over Client,Auth: Token Refresh Process Begins
Client->>Auth: Start token refresh

Client->>Queue: Add Request 1 to queue

Client->>API: Request 2 with token
API-->>Client: 401 Unauthorized
Client->>Queue: Add Request 2 to queue

Client->>API: Request 3 with token
API-->>Client: 401 Unauthorized
Client->>Queue: Add Request 3 to queue

Auth->>API: Refresh token request
API-->>Auth: New access token
Auth-->>Client: Update token

Note over Client,Queue: Process Queued Requests
Client->>API: Retry Request 1 with new token
Client->>API: Retry Request 2 with new token
Client->>API: Retry Request 3 with new token

API-->>Client: Response 1
API-->>Client: Response 2
API-->>Client: Response 3

Client-->>App: Response 1
Client-->>App: Response 2
Client-->>App: Response 3
`}
/>

We implement a queue mechanism that:

1. Detects when a refresh is in progress
2. Queues subsequent failed requests
3. Processes all queued requests after refresh completes
4. Handles refresh failures gracefully

## Handling Public vs. Authenticated API Endpoints

In our project, the differentiation between public API endpoints (which do not require authentication tokens) and authenticated endpoints (which do) is managed by our **established standard API client architecture**. This architecture, detailed in the [API Client Architecture Guide](/docs/api/client-architecture), utilizes separate `PublicApiClient` and `AuthenticatedApiClient` instances.

* `PublicApiClient`: Used for endpoints like login, registration, or public data fetching. It does not attach authentication tokens.
* `AuthenticatedApiClient`: Used for endpoints requiring user authentication. It handles attaching access tokens and is responsible for the token refresh mechanism, including request queueing.

This document focuses on the **request queueing mechanism implemented within the `AuthenticatedApiClient`** when a token refresh is triggered. The following sections will detail this queueing logic and how it integrates into the token refresh process of the `AuthenticatedApiClient`.

For comprehensive details on how `PublicApiClient` and `AuthenticatedApiClient` are structured and used, please refer to:

* [API Client Architecture Guide](/docs/api/client-architecture)
* [Authentication Architecture](/docs/api/authentication)

## Complete Implementation with Queue (within `AuthenticatedApiClient`)

This section details how request queueing is integrated into our standard `AuthenticatedApiClient`. The `AuthenticatedApiClientWithQueue` class shown below extends the `BaseApiClient` and incorporates the queueing logic.

<Callout type="warn" title="About the `AuthenticatedApiClientWithQueue` Example">
  The `AuthenticatedApiClientWithQueue` class presented below demonstrates the complete integration of request queueing into an authenticated API client.

  * It **illustrates the fully-featured version** of the `AuthenticatedApiClient` (which is introduced in the [API Client Architecture Guide](/docs/api/client-architecture) and further detailed in the [Authentication Architecture](/docs/api/authentication) guide).
  * In your actual project codebase, this queueing logic would typically be part of your main `AuthenticatedApiClient`. The name `AuthenticatedApiClientWithQueue` is used here for clear focus on the queueing enhancements.
  * It extends the canonical `BaseApiClient`, whose full definition is in the [API Client Architecture Guide](/docs/api/client-architecture).
  * It relies on `tokenService` and `authEvents` from the [Authentication Architecture](/docs/api/authentication) guide. For this example, assume these services provide methods like `getAccessToken`, `getRefreshToken`, `setTokens`, `clearTokens`, and an `EventEmitter` for auth-related events.
</Callout>

```typescript
// Conceptual Path: core/shared/api/authenticatedClientWithQueue.ts
// import { BaseApiClient } from './base'; // This import would be from your project's actual shared location for BaseApiClient
import axios, { AxiosInstance, AxiosRequestConfig, AxiosError, AxiosResponse } from 'axios'; // Still needed for refreshClient
import { tokenService } from '@/core/domains/auth/tokenService'; // Actual path should be verified
import { authEvents } from '@/core/domains/auth/events'; // Actual path should be verified

// BaseApiClient is NOT redefined in this code block. 
// AuthenticatedApiClientWithQueue extends the canonical BaseApiClient, 
// whose full definition and explanation can be found in the "API Client Architecture Guide".

export class AuthenticatedApiClientWithQueue extends BaseApiClient { // BaseApiClient would be imported
  private isRefreshing = false;
  private refreshPromise: Promise<string | void> | null = null;
  private requestQueue: Array<{
    config: AxiosRequestConfig; // Store original config
    resolve: (value: any) => void;
    reject: (error: any) => void;
  }> = [];

  constructor(config: AxiosRequestConfig) { 
    super(config); 
    this.setupInterceptors();
  }

  private setupInterceptors() {
    // Request interceptor - add token to requests
    this.client.interceptors.request.use(
      async (config) => {
        const token = await tokenService.getAccessToken();
        if (token) {
          config.headers = config.headers || {};
          config.headers.Authorization = `Bearer ${token}`;
        }
        return config;
      },
      (error) => Promise.reject(error)
    );

    // Response interceptor - handle token refresh and queueing
    this.client.interceptors.response.use(
      (response) => response, 
      async (error: AxiosError) => {
        const originalRequest = error.config as AxiosRequestConfig & { _retry?: boolean };

        if (!originalRequest || error.response?.status !== 401 || originalRequest._retry) {
          return Promise.reject(error);
        }

        originalRequest._retry = true;

        if (this.isRefreshing) {
          return this.queueRequest(originalRequest);
        } else {
          this.isRefreshing = true;
          this.refreshPromise = this.handleTokenRefresh().finally(() => {
            this.isRefreshing = false;
          });

          try {
            const newToken = await this.refreshPromise;
            if (typeof newToken === 'string') { 
              originalRequest.headers!.Authorization = `Bearer ${newToken}`;
              return this.client(originalRequest);
            } else {
                return Promise.reject(error); 
            }
          } catch (refreshError) {
            return Promise.reject(refreshError);
          }
        }
      }
    );
  }

  private async handleTokenRefresh(): Promise<string | void> {
    try {
      const refreshTokenValue = await tokenService.getRefreshToken();
      if (!refreshTokenValue) {
        throw new Error('No refresh token available');
      }

      const refreshClient = axios.create({ 
        baseURL: this.client.defaults.baseURL, 
      });
      const response = await refreshClient.post('/auth/refresh', { 
        refreshToken: refreshTokenValue,
      });

      const { accessToken, refreshToken: newRefreshToken } = response.data;
      await tokenService.setTokens(accessToken, newRefreshToken);
      authEvents.emit('auth:tokenRefreshed', { accessToken });

      this.processRequestQueue(accessToken);
      this.refreshPromise = null; 
      return accessToken; 

    } catch (error) {
      authEvents.emit('auth:sessionExpired'); 
      this.rejectRequestQueue(error); 
      await tokenService.clearTokens(); 
      this.refreshPromise = null; 
      return Promise.reject(error); 
    }
  }

  private queueRequest(config: AxiosRequestConfig): Promise<any> {
    return new Promise((resolve, reject) => {
      this.requestQueue.push({ config, resolve, reject });
    });
  }

  private processRequestQueue(token: string) {
    this.requestQueue.forEach(({ config, resolve, reject }) => {
      config.headers!.Authorization = `Bearer ${token}`;
      this.client(config)
        .then(resolve)
        .catch(reject);
    });
    this.requestQueue = [];
  }

  private rejectRequestQueue(error: any) {
    this.requestQueue.forEach(({ reject }) => {
      reject(error);
    });
    this.requestQueue = [];
  }
  // The HTTP helper methods (get, post, put, delete) are inherited from BaseApiClient
  // and do not need to be redefined here unless overridden.
}

// Note on instantiation:
// The AuthenticatedApiClientWithQueue class defined above would typically be instantiated 
// as a singleton. This process should align with patterns detailed in the 
// "API Client Architecture Guide" and the "Multi-API Architecture" guide.
// This often involves creating a specific configuration (e.g., with the baseURL 
// from environment variables) and exporting the client instance from a central module.
// The following illustrates a conceptual example:

// Conceptual example: core/shared/api/client.ts 

// import { AuthenticatedApiClientWithQueue } from './path/to/authenticatedClientWithQueue'; // Actual import path
// import { AxiosRequestConfig } from 'axios';

// const apiConfig: AxiosRequestConfig = {
//   baseURL: process.env.REACT_APP_API_URL || '/api',
//   // other shared configs for this specific client instance
// };

// export const authenticatedApiWithQueue = 
//   new AuthenticatedApiClientWithQueue(apiConfig);
```

## Request Queue Core Functionality

The core of the request queueing mechanism, as implemented within the `AuthenticatedApiClientWithQueue` (which aligns with the project's `AuthenticatedApiClient` pattern), revolves around these methods:

### The `queueRequest` Method

This method is invoked when an API request fails due to an expired token (401 error) and a token refresh operation is already underway. It defers the execution of the failed request by adding it to a queue.

<Callout type="info" title="Key Function: queueRequest (within AuthenticatedApiClientWithQueue)">
  ```typescript
  /**
   * Adds a request to the queue during token refresh.
   * @param config The original request configuration that failed.
   * @returns A new Promise that resolves/rejects when the queued request is processed.
   */
  private queueRequest(config: AxiosRequestConfig): Promise<any> {
    return new Promise((resolve, reject) => {
      this.requestQueue.push({ config, resolve, reject });
    });
  }
  ```
</Callout>

### The `processRequestQueue` Method

Called after a successful token refresh, this method iterates over all requests in the queue, updates their authorization headers with the new token, and retries them.

```typescript
/**
 * Processes all requests currently in the queue with the new token.
 * @param token The new access token.
 */
private processRequestQueue(token: string) {
  this.requestQueue.forEach(({ config, resolve, reject }) => {
    config.headers!.Authorization = `Bearer ${token}`;
    this.client(config) // Uses the client instance from BaseApiClient
      .then(resolve)
      .catch(reject);
  });
  this.requestQueue = []; // Clear the queue
}
```

### The `rejectRequestQueue` Method

If the token refresh attempt fails, this method is called to reject all pending requests in the queue, ensuring that no requests are left hanging and that the application can handle the refresh failure appropriately.

```typescript
/**
 * Rejects all requests currently in the queue with the given error.
 * @param error The error that occurred (e.g., during token refresh).
 */
private rejectRequestQueue(error: any) {
  this.requestQueue.forEach(({ reject }) => {
    reject(error);
  });
  this.requestQueue = []; // Clear the queue
}
```

These methods work in concert within the response interceptor of the `AuthenticatedApiClientWithQueue` to provide seamless handling of token expiration and refresh.

### Integration in the Response Interceptor

The updated response interceptor in `AuthenticatedApiClientWithQueue` uses these methods:

```typescript
// Inside AuthenticatedApiClientWithQueue's setupInterceptors method:
this.client.interceptors.response.use(
  (response) => response,
  async (error: AxiosError) => {
    const originalRequest = error.config as AxiosRequestConfig & { _retry?: boolean };

    if (!originalRequest || error.response?.status !== 401 || originalRequest._retry) {
      return Promise.reject(error);
    }
    originalRequest._retry = true;

    if (this.isRefreshing) {
      return this.queueRequest(originalRequest);
    } else {
      this.isRefreshing = true;
      this.refreshPromise = this.handleTokenRefresh().finally(() => {
        this.isRefreshing = false;
      });

      try {
        const newToken = await this.refreshPromise;
        if (typeof newToken === 'string') {
          originalRequest.headers!.Authorization = `Bearer ${newToken}`;
          return this.client(originalRequest);
        } else {
          return Promise.reject(error); 
        }
      } catch (refreshError) {
        return Promise.reject(refreshError);
      }
    }
  }
);
```

### Visualizing the Queue Flow

<Mermaid
  chart={`
sequenceDiagram
participant App as Application Code
participant Interceptor as Response Interceptor
participant Queue as Request Queue
participant TokenService as Token Service
participant API as Backend API

App->>Interceptor: API Request fails with 401
Interceptor->>Interceptor: Check if refreshing

alt Already refreshing token
  Interceptor->>Queue: queueRequest(originalRequest)
  Queue-->>App: Return promise to be resolved later
else Start refresh process
  Interceptor->>TokenService: refreshAccessToken() // This should be a call within the client, like this.handleTokenRefresh()
  TokenService->>API: Request new token
  API-->>TokenService: New token
  TokenService->>Queue: processRequestQueue(newToken) // This is now an internal call: this.processRequestQueue(newToken)
  Queue->>API: Retry all queued requests
  API-->>Queue: Response
  Queue-->>App: Resolve promises
end
`}
/>

## Testing Request Queueing

Testing the request queueing functionality is critical to ensure it works correctly under various conditions. Below are comprehensive test examples covering different scenarios.

### Setup For Testing

First, set up the test environment with the necessary mocks. Note that `AuthenticatedApiClientWithQueue` would typically be imported from its definition, and its constructor might require specific configuration (e.g., baseURL) based on your project setup.

```typescript
// core/shared/api/__tests__/request-queue.test.ts
// import { apiClient } from '../client'; // Removed: apiClient is no longer used directly here
import { AuthenticatedApiClientWithQueue } from '../authenticatedClientWithQueue'; // Assuming this is the path to the class defined above
import { tokenService } from '@/core/domains/auth/tokenService';
import MockAdapter from 'axios-mock-adapter';
import { authEvents } from '@/core/domains/auth/events';
import { AxiosRequestConfig } from 'axios';

describe('API Client Request Queueing with AuthenticatedApiClientWithQueue', () => {
  let authenticatedClient: AuthenticatedApiClientWithQueue;
  let mockAxios: MockAdapter;
  const mockTokenRefreshEmit = jest.fn();
  const mockSessionExpiredEmit = jest.fn();

  const clientConfig: AxiosRequestConfig = { baseURL: '/' }; // Example base URL

  beforeEach(() => {
    authenticatedClient = new AuthenticatedApiClientWithQueue(clientConfig);
    // The client property is protected in BaseApiClient, so we cast to any to access it for mocking.
    // In a real test setup, you might have a way to get the underlying Axios instance or use a more integrated test approach.
    mockAxios = new MockAdapter((authenticatedClient as any).client);
    
    jest.spyOn(tokenService, 'getAccessToken').mockResolvedValue('expired-token');
    jest.spyOn(tokenService, 'getRefreshToken').mockResolvedValue('valid-refresh-token');
    jest.spyOn(tokenService, 'setTokens').mockResolvedValue(undefined);
    jest.spyOn(tokenService, 'clearTokens').mockResolvedValue(undefined);
    
    authEvents.on('auth:tokenRefreshed', mockTokenRefreshEmit);
    authEvents.on('auth:sessionExpired', mockSessionExpiredEmit);
  });

  afterEach(() => {
    mockAxios.reset();
    jest.clearAllMocks();
    authEvents.off('auth:tokenRefreshed', mockTokenRefreshEmit);
    authEvents.off('auth:sessionExpired', mockSessionExpiredEmit);
  });
});
```

### Test Case 1: Successful Token Refresh and Request Retry

```typescript
// Test Case 1: Successful Token Refresh and Request Retry
test('should handle token refresh and retry the original request when a 401 is returned', async () => {
  // Mock a 401 response for the first request, then a 200 for the retry
  mockAxios.onGet('/api/data').replyOnce(401).onGet('/api/data').replyOnce(200, { success: true });
  
  // Mock the token refresh response
  mockAxios.onPost('/api/auth/refresh').replyOnce(200, {
    access_token: 'new-access-token',
    refresh_token: 'new-refresh-token'
  });
  
  // Override to simulate a real token refresh
  jest.spyOn(tokenService, 'getRefreshToken').mockResolvedValue('valid-refresh-token');
  jest.spyOn(authenticatedClient as any, 'handleTokenRefresh').mockImplementation(async () => {
    const resp = await (authenticatedClient as any).client.post('/api/auth/refresh', { 
      refreshToken: 'valid-refresh-token' 
    });
    
    const tokens = resp.data;
    await tokenService.setTokens(tokens.access_token, tokens.refresh_token);
    authEvents.emit('auth:tokenRefreshed');
    return tokens.access_token;
  });
  
  // Make the request
  const response = await authenticatedClient.get('/api/data');
  
  // Assertions
  expect(response.data).toEqual({ success: true });
  expect(tokenService.setTokens).toHaveBeenCalledWith('new-access-token', 'new-refresh-token');
  expect(mockTokenRefreshEmit).toHaveBeenCalled();
});
```

### Test Case 2: Multiple Concurrent Requests During Token Refresh

```typescript
// Test Case 2: Multiple Concurrent Requests During Token Refresh
test('should queue multiple requests during token refresh and process them after refresh', async () => {
  // Set up mock responses
  // All first attempts return 401
  mockAxios.onGet('/api/data/1').replyOnce(401);
  mockAxios.onGet('/api/data/2').replyOnce(401);
  mockAxios.onGet('/api/data/3').replyOnce(401);
  
  // All retries return 200 with different data
  mockAxios.onGet('/api/data/1').replyOnce(200, { id: 1 });
  mockAxios.onGet('/api/data/2').replyOnce(200, { id: 2 });
  mockAxios.onGet('/api/data/3').replyOnce(200, { id: 3 });
  
  // Token refresh response
  mockAxios.onPost('/api/auth/refresh').replyOnce(200, {
    access_token: 'new-access-token',
    refresh_token: 'new-refresh-token'
  });
  
  // Setup token refresh mock
  let refreshComplete = false;
  let refreshPromise: Promise<void>;
  
  jest.spyOn(authenticatedClient as any, 'handleTokenRefresh').mockImplementation(async () => {
    refreshPromise = new Promise<void>(resolve => {
      setTimeout(() => {
        refreshComplete = true;
        resolve();
      }, 50); // Small delay to simulate network latency
    }).then(async () => {
      const resp = await (authenticatedClient as any).client.post('/api/auth/refresh');
      const tokens = resp.data;
      await tokenService.setTokens(tokens.access_token, tokens.refresh_token);
      authEvents.emit('auth:tokenRefreshed');
      return tokens.access_token;
    });
    
    return refreshPromise;
  });
  
  // Make concurrent requests
  const request1 = authenticatedClient.get('/api/data/1');
  const request2 = authenticatedClient.get('/api/data/2');
  const request3 = authenticatedClient.get('/api/data/3');
  
  // Wait for all requests to complete
  const [response1, response2, response3] = await Promise.all([request1, request2, request3]);
  
  // Assertions
  expect(refreshComplete).toBe(true);
  expect(response1.data).toEqual({ id: 1 });
  expect(response2.data).toEqual({ id: 2 });
  expect(response3.data).toEqual({ id: 3 });
  expect(tokenService.setTokens).toHaveBeenCalledTimes(1);
  expect(mockTokenRefreshEmit).toHaveBeenCalledTimes(1);
});
```

### Test Case 3: Failed Token Refresh

```typescript
// Test Case 3: Failed Token Refresh
test('should reject all queued requests if token refresh fails', async () => {
  // Set up mock responses
  mockAxios.onGet('/api/data/1').replyOnce(401);
  mockAxios.onGet('/api/data/2').replyOnce(401);
  
  // Token refresh fails
  mockAxios.onPost('/api/auth/refresh').replyOnce(403, { 
    error: 'Invalid refresh token' 
  });
  
  // Setup token refresh mock that will fail
  jest.spyOn(authenticatedClient as any, 'handleTokenRefresh').mockImplementation(async () => {
    try {
      const resp = await (authenticatedClient as any).client.post('/api/auth/refresh');
      return resp.data.access_token;
    } catch (error) {
      await tokenService.clearTokens();
      authEvents.emit('auth:sessionExpired');
      throw error;
    }
  });
  
  // Make requests
  const request1 = authenticatedClient.get('/api/data/1');
  const request2 = authenticatedClient.get('/api/data/2');
  
  // Assertions
  await expect(request1).rejects.toThrow();
  await expect(request2).rejects.toThrow();
  expect(tokenService.clearTokens).toHaveBeenCalled();
  expect(mockSessionExpiredEmit).toHaveBeenCalled();
});
```

## Design Principles

Our request queueing implementation follows these key design principles:

1. **Separation of Concerns**: The queueing mechanism is encapsulated within the `AuthenticatedApiClientWithQueue` class, keeping authentication complexities hidden from application code.

2. **Efficiency**: Only one token refresh operation is performed when multiple requests fail simultaneously.

3. **Transparency**: Requests are automatically retried after token refresh without requiring application code intervention.

4. **Robustness**: Failed token refreshes are handled gracefully, with appropriate error propagation and event notifications.

5. **Progressive Enhancement**: The queueing mechanism enhances the base API client capabilities defined in the API Client Architecture.

## Alternative Approaches Considered

We evaluated several approaches before settling on our current implementation:

### 1. Global Axios Instance with Queue

**Approach**: Using a single global Axios instance with interceptors managing the queue.

**Pros**:

* Simpler implementation with less code
* Centralized queue management

**Cons**:

* Less flexibility for API clients with different base URLs or configurations
* Harder to test in isolation
* Potential for queue conflicts between different API domains

### 2. Redux Middleware for API Requests

**Approach**: Using Redux middleware to manage API requests and handle token refreshing.

**Pros**:

* Integrated with state management
* Potentially more visibility into request states

**Cons**:

* Tighter coupling between API layer and state management
* More complex implementation
* Not suitable for non-Redux applications

### 3. Separate Token Manager Service

**Approach**: Creating a separate service to manage token refresh, with API clients checking token validity before requests.

**Pros**:

* Clearer separation of responsibilities
* Potentially more reusable across different API client implementations

**Cons**:

* More complex coordination between services
* Potential for race conditions if not carefully implemented
* Additional overhead of token validity checks before each request

## Conclusion

The request queueing pattern implemented in our `AuthenticatedApiClientWithQueue` provides a robust solution for handling token refreshes in a way that's transparent to application code. By following the principles and implementation described in this document, developers can ensure that API authentication remains seamless even when tokens expire during active application use.

This implementation builds upon the foundation established in the [API Client Architecture Guide](/docs/api/client-architecture) and complements the authentication strategies outlined in the [Authentication Architecture](/docs/api/authentication) document.


# UTA API Integration: Multi-API Architecture
URL: https://dev.updatetheapp.com/docs/api/multi-api-setup
Documentation: https://dev.updatetheapp.com/docs/api/multi-api-setup

How to scale the API client pattern for multiple services and endpoints
        
***

title: Multi-API Architecture
description: How to scale the API client pattern for multiple services and endpoints
------------------------------------------------------------------------------------

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';

# Scalable Multi-API Client Architecture

## Overview

This document describes how to extend our standard API client architecture to support connections to multiple distinct API services, each potentially with its own base URL, authentication strategy, and configuration. It builds upon the foundational patterns established in the API Client Architecture and Authentication Architecture guides.

<Mermaid
  chart={`
classDiagram
class AuthStrategy {
  <<interface>>
  +applyAuth(config)
  +handleAuthError(error)
}

class BearerTokenStrategy {
  +applyAuth(config)
  +handleAuthError(error)
  +refreshAccessToken()
}

class ApiKeyStrategy {
  +applyAuth(config)
  +handleAuthError(error)
}

class OAuth2Strategy {
  +applyAuth(config)
  +handleAuthError(error)
  +refreshAccessToken()
}

class BaseApiClient {
  <<abstract>>
  #client: AxiosInstance
  +get(url, config)
  +post(url, data, config)
  +put(url, data, config)
  +delete(url, config)
  #handleResponse(response)
  #handleError(error)
}

class PublicApiClient {
  +constructor(config)
}

class AuthenticatedApiClient {
  -authStrategy: AuthStrategy
  +constructor(config, authStrategy)
  -setupAuthInterceptors()
}

AuthStrategy <|-- BearerTokenStrategy
AuthStrategy <|-- ApiKeyStrategy
AuthStrategy <|-- OAuth2Strategy

BaseApiClient <|-- PublicApiClient
BaseApiClient <|-- AuthenticatedApiClient

AuthenticatedApiClient o-- AuthStrategy : uses

note for AuthenticatedApiClient "Can be configured with\ndifferent AuthStrategies\nfor different API services"
`}
/>

## Purpose & Scope

This guide is for developers who need to integrate the application with more than one backend API service. It covers:

* Defining multiple API client instances.
* Implementing different authentication strategies per API.
* Managing environment-specific configurations for multiple APIs.

## Prerequisites

To effectively set up and manage multiple API services as described here, it's important to first be familiar with:

* **API Client Architecture**: A thorough understanding of the [API Client Architecture Guide](/docs/api/client-architecture) is crucial, as this guide extends those mandatory patterns (`BaseApiClient`, `PublicApiClient`, `AuthenticatedApiClient`).
* **Authentication Architecture**: Knowledge of the [Authentication Architecture](/docs/api/authentication), particularly `tokenService` and the general principles of token management for authenticated clients.
* **Authentication Strategies**: Basic familiarity with common API authentication mechanisms like Bearer tokens, API Keys, and OAuth2, as the examples will involve implementing strategies for these.
* **Environment Variables**: Understanding how to use environment variables (e.g., `process.env.MAIN_API_URL`) for configuring service URLs and secrets.

## Supporting Multiple API Services

As applications grow, they often need to connect to various backend services—such as a main application API, a payment gateway, an analytics service, or other third-party APIs. The architectural patterns described in this guide are designed to scale elegantly to support these multi-API scenarios, ensuring maintainability and flexibility:

This guide builds upon the foundational `BaseApiClient` defined in the [API Client Architecture Guide](/docs/api/client-architecture). For context, the `BaseApiClient` typically includes a constructor to set up an Axios instance with base URL and timeout, along with common HTTP methods (`get`, `post`, etc.) that handle responses and errors.

### 1. Base Client Configuration (Reference)

The `BaseApiClient` (detailed in the [API Client Architecture Guide](/docs/api/client-architecture)) provides the common foundation. Specific configurations per API service (like `baseURL`, `timeout`, custom `headers`) are passed via an `ApiClientConfig` object when instantiating concrete clients.

```typescript
// Conceptual path: core/shared/api/base.ts (Full definition in the API Client Architecture Guide)
// export abstract class BaseApiClient { ... }

// Configuration interface used when creating specific client instances for different APIs.
export interface ApiClientConfig {
  baseURL: string;
  timeout?: number;
  headers?: Record<string, string>;
  // other AxiosRequestConfig properties can be added if needed by specific clients
}
```

### 2. Different Authentication Strategies

To handle various authentication mechanisms for different API services, we define an `AuthStrategy` interface and concrete implementations. These strategies encapsulate the logic for applying authentication to requests and handling auth-specific errors.

<Tabs items={["AuthStrategy Interface", "BearerTokenStrategy", "ApiKeyStrategy", "OAuth2Strategy"]}>
  <Tab>
    The `AuthStrategy` interface defines the contract for all authentication strategies.

    > **Note:** The code examples throughout this document use conceptual imports with paths like `@/core/domains/...` or commented imports like `// import { TokenService } from...`. These are illustrative examples that would need to be adapted to match your actual project structure.

    ```typescript
    // core/shared/api/auth-strategies.ts
    import { AxiosRequestConfig, AxiosError } from 'axios';

    export interface AuthStrategy {
      applyAuth(config: AxiosRequestConfig): Promise<AxiosRequestConfig>;
      handleAuthError(error: AxiosError): Promise<any>;
    }
    ```
  </Tab>

  <Tab>
    `BearerTokenStrategy` handles APIs secured with bearer tokens, including token refresh logic via `tokenService`.

    ```typescript
    // core/shared/api/auth-strategies.ts (continued)
    // import { TokenService } from '@/core/domains/auth/tokenService'; // Assuming TokenService interface/type

    export class BearerTokenStrategy implements AuthStrategy {
      constructor(
        private tokenService: TokenService,
        // private apiClientInstance?: AxiosInstance // Optional: For retrying requests via the client instance
      ) {}

      async applyAuth(config: AxiosRequestConfig): Promise<AxiosRequestConfig> {
        const token = await this.tokenService.getAccessToken();
        if (token) {
          config.headers = config.headers || {};
          config.headers.Authorization = `Bearer ${token}`;
        }
        return config;
      }

      async handleAuthError(error: AxiosError): Promise<any> {
        // This method would implement token refresh and request queueing.
        // See [API Client with Request Queueing](/docs/api/request-queueing) for the detailed logic
        // that would be adapted here, using `this.tokenService` and potentially an injected client instance for retries.
        const originalRequest = error.config as AxiosRequestConfig & { _retry?: boolean };
        if (error.response?.status === 401 && originalRequest && !originalRequest._retry) {
            console.warn("[BearerTokenStrategy] Token refresh and queueing logic should be implemented here. See /docs/api/request-queueing for a detailed example.");
        }
        return Promise.reject(error);
      }
    }
    ```
  </Tab>

  <Tab>
    `ApiKeyStrategy` is for APIs that use a static API key for authentication.

    ```typescript
    // core/shared/api/auth-strategies.ts (continued)
    export class ApiKeyStrategy implements AuthStrategy {
      constructor(private apiKey: string) {}

      async applyAuth(config: AxiosRequestConfig): Promise<AxiosRequestConfig> {
        config.headers = config.headers || {};
        config.headers['X-API-Key'] = this.apiKey;
        return config;
      }

      async handleAuthError(error: AxiosError): Promise<any> {
        // API key authentication typically doesn't involve refresh tokens.
        // Either re-throw the error directly or implement specific error handling for API key failures.
        return Promise.reject(error);
      }
    }
    ```
  </Tab>

  <Tab>
    `OAuth2Strategy` could handle OAuth 2.0 flows, including token refresh if applicable to the grant type.

    ```typescript
    // core/shared/api/auth-strategies.ts (continued)
    // import { OAuthService } from './oauthService'; // Assuming an OAuthService for token management

    export class OAuth2Strategy implements AuthStrategy {
      constructor(private oauthService: any /* OAuthService */) {}

      async applyAuth(config: AxiosRequestConfig): Promise<AxiosRequestConfig> {
        const token = await this.oauthService.getToken();
        config.headers = config.headers || {};
        config.headers.Authorization = `Bearer ${token}`;
        return config;
      }

      async handleAuthError(error: AxiosError): Promise<any> {
        if (error.response?.status === 401) {
          // Attempt to refresh the OAuth token
          // await this.oauthService.refreshToken();
          // Then, the original request might be retried by the AuthenticatedApiClient.
          // For simplicity, this example just rejects.
          console.warn("[OAuth2Strategy] OAuth token refresh logic to be implemented here.");
        }
        return Promise.reject(error);
      }
    }
    ```
  </Tab>
</Tabs>

### 3. Multiple API Clients

With the base clients and authentication strategies defined, we can now construct specific API client instances. The `PublicApiClient` is used for non-authenticated endpoints, and the `AuthenticatedApiClient` is configured with an appropriate `AuthStrategy` for endpoints requiring authentication.

<Tabs items={["PublicApiClient Definition", "AuthenticatedApiClient (Strategy-based) Definition"]}>
  <Tab>
    `PublicApiClient` extends `BaseApiClient` and requires no special authentication handling.

    ```typescript
    // Conceptual path: core/shared/api/public.ts (extends BaseApiClient defined in the API Client Architecture Guide)
    // import { BaseApiClient } from './base'; // If BaseApiClient is in a separate file

    export class PublicApiClient extends BaseApiClient {
      // No specific authentication logic needed.
      // Inherits constructor and methods from BaseApiClient.
      constructor(config: ApiClientConfig) {
        super(config);
      }
    }
    ```
  </Tab>

  <Tab>
    `AuthenticatedApiClient` also extends `BaseApiClient` but delegates authentication tasks to an injected `AuthStrategy`.

    ```typescript
    // Conceptual path: core/shared/api/authenticated.ts (extends BaseApiClient defined in the API Client Architecture Guide)
    // import { BaseApiClient, ApiClientConfig } from './base';
    // import { AuthStrategy } from './auth-strategies';
    // import { AxiosRequestConfig, AxiosError, AxiosResponse } from 'axios';

    export class AuthenticatedApiClient extends BaseApiClient {
      constructor(config: ApiClientConfig, private authStrategy: AuthStrategy) {
        super(config);
        this.setupInterceptors();
      }

      private setupInterceptors() {
        // Request interceptor delegates to the strategy to apply auth (e.g., add token)
        this.client.interceptors.request.use(
          (config) => this.authStrategy.applyAuth(config),
          (error) => Promise.reject(error)
        );

        // Response interceptor delegates to the strategy to handle auth errors (e.g., refresh token)
        this.client.interceptors.response.use(
          (response) => response,
          (error) => this.authStrategy.handleAuthError(error as AxiosError)
        );
      }
    }
    ```
  </Tab>
</Tabs>

Now, we can create and export instances for each API service your application needs to communicate with:

```typescript
// core/shared/api/clients.ts (continued - Instantiation Example)
// Ensure necessary classes (PublicApiClient, AuthenticatedApiClient, Strategies) and services (tokenService, oauthService) are imported.
// import { PublicApiClient } from './public'; 
// import { AuthenticatedApiClient } from './authenticated'; 
// import { BearerTokenStrategy, ApiKeyStrategy, OAuth2Strategy } from './auth-strategies';
// import { tokenService } from '@/core/domains/auth/tokenService';
// import { oauthService } from '@/core/domains/auth/oauthService'; // Example service
// import { ApiClientConfig } from './base';

// Example: Main API with bearer token auth
export const mainApi = {
  public: new PublicApiClient({
    baseURL: process.env.MAIN_API_URL,
  }),
  authenticated: new AuthenticatedApiClient(
    { baseURL: process.env.MAIN_API_URL },
    new BearerTokenStrategy(tokenService)
  ),
};

// Example: Payment API with API key auth
export const paymentApi = new AuthenticatedApiClient(
  { baseURL: process.env.PAYMENT_API_URL },
  new ApiKeyStrategy(process.env.PAYMENT_API_KEY!)
);

// Example: Analytics API with OAuth2
// const oauthService = new YourOAuthService(); // Instantiate your OAuth service
export const analyticsApi = new AuthenticatedApiClient(
  { baseURL: process.env.ANALYTICS_API_URL },
  new OAuth2Strategy(oauthService) // oauthService needs to be defined/imported
);

// Example: A third-party API that is public
export const thirdPartyApi = new PublicApiClient({
  baseURL: 'https://api.thirdparty.com',
  headers: {
    'Accept': 'application/json',
    'X-Client-Version': '1.0.0',
  },
});
```

### 4. Domain-Specific Implementations

Once you have specific client instances (like `paymentApi` or `analyticsApi`), you would use them within your domain-specific API service files to define the actual methods your application will call. Here are a couple of examples:

```typescript
// Conceptual path: core/domains/payment/api.ts
import { paymentApi } from '@/core/shared/api/clients'; // Assuming 'paymentApi' is exported from your client instances file

export const paymentDomainApi = {
  createPaymentIntent: async (amount: number, currency: string) => {
    const { data } = await paymentApi.post('/payment-intents', {
      amount,
      currency,
    });
    return data;
  },

  confirmPayment: async (paymentIntentId: string) => {
    const { data } = await paymentApi.post(`/payment-intents/${paymentIntentId}/confirm`);
    return data;
  },

  getPaymentMethods: async () => {
    const { data } = await paymentApi.get('/payment-methods');
    return data;
  },
};
```

```typescript
// Conceptual path: core/domains/analytics/api.ts
import { analyticsApi } from '@/core/shared/api/clients'; // Assuming 'analyticsApi' is exported from your client instances file
// import { AnalyticsEvent } from './types'; // Assuming AnalyticsEvent type definition

export const analyticsDomainApi = {
  trackEvent: async (event: any /* AnalyticsEvent */) => { // Using 'any' as AnalyticsEvent is not defined in this snippet
    await analyticsApi.post('/events', event);
  },

  getUserMetrics: async (userId: string) => {
    const { data } = await analyticsApi.get(`/users/${userId}/metrics`);
    return data;
  },
};
```

### 5. Environment-Specific Configuration

```typescript
// core/shared/api/config.ts
export const API_CONFIGS = {
  development: {
    mainApi: {
      baseURL: 'http://localhost:3000/api',
      timeout: 60000, // Longer timeout for dev
    },
    paymentApi: {
      baseURL: 'https://sandbox.payment.com/api',
    },
    analyticsApi: {
      baseURL: 'https://dev.analytics.com/api',
    },
  },
  staging: {
    mainApi: {
      baseURL: 'https://staging-api.myapp.com',
      timeout: 30000,
    },
    paymentApi: {
      baseURL: 'https://sandbox.payment.com/api',
    },
    analyticsApi: {
      baseURL: 'https://staging.analytics.com/api',
    },
  },
  production: {
    mainApi: {
      baseURL: 'https://api.myapp.com',
      timeout: 15000,
    },
    paymentApi: {
      baseURL: 'https://api.payment.com',
    },
    analyticsApi: {
      baseURL: 'https://analytics.com/api',
    },
  },
};

// Use environment-specific config
const config = API_CONFIGS[process.env.NODE_ENV];

export const apis = {
  main: {
    public: new PublicApiClient(config.mainApi),
    authenticated: new AuthenticatedApiClient(
      config.mainApi,
      new BearerTokenStrategy(tokenService)
    ),
  },
  payment: new AuthenticatedApiClient(
    config.paymentApi,
    new ApiKeyStrategy(process.env.PAYMENT_API_KEY)
  ),
  analytics: new AuthenticatedApiClient(
    config.analyticsApi,
    new OAuth2Strategy(oauthService)
  ),
};
```

### 6. Error Handling per Service

When dealing with multiple API services, it's often beneficial to have service-specific error types that can extend a common base `ApiError`. This allows for more granular error handling and identification of which service an error originated from.

**Error Class Definitions:**

The following classes would typically reside in a shared error definitions file, for example, `core/shared/api/errors.ts`.

```typescript
// Conceptual path: core/shared/api/errors.ts
export class ApiError extends Error {
  constructor(
    message: string,
    public status: number,
    public service: string, // Added to identify the service
    public originalError?: any
  ) {
    super(message);
    this.name = 'ApiError';
  }
}

// Specific error handlers that extend the base ApiError
export class PaymentApiError extends ApiError {
  constructor(message: string, status: number, public code?: string) {
    super(message, status, 'payment', /* pass originalError if available */);
  }
}

export class AnalyticsApiError extends ApiError {
  constructor(message: string, status: number) {
    super(message, status, 'analytics', /* pass originalError if available */);
  }
}
```

**Example Usage in a Domain API:**

This shows how `PaymentApiError` could be thrown from within a payment domain method.

```typescript
// Conceptual path: core/domains/payment/api.ts (Example snippet)
// import { paymentApi } from '@/core/shared/api/clients'; // Assuming 'paymentApi' is available
// import { PaymentApiError } from '@/core/shared/api/errors'; // Assuming import of the error class

export const paymentDomainApi = {
  createPaymentIntent: async (amount: number, currency: string) => {
    try {
      // const { data } = await paymentApi.post('/payment-intents', { // paymentApi would be used here
      //   amount,
      //   currency,
      // });
      // return data;
      throw { response: { status: 402 } }; // Simulating an error for example purposes
    } catch (error: any) { // Typed error as any for example flexibility
      if (error.response?.status === 402) {
        throw new PaymentApiError(
          'Insufficient funds',
          402,
          'insufficient_funds'
        );
      }
      // For other errors, you might re-throw or use a more generic error handler
      throw error; 
    }
  },
};
```

### 7. Monitoring and Logging

```typescript
// core/shared/api/middleware.ts
export class LoggingInterceptor {
  static request(config: AxiosRequestConfig) {
    console.log(`[API] ${config.method?.toUpperCase()} ${config.url}`);
    return config;
  }

  static response(response: AxiosResponse) {
    console.log(`[API] Response ${response.status} from ${response.config.url}`);
    return response;
  }

  static error(error: AxiosError) {
    console.error(`[API] Error ${error.response?.status} from ${error.config?.url}`);
    return Promise.reject(error);
  }
}

// Apply to specific clients
export class MonitoredApiClient extends AuthenticatedApiClient {
  constructor(config: ApiClientConfig, authStrategy: AuthStrategy) {
    super(config, authStrategy);
    
    // Add monitoring
    this.client.interceptors.request.use(LoggingInterceptor.request);
    this.client.interceptors.response.use(
      LoggingInterceptor.response,
      LoggingInterceptor.error
    );
  }
}
```

### 8. Testing with Multiple APIs

```typescript
// __tests__/api/multi-api.test.ts
import { mainApi, paymentApi, analyticsApi } from '@/core/shared/api/clients';
import MockAdapter from 'axios-mock-adapter';

describe('Multi-API Architecture', () => {
  let mainMock: MockAdapter;
  let paymentMock: MockAdapter;
  let analyticsMock: MockAdapter;

  beforeEach(() => {
    mainMock = new MockAdapter(mainApi.authenticated.client);
    paymentMock = new MockAdapter(paymentApi.client);
    analyticsMock = new MockAdapter(analyticsApi.client);
  });

  it('should handle different authentication strategies', async () => {
    // Main API uses Bearer token
    mainMock.onGet('/users/me').reply((config) => {
      expect(config.headers.Authorization).toMatch(/^Bearer /);
      return [200, { id: '123' }];
    });

    // Payment API uses API key
    paymentMock.onPost('/charges').reply((config) => {
      expect(config.headers['X-API-Key']).toBeDefined();
      return [200, { chargeId: 'ch_123' }];
    });

    // Test each API
    await mainApi.authenticated.get('/users/me');
    await paymentApi.post('/charges', { amount: 100 });
  });
});
```

## Benefits of This Scalable Approach

1. **Service Isolation**: Each API has its own client instance and configuration
2. **Authentication Flexibility**: Different auth strategies per service
3. **Environment Management**: Easy to switch between dev/staging/prod
4. **Error Handling**: Service-specific error types and handling
5. **Type Safety**: Full TypeScript support across all APIs
6. **Testability**: Can mock each API independently
7. **Monitoring**: Add logging/metrics per service
8. **Maintainability**: Clear separation of concerns

## Design Principles

### Core Architectural Principles

1. **Polymorphic API Client Interfaces**
   * Each API client shares common interface but may have unique implementation
   * Authentication strategies can be swapped without changing client code
   * Error handling adapted to each service's specific requirements

2. **Strategy Pattern for Authentication**
   * Authentication logic encapsulated in strategy objects
   * Clients delegate authentication to the appropriate strategy
   * New auth mechanisms can be added without modifying existing clients

3. **Environment-Based Configuration**
   * Configuration driven by environment rather than hardcoded
   * Clear separation between development, staging, and production environments
   * No code changes required when moving between environments

### Trade-offs and Design Decisions

| Decision                    | Benefits                                            | Drawbacks                                  | Rationale                                                         |
| --------------------------- | --------------------------------------------------- | ------------------------------------------ | ----------------------------------------------------------------- |
| Strategy pattern for auth   | Easily add new auth methods, cleaner code           | More classes and interfaces                | Provides flexibility as app grows and adds more external services |
| Service-specific clients    | Clean domain boundaries, appropriate error handling | More boilerplate compared to single client | Different APIs have different requirements and error structures   |
| Environment config objects  | Single source of truth for all environments         | Larger config files                        | Simplifies deployment and environment switching                   |
| Base client with extensions | Reduces code duplication                            | Can lead to inheritance issues             | Balance between code reuse and flexibility                        |

### Constraints and Considerations

* Each client should handle its own rate limiting and backoff strategies
* Environment-specific configuration should never be committed with sensitive keys
* Error handling must be customized per service but follow consistent patterns
* Authentication state must be properly synchronized across clients when tokens refresh

## Implementation Considerations

### Performance Implications

* **Client Initialization**: Initialize clients lazily when first needed, not all at startup
* **Request Batching**: Group multiple calls to the same service when possible
* **Caching Strategy**: Implement appropriate caching per API based on data volatility
* **Header Optimization**: Minimize custom headers to reduce request size

### Security Considerations

* **API Key Storage**: Environment variables for development, secure storage for production
* **Token Refresh**: Ensure secure handling of refresh tokens across different services
* **Error Exposure**: Filter sensitive information from error messages before logging
* **Certificate Management**: Properly manage client certificates for secure services

### Scalability Aspects

* The architecture scales easily with additional services
* New authentication strategies can be implemented without disrupting existing ones
* Domain-specific wrappers provide clear boundaries as the application grows
* Environment configuration system adapts well to new deployment targets

## Related Documents

* [API Client Architecture](/docs/api/client-architecture) - Core client implementation details
* [Authentication Architecture](/docs/api/authentication) - Token management and auth flows
* [Error Handling](/docs/api/error-handling) - Global and service-specific error handling
* [Request Queueing](/docs/api/request-queueing) - Queue mechanism for auth token refresh

## Migration Strategy

To migrate to this multi-API architecture:

1. Start with your main API using the pattern
2. Add new API services one at a time
3. Implement appropriate auth strategies
4. Update domains to use specific API clients
5. Add monitoring and error handling
6. Update tests for each service

By adopting this scalable architecture, our team can confidently integrate with multiple API services while maintaining a clean, organized, and maintainable codebase.


# UTA API Integration: Error Handling Architecture
URL: https://dev.updatetheapp.com/docs/api/error-handling
Documentation: https://dev.updatetheapp.com/docs/api/error-handling

Comprehensive error handling patterns and custom error classes for the application
        
***

title: Error Handling Architecture
description: Comprehensive error handling patterns and custom error classes for the application
-----------------------------------------------------------------------------------------------

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';

# Error Handling Architecture

## Overview

This document defines our error handling strategy, including custom error classes, error propagation patterns, and user-friendly error messages. Consistent error handling improves debugging, user experience, and app reliability. Our approach implements a hierarchical class structure with propagation mechanisms to ensure errors are caught, processed, and presented appropriately throughout the application.

## Purpose & Scope

This guide outlines:

* The custom error class hierarchy used across the application.
* Standardized error codes and HTTP status mappings.
* Patterns for handling and transforming errors at different layers (API, Domain, UI).
* Best practices for logging, monitoring, and displaying errors to users.

## Prerequisites

To effectively understand and implement the error handling patterns described here, readers should be familiar with:

* **JavaScript Error Handling**: Fundamentals of `Error` objects, `try...catch` blocks, and error propagation in JavaScript/TypeScript.
* **HTTP Status Codes**: A basic understanding of common HTTP status codes and their meanings (e.g., 2xx, 4xx, 5xx series).
* **API Client (Recommended)**: Familiarity with the project's [API Client Architecture](/docs/api/client-architecture) can be helpful to understand how API errors are initially caught and processed, especially regarding the `handleApiError` utility.
* **Logging/Monitoring Tools (Contextual)**: While not mandatory for understanding the error classes, awareness of any project-specific logging or crash reporting tools (e.g., Crashlytics, Sentry) will provide context for the error logging examples.

## Constants Organization

Our error handling system relies on a structured set of constants for error codes, HTTP status codes, and API configurations. These are typically organized as follows:

<Tabs items={["index.ts (Entry Point)", "errorCodes.ts", "apiConstants.ts"]}>
  <Tab>
    `index.ts` serves as the barrel file for exporting all constants from this module.

    ```typescript
    // core/shared/constants/index.ts
    export * from './httpStatusCodes';
    export * from './errorCodes';
    export * from './apiConstants';
    ```
  </Tab>

  <Tab>
    `errorCodes.ts` defines a comprehensive list of specific error codes used throughout the application.

    ```typescript
    // core/shared/constants/errorCodes.ts
    export const ERROR_CODES = {
      // Network errors
      NO_INTERNET_CONNECTION: 'NO_INTERNET_CONNECTION',
      REQUEST_TIMEOUT: 'REQUEST_TIMEOUT',
      NETWORK_ERROR: 'NETWORK_ERROR',
      
      // Authentication errors
      AUTH_ERROR: 'AUTH_ERROR',
      INVALID_CREDENTIALS: 'INVALID_CREDENTIALS',
      SESSION_EXPIRED: 'SESSION_EXPIRED',
      REFRESH_TOKEN_EXPIRED: 'REFRESH_TOKEN_EXPIRED',
      UNAUTHORIZED: 'UNAUTHORIZED',
      
      // Validation errors
      VALIDATION_ERROR: 'VALIDATION_ERROR',
      FORM_VALIDATION_ERROR: 'FORM_VALIDATION_ERROR',
      
      // Business logic errors
      INSUFFICIENT_BALANCE: 'INSUFFICIENT_BALANCE',
      DUPLICATE_RESOURCE: 'DUPLICATE_RESOURCE',
      RESOURCE_LOCKED: 'RESOURCE_LOCKED',
      
      // Storage errors
      STORAGE_ERROR: 'STORAGE_ERROR',
      STORAGE_QUOTA_EXCEEDED: 'STORAGE_QUOTA_EXCEEDED',
      STORAGE_PERMISSION_DENIED: 'STORAGE_PERMISSION_DENIED',
      
      // API errors
      API_RESPONSE_ERROR: 'API_RESPONSE_ERROR',
      RATE_LIMIT_ERROR: 'RATE_LIMIT_ERROR',
      MAINTENANCE_MODE: 'MAINTENANCE_MODE',
    } as const;

    export type ErrorCode = typeof ERROR_CODES[keyof typeof ERROR_CODES];
    ```
  </Tab>

  <Tab>
    `apiConstants.ts` provides constants related to API interactions, like timeouts and retry configurations.

    ```typescript
    // core/shared/constants/apiConstants.ts
    export const API_TIMEOUTS = {
      DEFAULT: 30000, // 30 seconds
      UPLOAD: 300000, // 5 minutes
      DOWNLOAD: 300000, // 5 minutes
      SHORT: 10000, // 10 seconds
    } as const;

    export const RETRY_CONFIG = {
      MAX_ATTEMPTS: 3,
      INITIAL_DELAY: 1000, // 1 second
      MAX_DELAY: 10000, // 10 seconds
      BACKOFF_FACTOR: 2,
    } as const;
    ```
  </Tab>
</Tabs>

## Status Code Constants

```typescript
// core/shared/constants/httpStatusCodes.ts
export const HTTP_STATUS = {
  // Success responses
  OK: 200,
  CREATED: 201,
  ACCEPTED: 202,
  NO_CONTENT: 204,
  
  // Redirection messages
  MOVED_PERMANENTLY: 301,
  FOUND: 302,
  NOT_MODIFIED: 304,
  
  // Client error responses
  BAD_REQUEST: 400,
  UNAUTHORIZED: 401,
  FORBIDDEN: 403,
  NOT_FOUND: 404,
  METHOD_NOT_ALLOWED: 405,
  CONFLICT: 409,
  UNPROCESSABLE_ENTITY: 422,
  TOO_MANY_REQUESTS: 429,
  
  // Server error responses
  INTERNAL_SERVER_ERROR: 500,
  NOT_IMPLEMENTED: 501,
  BAD_GATEWAY: 502,
  SERVICE_UNAVAILABLE: 503,
  GATEWAY_TIMEOUT: 504,
} as const;

export type HttpStatusCode = typeof HTTP_STATUS[keyof typeof HTTP_STATUS];

// Semantic aliases for better readability
export const API_STATUS = {
  SUCCESS: HTTP_STATUS.OK,
  CREATED: HTTP_STATUS.CREATED,
  INVALID_REQUEST: HTTP_STATUS.BAD_REQUEST,
  NEEDS_AUTH: HTTP_STATUS.UNAUTHORIZED,
  ACCESS_DENIED: HTTP_STATUS.FORBIDDEN,
  NOT_FOUND: HTTP_STATUS.NOT_FOUND,
  DUPLICATE: HTTP_STATUS.CONFLICT,
  VALIDATION_ERROR: HTTP_STATUS.UNPROCESSABLE_ENTITY,
  RATE_LIMITED: HTTP_STATUS.TOO_MANY_REQUESTS,
  SERVER_ERROR: HTTP_STATUS.INTERNAL_SERVER_ERROR,
  MAINTENANCE: HTTP_STATUS.SERVICE_UNAVAILABLE,
} as const;

// Helper functions
export const isSuccessStatus = (status: number): boolean => 
  status >= 200 && status < 300;

export const isClientError = (status: number): boolean => 
  status >= 400 && status < 500;

export const isServerError = (status: number): boolean => 
  status >= 500;
```

## Error Class Hierarchy

<Mermaid
  chart={`
classDiagram
class Error {
  <<JavaScript>>
  +name: string
  +message: string
  +stack: string
}

class ExtendableError {
  +timestamp: Date
  +code: string
  +statusCode?: number
  +data?: any
  +toJSON()
}

class NetworkError {
  <<Abstract>>
}

class ApiResponseError {
  +endpoint: string
  +responseData?: any
}

class AuthenticationError {
  <<Domain>>
}

class ValidationError {
  +fields: ValidationErrorField[]
  +addFieldError()
  +hasFieldError()
  +getFieldError()
}

class BusinessLogicError {
  <<Domain>>
}

class StorageError {
  <<Infrastructure>>
}

Error <|-- ExtendableError
ExtendableError <|-- NetworkError
ExtendableError <|-- ApiResponseError
ExtendableError <|-- AuthenticationError
ExtendableError <|-- ValidationError
ExtendableError <|-- BusinessLogicError
ExtendableError <|-- StorageError

NetworkError <|-- NoInternetConnectionError
NetworkError <|-- RequestTimeoutError

ApiResponseError <|-- ResponseMaintenanceModeError
ApiResponseError <|-- ResponseRateLimitError
ApiResponseError <|-- ResponseNotFoundError

AuthenticationError <|-- RefreshTokenExpiredError
AuthenticationError <|-- InvalidCredentialsError
AuthenticationError <|-- SessionExpiredError
AuthenticationError <|-- UnauthorizedError

ValidationError <|-- FormValidationError

BusinessLogicError <|-- InsufficientBalanceError
BusinessLogicError <|-- DuplicateResourceError
BusinessLogicError <|-- ResourceLockedError

StorageError <|-- StorageQuotaExceededError
StorageError <|-- StoragePermissionDeniedError
`}
/>

### Base Error Class

```typescript
// core/shared/errors/ExtendableError.ts
export class ExtendableError extends Error {
  public readonly timestamp: Date;
  public readonly code: string;
  public readonly statusCode?: number;
  public readonly data?: any;

  constructor(
    message: string,
    code: string,
    statusCode?: number,
    data?: any
  ) {
    super(message);
    this.name = this.constructor.name;
    this.code = code;
    this.statusCode = statusCode;
    this.data = data;
    this.timestamp = new Date();

    // Maintains proper stack trace for where error was thrown
    Error.captureStackTrace(this, this.constructor);
  }

  toJSON() {
    return {
      name: this.name,
      message: this.message,
      code: this.code,
      statusCode: this.statusCode,
      data: this.data,
      timestamp: this.timestamp,
      stack: this.stack,
    };
  }
}
```

## Network Error Classes

### No Internet Connection Error

```typescript
// core/shared/errors/NoInternetConnectionError.ts
import { ExtendableError } from './ExtendableError';

export class NoInternetConnectionError extends ExtendableError {
  constructor(message: string = 'No internet connection available') {
    super(message, 'NO_INTERNET_CONNECTION');
  }
}
```

### Request Timeout Error

```typescript
// core/shared/errors/RequestTimeoutError.ts
import { ExtendableError } from './ExtendableError';
import { HTTP_STATUS } from '@/core/shared/constants/httpStatusCodes';

export class RequestTimeoutError extends ExtendableError {
  constructor(
    url: string,
    timeout: number,
    message?: string
  ) {
    super(
      message || `Request to ${url} timed out after ${timeout}ms`,
      'REQUEST_TIMEOUT',
      HTTP_STATUS.REQUEST_TIMEOUT
    );
  }
}
```

### API Response Errors

```typescript
// core/shared/errors/ApiResponseError.ts
import { ExtendableError } from './ExtendableError';

export class ApiResponseError extends ExtendableError {
  constructor(
    message: string,
    statusCode: number,
    endpoint: string,
    responseData?: any
  ) {
    super(
      message,
      'API_RESPONSE_ERROR',
      statusCode,
      { endpoint, responseData }
    );
  }
}

// Specific API response errors
export class ResponseMaintenanceModeError extends ApiResponseError {
  constructor(endpoint: string, retryAfter?: number) {
    super(
      'Service is currently under maintenance',
      503,
      endpoint,
      { retryAfter }
    );
  }
}

export class ResponseRateLimitError extends ApiResponseError {
  constructor(endpoint: string, retryAfter: number) {
    super(
      'Rate limit exceeded',
      429,
      endpoint,
      { retryAfter }
    );
  }
}

export class ResponseNotFoundError extends ApiResponseError {
  constructor(resource: string, id?: string) {
    super(
      `${resource} not found`,
      404,
      resource,
      { id }
    );
  }
}
```

## Authentication Error Classes

```typescript
// core/shared/errors/AuthenticationError.ts
import { ExtendableError } from './ExtendableError';
import { HTTP_STATUS } from '@/core/shared/constants/httpStatusCodes';

export class AuthenticationError extends ExtendableError {
  constructor(
    message: string,
    code: string = 'AUTH_ERROR',
    statusCode: number = HTTP_STATUS.UNAUTHORIZED
  ) {
    super(message, code, statusCode);
  }
}

export class RefreshTokenExpiredError extends AuthenticationError {
  constructor() {
    super(
      'Refresh token has expired. Please login again.',
      'REFRESH_TOKEN_EXPIRED',
      HTTP_STATUS.UNAUTHORIZED
    );
  }
}

export class InvalidCredentialsError extends AuthenticationError {
  constructor() {
    super(
      'Invalid email or password',
      'INVALID_CREDENTIALS',
      HTTP_STATUS.UNAUTHORIZED
    );
  }
}

export class SessionExpiredError extends AuthenticationError {
  constructor() {
    super(
      'Your session has expired. Please login again.',
      'SESSION_EXPIRED',
      HTTP_STATUS.UNAUTHORIZED
    );
  }
}

export class UnauthorizedError extends AuthenticationError {
  constructor(resource?: string) {
    super(
      `You don't have permission to access ${resource || 'this resource'}`,
      'UNAUTHORIZED',
      HTTP_STATUS.FORBIDDEN
    );
  }
}
```

## Validation Error Classes

```typescript
// core/shared/errors/ValidationError.ts
import { ExtendableError } from './ExtendableError';
import { HTTP_STATUS } from '@/core/shared/constants/httpStatusCodes';

export interface ValidationErrorField {
  field: string;
  message: string;
  value?: any;
}

export class ValidationError extends ExtendableError {
  public readonly fields: ValidationErrorField[];

  constructor(
    message: string = 'Validation failed',
    fields: ValidationErrorField[] = []
  ) {
    super(message, 'VALIDATION_ERROR', HTTP_STATUS.BAD_REQUEST, { fields });
    this.fields = fields;
  }

  addFieldError(field: string, message: string, value?: any) {
    this.fields.push({ field, message, value });
  }

  hasFieldError(field: string): boolean {
    return this.fields.some(f => f.field === field);
  }

  getFieldError(field: string): ValidationErrorField | undefined {
    return this.fields.find(f => f.field === field);
  }
}

export class FormValidationError extends ValidationError {
  constructor(fields: ValidationErrorField[]) {
    super('Please correct the errors in the form', fields);
  }
}
```

## Business Logic Errors

```typescript
// core/shared/errors/BusinessLogicError.ts
import { ExtendableError } from './ExtendableError';
import { HTTP_STATUS } from '@/core/shared/constants/httpStatusCodes';

export class BusinessLogicError extends ExtendableError {
  constructor(
    message: string,
    code: string,
    data?: any
  ) {
    super(message, code, HTTP_STATUS.UNPROCESSABLE_ENTITY, data);
  }
}

export class InsufficientBalanceError extends BusinessLogicError {
  constructor(required: number, available: number) {
    super(
      `Insufficient balance. Required: ${required}, Available: ${available}`,
      'INSUFFICIENT_BALANCE',
      { required, available }
    );
  }
}

export class DuplicateResourceError extends BusinessLogicError {
  constructor(resource: string, field: string, value: any) {
    super(
      `${resource} with ${field} '${value}' already exists`,
      'DUPLICATE_RESOURCE',
      { resource, field, value }
    );
  }
}

export class ResourceLockedError extends BusinessLogicError {
  constructor(resource: string, reason?: string) {
    super(
      `${resource} is currently locked${reason ? `: ${reason}` : ''}`,
      'RESOURCE_LOCKED',
      { resource, reason }
    );
  }
}
```

## Storage Errors

```typescript
// core/shared/errors/StorageError.ts
import { ExtendableError } from './ExtendableError';

export class StorageError extends ExtendableError {
  constructor(
    message: string,
    code: string = 'STORAGE_ERROR',
    data?: any
  ) {
    super(message, code, undefined, data);
  }
}

export class StorageQuotaExceededError extends StorageError {
  constructor(required: number, available: number) {
    super(
      'Storage quota exceeded',
      'STORAGE_QUOTA_EXCEEDED',
      { required, available }
    );
  }
}

export class StoragePermissionDeniedError extends StorageError {
  constructor() {
    super(
      'Storage permission denied',
      'STORAGE_PERMISSION_DENIED'
    );
  }
}
```

## Error Handling Flow

<Mermaid
  chart={`
flowchart TD
subgraph API[API Layer]
  ApiRequest[API Request]
  ErrorHandler[Error Handler]
  ErrorTransformer[Error Transformer]
end

subgraph Domain[Domain Layer]
  DomainLogic[Domain Logic]
  DomainService[Domain Service]
end

subgraph UI[UI Layer]
  Component[UI Component]
  ErrorBoundary[Error Boundary]
  ErrorDisplay[Error Display]
end

subgraph Monitoring[Monitoring]
  ErrorLogger[Error Logger]
  Analytics[Analytics Service]
  Crashlytics[Crashlytics]
end

ApiRequest -->|Error occurs| ErrorHandler
ErrorHandler -->|Transform| ErrorTransformer
ErrorTransformer -->|Domain-specific error| DomainService
ErrorTransformer -->|Business logic error| DomainLogic
DomainService -->|Propagate| Component
DomainLogic -->|Propagate| Component

Component -->|Handle locally| ErrorDisplay
Component -->|Unhandled error| ErrorBoundary

ErrorHandler -->|Log| ErrorLogger
ErrorDisplay -->|Log| ErrorLogger
ErrorBoundary -->|Log| ErrorLogger

ErrorLogger -->|Record| Analytics
ErrorLogger -->|Record| Crashlytics

style ErrorHandler fill:#f96,stroke:#333,stroke-width:2px
style ErrorLogger fill:#96f,stroke:#333,stroke-width:2px
style ErrorBoundary fill:#9af,stroke:#333,stroke-width:2px
`}
/>

## Error Handling in API Client

```typescript
// core/shared/api/errorHandler.ts
import { AxiosError } from 'axios';
import { HTTP_STATUS } from '@/core/shared/constants/httpStatusCodes';
import {
  NoInternetConnectionError,
  RequestTimeoutError,
  ResponseMaintenanceModeError,
  ResponseRateLimitError,
  RefreshTokenExpiredError,
  UnauthorizedError,
  ValidationError,
  ApiResponseError,
} from '@/core/shared/errors';

export function handleApiError(error: AxiosError): never {
  // No internet connection
  if (!error.response && error.code === 'NETWORK_ERROR') {
    throw new NoInternetConnectionError();
  }

  // Request timeout
  if (error.code === 'ECONNABORTED') {
    throw new RequestTimeoutError(
      error.config?.url || 'Unknown',
      error.config?.timeout || 30000
    );
  }

  // Handle specific response status codes
  if (error.response) {
    const { status, data } = error.response;
    const endpoint = error.config?.url || 'Unknown';

    switch (status) {
      case HTTP_STATUS.BAD_REQUEST:
        if (data.errors) {
          throw new ValidationError('Validation failed', data.errors);
        }
        break;

      case HTTP_STATUS.UNAUTHORIZED:
        if (data.code === 'REFRESH_TOKEN_EXPIRED') {
          throw new RefreshTokenExpiredError();
        }
        throw new UnauthorizedError();

      case HTTP_STATUS.FORBIDDEN:
        throw new UnauthorizedError(data.resource);

      case HTTP_STATUS.NOT_FOUND:
        throw new ResponseNotFoundError(data.resource, data.id);

      case HTTP_STATUS.TOO_MANY_REQUESTS:
        throw new ResponseRateLimitError(endpoint, data.retryAfter);

      case HTTP_STATUS.SERVICE_UNAVAILABLE:
        throw new ResponseMaintenanceModeError(endpoint, data.retryAfter);

      default:
        throw new ApiResponseError(
          data.message || 'An error occurred',
          status,
          endpoint,
          data
        );
    }
  }

  // Default error
  throw error;
}
```

## Error Handling in Domain APIs

```typescript
// core/domains/products/api.ts
import { handleApiError } from '@/core/shared/api/errorHandler';
import { DuplicateResourceError } from '@/core/shared/errors';
import { HTTP_STATUS } from '@/core/shared/constants/httpStatusCodes';

class ProductApi {
  public readonly protected = {
    create: async (product: CreateProductDto): Promise<Product> => {
      try {
        return await authenticatedApi.post('/products', product);
      } catch (error) {
        // Handle domain-specific errors
        if (error.response?.status === HTTP_STATUS.CONFLICT) {
          throw new DuplicateResourceError(
            'Product',
            'name',
            product.name
          );
        }
        
        // Use centralized error handler for other errors
        return handleApiError(error);
      }
    },
  };
}
```

## Error Handling in UI Components

```typescript
// features/products/screens/CreateProductScreen.tsx
import { useCreateProduct } from '@/core/domains/products/hooks';
import {
  ValidationError,
  DuplicateResourceError,
  NoInternetConnectionError,
} from '@/core/shared/errors';

export function CreateProductScreen() {
  const createProduct = useCreateProduct();
  const [errors, setErrors] = useState<Record<string, string>>({});

  const handleSubmit = async (data: ProductFormData) => {
    try {
      await createProduct.mutateAsync(data);
      navigation.goBack();
    } catch (error) {
      if (error instanceof ValidationError) {
        // Show field-specific errors
        const fieldErrors: Record<string, string> = {};
        error.fields.forEach(field => {
          fieldErrors[field.field] = field.message;
        });
        setErrors(fieldErrors);
      } else if (error instanceof DuplicateResourceError) {
        Alert.alert(
          'Product Already Exists',
          'A product with this name already exists.'
        );
      } else if (error instanceof NoInternetConnectionError) {
        Alert.alert(
          'No Internet',
          'Please check your internet connection and try again.'
        );
      } else {
        // Generic error handling
        Alert.alert(
          'Error',
          error.message || 'An unexpected error occurred'
        );
      }
    }
  };

  return (
    <Form onSubmit={handleSubmit}>
      <TextInput
        label="Product Name"
        error={errors.name}
        onChangeText={() => setErrors({ ...errors, name: undefined })}
      />
      {/* Other form fields */}
    </Form>
  );
}
```

## Global Error Boundary

```typescript
// App.tsx
import { ErrorBoundary } from 'react-error-boundary';
import { ExtendableError } from '@/core/shared/errors';

function ErrorFallback({ error, resetErrorBoundary }) {
  // Log error to crash reporting service
  if (__DEV__) {
    console.error('Error caught by boundary:', error);
  } else {
    crashlytics().recordError(error);
  }

  return (
    <View style={styles.container}>
      <Text style={styles.title}>Oops! Something went wrong</Text>
      <Text style={styles.message}>
        {error instanceof ExtendableError
          ? error.message
          : 'An unexpected error occurred'}
      </Text>
      <Button title="Try Again" onPress={resetErrorBoundary} />
    </View>
  );
}

export function App() {
  return (
    <ErrorBoundary
      FallbackComponent={ErrorFallback}
      onReset={() => {
        // Reset app state if needed
      }}
    >
      <AppContent />
    </ErrorBoundary>
  );
}
```

## Error Logging and Monitoring

```typescript
// core/shared/services/errorLogger.ts
import crashlytics from '@react-native-firebase/crashlytics';
import analytics from '@react-native-firebase/analytics';
import { ExtendableError } from '@/core/shared/errors';

export class ErrorLogger {
  static logError(error: Error, context?: Record<string, any>) {
    if (__DEV__) {
      console.error('Error:', error, context);
      return;
    }

    // Log to crash reporting
    if (error instanceof ExtendableError) {
      crashlytics().recordError(error, {
        code: error.code,
        statusCode: error.statusCode,
        ...context,
      });
    } else {
      crashlytics().recordError(error);
    }

    // Log to analytics
    analytics().logEvent('error_occurred', {
      error_type: error.name,
      error_message: error.message,
      ...context,
    });
  }

  static logApiError(
    error: ExtendableError,
    endpoint: string,
    method: string
  ) {
    this.logError(error, {
      endpoint,
      method,
      api_error: true,
    });
  }
}
```

## Error Message Localization

```typescript
// core/shared/errors/errorMessages.ts
export const ERROR_MESSAGES = {
  NO_INTERNET_CONNECTION: {
    en: 'No internet connection available',
    es: 'No hay conexión a internet disponible',
    fr: 'Aucune connexion internet disponible',
  },
  SESSION_EXPIRED: {
    en: 'Your session has expired. Please login again.',
    es: 'Tu sesión ha expirado. Por favor inicia sesión nuevamente.',
    fr: 'Votre session a expiré. Veuillez vous reconnecter.',
  },
  // ... other messages
};

// Helper to get localized message
export function getErrorMessage(
  code: string,
  locale: string = 'en'
): string {
  return ERROR_MESSAGES[code]?.[locale] || ERROR_MESSAGES[code]?.en || code;
}
```

## Testing Error Scenarios

> **Note:** These error testing strategies integrate with our broader testing approach outlined in the [Testing Strategy](/docs/guides/testing) document. The error tests focus on unit testing individual error classes and integration testing error handling mechanisms, complementing the end-to-end tests that verify complete user flows during error conditions.

```typescript
// core/shared/errors/__tests__/errors.test.ts
describe('Error Classes', () => {
  it('should create NoInternetConnectionError correctly', () => {
    const error = new NoInternetConnectionError();
    
    expect(error.code).toBe('NO_INTERNET_CONNECTION');
    expect(error.message).toBe('Unable to connect to the internet');
    expect(error.timestamp instanceof Date).toBeTruthy();
  });
  
  it('should test ApiResponseError with error details', () => {
    const error = new ApiResponseError(
      'Bad Request', 
      400, 
      '/users', 
      { field: 'email', message: 'Invalid format' }
    );
    
    expect(error.code).toBe('API_RESPONSE_ERROR');
    expect(error.statusCode).toBe(400);
    expect(error.data).toBeDefined();
  });
  
  it('should test FormValidationError fields access', () => {
    const error = new FormValidationError([
      { field: 'email', message: 'Invalid email format' },
      { field: 'password', message: 'Password too short' }
    ]);
    
    expect(error.getFieldError('email')?.message).toBe('Invalid email format');
  });
});

// Test error handling in API
describe('API Error Handling', () => {
  it('should throw NoInternetConnectionError on network failure', async () => {
    const axiosError = new AxiosError('Network Error');
    axiosError.code = 'NETWORK_ERROR';
    
    expect(() => handleApiError(axiosError))
      .toThrow(NoInternetConnectionError);
  });
});
```

## Best Practices

To maintain a robust and understandable error handling system, we recommend adhering to the following best practices:

1. **(Do ✅) Use Specific Error Classes**: Create and use distinct error classes that inherit from `ExtendableError` for different categories of errors (e.g., `NetworkError`, `AuthenticationError`, `ValidationError`). This enables more precise `instanceof` checks, targeted error handling logic, and clearer intent in your code.
2. **(Do ✅) Include Rich Context**: When throwing or logging errors, ensure they carry as much relevant context as possible (e.g., `statusCode`, `errorCode`, `endpoint`, relevant data). This significantly aids in debugging and understanding the root cause of issues.
3. **(Do ✅) Provide User-Friendly Messages**: For errors that will be displayed to the user, craft messages that are clear, concise, and actionable, guiding them on what to do next or what went wrong in understandable terms. Avoid exposing raw technical error details directly to users.
4. **(Do ✅) Log Errors Comprehensively**: Implement thorough error logging with sufficient context (as per point 2) at appropriate layers. This is crucial for monitoring application health, identifying patterns, and diagnosing problems in development and production.
5. **(Do ✅) Handle Errors Gracefully**: Always ensure there are fallback mechanisms (like Error Boundaries in UI) to catch unexpected errors and prevent application crashes, providing a more stable user experience.
6. **(Do ✅) Test Error Paths Thoroughly**: Write unit and integration tests specifically for error scenarios to verify that your error handling logic behaves as expected under various failure conditions.
7. **(Do ✅) Localize User-Facing Error Messages**: If your application supports multiple languages, ensure that error messages displayed to users are properly localized for a better user experience globally.

## Design Principles

### Core Architectural Principles

1. **Hierarchical Organization**
   * Error classes follow a clear, logical inheritance hierarchy
   * Common behavior implemented in base classes
   * Specific behavior in specialized classes

2. **Contextual Information**
   * Errors carry detailed context about what went wrong
   * Status codes mapped to semantic error types
   * Supporting data attached to aid debugging

3. **Error Propagation**
   * Errors are transformed at system boundaries
   * Domain-specific errors remain isolated to their domains
   * Central error handling manages common error patterns

### Trade-offs and Design Decisions

| Decision                            | Benefits                         | Drawbacks                         | Rationale                                                      |
| ----------------------------------- | -------------------------------- | --------------------------------- | -------------------------------------------------------------- |
| Custom error classes                | Type-safe handling, rich context | More code to maintain             | Enables precise error handling patterns and better debugging   |
| Centralized error handler           | Consistent handling, DRY         | Potential single point of failure | Ensures consistent error transformation across the application |
| Error boundaries at component level | Graceful recovery, isolation     | More complex component structure  | Prevents entire app crashes due to UI errors                   |
| Typed error codes                   | Static analysis, auto-completion | Overhead in maintenance           | Makes error handling more robust and less prone to typos       |

### Constraints and Considerations

* All error messages must be localizable
* Error handling must work in offline scenarios
* Performance impact of try/catch blocks must be considered
* Sensitive information must never appear in error messages or logs

## Implementation Considerations

### Performance Implications

* **Error Creation**: Creating error objects with full stack traces can be expensive; optimize for production
* **Try/Catch Blocks**: Excessive try/catch can affect JavaScript engine optimization
* **Error Transformation**: Complex transformations should be avoided in critical paths
* **Logging**: Asynchronous logging prevents UI thread blocking

### Security Considerations

* **Sensitive Data**: Never include auth tokens, passwords or PII in error messages or logs
* **User Messages**: External-facing error messages should be sanitized
* **Stack Traces**: Never expose stack traces to end users
* **Input Validation**: Validate all inputs to prevent injection attacks through error messages

### Scalability Aspects

* **Error Categories**: The system supports adding new error categories without modifying core logic
* **Error Routing**: Error handling architecture supports routing errors to different handlers
* **Domain Isolation**: Domain-specific errors don't leak across boundaries
* **Monitoring**: Error tracking scales with automatically grouped similar errors

## Summary

This comprehensive error handling architecture provides:

* Clear error class hierarchy
* Specific errors for different scenarios
* Centralized error handling
* User-friendly error messages
* Proper error propagation
* Error logging and monitoring
* Localization support

## Related Documents

* [API Client Architecture](/docs/api/client-architecture) - Details on API client implementation
* [Authentication Architecture](/docs/api/authentication) - Details on authentication flows and how `authEvents` like `auth:sessionExpired` are emitted.
* [API Client with Request Queueing](/docs/api/request-queueing) - How the API client handles 401s internally with token refresh and request queueing before an error might propagate to the general `handleApiError`.
* [Communication Patterns](/docs/features/communication-patterns) - Error events propagation
* [Testing Strategy](/docs/guides/testing) - Testing error scenarios
* [Monitoring and Analytics](/docs/guides/monitoring-analytics)


# UTA API Integration: Header Customization Architecture
URL: https://dev.updatetheapp.com/docs/api/headers/header-customization
Documentation: https://dev.updatetheapp.com/docs/api/headers/header-customization

Architectural patterns for implementing and managing custom API headers across different use cases
        
***

title: Header Customization Architecture
description: Architectural patterns for implementing and managing custom API headers across different use cases
---------------------------------------------------------------------------------------------------------------

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Callout } from 'fumadocs-ui/components/callout';

# Header Customization Architecture

## Overview

This document outlines the architectural patterns for implementing custom headers in API requests. API headers provide critical context to backend services, enabling features like multi-tenancy, device tracking, session management, and request correlation.

Our approach integrates seamlessly with the established API client architecture while leveraging Zustand for state management, creating a flexible and maintainable system for header customization across the application.

## Purpose & Scope

This guide establishes:

* Core patterns for implementing custom API headers
* Integration with Zustand state management
* Extensible header provider architecture
* Decision framework for when to use different header types
* Testing strategies for header implementations

This document is intended for all developers working with API integrations and those needing to add custom contextual information to API requests.

## Quick Start

If you're looking to quickly implement custom headers in your API client, here's how to get started:

1. **Define your header constants**:
   ```typescript
   // core/shared/constants/headers.ts
   export const API_HEADERS = {
     ORGANIZATION_ID: 'X-ORG-ID',
     DEVICE_UUID: 'X-DEVICE-UUID'
   };
   ```

2. **Create a header provider**:
   ```typescript
   // core/domains/tenant/headerProvider.ts
   import { HeaderProvider } from '@/core/shared/api/headers/types';
   import { API_HEADERS } from '@/core/shared/constants/headers';
   import { useTenantStore } from './store';

   export class TenantHeaderProvider implements HeaderProvider {
     id = 'tenant';
     priority = 100;
     
     async getHeaders() {
       const { organizationId } = useTenantStore.getState();
       return {
         [API_HEADERS.ORGANIZATION_ID]: organizationId
       };
     }
   }
   ```

3. **Register with your API client**:
   ```typescript
   // In your API client setup
   const apiClient = new AuthenticatedApiClient(config);
   apiClient.registerHeaderProvider(new TenantHeaderProvider());
   ```

For more detailed implementation, continue reading the sections below.

## Prerequisites

To effectively use this guide, you should be familiar with:

* [API Client Architecture](/docs/api/client-architecture) - Our standard API client structure
* [Authentication Architecture](/docs/api/authentication) - How authentication headers are managed
* [Client State Management](/docs/state-management/client-state) - Zustand store patterns
* [Multi-API Setup](/docs/api/multi-api-setup) - For service-specific header configurations

## Architecture Overview

Custom headers are implemented through a combination of header providers, Zustand stores, and interceptors in our API client architecture:

<Mermaid
  chart={`
flowchart TD
  subgraph Client[React Native App]
    ZustandStores[Zustand Stores]
    HeaderProviders[Header Providers]
    BaseApiClient[BaseApiClient]
    Interceptors[Request Interceptors]
    DomainApis[Domain APIs]
  end
  
  subgraph Server[Backend Services]
    ApiEndpoints[API Endpoints]
    HeaderProcessing[Header Processing]
    BusinessLogic[Business Logic]
  end
  
  ZustandStores -->|Provide state| HeaderProviders
  HeaderProviders -->|Supply headers| Interceptors
  Interceptors -->|Add headers| BaseApiClient
  BaseApiClient -->|Send requests| ApiEndpoints
  DomainApis -->|Use| BaseApiClient
  ApiEndpoints -->|Extract headers| HeaderProcessing
  HeaderProcessing -->|Apply context| BusinessLogic
`}
/>

## Header Types and Use Cases

Different header types serve different purposes in your application:

| Header Type | Purpose                     | Examples                           | Priority |
| ----------- | --------------------------- | ---------------------------------- | -------- |
| Identity    | Identifies tenant context   | `X-ORG-ID`, `X-PROJECT-ID`         | High     |
| Device      | Provides device context     | `X-DEVICE-UUID`, `User-Agent`      | High     |
| Tracking    | Enables request correlation | `X-REQUEST-ID`, `X-CORRELATION-ID` | Medium   |
| Session     | Maintains session context   | `X-SESSION-ID`                     | Medium   |
| Feature     | Enables feature flags       | `X-FEATURE-FLAGS`                  | Low      |
| Debugging   | Provides debug information  | `X-DEBUG-MODE`                     | Low      |

<Callout type="info">
  Header priorities indicate their importance in the architecture. High-priority headers should be consistently implemented across all APIs, while low-priority headers might be optional or use-case specific.
</Callout>

## Core Components

### Conceptual Overview

Our header customization architecture consists of four main components working together:

1. **Header Providers**: Modular components that supply specific header values
2. **Zustand Stores**: State containers that hold header-related data
3. **Provider Registry**: System within BaseApiClient to register and manage providers
4. **Interceptor Integration**: Mechanism to apply headers to outgoing requests

## Implementation Guides

For detailed implementation examples of specific header types, refer to these guides:

<Cards>
  <Card title="Multi-Tenant Headers" href="/docs/api/headers/multi-tenant-headers" description="Implementation guide for organization and project context headers" />

  <Card title="Device Identification Headers" href="/docs/api/headers/device-identification" description="Implementation guide for device identification and tracking headers" />

  <Card title="Session Tracking Headers" href="/docs/api/headers/session-tracking" description="Implementation guide for session tracking and correlation headers" />

  <Card title="User Preferences Headers" href="/docs/api/headers/user-preferences-headers" description="Implementation guide for personalized user preference headers" />

  <Card title="User-Agent Headers" href="/docs/api/headers/user-agent-headers" description="Implementation guide for custom User-Agent headers" />
</Cards>

The remainder of this document details the core components of the header architecture that all these implementation guides build upon.

This architecture follows a plugin pattern, where different header providers can be registered with API clients, making the system highly extensible while maintaining a consistent implementation approach.

<Callout type="info">
  The header provider pattern creates a clear separation of concerns: state management is handled by Zustand stores, while the logic for transforming state into headers lives in providers.
</Callout>

### 1. Header Provider Interface

The foundation of our architecture is the `HeaderProvider` interface, which creates a consistent pattern for different header types:

```typescript
// core/shared/api/headers/types.ts
export interface HeaderProvider {
  /**
   * Retrieves headers to be added to API requests
   * @returns Promise resolving to a map of header names to values
   */
  getHeaders(): Promise<Record<string, string | undefined>>;
  
  /**
   * Priority level for this provider (higher numbers applied first)
   */
  priority: number;
  
  /**
   * Unique identifier for this provider
   */
  id: string;
}
```

### 2. Header Constants

Centralized constants ensure consistent header names across the application:

```typescript
// core/shared/constants/headers.ts
export const API_HEADERS = {
  // Identity headers
  ORGANIZATION_ID: 'X-ORG-ID',
  PROJECT_ID: 'X-PROJECT-ID',
  TENANT_ID: 'X-TENANT-ID',
  
  // Device headers
  DEVICE_UUID: 'X-DEVICE-UUID',
  DEVICE_TYPE: 'X-DEVICE-TYPE',
  APP_VERSION: 'X-APP-VERSION',
  
  // Tracking headers
  SESSION_ID: 'X-SESSION-ID',
  REQUEST_ID: 'X-REQUEST-ID',
  CORRELATION_ID: 'X-CORRELATION-ID',
  
  // Feature headers
  FEATURE_FLAGS: 'X-FEATURE-FLAGS',
  
  // Debugging headers
  DEBUG_MODE: 'X-DEBUG-MODE',
} as const;

export type ApiHeaderKey = keyof typeof API_HEADERS;
export type ApiHeaderValue = typeof API_HEADERS[ApiHeaderKey];
```

### 3. Extended BaseApiClient

The `BaseApiClient` is extended to support header providers:

```typescript
// core/shared/api/base.ts - Extended portion
export abstract class BaseApiClient {
  // ... existing implementation
  
  protected headerProviders: HeaderProvider[] = [];
  
  /**
   * Registers a header provider with this client instance
   * @param provider The header provider to register
   */
  protected registerHeaderProvider(provider: HeaderProvider): void {
    // Ensure no duplicates by id
    this.headerProviders = this.headerProviders.filter(p => p.id !== provider.id);
    this.headerProviders.push(provider);
    // Sort by priority (highest first)
    this.headerProviders.sort((a, b) => b.priority - a.priority);
  }
  
  protected setupHeaderInterceptors(): void {
    this.client.interceptors.request.use(async (config) => {
      try {
        // Apply all registered header providers in priority order
        for (const provider of this.headerProviders) {
          const headers = await provider.getHeaders();
          for (const [key, value] of Object.entries(headers)) {
            if (value !== undefined) {
              config.headers[key] = value;
            }
          }
        }
      } catch (error) {
        // Log but don't fail the request due to header issues
        console.warn('Error applying headers:', error);
      }
      return config;
    });
  }
  
  // Constructor enhancement
  constructor(config?: AxiosRequestConfig) {
    // ... existing initialization
    
    // Setup standard interceptors
    this.setupErrorHandlingInterceptors();
    this.setupHeaderInterceptors();
  }
}
```

## Header Implementation Patterns

We support three patterns for implementing headers, each with specific use cases:

### 1. Static Headers

Static headers remain constant across all requests and are typically configured during client initialization.

```typescript
// Example of static header configuration
const commonConfig = {
  headers: {
    'X-API-VERSION': '2.0',
    'X-CLIENT-TYPE': 'mobile-app',
  },
};

export const publicApi = new PublicApiClient(commonConfig);
export const authenticatedApi = new AuthenticatedApiClient(commonConfig);
```

**Use when**: The header value is constant and known at initialization time.

### 2. Zustand-Based Dynamic Headers

For headers that depend on application state, we use Zustand stores rather than separate context services, aligning with our state management architecture:

```typescript
// core/domains/tenant/store.ts
interface TenantState {
  organizationId: string | null;
  projectId: string | null;
  setOrganizationId: (id: string | null) => void;
  setProjectId: (id: string | null) => void;
}

export const useTenantStore = create<TenantState>((set) => ({
  organizationId: null,
  projectId: null,
  setOrganizationId: (id) => set({ organizationId: id }),
  setProjectId: (id) => set({ projectId: id }),
}));
```

Then implement a corresponding header provider:

```typescript
// core/domains/tenant/headerProvider.ts
import { HeaderProvider } from '@/core/shared/api/headers/types';
import { API_HEADERS } from '@/core/shared/constants/headers';
import { useTenantStore } from './store';

export class TenantHeaderProvider implements HeaderProvider {
  id = 'tenant';
  priority = 100; // High priority
  
  async getHeaders(): Promise<Record<string, string | undefined>> {
    // Get current state values using Zustand's getState()
    const { organizationId, projectId } = useTenantStore.getState();
    
    return {
      [API_HEADERS.ORGANIZATION_ID]: organizationId || undefined,
      [API_HEADERS.PROJECT_ID]: projectId || undefined,
    };
  }
}
```

**Use when**: The header values depend on user selection, app state, or other runtime factors.

### 3. Per-Request Headers

Headers specified for individual API calls that override global defaults:

```typescript
// Example of per-request headers
userApi.protected.getUserDetails(userId, { 
  headers: { 
    'X-CUSTOM-CONTEXT': 'specific-value',
  }
});
```

**Use when**: The header is specific to a particular request and not applicable globally.

## Common Header Provider Implementations

### Device Information Provider

```typescript
// core/shared/api/headers/providers/deviceHeaderProvider.ts
import { HeaderProvider } from '../types';
import { API_HEADERS } from '@/core/shared/constants/headers';
import DeviceInfo from 'react-native-device-info';

export class DeviceHeaderProvider implements HeaderProvider {
  id = 'device';
  priority = 90;
  
  async getHeaders(): Promise<Record<string, string | undefined>> {
    // Get device information
    const deviceId = await DeviceInfo.getUniqueId();
    const appVersion = DeviceInfo.getVersion();
    const buildNumber = DeviceInfo.getBuildNumber();
    const deviceType = DeviceInfo.getDeviceType();
    
    return {
      [API_HEADERS.DEVICE_UUID]: deviceId,
      [API_HEADERS.APP_VERSION]: `${appVersion}+${buildNumber}`,
      [API_HEADERS.DEVICE_TYPE]: deviceType,
    };
  }
}
```

### Request Tracking Provider

```typescript
// core/shared/api/headers/providers/trackingHeaderProvider.ts
import { HeaderProvider } from '../types';
import { API_HEADERS } from '@/core/shared/constants/headers';
import { v4 as uuidv4 } from 'uuid';
import { storage } from '@/core/shared/utils/storage';

export class TrackingHeaderProvider implements HeaderProvider {
  id = 'tracking';
  priority = 80;
  private sessionId: string | null = null;
  
  async getHeaders(): Promise<Record<string, string | undefined>> {
    // Get or create session ID
    if (!this.sessionId) {
      this.sessionId = await this.getOrCreateSessionId();
    }
    
    // Generate a new request ID for each call
    const requestId = uuidv4();
    
    return {
      [API_HEADERS.SESSION_ID]: this.sessionId,
      [API_HEADERS.REQUEST_ID]: requestId,
    };
  }
  
  private async getOrCreateSessionId(): Promise<string> {
    let sessionId = await storage.getItem('session_id');
    if (!sessionId) {
      sessionId = uuidv4();
      await storage.setItem('session_id', sessionId);
    }
    return sessionId;
  }
}
```

### Debug Mode Provider

```typescript
// core/shared/api/headers/providers/debugHeaderProvider.ts
import { HeaderProvider } from '../types';
import { API_HEADERS } from '@/core/shared/constants/headers';
import { useDebugStore } from '@/core/shared/store/debugStore';

export class DebugHeaderProvider implements HeaderProvider {
  id = 'debug';
  priority = 50;
  
  async getHeaders(): Promise<Record<string, string | undefined>> {
    const { debugMode, verboseLogging } = useDebugStore.getState();
    
    if (!debugMode) {
      return {};
    }
    
    return {
      [API_HEADERS.DEBUG_MODE]: 'true',
      ...(verboseLogging ? { 'X-VERBOSE-LOGGING': 'true' } : {}),
    };
  }
}
```

## Registering Header Providers with API Clients

<Tabs items={["API Client Setup", "Multiple API Clients"]}>
  <Tab>
    ```typescript
    // Enhancing authenticated client with header providers
    export class AuthenticatedApiClient extends BaseApiClient {
      constructor(config?: AxiosRequestConfig) {
        super(config);
        
        // Register header providers
        this.registerHeaderProvider(new DeviceHeaderProvider());
        this.registerHeaderProvider(new TenantHeaderProvider());
        this.registerHeaderProvider(new TrackingHeaderProvider());
        // Debug headers last (lowest priority)
        this.registerHeaderProvider(new DebugHeaderProvider());
        
        // Setup auth interceptors
        this.setupAuthInterceptors();
      }
      
      // ... rest of the authenticated client implementation
    }
    ```
  </Tab>

  <Tab>
    ```typescript
    // Different header configurations for different API services
    // core/shared/api/clients.ts

    // Main application API
    export const mainApi = {
      public: new PublicApiClient({
        baseURL: process.env.MAIN_API_URL,
      }),
      authenticated: new AuthenticatedApiClient({
        baseURL: process.env.MAIN_API_URL,
      }),
    };

    // Add all standard header providers
    [
      new DeviceHeaderProvider(),
      new TenantHeaderProvider(),
      new TrackingHeaderProvider(),
      new DebugHeaderProvider()
    ].forEach(provider => {
      (mainApi.authenticated as any).registerHeaderProvider(provider);
    });

    // Analytics API (might only need device and session info)
    export const analyticsApi = new AuthenticatedApiClient({
      baseURL: process.env.ANALYTICS_API_URL,
    }, new ApiKeyStrategy(process.env.ANALYTICS_API_KEY));

    // Register only needed providers
    (analyticsApi as any).registerHeaderProvider(new DeviceHeaderProvider());
    (analyticsApi as any).registerHeaderProvider(new TrackingHeaderProvider());
    ```
  </Tab>
</Tabs>

## Testing Header Implementations

<Tabs items={["Header Provider Tests", "API Client Integration Tests"]}>
  <Tab>
    ```typescript
    // __tests__/core/shared/api/headers/providers/tenantHeaderProvider.test.ts
    import { TenantHeaderProvider } from '@/core/domains/tenant/headerProvider';
    import { useTenantStore } from '@/core/domains/tenant/store';
    import { API_HEADERS } from '@/core/shared/constants/headers';

    describe('TenantHeaderProvider', () => {
      beforeEach(() => {
        // Reset store state
        useTenantStore.setState({
          organizationId: null,
          projectId: null,
        });
      });
      
      it('should return empty headers when no tenant is selected', async () => {
        const provider = new TenantHeaderProvider();
        const headers = await provider.getHeaders();
        
        expect(headers[API_HEADERS.ORGANIZATION_ID]).toBeUndefined();
        expect(headers[API_HEADERS.PROJECT_ID]).toBeUndefined();
      });
      
      it('should return organization ID in headers when set', async () => {
        // Setup store with test data
        useTenantStore.setState({ organizationId: 'org-123' });
        
        const provider = new TenantHeaderProvider();
        const headers = await provider.getHeaders();
        
        expect(headers[API_HEADERS.ORGANIZATION_ID]).toBe('org-123');
      });
      
      it('should return both organization and project IDs when set', async () => {
        // Setup store with test data
        useTenantStore.setState({
          organizationId: 'org-123',
          projectId: 'proj-456',
        });
        
        const provider = new TenantHeaderProvider();
        const headers = await provider.getHeaders();
        
        expect(headers[API_HEADERS.ORGANIZATION_ID]).toBe('org-123');
        expect(headers[API_HEADERS.PROJECT_ID]).toBe('proj-456');
      });
    });
    ```
  </Tab>

  <Tab>
    ```typescript
    // __tests__/core/shared/api/authenticatedApiClient.test.ts
    import { AuthenticatedApiClient } from '@/core/shared/api/authenticated';
    import { TenantHeaderProvider } from '@/core/domains/tenant/headerProvider';
    import { useTenantStore } from '@/core/domains/tenant/store';
    import MockAdapter from 'axios-mock-adapter';
    import { API_HEADERS } from '@/core/shared/constants/headers';

    describe('AuthenticatedApiClient with headers', () => {
      let client: AuthenticatedApiClient;
      let mockAxios: MockAdapter;
      
      beforeEach(() => {
        client = new AuthenticatedApiClient({
          baseURL: 'https://api.example.com',
        });
        
        // Add tenant header provider for testing
        client.registerHeaderProvider(new TenantHeaderProvider());
        
        // Access the axios instance for mocking
        mockAxios = new MockAdapter((client as any).client);
        
        // Reset tenant store
        useTenantStore.setState({
          organizationId: null,
          projectId: null,
        });
      });
      
      afterEach(() => {
        mockAxios.restore();
      });
      
      it('should include tenant headers when making requests', async () => {
        // Setup tenant context
        useTenantStore.setState({ organizationId: 'org-123' });
        
        // Setup mock response
        mockAxios.onGet('/users').reply((config) => {
          // Verify headers were set correctly
          expect(config.headers[API_HEADERS.ORGANIZATION_ID]).toBe('org-123');
          return [200, { data: [] }];
        });
        
        // Make request
        await client.get('/users');
        
        // MockAdapter expectations are verified inside the reply callback
      });
      
      it('should update headers when tenant context changes', async () => {
        // Initial request with no tenant
        mockAxios.onGet('/initial').reply((config) => {
          expect(config.headers[API_HEADERS.ORGANIZATION_ID]).toBeUndefined();
          return [200, {}];
        });
        
        await client.get('/initial');
        
        // Update tenant context
        useTenantStore.setState({ organizationId: 'org-456' });
        
        // Next request should have updated headers
        mockAxios.onGet('/updated').reply((config) => {
          expect(config.headers[API_HEADERS.ORGANIZATION_ID]).toBe('org-456');
          return [200, {}];
        });
        
        await client.get('/updated');
      });
    });
    ```
  </Tab>
</Tabs>

## Decision Framework: When to Use Which Headers

Use this framework to determine which headers to implement for your specific use case:

### Identity Headers

**When to use**:

* Multi-tenant applications where users belong to organizations
* Resource segmentation based on organizational hierarchies
* Project or team-based access controls

**Common headers**:

* `X-ORG-ID`: Organization identifier
* `X-PROJECT-ID`: Project identifier within an organization
* `X-TENANT-ID`: Generic tenant identifier

### Device Headers

**When to use**:

* Device-specific features or optimizations
* Analytics tracking device usage
* Security auditing and device verification

**Common headers**:

* `X-DEVICE-UUID`: Unique device identifier
* `X-DEVICE-TYPE`: Device type (phone, tablet, etc.)
* `User-Agent`: Custom or extended user agent information

### Session and Tracking Headers

**When to use**:

* Request correlation for troubleshooting
* Analytics flow tracking
* Performance monitoring

**Common headers**:

* `X-SESSION-ID`: User session identifier
* `X-REQUEST-ID`: Unique request identifier
* `X-CORRELATION-ID`: Identifier for tracing requests across services

## Implementation Considerations

### Security Implications

<Callout type="warning">
  Be careful about what information you include in headers. Headers can be exposed in network logs and could potentially leak sensitive information.
</Callout>

* We strongly recommend against including sensitive information like passwords, tokens, or PII in custom headers
* It's advisable to use non-sequential, non-predictable IDs for organization and project identifiers
* Consider encrypting certain header values if they contain semi-sensitive information

### Performance Impact

* Headers add minimal overhead to requests, but caching header values can improve performance
* Implement caching in header providers where appropriate to avoid redundant computations
* Consider the frequency of state changes when designing Zustand stores for header values

### Consistency and Maintainability

* Use a single source of truth for header names (constants or enums)
* Document headers thoroughly, including purpose, format, and fallback behavior
* Follow the HeaderProvider interface consistently for all header types

## Design Principles

### Core Architectural Principles

1. **Modularity**
   * Each header provider is responsible for a specific header type
   * Providers can be added, removed, or modified independently
   * Composable architecture allows for customization per API client

2. **State Management Integration**
   * Consistent use of Zustand for state-driven headers
   * Aligns with the project's "Golden Rule" for state management

3. **Priority-Based Application**
   * Header providers have explicit priorities
   * Providers are applied in priority order to ensure consistent resolution

### Trade-offs and Design Decisions

| Decision                 | Benefits                                     | Drawbacks                                     | Rationale                                                                |
| ------------------------ | -------------------------------------------- | --------------------------------------------- | ------------------------------------------------------------------------ |
| HeaderProvider interface | Consistent implementation, testability       | More boilerplate compared to simple functions | Creates a pluggable system that scales better with multiple header types |
| Zustand integration      | Aligns with state management architecture    | Requires Zustand knowledge                    | Maintains consistency with our established patterns                      |
| Priority-based ordering  | Clear resolution order, predictable behavior | Additional complexity                         | Ensures critical headers are consistently applied first                  |
| Type-safe constants      | Compile-time validation                      | Requires maintenance when adding headers      | Prevents typos and inconsistencies across the codebase                   |

## Implementation Examples

Here are examples of using header providers in different domains:

### User Preferences in Profile API

```typescript
// core/domains/profile/api.ts
import { publicApi, authenticatedApi } from '@/core/shared/api/client';
import type { UserProfile, ProfilePreferences } from './types';

export const profileApi = {
  public: {},
  protected: {
    // Headers from registered providers are automatically applied
    async getUserProfile(): Promise<UserProfile> {
      return authenticatedApi.get<UserProfile>('/profile');
    },
    
    // Use per-request headers to override preferences for a specific call
    async getProfileWithLocale(locale: string): Promise<UserProfile> {
      return authenticatedApi.get<UserProfile>('/profile', {
        headers: {
          'X-PREFERRED-LOCALE': locale // Override just for this request
        }
      });
    },
  }
};
```

### Organization Context in Projects API

```typescript
// core/domains/projects/api.ts
import { authenticatedApi } from '@/core/shared/api/client';
import { useTenantStore } from '@/core/domains/tenant/store';
import type { Project, ProjectDetails } from './types';

export const projectsApi = {
  public: {},
  protected: {
    // Tenant headers (X-ORG-ID) are automatically applied
    async getProjects(): Promise<Project[]> {
      return authenticatedApi.get<Project[]>('/projects');
    },
    
    // When context needs to be temporarily switched for a single request
    async getProjectFromDifferentOrg(projectId: string, orgId: string): Promise<ProjectDetails> {
      const { organizationId } = useTenantStore.getState();
      const originalOrgId = organizationId;
      
      try {
        // Temporarily change context
        useTenantStore.getState().setOrganizationId(orgId);
        
        // Make the request with the temporary context
        return await authenticatedApi.get<ProjectDetails>(`/projects/${projectId}`);
      } finally {
        // Restore original context
        useTenantStore.getState().setOrganizationId(originalOrgId);
      }
    }
  }
};
```

## Troubleshooting

Here are solutions to common issues when implementing custom headers:

### Headers Not Being Applied

**Issue**: Your custom headers aren't showing up in network requests

**Solutions**:

* Ensure your header provider is properly registered with the API client
* Check that your Zustand store is properly initialized
* Verify header provider priority values (higher priorities are applied first)
* Look for console warnings about header provider errors

### Conflicting Headers

**Issue**: Multiple providers are trying to set the same header with different values

**Solution**: Adjust provider priorities to ensure the correct provider wins, or refactor providers to have clearer responsibilities.

### Performance Issues

**Issue**: Header resolution is causing noticeable delays in API requests

**Solutions**:

* Implement caching in your header providers
* Reduce async operations where possible
* Consider using a memory cache for frequently accessed header values

## Migration Guide

If you're migrating from an older header implementation, follow these steps:

1. Define header constants in a central location
2. Create header providers for each header category
3. Update API client initialization to register providers
4. Remove any inline header creation from domain APIs
5. Update tests to mock header providers rather than specific headers

## Related Documents

* [API Client Architecture](/docs/api/client-architecture) - Base client structure this builds upon
* [Authentication Architecture](/docs/api/authentication) - How auth headers are managed (authentication headers use a different mechanism than covered in this document)
* [Client State Management](/docs/state-management/client-state) - Zustand patterns used for header state
* [Multi-API Setup](/docs/api/multi-api-setup) - For service-specific header configurations

## Summary

This header customization architecture provides a flexible, maintainable approach to managing API headers across your application. By leveraging Zustand for state management and implementing a modular provider system, you can easily add, modify, or extend custom headers as your application requirements evolve.

Key takeaways:

* The HeaderProvider interface creates a consistent pattern for header implementation
* Zustand stores provide a clean way to manage state that affects headers
* The priority system ensures predictable header resolution
* This architecture scales well as your application grows
* Each header provider can be tested independently

By following these established patterns, you can ensure your API headers remain well-organized and aligned with the rest of the application architecture.


# UTA API Integration: Multi-Tenant Headers
URL: https://dev.updatetheapp.com/docs/api/headers/multi-tenant-headers
Documentation: https://dev.updatetheapp.com/docs/api/headers/multi-tenant-headers

Detailed implementation of multi-tenant headers for organization and project context
        
***

title: Multi-Tenant Headers
description: Detailed implementation of multi-tenant headers for organization and project context
-------------------------------------------------------------------------------------------------

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Callout } from 'fumadocs-ui/components/callout';

# Multi-Tenant Headers

## Overview

This guide provides a detailed implementation for multi-tenant headers using the architecture defined in the [Header Customization](/docs/api/headers/header-customization) document. Multi-tenant headers enable your API to understand the organizational context of each request, allowing proper data segmentation and access control in multi-tenant applications.

## Quick Start

If you need to quickly implement tenant headers in your application, follow these three steps:

1. **Create your tenant store**:
   ```typescript
   // core/domains/tenant/store.ts
   export const useTenantStore = create<TenantState>()(
     persist(
       (set) => ({
         organizationId: null,
         projectId: null,
         setOrganization: (id) => set({ organizationId: id, projectId: null }),
         setProject: (id) => set({ projectId: id }),
       }),
       { name: 'tenant-storage' }
     )
   );
   ```

2. **Implement tenant header provider**:
   ```typescript
   // core/domains/tenant/headerProvider.ts
   export class TenantHeaderProvider implements HeaderProvider {
     id = 'tenant';
     priority = 100;
     
     async getHeaders() {
       const { organizationId, projectId } = useTenantStore.getState();
       return {
         [API_HEADERS.ORGANIZATION_ID]: organizationId || undefined,
         [API_HEADERS.PROJECT_ID]: projectId || undefined,
       };
     }
   }
   ```

3. **Register with your API client**:
   ```typescript
   // core/shared/api/client.ts
   const apiClient = new AuthenticatedApiClient(config);
   apiClient.registerHeaderProvider(new TenantHeaderProvider());
   ```

For complete implementation details, continue reading the sections below.

## Purpose & Scope

This implementation guide covers:

* Zustand store for tenant context management
* Header provider implementation for tenant headers
* UI components for tenant selection
* Testing strategies specific to tenant headers
* Backend integration considerations

## Prerequisites

Before implementing multi-tenant headers, ensure you're familiar with:

* [](/docs/api/headers/header-customization) - Core header architecture
* [Client State Management](/docs/state-management/client-state) - Zustand store patterns

## Tenant Header Architecture

The multi-tenant header system consists of three main components:

<Mermaid
  chart={`
flowchart TD
  TenantStore[Tenant Zustand Store]
  HeaderProvider[Tenant Header Provider]
  UI[Tenant Selection UI]
  ApiClient[API Client]
  Backend[Backend API]
  
  UI -->|Set tenant| TenantStore
  TenantStore -->|Read state| HeaderProvider
  HeaderProvider -->|Add headers| ApiClient
  ApiClient -->|Include headers| Backend
  Backend -->|Apply tenant context| Backend
`}
/>

## Tenant Store Implementation

The tenant store manages the current organization and project selection:

```typescript
// core/domains/tenant/store.ts
import { create } from 'zustand';
import { persist } from 'zustand/middleware';

export interface TenantState {
  // State
  organizationId: string | null;
  projectId: string | null;
  organizationName: string | null;
  projectName: string | null;
  
  // Actions
  setOrganization: (id: string | null, name: string | null) => void;
  setProject: (id: string | null, name: string | null) => void;
  clearTenant: () => void;
}

export const useTenantStore = create<TenantState>()(
  persist(
    (set) => ({
      // Initial state
      organizationId: null,
      projectId: null,
      organizationName: null,
      projectName: null,
      
      // Actions
      setOrganization: (id, name) => set({
        organizationId: id,
        organizationName: name,
        // Clear project when organization changes
        projectId: null,
        projectName: null,
      }),
      
      setProject: (id, name) => set({
        projectId: id,
        projectName: name,
      }),
      
      clearTenant: () => set({
        organizationId: null,
        projectId: null,
        organizationName: null,
        projectName: null,
      }),
    }),
    {
      name: 'tenant-storage',
      // Only persist IDs, not names (they can be refetched)
      partialize: (state) => ({
        organizationId: state.organizationId,
        projectId: state.projectId,
      }),
    }
  )
);
```

## Tenant Header Provider

The header provider reads from the tenant store and adds the appropriate headers:

```typescript
// core/domains/tenant/headerProvider.ts
import { HeaderProvider } from '@/core/shared/api/headers/types';
import { API_HEADERS } from '@/core/shared/constants/headers';
import { useTenantStore } from './store';

export class TenantHeaderProvider implements HeaderProvider {
  id = 'tenant';
  priority = 100; // High priority
  
  async getHeaders(): Promise<Record<string, string | undefined>> {
    // Get current state values using Zustand's getState()
    const { organizationId, projectId } = useTenantStore.getState();
    
    return {
      [API_HEADERS.ORGANIZATION_ID]: organizationId || undefined,
      [API_HEADERS.PROJECT_ID]: projectId || undefined,
    };
  }
}
```

## UI Implementation

### Tenant Selector Component

A reusable component for selecting the current organization and project:

```typescript
// features/tenant/components/TenantSelector.tsx
import React, { useEffect, useState } from 'react';
import { View, Text, TouchableOpacity, StyleSheet } from 'react-native';
import { useTenantStore } from '@/core/domains/tenant/store';
import { useOrganizations, useProjects } from '@/core/domains/organizations/hooks';
import { Dropdown } from '@/ui/Dropdown';

export const TenantSelector: React.FC = () => {
  const { 
    organizationId, 
    projectId, 
    setOrganization, 
    setProject 
  } = useTenantStore();
  
  // Fetch available organizations
  const { data: organizations, isLoading: orgsLoading } = useOrganizations();
  
  // Fetch projects for selected organization
  const { 
    data: projects, 
    isLoading: projectsLoading 
  } = useProjects(organizationId, { enabled: !!organizationId });
  
  const handleOrgChange = (id: string) => {
    const org = organizations?.find(o => o.id === id);
    setOrganization(id, org?.name || null);
  };
  
  const handleProjectChange = (id: string) => {
    const project = projects?.find(p => p.id === id);
    setProject(id, project?.name || null);
  };
  
  return (
    <View style={styles.container}>
      <View style={styles.selectorContainer}>
        <Text style={styles.label}>Organization</Text>
        <Dropdown
          placeholder="Select organization"
          value={organizationId}
          items={organizations?.map(org => ({ 
            label: org.name, 
            value: org.id 
          })) || []}
          onValueChange={handleOrgChange}
          disabled={orgsLoading}
          loading={orgsLoading}
        />
      </View>
      
      {organizationId && (
        <View style={styles.selectorContainer}>
          <Text style={styles.label}>Project</Text>
          <Dropdown
            placeholder="Select project"
            value={projectId}
            items={projects?.map(project => ({ 
              label: project.name, 
              value: project.id 
            })) || []}
            onValueChange={handleProjectChange}
            disabled={projectsLoading || !organizationId}
            loading={projectsLoading}
          />
        </View>
      )}
    </View>
  );
};

const styles = StyleSheet.create({
  container: {
    marginBottom: 16,
  },
  selectorContainer: {
    marginBottom: 12,
  },
  label: {
    fontSize: 14,
    fontWeight: '500',
    marginBottom: 4,
  },
});
```

### Tenant Header Display

A component to show the current tenant context:

```typescript
// features/tenant/components/TenantHeader.tsx
import React from 'react';
import { View, Text, StyleSheet } from 'react-native';
import { useTenantStore } from '@/core/domains/tenant/store';

export const TenantHeader: React.FC = () => {
  const { organizationName, projectName } = useTenantStore();
  
  if (!organizationName) {
    return null;
  }
  
  return (
    <View style={styles.container}>
      <Text style={styles.orgText}>{organizationName}</Text>
      {projectName && (
        <>
          <Text style={styles.separator}>/</Text>
          <Text style={styles.projectText}>{projectName}</Text>
        </>
      )}
    </View>
  );
};

const styles = StyleSheet.create({
  container: {
    flexDirection: 'row',
    alignItems: 'center',
    padding: 8,
  },
  orgText: {
    fontSize: 16,
    fontWeight: 'bold',
  },
  separator: {
    fontSize: 16,
    marginHorizontal: 4,
    color: '#888',
  },
  projectText: {
    fontSize: 16,
    color: '#444',
  },
});
```

## Integration with API Clients

Register the tenant header provider with your API clients:

```typescript
// core/shared/api/client.ts
import { PublicApiClient, AuthenticatedApiClient } from '@/core/shared/api/base';
import { TenantHeaderProvider } from '@/core/domains/tenant/headerProvider';

// Create API client instances
export const publicApi = new PublicApiClient({
  baseURL: process.env.API_BASE_URL,
});

export const authenticatedApi = new AuthenticatedApiClient({
  baseURL: process.env.API_BASE_URL,
});

// Register the tenant header provider
authenticatedApi.registerHeaderProvider(new TenantHeaderProvider());
```

## Backend Integration

The backend API will need to extract and validate the tenant headers:

```typescript
// Example Express middleware for tenant context (backend code)
const tenantMiddleware = (req, res, next) => {
  const orgId = req.headers['x-org-id'];
  const projectId = req.headers['x-project-id'];
  
  if (!orgId) {
    return res.status(401).json({ 
      error: 'Organization ID header is required' 
    });
  }
  
  // Set tenant context for this request
  req.tenantContext = {
    organizationId: orgId,
    projectId: projectId || null,
  };
  
  // Continue with request
  next();
};

// Use in routes
app.use('/api/protected', authMiddleware, tenantMiddleware, protectedRoutes);
```

## Testing Tenant Headers

<Tabs items={["Testing the Store", "Testing the Provider", "Testing API Integration"]}>
  <Tab>
    ```typescript
    // __tests__/core/domains/tenant/store.test.ts
    import { useTenantStore } from '@/core/domains/tenant/store';

    describe('TenantStore', () => {
      beforeEach(() => {
        // Reset store state before each test
        useTenantStore.setState({
          organizationId: null,
          projectId: null,
          organizationName: null,
          projectName: null,
        });
      });
      
      it('should set organization', () => {
        const orgId = 'org-123';
        const orgName = 'Test Organization';
        
        useTenantStore.getState().setOrganization(orgId, orgName);
        
        expect(useTenantStore.getState().organizationId).toBe(orgId);
        expect(useTenantStore.getState().organizationName).toBe(orgName);
      });
      
      it('should clear project when organization changes', () => {
        // Set initial org and project
        useTenantStore.getState().setOrganization('org-1', 'Org 1');
        useTenantStore.getState().setProject('proj-1', 'Project 1');
        
        // Verify both are set
        expect(useTenantStore.getState().organizationId).toBe('org-1');
        expect(useTenantStore.getState().projectId).toBe('proj-1');
        
        // Change organization
        useTenantStore.getState().setOrganization('org-2', 'Org 2');
        
        // Project should be cleared
        expect(useTenantStore.getState().organizationId).toBe('org-2');
        expect(useTenantStore.getState().projectId).toBeNull();
      });
      
      it('should clear all tenant data', () => {
        // Set initial state
        useTenantStore.getState().setOrganization('org-1', 'Org 1');
        useTenantStore.getState().setProject('proj-1', 'Project 1');
        
        // Clear tenant
        useTenantStore.getState().clearTenant();
        
        // Verify all cleared
        expect(useTenantStore.getState().organizationId).toBeNull();
        expect(useTenantStore.getState().projectId).toBeNull();
        expect(useTenantStore.getState().organizationName).toBeNull();
        expect(useTenantStore.getState().projectName).toBeNull();
      });
    });
    ```
  </Tab>

  <Tab>
    ```typescript
    // __tests__/core/domains/tenant/headerProvider.test.ts
    import { TenantHeaderProvider } from '@/core/domains/tenant/headerProvider';
    import { useTenantStore } from '@/core/domains/tenant/store';
    import { API_HEADERS } from '@/core/shared/constants/headers';

    describe('TenantHeaderProvider', () => {
      beforeEach(() => {
        // Reset store state
        useTenantStore.setState({
          organizationId: null,
          projectId: null,
          organizationName: null,
          projectName: null,
        });
      });
      
      it('should return empty headers when no tenant is selected', async () => {
        const provider = new TenantHeaderProvider();
        const headers = await provider.getHeaders();
        
        expect(headers[API_HEADERS.ORGANIZATION_ID]).toBeUndefined();
        expect(headers[API_HEADERS.PROJECT_ID]).toBeUndefined();
      });
      
      it('should return organization ID header when organization is set', async () => {
        // Set organization in store
        useTenantStore.getState().setOrganization('org-123', 'Test Org');
        
        const provider = new TenantHeaderProvider();
        const headers = await provider.getHeaders();
        
        expect(headers[API_HEADERS.ORGANIZATION_ID]).toBe('org-123');
        expect(headers[API_HEADERS.PROJECT_ID]).toBeUndefined();
      });
      
      it('should return both organization and project headers when both are set', async () => {
        // Set organization and project in store
        useTenantStore.getState().setOrganization('org-123', 'Test Org');
        useTenantStore.getState().setProject('proj-456', 'Test Project');
        
        const provider = new TenantHeaderProvider();
        const headers = await provider.getHeaders();
        
        expect(headers[API_HEADERS.ORGANIZATION_ID]).toBe('org-123');
        expect(headers[API_HEADERS.PROJECT_ID]).toBe('proj-456');
      });
    });
    ```
  </Tab>

  <Tab>
    ```typescript
    // __tests__/integration/tenantHeaders.test.ts
    import { authenticatedApi } from '@/core/shared/api/client';
    import { useTenantStore } from '@/core/domains/tenant/store';
    import MockAdapter from 'axios-mock-adapter';
    import { API_HEADERS } from '@/core/shared/constants/headers';

    describe('Tenant Headers Integration', () => {
      let mockAxios: MockAdapter;
      
      beforeEach(() => {
        // Create mock for axios instance
        mockAxios = new MockAdapter((authenticatedApi as any).client);
        
        // Reset tenant store
        useTenantStore.setState({
          organizationId: null,
          projectId: null,
          organizationName: null,
          projectName: null,
        });
      });
      
      afterEach(() => {
        mockAxios.restore();
      });
      
      it('should include tenant headers in API requests', async () => {
        // Set tenant context
        useTenantStore.getState().setOrganization('org-123', 'Test Org');
        useTenantStore.getState().setProject('proj-456', 'Test Project');
        
        // Setup mock response that verifies headers
        mockAxios.onGet('/test-endpoint').reply((config) => {
          expect(config.headers[API_HEADERS.ORGANIZATION_ID]).toBe('org-123');
          expect(config.headers[API_HEADERS.PROJECT_ID]).toBe('proj-456');
          return [200, { success: true }];
        });
        
        // Make the API request
        await authenticatedApi.get('/test-endpoint');
        
        // The assertion is in the mock response
      });
      
      it('should update headers when tenant changes between requests', async () => {
        // First request with org-1
        useTenantStore.getState().setOrganization('org-1', 'Org 1');
        
        mockAxios.onGet('/request-1').reply((config) => {
          expect(config.headers[API_HEADERS.ORGANIZATION_ID]).toBe('org-1');
          return [200, {}];
        });
        
        await authenticatedApi.get('/request-1');
        
        // Change tenant context
        useTenantStore.getState().setOrganization('org-2', 'Org 2');
        
        // Second request should have updated org
        mockAxios.onGet('/request-2').reply((config) => {
          expect(config.headers[API_HEADERS.ORGANIZATION_ID]).toBe('org-2');
          return [200, {}];
        });
        
        await authenticatedApi.get('/request-2');
      });
    });
    ```
  </Tab>
</Tabs>

## Best Practices

### Tenant Header Security

<Callout type="warning">
  Organization and project IDs should be treated as sensitive identifiers. While not as sensitive as authentication tokens, they should be protected from tampering and manipulation.
</Callout>

Key security considerations:

* Use non-sequential, non-predictable IDs for organizations and projects
* Validate tenancy on the server for every authenticated request
* Implement proper access control to prevent tenant ID spoofing
* Consider using signed tenant tokens for high-security applications

### Performance Considerations

* Store recently used projects in memory to reduce selection operations
* Consider batching organization/project data for offline access
* Cache tenant validation on the server to reduce database lookups

### User Experience

* Save and restore the last used organization and project
* Provide clear visual indication of the current tenant context
* Consider auto-selecting projects if there's only one available
* Allow quick switching between frequently used contexts

## Tenant Header Use Cases

1. **Data Segmentation**: Ensure API responses only include data from the selected organization and project.

2. **Multi-tenant Dashboards**: Display metrics and data specific to the current organization context.

3. **Role-Based Access Control**: Combine tenant headers with user roles for fine-grained permissions.

4. **Audit Logging**: Include tenant context in all audit logs to track actions across organizations.

## Troubleshooting

| Issue                   | Possible Cause                  | Solution                                                  |
| ----------------------- | ------------------------------- | --------------------------------------------------------- |
| Missing tenant headers  | Tenant not selected in UI       | Ensure organization is selected and stored                |
| Missing project context | Project not selected            | Verify project ID is set in tenant store                  |
| 401 Unauthorized errors | Missing required tenant headers | Check if server requires tenant headers for this endpoint |
| Incorrect data returned | Wrong tenant context active     | Verify the correct organization/project is selected       |

## Migration Considerations

If you're migrating from a different tenant identification approach, follow these steps to transition smoothly:

### From Context/Service-based Approach

If you previously used a context service pattern:

1. **Create the Zustand store** first, maintaining the same interface where possible
2. **Initialize the store** with any existing tenant data from your current implementation
3. **Keep both implementations running** in parallel during transition
4. **Update components** to use the Zustand store instead of the context service
5. **Remove the old implementation** once all components have been updated

### From URL-based Tenant Identification

If you were passing tenant information via URL segments:

1. **Implement route parameter extraction** to set the tenant store state
2. **Add navigation middleware** that updates the tenant store when routes change
3. **Gradually transition endpoints** to use headers instead of URL parameters

### From Per-request Header Addition

If you were manually adding tenant headers to each request:

1. **Create the tenant store** to centralize tenant state
2. **Implement the header provider** as shown in this guide
3. **Remove manual header addition** from individual API calls
4. **Update tests** to mock the tenant store instead of individual headers

## Related Documents

* [](/docs/api/headers/header-customization) - Core architecture for header customization
* [Client State Management](/docs/state-management/client-state) - Zustand store patterns used in this implementation
* [Authentication Architecture](/docs/api/authentication) - How tenant context relates to user authentication
* [Security Guidelines](/docs/coding-standards/security) - Best practices for secure multi-tenant implementations
* [Project Structure](/docs/architecture/project-structure) - Where tenant-related code should be placed
* [API Integration Guide](/docs/guides/api-integration) - Practical guide to integrating APIs with tenant context

## Summary

Implementing tenant headers is critical for multi-tenant applications. By following the patterns in this guide, you can create a clean, maintainable solution that:

1. Stores tenant context in Zustand for global access
2. Automatically adds tenant headers to API requests
3. Provides a consistent UI for tenant selection
4. Ensures proper testing across all layers

This implementation aligns with our broader API header customization architecture while providing specific guidance for the multi-tenant use case.


# UTA API Integration: User Preferences Headers
URL: https://dev.updatetheapp.com/docs/api/headers/user-preferences-headers
Documentation: https://dev.updatetheapp.com/docs/api/headers/user-preferences-headers

Implementation guide for user preference headers across API requests
        
***

title: User Preferences Headers
description: Implementation guide for user preference headers across API requests
---------------------------------------------------------------------------------

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Callout } from 'fumadocs-ui/components/callout';

# User Preferences Headers

## Overview

This guide details the implementation approach for user preferences headers within our API header customization architecture. User preference headers allow backend services to deliver personalized experiences based on user settings without requiring repeated preference lookups. These headers enable content localization, accessibility optimizations, theme-based rendering, and other user-specific customizations.

<Mermaid
  chart={`
sequenceDiagram
  participant App as React Native App
  participant Store as PreferencesStore
  participant Provider as UserPreferencesHeaderProvider
  participant ApiClient as API Client
  participant Backend as Backend Service
  
  App->>Store: User updates preference
  Store->>Store: Update state & persist
  App->>ApiClient: Make API request
  ApiClient->>Provider: getHeaders()
  Provider->>Store: Get current preferences
  Store-->>Provider: Preference values
  Provider-->>ApiClient: Preference headers
  ApiClient->>Backend: Request with preference headers
  Backend->>Backend: Adapt response to preferences
  Backend-->>ApiClient: Personalized response
  ApiClient-->>App: Personalized content
`}
/>

## Quick Start

If you need to quickly implement user preference headers in your application, follow these steps:

1. **Define preference header constants**:
   ```typescript
   // core/shared/constants/headers.ts
   export const API_HEADERS = {
     // Other headers...
     LOCALE: 'X-LOCALE',
     THEME: 'X-THEME',
     TIMEZONE: 'X-TIMEZONE',
     ACCESSIBILITY: 'X-ACCESSIBILITY',
     CONTENT_DENSITY: 'X-CONTENT-DENSITY',
     UNITS: 'X-UNITS',
   };
   ```

2. **Create a simple preferences store**:
   ```typescript
   // core/domains/preferences/store.ts
   import { create } from 'zustand';
   import { persist } from 'zustand/middleware';
   import AsyncStorage from '@react-native-async-storage/async-storage';
   import * as Localization from 'expo-localization';

   export const usePreferencesStore = create(
     persist(
       (set) => ({
         locale: Localization.locale,
         theme: 'system',
         timezone: Localization.timezone,
         sharePreferencesWithApi: true,
         setLocale: (locale) => set({ locale }),
         setTheme: (theme) => set({ theme }),
         setTimezone: (timezone) => set({ timezone }),
         setSharePreferencesWithApi: (share) => set({ sharePreferencesWithApi }),
       }),
       { name: 'user-preferences', getStorage: () => AsyncStorage }
     )
   );
   ```

3. **Implement a preferences header provider**:
   ```typescript
   // core/shared/api/headers/providers/userPreferencesHeaderProvider.ts
   import { HeaderProvider } from '../types';
   import { API_HEADERS } from '@/core/shared/constants/headers';
   import { usePreferencesStore } from '@/core/domains/preferences/store';

   export class UserPreferencesHeaderProvider implements HeaderProvider {
     id = 'user-preferences';
     priority = 40; // Lower priority than device or session headers

     async getHeaders() {
       const { locale, theme, timezone, sharePreferencesWithApi } = 
         usePreferencesStore.getState();

       // Honor user's preference sharing choice
       if (!sharePreferencesWithApi) {
         return {};
       }

       return {
         [API_HEADERS.LOCALE]: locale,
         [API_HEADERS.THEME]: theme !== 'system' ? theme : undefined,
         [API_HEADERS.TIMEZONE]: timezone,
       };
     }
   }
   ```

4. **Register the provider with your API client**:
   ```typescript
   // core/shared/api/client.ts
   import { UserPreferencesHeaderProvider } from './headers/providers/userPreferencesHeaderProvider';

   // Register with your API client
   apiClient.registerHeaderProvider(new UserPreferencesHeaderProvider());
   ```

For more advanced implementation details and best practices, continue reading the sections below.

## Purpose & Scope

This implementation guide covers:

* Creating a comprehensive user preferences header provider
* Managing preference state with Zustand stores
* Persisting preferences across app sessions
* Allowing users to control preference sharing
* Testing preference header implementations
* Security and privacy considerations

This document extends the concepts established in the [](/docs/api/headers/header-customization) guide, focusing specifically on implementing user preference headers.

## Prerequisites

To effectively implement user preference headers, you should be familiar with:

* [](/docs/api/headers/header-customization) - Core concepts and the `HeaderProvider` interface
* [Client State Management](/docs/state-management/client-state) - Zustand store patterns for managing preference state
* [API Client Architecture](/docs/api/client-architecture) - Our API client structure and registration pattern

## Key User Preference Headers

The following preference headers provide important context about user settings:

| Header              | Description                      | Purpose                | Example Value                          |
| ------------------- | -------------------------------- | ---------------------- | -------------------------------------- |
| `X-LOCALE`          | User's preferred language/locale | Content localization   | `"en-US"` or `"fr-FR"`                 |
| `X-THEME`           | User's preferred theme           | Theme-based rendering  | `"light"` or `"dark"`                  |
| `X-TIMEZONE`        | User's preferred timezone        | Time-sensitive content | `"America/New_York"`                   |
| `X-ACCESSIBILITY`   | Accessibility requirements       | A11y optimizations     | `"screen-reader"` or `"high-contrast"` |
| `X-CONTENT-DENSITY` | UI density preference            | Layout optimization    | `"compact"` or `"comfortable"`         |
| `X-UNITS`           | Measurement unit preference      | Unit conversion        | `"metric"` or `"imperial"`             |

## Implementation

### 1. User Preferences Store

First, implement a Zustand store to manage user preferences:

```typescript
// core/domains/preferences/store.ts
import { create } from 'zustand';
import { persist } from 'zustand/middleware';
import AsyncStorage from '@react-native-async-storage/async-storage';
import * as Localization from 'expo-localization';
import { I18n } from 'i18n-js';

// Define supported preference types
export type ThemeType = 'light' | 'dark' | 'system';
export type AccessibilityType = 'default' | 'screen-reader' | 'high-contrast' | 'reduced-motion';
export type ContentDensity = 'default' | 'compact' | 'comfortable';
export type UnitSystem = 'metric' | 'imperial' | 'auto';

export interface UserPreferences {
  // User preference values
  locale: string;
  theme: ThemeType;
  timezone: string;
  accessibility: AccessibilityType;
  contentDensity: ContentDensity;
  unitSystem: UnitSystem;
  
  // Control flags
  sharePreferencesWithApi: boolean;
  
  // Actions
  setLocale: (locale: string) => void;
  setTheme: (theme: ThemeType) => void;
  setTimezone: (timezone: string) => void;
  setAccessibility: (type: AccessibilityType) => void;
  setContentDensity: (density: ContentDensity) => void;
  setUnitSystem: (system: UnitSystem) => void;
  setSharePreferencesWithApi: (share: boolean) => void;
  resetToDefaults: () => void;
}

// Default preferences
const getDefaultPreferences = () => ({
  locale: Localization.locale,
  theme: 'system' as ThemeType,
  timezone: Localization.timezone,
  accessibility: 'default' as AccessibilityType,
  contentDensity: 'default' as ContentDensity,
  unitSystem: 'auto' as UnitSystem,
  sharePreferencesWithApi: true,
});

export const usePreferencesStore = create<UserPreferences>()(
  persist(
    (set) => ({
      ...getDefaultPreferences(),
      
      // Setters for each preference
      setLocale: (locale) => set({ locale }),
      setTheme: (theme) => set({ theme }),
      setTimezone: (timezone) => set({ timezone }),
      setAccessibility: (accessibility) => set({ accessibility }),
      setContentDensity: (contentDensity) => set({ contentDensity }),
      setUnitSystem: (unitSystem) => set({ unitSystem }),
      setSharePreferencesWithApi: (sharePreferencesWithApi) => set({ sharePreferencesWithApi }),
      
      // Reset all preferences to default values
      resetToDefaults: () => set(getDefaultPreferences()),
    }),
    {
      name: 'user-preferences-storage',
      storage: {
        getItem: async (name) => {
          const value = await AsyncStorage.getItem(name);
          return value ?? null;
        },
        setItem: async (name, value) => {
          await AsyncStorage.setItem(name, value);
        },
        removeItem: async (name) => {
          await AsyncStorage.removeItem(name);
        },
      },
    }
  )
);
```

### 2. User Preferences Header Provider

Next, implement the header provider that retrieves values from the preferences store:

```typescript
// core/shared/api/headers/providers/userPreferencesHeaderProvider.ts
import { HeaderProvider } from '../types';
import { API_HEADERS } from '@/core/shared/constants/headers';
import { usePreferencesStore } from '@/core/domains/preferences/store';

export class UserPreferencesHeaderProvider implements HeaderProvider {
  id = 'user-preferences';
  priority = 80; // High priority but below device headers
  
  /**
   * Returns preference-related headers for API requests
   */
  async getHeaders(): Promise<Record<string, string | undefined>> {
    // Get current preferences from store
    const {
      locale,
      theme,
      timezone,
      accessibility,
      contentDensity,
      unitSystem,
      sharePreferencesWithApi
    } = usePreferencesStore.getState();
    
    // If user has opted out of sharing preferences, return empty object
    if (!sharePreferencesWithApi) {
      return {};
    }
    
    // Map preferences to header values
    return {
      [API_HEADERS.LOCALE]: locale,
      [API_HEADERS.THEME]: theme === 'system' ? undefined : theme,
      [API_HEADERS.TIMEZONE]: timezone,
      [API_HEADERS.ACCESSIBILITY]: accessibility === 'default' ? undefined : accessibility,
      [API_HEADERS.CONTENT_DENSITY]: contentDensity === 'default' ? undefined : contentDensity,
      [API_HEADERS.UNITS]: unitSystem === 'auto' ? undefined : unitSystem,
    };
  }
}
```

### 3. Registering the Provider

Add the preferences header provider to your API clients as outlined in the API Header Customization guide:

```typescript
// core/shared/api/client.ts
import { PublicApiClient, AuthenticatedApiClient } from '@/core/shared/api/client';
import { DeviceHeaderProvider } from '@/core/shared/api/headers/providers/deviceHeaderProvider';
import { UserPreferencesHeaderProvider } from '@/core/shared/api/headers/providers/userPreferencesHeaderProvider';

// Create API client instances
const apiConfig = { baseURL: process.env.API_BASE_URL };
export const publicApi = new PublicApiClient(apiConfig);
export const authenticatedApi = new AuthenticatedApiClient(apiConfig);

// Register header providers
// Device headers (higher priority)
const deviceHeaderProvider = new DeviceHeaderProvider();
publicApi.registerHeaderProvider(deviceHeaderProvider);
authenticatedApi.registerHeaderProvider(deviceHeaderProvider);

// User preference headers
const preferencesHeaderProvider = new UserPreferencesHeaderProvider();
publicApi.registerHeaderProvider(preferencesHeaderProvider);
authenticatedApi.registerHeaderProvider(preferencesHeaderProvider);
```

### 4. API Header Constants

Ensure the preference headers are defined in your header constants:

```typescript
// core/shared/constants/headers.ts
export const API_HEADERS = {
  // ... existing headers
  
  // User preference headers
  LOCALE: 'X-LOCALE',
  THEME: 'X-THEME',
  TIMEZONE: 'X-TIMEZONE',
  ACCESSIBILITY: 'X-ACCESSIBILITY',
  CONTENT_DENSITY: 'X-CONTENT-DENSITY',
  UNITS: 'X-UNITS',
  
  // ... other headers
} as const;
```

## Advanced Use Cases

### 1. User Preference Override for Specific Requests

Sometimes you might need to override user preferences for specific API requests:

```typescript
// core/domains/content/api.ts
import { authenticatedApi } from '@/core/shared/api/client';
import { API_HEADERS } from '@/core/shared/constants/headers';

class ContentApi {
  public readonly protected = {
    // Get content with standard user preferences
    getContent: async (contentId: string) => {
      return await authenticatedApi.get(`/content/${contentId}`);
    },
    
    // Get content with a specific locale override
    getContentInLocale: async (contentId: string, locale: string) => {
      return await authenticatedApi.get(`/content/${contentId}`, {
        headers: {
          [API_HEADERS.LOCALE]: locale, // Override the user's default locale
        },
      });
    },
    
    // Preview content with different theme
    previewContentWithTheme: async (contentId: string, theme: 'light' | 'dark') => {
      return await authenticatedApi.get(`/content/${contentId}/preview`, {
        headers: {
          [API_HEADERS.THEME]: theme, // Override user's theme preference
        },
      });
    },
  };
}

export const contentApi = new ContentApi();
```

### 2. Syncing Preferences with User Profile

For applications that store user preferences in the backend, you might need to sync local preferences with the server profile:

```typescript
// core/domains/preferences/syncService.ts
import { usePreferencesStore } from './store';
import { useUserStore } from '@/core/domains/user/store';
import { userApi } from '@/core/domains/user/api';

export class PreferenceSyncService {
  /**
   * Sync local preferences with user profile from server
   */
  async syncWithServer(): Promise<void> {
    const { user } = useUserStore.getState();
    
    // Only sync for authenticated users
    if (!user) {
      return;
    }
    
    try {
      // Fetch latest preferences from server
      const userProfile = await userApi.protected.getCurrentUser();
      
      // Only update preferences that exist in the profile
      const preferenceUpdates: Partial<typeof usePreferencesStore.getState()> = {};
      
      if (userProfile.preferences) {
        const { preferences } = userProfile;
        
        if (preferences.locale) preferenceUpdates.locale = preferences.locale;
        if (preferences.theme) preferenceUpdates.theme = preferences.theme;
        if (preferences.timezone) preferenceUpdates.timezone = preferences.timezone;
        if (preferences.accessibility) preferenceUpdates.accessibility = preferences.accessibility;
        if (preferences.contentDensity) preferenceUpdates.contentDensity = preferences.contentDensity;
        if (preferences.unitSystem) preferenceUpdates.unitSystem = preferences.unitSystem;
      }
      
      // Update local preferences if there are changes
      if (Object.keys(preferenceUpdates).length > 0) {
        // Use the "set" function from Zustand
        usePreferencesStore.setState(preferenceUpdates);
      }
    } catch (error) {
      console.error('Failed to sync preferences with server:', error);
      // Continue with local preferences
    }
  }
  
  /**
   * Save local preferences to server
   */
  async saveToServer(): Promise<void> {
    const { user } = useUserStore.getState();
    
    // Only sync for authenticated users
    if (!user) {
      return;
    }
    
    const {
      locale,
      theme,
      timezone,
      accessibility,
      contentDensity,
      unitSystem,
    } = usePreferencesStore.getState();
    
    try {
      // Send preferences to server
      await userApi.protected.updatePreferences({
        locale,
        theme,
        timezone,
        accessibility,
        contentDensity,
        unitSystem,
      });
    } catch (error) {
      console.error('Failed to save preferences to server:', error);
      // Continue with local preferences
    }
  }
}

// Create a hook for easy access to the sync service
export function usePreferenceSync() {
  const syncService = new PreferenceSyncService();
  
  return {
    syncWithServer: () => syncService.syncWithServer(),
    saveToServer: () => syncService.saveToServer(),
  };
}
```

### 3. Context-Specific Preferences

Some applications may need to handle different preferences for different contexts (e.g., work vs. personal):

```typescript
// core/domains/preferences/contextStore.ts
import { create } from 'zustand';
import { persist } from 'zustand/middleware';
import AsyncStorage from '@react-native-async-storage/async-storage';

export type PreferenceContext = 'personal' | 'work' | 'custom';

interface ContextState {
  activeContext: PreferenceContext;
  setActiveContext: (context: PreferenceContext) => void;
}

export const usePreferenceContextStore = create<ContextState>()(
  persist(
    (set) => ({
      activeContext: 'personal',
      setActiveContext: (activeContext) => set({ activeContext }),
    }),
    {
      name: 'preference-context-storage',
      storage: {
        getItem: async (name) => {
          const value = await AsyncStorage.getItem(name);
          return value ?? null;
        },
        setItem: async (name, value) => {
          await AsyncStorage.setItem(name, value);
        },
        removeItem: async (name) => {
          await AsyncStorage.removeItem(name);
        },
      },
    }
  )
);

// Enhanced provider that includes context
export class ContextualPreferencesHeaderProvider extends UserPreferencesHeaderProvider {
  id = 'contextual-user-preferences';
  
  async getHeaders(): Promise<Record<string, string | undefined>> {
    // Get base preference headers
    const headers = await super.getHeaders();
    
    // Add context information
    const { activeContext } = usePreferenceContextStore.getState();
    
    return {
      ...headers,
      'X-PREFERENCE-CONTEXT': activeContext,
    };
  }
}
```

## Testing Strategies

### 1. Unit Testing the Provider

```typescript
// __tests__/core/shared/api/headers/providers/userPreferencesHeaderProvider.test.ts
import { UserPreferencesHeaderProvider } from '@/core/shared/api/headers/providers/userPreferencesHeaderProvider';
import { usePreferencesStore } from '@/core/domains/preferences/store';
import { API_HEADERS } from '@/core/shared/constants/headers';

describe('UserPreferencesHeaderProvider', () => {
  let provider: UserPreferencesHeaderProvider;
  
  beforeEach(() => {
    // Reset mocks and state
    jest.clearAllMocks();
    
    // Reset preferences store to default values
    usePreferencesStore.setState({
      locale: 'en-US',
      theme: 'system',
      timezone: 'America/New_York',
      accessibility: 'default',
      contentDensity: 'default',
      unitSystem: 'auto',
      sharePreferencesWithApi: true,
      // Include the required functions to satisfy the type
      setLocale: jest.fn(),
      setTheme: jest.fn(),
      setTimezone: jest.fn(),
      setAccessibility: jest.fn(),
      setContentDensity: jest.fn(),
      setUnitSystem: jest.fn(),
      setSharePreferencesWithApi: jest.fn(),
      resetToDefaults: jest.fn(),
    });
    
    // Create provider instance
    provider = new UserPreferencesHeaderProvider();
  });
  
  it('should return user preference headers', async () => {
    // Update preferences store with test values
    usePreferencesStore.setState({
      locale: 'fr-FR',
      theme: 'dark',
      timezone: 'Europe/Paris',
      accessibility: 'high-contrast',
      contentDensity: 'compact',
      unitSystem: 'metric',
    });
    
    const headers = await provider.getHeaders();
    
    // Verify headers contain the correct values
    expect(headers[API_HEADERS.LOCALE]).toBe('fr-FR');
    expect(headers[API_HEADERS.THEME]).toBe('dark');
    expect(headers[API_HEADERS.TIMEZONE]).toBe('Europe/Paris');
    expect(headers[API_HEADERS.ACCESSIBILITY]).toBe('high-contrast');
    expect(headers[API_HEADERS.CONTENT_DENSITY]).toBe('compact');
    expect(headers[API_HEADERS.UNITS]).toBe('metric');
  });
  
  it('should not include default values in headers', async () => {
    // 'system', 'default', and 'auto' values should be excluded
    usePreferencesStore.setState({
      theme: 'system',
      accessibility: 'default',
      contentDensity: 'default',
      unitSystem: 'auto',
    });
    
    const headers = await provider.getHeaders();
    
    expect(headers[API_HEADERS.THEME]).toBeUndefined();
    expect(headers[API_HEADERS.ACCESSIBILITY]).toBeUndefined();
    expect(headers[API_HEADERS.CONTENT_DENSITY]).toBeUndefined();
    expect(headers[API_HEADERS.UNITS]).toBeUndefined();
  });
  
  it('should not include any headers when user opts out of sharing', async () => {
    // Opt out of sharing preferences
    usePreferencesStore.setState({
      sharePreferencesWithApi: false,
      locale: 'fr-FR',
      theme: 'dark',
    });
    
    const headers = await provider.getHeaders();
    
    // Should return empty object
    expect(Object.keys(headers).length).toBe(0);
    expect(headers[API_HEADERS.LOCALE]).toBeUndefined();
    expect(headers[API_HEADERS.THEME]).toBeUndefined();
  });
});
```

### 2. Integration Testing with API Client

```typescript
// __tests__/integration/api/userPreferencesIntegration.test.ts
import { authenticatedApi } from '@/core/shared/api/client';
import { UserPreferencesHeaderProvider } from '@/core/shared/api/headers/providers/userPreferencesHeaderProvider';
import { usePreferencesStore } from '@/core/domains/preferences/store';
import { API_HEADERS } from '@/core/shared/constants/headers';
import MockAdapter from 'axios-mock-adapter';

describe('User Preferences Headers Integration', () => {
  let mockAxios: MockAdapter;
  
  beforeEach(() => {
    // Setup mock for the Axios instance
    mockAxios = new MockAdapter((authenticatedApi as any).client);
    
    // Reset preferences store
    usePreferencesStore.setState({
      locale: 'en-US',
      theme: 'system',
      timezone: 'America/New_York',
      accessibility: 'default',
      contentDensity: 'default',
      unitSystem: 'auto',
      sharePreferencesWithApi: true,
      // Include the required functions
      setLocale: jest.fn(),
      setTheme: jest.fn(),
      setTimezone: jest.fn(),
      setAccessibility: jest.fn(),
      setContentDensity: jest.fn(),
      setUnitSystem: jest.fn(),
      setSharePreferencesWithApi: jest.fn(),
      resetToDefaults: jest.fn(),
    });
    
    // Register preferences header provider for testing
    authenticatedApi.registerHeaderProvider(new UserPreferencesHeaderProvider());
  });
  
  afterEach(() => {
    mockAxios.restore();
  });
  
  it('should include user preference headers in API requests', async () => {
    // Set specific preferences for testing
    usePreferencesStore.setState({
      locale: 'es-ES',
      theme: 'dark',
      timezone: 'Europe/Madrid',
    });
    
    // Setup mock response
    mockAxios.onGet('/test-endpoint').reply((config) => {
      // Check that preference headers are present
      expect(config.headers[API_HEADERS.LOCALE]).toBe('es-ES');
      expect(config.headers[API_HEADERS.THEME]).toBe('dark');
      expect(config.headers[API_HEADERS.TIMEZONE]).toBe('Europe/Madrid');
      
      return [200, { success: true }];
    });
    
    // Make request
    await authenticatedApi.get('/test-endpoint');
    
    // Verification is done in the mock response
    expect(mockAxios.history.get.length).toBe(1);
  });
  
  it('should allow per-request header overrides', async () => {
    // Set default preferences
    usePreferencesStore.setState({
      locale: 'en-US',
      theme: 'light',
    });
    
    // Setup mock response
    mockAxios.onGet('/test-endpoint').reply((config) => {
      // Check that the override header is used instead of store value
      expect(config.headers[API_HEADERS.LOCALE]).toBe('fr-FR');
      expect(config.headers[API_HEADERS.THEME]).toBe('light'); // From store, not overridden
      
      return [200, { success: true }];
    });
    
    // Make request with locale override
    await authenticatedApi.get('/test-endpoint', {
      headers: {
        [API_HEADERS.LOCALE]: 'fr-FR',
      },
    });
    
    // Verification is done in the mock response
    expect(mockAxios.history.get.length).toBe(1);
  });
});
```

## Privacy and Security Considerations

When implementing user preference headers, it's important to consider these privacy and security best practices to protect user data while still providing personalization:

1. **User Consent**:
   * (Do ✅) Always provide users with the option to opt out of sharing preferences with the API.
   * (Do ✅) Clearly explain how preference information is used by your application.
   * (Consider 🤔) Implementing granular controls for which preferences are shared.

2. **Data Minimization**:
   * (Do ✅) Only include necessary preference information in headers.
   * (Do ✅) Exclude default values to minimize data transfer.
   * (Don't ❌) Include personally identifiable information in preference headers.

3. **Transport Security**:
   * (Do ✅) Always transmit preference headers over HTTPS.
   * (Consider 🤔) Hashing preference values that might reveal sensitive information.

4. **Storage Security**:
   * (Do ✅) Use secure, encrypted storage for persistence.
   * (Consider 🤔) Implementing timeout periods for sensitive preferences.

5. **Preference Validation**:
   * (Do ✅) Validate preference values on both client and server.
   * (Don't ❌) Trust client-provided preferences for security decisions.

## Best Practices

### 1. Performance Optimization

* **Cache preferences** in memory during app session to avoid repeated AsyncStorage access.
* **Batch preference updates** when multiple preferences change simultaneously.
* **Debounce preference syncing** with the server to prevent excessive API calls.

### 2. Preference Management UI

* **Provide a dedicated settings screen** for users to manage their preferences.
* **Group related preferences** for better usability.
* **Show real-time previews** of preference changes when possible.
* **Include an explicit option** to control preference sharing with APIs.

### 3. Integration Best Practices

* **Load preferences early** in the application lifecycle.
* **Handle preference loading errors** gracefully with sensible defaults.
* **Maintain preference continuity** across app updates.
* **Consider device capabilities** when applying preferences (e.g., high-contrast might not work on all devices).

### 4. Preference Lifecycle Management

* **Sync preferences** across devices for logged-in users.
* **Preserve preferences** during account transitions when appropriate.
* **Provide reset options** for individual preferences and all preferences.
* **Migrate preferences** when your preference schema changes.

## Migration Considerations

If you're transitioning to this user preferences header approach, consider the following migration paths:

### From Hard-Coded Preferences

If your application currently uses hard-coded preferences directly in API calls:

1. **Identify all hard-coded preferences** in your codebase, typically found near API call sites
2. **Create the preference store** to centralize preference management
3. **Implement the preference header provider** as outlined in this guide
4. **Remove hard-coded preferences** from individual API calls
5. **Update unit tests** to reflect the new approach

### From Query Parameters

If you're currently passing user preferences as query parameters:

1. **Identify query parameter patterns** used across your API calls
2. **Map query parameters to headers** in your implementation
3. **Coordinate with backend teams** to support both approaches during transition
4. **Gradually migrate endpoints** to use header-based preferences
5. **Remove query parameter code** once migration is complete

### From Server-Side User Profile

If preferences are currently stored and retrieved solely from server profiles:

1. **Implement client-side preference store** while maintaining server storage
2. **Create synchronization logic** between client and server preferences
3. **Add header provider** to include preferences in API calls
4. **Update backend services** to prioritize header preferences over stored preferences when present
5. **Monitor performance improvements** from reduced profile lookups

## Related Documents

* [](/docs/api/headers/header-customization) - Core header customization patterns
* [Device Identification Headers](/docs/api/headers/header-customization/device-identification) - Device-specific header implementation
* [API Client Architecture](/docs/api/client-architecture) - Base API client implementation
* [Client State Management](/docs/state-management/client-state) - Zustand store patterns
* [Accessibility Guidelines](/docs/ui-development/accessibility) - Best practices for accessibility features

## Summary

User preference headers provide a robust mechanism for communicating user settings to backend services, enabling personalized experiences without additional API calls. By implementing the `UserPreferencesHeaderProvider` and integrating it with our API client architecture, we ensure consistent preference application across all API interactions while respecting user privacy choices.

Key takeaways:

* Use Zustand for preference state management and persistence
* Implement the HeaderProvider pattern for seamless integration with API clients
* Only include non-default preference values in headers
* Respect user opt-out options for preference sharing
* Enable per-request overrides for specific use cases
* Consider both performance and privacy implications

This implementation approach ensures that user preferences are consistently applied across your application while maintaining the flexibility to override preferences when needed for specific contexts.


# UTA API Integration: Device Identification Headers
URL: https://dev.updatetheapp.com/docs/api/headers/device-identification
Documentation: https://dev.updatetheapp.com/docs/api/headers/device-identification

Implementation guide for device identification and tracking headers across API requests
        
***

title: Device Identification Headers
description: Implementation guide for device identification and tracking headers across API requests
----------------------------------------------------------------------------------------------------

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Callout } from 'fumadocs-ui/components/callout';

# Device Identification Headers

## Overview

This guide provides a detailed implementation approach for device identification headers, a critical component of our API header customization architecture. Device headers enable backend services to identify, track, and optimize experiences based on the specific device making API requests. They form the foundation for device-specific features, analytics, and security auditing.

<Mermaid
  chart={`
sequenceDiagram
  participant App as React Native App
  participant Provider as DeviceHeaderProvider
  participant ApiClient as API Client
  participant Backend as Backend Service
  
  App->>Provider: Initialize app
  Provider->>Provider: Collect device info
  App->>ApiClient: Make API request
  ApiClient->>Provider: getHeaders()
  Provider-->>ApiClient: Device headers
  ApiClient->>Backend: Request with device headers
  Backend->>Backend: Process device context
  Backend-->>ApiClient: Response with optimizations
  ApiClient-->>App: Processed response
`}
/>

## Purpose & Scope

This implementation guide covers:

* Implementing device identification headers using our header provider pattern
* Collecting essential device information in React Native applications
* Persisting device identifiers across app sessions
* Security considerations for device tracking
* Integration with analytics and monitoring systems

This document extends the core concepts established in the [](/docs/api/headers/header-customization) guide, focusing specifically on device identification implementation patterns.

## Prerequisites

To effectively implement device identification headers, you should be familiar with:

* [](/docs/api/headers/header-customization) - Core concepts and the `HeaderProvider` interface
* [API Client Architecture](/docs/api/client-architecture) - Understanding of our API client structure
* React Native device information libraries (specifically `react-native-device-info`)
* Basic device security principles

## Key Device Headers

The following device headers provide essential context about the requesting device:

| Header           | Description                | Purpose                           | Example Value                            |
| ---------------- | -------------------------- | --------------------------------- | ---------------------------------------- |
| `X-DEVICE-UUID`  | Unique device identifier   | Device tracking & user experience | `"550e8400-e29b-41d4-a716-446655440000"` |
| `X-DEVICE-TYPE`  | Physical device type       | Response optimization             | `"Handset"` or `"Tablet"`                |
| `X-APP-VERSION`  | App version + build number | Version-specific handling         | `"2.4.1+42"`                             |
| `X-OS-VERSION`   | Operating system version   | OS-specific optimizations         | `"iOS 16.2"` or `"Android 13"`           |
| `X-DEVICE-MODEL` | Device model               | Device-specific optimizations     | `"iPhone 14 Pro"`                        |
| `X-CARRIER`      | Network carrier            | Network-specific optimizations    | `"AT&T"`                                 |

## Implementation

### 1. Base Device Header Provider

First, we'll implement a complete `DeviceHeaderProvider` that collects essential device information:

```typescript
// core/shared/api/headers/providers/deviceHeaderProvider.ts
import { HeaderProvider } from '../types';
import { API_HEADERS } from '@/core/shared/constants/headers';
import DeviceInfo from 'react-native-device-info';
import { Platform } from 'react-native';
import { storage } from '@/core/shared/utils/storage';

export class DeviceHeaderProvider implements HeaderProvider {
  id = 'device';
  priority = 90; // High priority to ensure device context is available to other providers
  private deviceId: string | null = null;
  
  /**
   * Returns all device-related headers for API requests
   */
  async getHeaders(): Promise<Record<string, string | undefined>> {
    // Ensure we have a device ID
    if (!this.deviceId) {
      this.deviceId = await this.getOrCreateDeviceId();
    }
    
    // Collect basic device information
    const appVersion = DeviceInfo.getVersion();
    const buildNumber = DeviceInfo.getBuildNumber();
    const deviceType = DeviceInfo.getDeviceType();
    const deviceModel = await DeviceInfo.getModel();
    const systemVersion = DeviceInfo.getSystemVersion();
    const carrier = await DeviceInfo.getCarrierSync();
    
    return {
      [API_HEADERS.DEVICE_UUID]: this.deviceId,
      [API_HEADERS.DEVICE_TYPE]: deviceType,
      [API_HEADERS.APP_VERSION]: `${appVersion}+${buildNumber}`,
      [API_HEADERS.OS_VERSION]: `${Platform.OS} ${systemVersion}`,
      [API_HEADERS.DEVICE_MODEL]: deviceModel,
      ...(carrier ? { [API_HEADERS.CARRIER]: carrier } : {}),
    };
  }
  
  /**
   * Retrieves a stored device ID or creates a new one.
   * We persist this ID to provide consistent device identification
   * across app sessions.
   */
  private async getOrCreateDeviceId(): Promise<string> {
    // Try to get stored device ID
    let deviceId = await storage.getSecureItem('device_uuid');
    
    if (!deviceId) {
      // Create new device ID if none exists
      try {
        // First try to use the device's unique ID if available
        deviceId = await DeviceInfo.getUniqueId();
      } catch (error) {
        // Fallback to a generated UUID
        deviceId = this.generateUuidV4();
      }
      
      // Store for future use
      await storage.setSecureItem('device_uuid', deviceId);
    }
    
    return deviceId;
  }
  
  /**
   * Generate a UUID v4 as fallback device identifier
   */
  private generateUuidV4(): string {
    return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, function(c) {
      const r = Math.random() * 16 | 0, 
          v = c == 'x' ? r : (r & 0x3 | 0x8);
      return v.toString(16);
    });
  }
}
```

### 2. Registering the Provider

Add the device header provider to your API clients as outlined in the API Header Customization guide:

```typescript
// Example: Setting up API clients with device headers
import { PublicApiClient, AuthenticatedApiClient } from '@/core/shared/api/client';
import { DeviceHeaderProvider } from '@/core/shared/api/headers/providers/deviceHeaderProvider';

// Client setup
const apiConfig = { baseURL: process.env.API_BASE_URL };

// Create client instances
export const publicApi = new PublicApiClient(apiConfig);
export const authenticatedApi = new AuthenticatedApiClient(apiConfig);

// Register device header provider with both clients
const deviceHeaderProvider = new DeviceHeaderProvider();
publicApi.registerHeaderProvider(deviceHeaderProvider);
authenticatedApi.registerHeaderProvider(deviceHeaderProvider);
```

### 3. Enhanced Implementation with Device Fingerprinting

For applications requiring stronger device identification, you can extend the basic provider with fingerprinting:

```typescript
// core/shared/api/headers/providers/enhancedDeviceHeaderProvider.ts
import { DeviceHeaderProvider } from './deviceHeaderProvider';
import DeviceInfo from 'react-native-device-info';
import { Platform } from 'react-native';
import { API_HEADERS } from '@/core/shared/constants/headers';

export class EnhancedDeviceHeaderProvider extends DeviceHeaderProvider {
  id = 'enhanced-device';
  
  /**
   * Creates a device fingerprint from multiple device characteristics
   */
  private async createDeviceFingerprint(): Promise<string> {
    // Collect various device properties
    const brand = DeviceInfo.getBrand();
    const model = await DeviceInfo.getModel();
    const systemName = DeviceInfo.getSystemName();
    const systemVersion = DeviceInfo.getSystemVersion();
    const buildId = await DeviceInfo.getBuildId();
    const deviceName = await DeviceInfo.getDeviceName();
    const timezone = DeviceInfo.getTimezone();
    const hasNotch = DeviceInfo.hasNotch();
    
    // Combine properties into fingerprint string
    const fingerprintData = [
      brand,
      model,
      systemName,
      systemVersion,
      buildId,
      deviceName,
      timezone,
      hasNotch ? 'notch' : 'no-notch',
      Platform.constants?.reactNativeVersion || '',
    ].join('|');
    
    // Create hash of the fingerprint
    const fingerprintHash = await this.hashString(fingerprintData);
    return fingerprintHash;
  }
  
  /**
   * Simple hash function for fingerprint
   */
  private async hashString(str: string): Promise<string> {
    // This is a simple hash for demonstration purposes
    // In a real implementation, use a cryptographic hash function
    let hash = 0;
    for (let i = 0; i < str.length; i++) {
      const char = str.charCodeAt(i);
      hash = ((hash << 5) - hash) + char;
      hash = hash & hash;
    }
    return hash.toString(16);
  }
  
  /**
   * Override getHeaders to include fingerprint
   */
  async getHeaders(): Promise<Record<string, string | undefined>> {
    // Get base headers from parent class
    const baseHeaders = await super.getHeaders();
    
    // Add fingerprint
    const fingerprint = await this.createDeviceFingerprint();
    
    return {
      ...baseHeaders,
      'X-DEVICE-FINGERPRINT': fingerprint,
    };
  }
}
```

## Advanced Use Cases

### 1. Device Change Detection

In some applications, detecting when a user's device changes can be important for security. Here's how to implement device change detection:

```typescript
// core/domains/security/deviceChangeDetector.ts
import { HeaderProvider } from '@/core/shared/api/headers/types';
import { API_HEADERS } from '@/core/shared/constants/headers';
import { useAuthStore } from '@/core/domains/auth/store';
import { storage } from '@/core/shared/utils/storage';

export class DeviceChangeDetector {
  /**
   * Checks if the current device differs from the last authenticated device
   * @param userId The ID of the current user
   * @param currentDeviceId The current device UUID
   */
  async checkDeviceChanged(userId: string, currentDeviceId: string): Promise<boolean> {
    const storageKey = `last_device_${userId}`;
    const lastDeviceId = await storage.getSecureItem(storageKey);
    
    // If no previous device ID or same device, no change detected
    if (!lastDeviceId || lastDeviceId === currentDeviceId) {
      // Update the last device ID
      await storage.setSecureItem(storageKey, currentDeviceId);
      return false;
    }
    
    // Device has changed
    // Update the stored device ID
    await storage.setSecureItem(storageKey, currentDeviceId);
    return true;
  }
}

/**
 * Hook to check device changes on login
 */
export function useDeviceChangeDetection() {
  const deviceChangeDetector = new DeviceChangeDetector();
  
  const checkDeviceChange = async (deviceId: string): Promise<boolean> => {
    const { user } = useAuthStore.getState();
    
    if (!user) {
      return false;
    }
    
    return deviceChangeDetector.checkDeviceChanged(user.id, deviceId);
  };
  
  return { checkDeviceChange };
}
```

### 2. Network Quality Headers

Extending device headers with network information can help backends optimize responses based on connection quality:

```typescript
// core/shared/api/headers/providers/networkQualityHeaderProvider.ts
import { HeaderProvider } from '../types';
import { API_HEADERS } from '@/core/shared/constants/headers';
import NetInfo, { NetInfoState } from '@react-native-community/netinfo';

export class NetworkQualityHeaderProvider implements HeaderProvider {
  id = 'network-quality';
  priority = 85; // Just below device headers
  
  async getHeaders(): Promise<Record<string, string | undefined>> {
    try {
      const netInfo = await NetInfo.fetch();
      
      return {
        'X-CONNECTION-TYPE': netInfo.type,
        'X-CONNECTION-EFFECTIVE-TYPE': netInfo.details?.effectiveType,
        ...(netInfo.isConnected !== null ? { 'X-CONNECTED': netInfo.isConnected.toString() } : {}),
        ...(typeof netInfo.details?.isConnectionExpensive === 'boolean' 
            ? { 'X-EXPENSIVE-CONNECTION': netInfo.details.isConnectionExpensive.toString() } 
            : {}),
      };
    } catch (error) {
      console.warn('Failed to get network information:', error);
      return {};
    }
  }
  
  /**
   * Subscribe to network changes and update network quality metrics
   */
  subscribeToNetworkChanges(callback?: (state: NetInfoState) => void): () => void {
    return NetInfo.addEventListener(state => {
      if (callback) {
        callback(state);
      }
    });
  }
}
```

## Testing Strategies

### 1. Unit Testing the Provider

```typescript
// __tests__/core/shared/api/headers/providers/deviceHeaderProvider.test.ts
import { DeviceHeaderProvider } from '@/core/shared/api/headers/providers/deviceHeaderProvider';
import DeviceInfo from 'react-native-device-info';
import { API_HEADERS } from '@/core/shared/constants/headers';
import { storage } from '@/core/shared/utils/storage';

// Mock dependencies
jest.mock('react-native-device-info');
jest.mock('@/core/shared/utils/storage');

describe('DeviceHeaderProvider', () => {
  let provider: DeviceHeaderProvider;
  
  beforeEach(() => {
    // Reset mocks
    jest.clearAllMocks();
    
    // Setup default mock values
    (DeviceInfo.getVersion as jest.Mock).mockReturnValue('1.0.0');
    (DeviceInfo.getBuildNumber as jest.Mock).mockReturnValue('42');
    (DeviceInfo.getDeviceType as jest.Mock).mockReturnValue('Handset');
    (DeviceInfo.getModel as jest.Mock).mockResolvedValue('iPhone 12');
    (DeviceInfo.getSystemVersion as jest.Mock).mockReturnValue('14.5');
    (DeviceInfo.getCarrierSync as jest.Mock).mockReturnValue('T-Mobile');
    (DeviceInfo.getUniqueId as jest.Mock).mockResolvedValue('device-123');
    
    // Mock storage
    (storage.getSecureItem as jest.Mock).mockResolvedValue(null);
    (storage.setSecureItem as jest.Mock).mockResolvedValue(undefined);
    
    // Create provider instance
    provider = new DeviceHeaderProvider();
  });
  
  it('should retrieve device UUID from storage if it exists', async () => {
    // Setup storage mock to return existing device ID
    (storage.getSecureItem as jest.Mock).mockResolvedValue('stored-device-id');
    
    const headers = await provider.getHeaders();
    
    // Assert stored device ID is used
    expect(headers[API_HEADERS.DEVICE_UUID]).toBe('stored-device-id');
    
    // Verify storage was checked but not set
    expect(storage.getSecureItem).toHaveBeenCalledWith('device_uuid');
    expect(storage.setSecureItem).not.toHaveBeenCalled();
  });
  
  it('should create and store new device UUID if none exists', async () => {
    // Ensure storage returns null (no existing ID)
    (storage.getSecureItem as jest.Mock).mockResolvedValue(null);
    
    const headers = await provider.getHeaders();
    
    // Assert device ID is retrieved from DeviceInfo and stored
    expect(headers[API_HEADERS.DEVICE_UUID]).toBe('device-123');
    expect(storage.setSecureItem).toHaveBeenCalledWith('device_uuid', 'device-123');
  });
  
  it('should include all required device headers', async () => {
    const headers = await provider.getHeaders();
    
    // Verify all expected headers are present
    expect(headers[API_HEADERS.DEVICE_UUID]).toBeDefined();
    expect(headers[API_HEADERS.DEVICE_TYPE]).toBe('Handset');
    expect(headers[API_HEADERS.APP_VERSION]).toBe('1.0.0+42');
    expect(headers[API_HEADERS.OS_VERSION]).toContain('14.5');
    expect(headers[API_HEADERS.DEVICE_MODEL]).toBe('iPhone 12');
    expect(headers[API_HEADERS.CARRIER]).toBe('T-Mobile');
  });
  
  it('should handle errors from DeviceInfo gracefully', async () => {
    // Make DeviceInfo.getUniqueId throw an error
    (DeviceInfo.getUniqueId as jest.Mock).mockRejectedValue(new Error('Failed to get unique ID'));
    
    // Mock the UUID generation
    const mockUuid = 'generated-uuid-123';
    jest.spyOn(provider as any, 'generateUuidV4').mockReturnValue(mockUuid);
    
    const headers = await provider.getHeaders();
    
    // Verify fallback UUID was used
    expect(headers[API_HEADERS.DEVICE_UUID]).toBe(mockUuid);
    expect(storage.setSecureItem).toHaveBeenCalledWith('device_uuid', mockUuid);
  });
});
```

### 2. Integration Testing with API Client

```typescript
// __tests__/integration/api/deviceHeadersIntegration.test.ts
import { authenticatedApi } from '@/core/shared/api/client';
import { DeviceHeaderProvider } from '@/core/shared/api/headers/providers/deviceHeaderProvider';
import { API_HEADERS } from '@/core/shared/constants/headers';
import MockAdapter from 'axios-mock-adapter';

describe('Device Headers Integration', () => {
  let mockAxios: MockAdapter;
  
  beforeEach(() => {
    // Setup mock for the Axios instance
    mockAxios = new MockAdapter((authenticatedApi as any).client);
    
    // Register device header provider for testing
    authenticatedApi.registerHeaderProvider(new DeviceHeaderProvider());
  });
  
  afterEach(() => {
    mockAxios.restore();
  });
  
  it('should include device headers in API requests', async () => {
    // Setup mock response
    mockAxios.onGet('/test-endpoint').reply((config) => {
      // Check that device headers are present
      expect(config.headers[API_HEADERS.DEVICE_UUID]).toBeDefined();
      expect(config.headers[API_HEADERS.DEVICE_TYPE]).toBeDefined();
      expect(config.headers[API_HEADERS.APP_VERSION]).toBeDefined();
      
      return [200, { success: true }];
    });
    
    // Make request
    await authenticatedApi.get('/test-endpoint');
    
    // Verification is done in the mock response
    expect(mockAxios.history.get.length).toBe(1);
  });
});
```

## Security Considerations

When implementing device headers, consider these security best practices:

1. **Storage Security**: Always store device identifiers in secure storage like Keychain (iOS) or EncryptedSharedPreferences (Android).

2. **Identifier Persistence**:
   * (Do ✅) Use non-resettable identifiers for fraud prevention and security-critical features.
   * (Do ✅) Use resettable identifiers for analytics and user experience features.
   * (Consider 🤔) Supporting "reset tracking identifiers" functionality for privacy-conscious users.

3. **Header Transport**:
   * (Do ✅) Always send device headers over HTTPS connections.
   * (Don't ❌) Include sensitive device information that could compromise user privacy.

4. **PII Considerations**:
   * (Don't ❌) Include personally identifiable information in device headers.
   * (Don't ❌) Use actual device names that may contain user names.
   * (Do ✅) Consider hashing any potentially user-identifying values.

5. **Compliance**:
   * (Do ✅) Ensure device tracking complies with relevant privacy regulations (GDPR, CCPA, etc.).
   * (Do ✅) Disclose device tracking in your privacy policy.
   * (Do ✅) Allow users to opt-out of non-essential tracking when required by regulations.

## Best Practices

1. **Initialization**:
   * Initialize device header providers early in the application lifecycle to ensure consistent tracking.
   * Consider deferring fingerprinting to a background task if it's computationally expensive.

2. **Header Retention**:
   * (Do ✅) Keep device headers consistent across the application session.
   * (Do ✅) Cache device information to avoid repeated expensive device queries.
   * (Consider 🤔) Updating device information periodically (e.g., daily) for long-running apps.

3. **Performance**:
   * Cache device information that doesn't change frequently.
   * Use lazy loading for expensive device information operations.
   * Consider batching device information updates.

4. **Troubleshooting**:
   * Include device headers in application logs for easier debugging.
   * Develop a system to correlate backend and client-side logs using device identifiers.

## Related Documents

* [](/docs/api/headers/header-customization/api-header-customization) - Core header customization patterns
* [API Client Architecture](/docs/api/client-architecture) - Base API client implementation
* [Error Handling](/docs/api/error-handling) - Error handling architecture
* [Security Guidelines](/docs/security/mobile-security-guidelines) - Mobile application security best practices

## Summary

Device identification headers provide critical context for backend services to understand the client environment. By implementing robust device tracking using the `HeaderProvider` pattern, we can enable device-specific optimizations, enhance security, and improve analytics across our application. The implementation patterns provided in this guide work seamlessly with our established API client architecture while maintaining appropriate security and privacy safeguards.

Key takeaways:

* Use the `DeviceHeaderProvider` to consistently attach device context to all API requests
* Securely persist device identifiers across app sessions
* Consider enhanced implementations for more sophisticated device fingerprinting
* Always balance device tracking needs with privacy and security considerations
* Integrate with analytics systems for better user experience monitoring


# UTA API Integration: Session Tracking Headers
URL: https://dev.updatetheapp.com/docs/api/headers/session-tracking
Documentation: https://dev.updatetheapp.com/docs/api/headers/session-tracking

Implementation guide for session tracking and correlation headers in API requests
        
***

title: Session Tracking Headers
description: Implementation guide for session tracking and correlation headers in API requests
----------------------------------------------------------------------------------------------

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Callout } from 'fumadocs-ui/components/callout';

# Session Tracking Headers

## Overview

This guide details the implementation of session tracking headers, a key component of our API header customization architecture. Session headers create continuity across API requests, enabling request correlation, user journey tracking, and performance monitoring. These headers are essential for maintaining context across distributed systems, debugging complex interactions, and analyzing user behavior patterns.

<Mermaid
  chart={`
sequenceDiagram
  participant User as User
  participant App as Mobile App
  participant Provider as SessionHeaderProvider
  participant ApiClient as API Client
  participant API as API Gateway
  participant Services as Backend Services
  
  User->>App: Open application
  App->>Provider: Initialize session
  Provider->>Provider: Generate session ID
  
  User->>App: Perform action
  App->>ApiClient: Make API request
  ApiClient->>Provider: getHeaders()
  Provider-->>ApiClient: Session headers
  ApiClient->>API: Request with session headers
  API->>Services: Forward request with context
  Services-->>API: Response
  API-->>ApiClient: Response
  ApiClient-->>App: Processed response
  
  Note over Provider,API: Session ID remains consistent<br/>Request IDs are unique per request
`}
/>

## Quick Start

If you need to quickly implement session tracking in your application, follow these three steps:

1. **Create a session header provider**:
   ```typescript
   // core/shared/api/headers/providers/sessionHeaderProvider.ts
   export class SessionHeaderProvider implements HeaderProvider {
     id = 'session';
     priority = 80;
     
     async getHeaders() {
       const sessionId = await this.getOrCreateSessionId();
       const requestId = `req-${uuidv4()}`;
       
       return {
         [API_HEADERS.SESSION_ID]: sessionId,
         [API_HEADERS.REQUEST_ID]: requestId,
         [API_HEADERS.REQUEST_START_TIME]: new Date().toISOString(),
       };
     }
     
     private async getOrCreateSessionId() {
       let sessionId = await storage.getItem('current_session_id');
       if (!sessionId) {
         sessionId = `sess-${uuidv4()}`;
         await storage.setItem('current_session_id', sessionId);
       }
       return sessionId;
     }
   }
   ```

2. **Register with your API client**:
   ```typescript
   // core/shared/api/client.ts
   const apiClient = new AuthenticatedApiClient(config);
   apiClient.registerHeaderProvider(new SessionHeaderProvider());
   ```

3. **Add logging integration**:
   ```typescript
   // core/shared/logger/index.ts
   logger.addInterceptor((logEntry) => {
     // Add current session context to all log entries
     const sessionId = apiClient.getLastRequestHeader(API_HEADERS.SESSION_ID);
     const requestId = apiClient.getLastRequestHeader(API_HEADERS.REQUEST_ID);
     return {
       ...logEntry,
       sessionId,
       requestId,
     };
   });
   ```

For a complete implementation with more features, continue reading the sections below.

## Purpose & Scope

This implementation guide covers:

* Creating and maintaining unique session identifiers
* Generating per-request correlation IDs
* Implementing the appropriate header provider pattern
* Best practices for session management
* Integration with logging and analytics systems

This document builds upon the foundation established in the [](/docs/api/headers/header-customization) guide, with specific focus on implementing session tracking and correlation headers.

## Prerequisites

To effectively implement session tracking headers, you should be familiar with:

* [](/docs/api/headers/header-customization) - Core concepts and the `HeaderProvider` interface
* [API Client Architecture](/docs/api/client-architecture) - Understanding of our API client structure
* [Error Handling](/docs/api/error-handling) - How correlation IDs help with error tracing
* Basic principles of distributed tracing and request correlation

## Key Session Headers

The following session headers provide essential context for request tracking and correlation:

| Header                 | Description                          | Purpose                                    | Example Value                                 |
| ---------------------- | ------------------------------------ | ------------------------------------------ | --------------------------------------------- |
| `X-SESSION-ID`         | Persistent session identifier        | Session continuity & user journey tracking | `"sess-4f58a782-1b8c-4932-8998-5a3c987541e2"` |
| `X-REQUEST-ID`         | Unique identifier for each request   | Request identification & correlation       | `"req-c7d2b51f-e1b5-487e-9a34-95f893c428bf"`  |
| `X-CORRELATION-ID`     | ID for tracking across services      | Distributed tracing                        | `"corr-3a7bf5e1-009d-4648-a2c5-f0d1eb7f3f87"` |
| `X-REQUEST-START-TIME` | Timestamp when request was initiated | Performance timing                         | `"2023-07-15T14:25:32.145Z"`                  |

## Implementation

### 1. Session Header Provider

First, let's implement a complete `SessionHeaderProvider` that creates and maintains session information:

```typescript
// core/shared/api/headers/providers/sessionHeaderProvider.ts
import { HeaderProvider } from '../types';
import { API_HEADERS } from '@/core/shared/constants/headers';
import { storage } from '@/core/shared/utils/storage';
import { v4 as uuidv4 } from 'uuid';

export class SessionHeaderProvider implements HeaderProvider {
  id = 'session';
  priority = 80; // High priority but below device headers
  private sessionId: string | null = null;
  
  /**
   * Returns all session-related headers for API requests
   */
  async getHeaders(): Promise<Record<string, string | undefined>> {
    // Ensure we have a session ID
    if (!this.sessionId) {
      this.sessionId = await this.getOrCreateSessionId();
    }
    
    // Generate a unique request ID for this specific API call
    const requestId = this.generateRequestId();
    
    // Generate correlation ID (or use request ID if no existing correlation context)
    const correlationId = this.getCorrelationId() || requestId;
    
    // Capture request start time
    const requestStartTime = new Date().toISOString();
    
    return {
      [API_HEADERS.SESSION_ID]: this.sessionId,
      [API_HEADERS.REQUEST_ID]: requestId,
      [API_HEADERS.CORRELATION_ID]: correlationId,
      [API_HEADERS.REQUEST_START_TIME]: requestStartTime,
    };
  }
  
  /**
   * Retrieves the existing session ID or creates a new one
   */
  private async getOrCreateSessionId(): Promise<string> {
    // Try to get stored session ID
    let sessionId = await storage.getItem('current_session_id');
    
    if (!sessionId) {
      // Generate new session ID with sess- prefix
      sessionId = `sess-${uuidv4()}`;
      
      // Store for future use within this session
      await storage.setItem('current_session_id', sessionId);
      
      // Record session start time
      const sessionStartTime = new Date().toISOString();
      await storage.setItem('session_start_time', sessionStartTime);
    }
    
    return sessionId;
  }
  
  /**
   * Generate a unique request ID with req- prefix
   */
  private generateRequestId(): string {
    return `req-${uuidv4()}`;
  }
  
  /**
   * Get correlation ID from current context if available
   * This implementation uses a simple in-memory approach, but
   * a more robust implementation might use React context or another
   * method to propagate correlation IDs
   */
  private getCorrelationId(): string | null {
    // Simple implementation - in a real app, this might pull from
    // a more sophisticated correlation context system
    return null;
  }
  
  /**
   * Reset the session ID to force a new session
   */
  public async resetSession(): Promise<string> {
    // Generate new session ID
    const newSessionId = `sess-${uuidv4()}`;
    
    // Update stored session ID
    await storage.setItem('current_session_id', newSessionId);
    
    // Record new session start time
    const sessionStartTime = new Date().toISOString();
    await storage.setItem('session_start_time', sessionStartTime);
    
    // Update instance variable
    this.sessionId = newSessionId;
    
    return newSessionId;
  }
  
  /**
   * Get the current session duration in milliseconds
   */
  public async getSessionDuration(): Promise<number | null> {
    const sessionStartTime = await storage.getItem('session_start_time');
    
    if (!sessionStartTime) {
      return null;
    }
    
    const startTime = new Date(sessionStartTime).getTime();
    const currentTime = new Date().getTime();
    
    return currentTime - startTime;
  }
}
```

### 2. Distributed Tracing Enhancement

For applications requiring distributed tracing, we can extend the basic provider with more sophisticated correlation:

```typescript
// core/shared/api/headers/providers/tracingHeaderProvider.ts
import { SessionHeaderProvider } from './sessionHeaderProvider';
import { API_HEADERS } from '@/core/shared/constants/headers';

/**
 * Storage for the current trace context throughout the app lifecycle
 */
class TraceContextManager {
  private static instance: TraceContextManager;
  private correlationId: string | null = null;
  private traceState: Record<string, string> = {};
  
  public static getInstance(): TraceContextManager {
    if (!TraceContextManager.instance) {
      TraceContextManager.instance = new TraceContextManager();
    }
    return TraceContextManager.instance;
  }
  
  /**
   * Set the current correlation ID
   */
  setCorrelationId(id: string): void {
    this.correlationId = id;
  }
  
  /**
   * Get the current correlation ID
   */
  getCorrelationId(): string | null {
    return this.correlationId;
  }
  
  /**
   * Clear the current trace context
   */
  clearContext(): void {
    this.correlationId = null;
    this.traceState = {};
  }
  
  /**
   * Set a trace state value
   */
  setTraceState(key: string, value: string): void {
    this.traceState[key] = value;
  }
  
  /**
   * Get the full trace state
   */
  getTraceState(): Record<string, string> {
    return { ...this.traceState };
  }
  
  /**
   * Get the trace state as a W3C-compatible string
   */
  getTraceStateString(): string {
    return Object.entries(this.traceState)
      .map(([key, value]) => `${key}=${value}`)
      .join(',');
  }
}

/**
 * Enhanced session provider with distributed tracing capabilities
 */
export class TracingHeaderProvider extends SessionHeaderProvider {
  id = 'tracing';
  private traceContext: TraceContextManager;
  
  constructor() {
    super();
    this.traceContext = TraceContextManager.getInstance();
  }
  
  /**
   * Override to add trace context headers
   */
  async getHeaders(): Promise<Record<string, string | undefined>> {
    // Get base session headers
    const baseHeaders = await super.getHeaders();
    
    // Get trace context
    const correlationId = this.traceContext.getCorrelationId() || baseHeaders[API_HEADERS.CORRELATION_ID];
    const traceState = this.traceContext.getTraceStateString();
    
    // If this is a new correlation ID, store it
    if (correlationId && correlationId !== this.traceContext.getCorrelationId()) {
      this.traceContext.setCorrelationId(correlationId);
    }
    
    // Add tracing headers
    return {
      ...baseHeaders,
      [API_HEADERS.CORRELATION_ID]: correlationId,
      ...(traceState ? { 'traceparent': traceState } : {}),
    };
  }
  
  /**
   * Process incoming trace context from responses
   * @param headers Response headers containing trace info
   */
  processResponseTraceContext(headers: Record<string, string>): void {
    // Extract server-side correlation ID if present
    const serverCorrelationId = headers[API_HEADERS.CORRELATION_ID.toLowerCase()];
    
    if (serverCorrelationId) {
      this.traceContext.setCorrelationId(serverCorrelationId);
    }
    
    // Extract trace state if present
    const traceParent = headers['traceparent'];
    if (traceParent) {
      // Parse W3C trace context format
      // In a real implementation, we would properly parse the traceparent format
      this.traceContext.setTraceState('server-trace', traceParent);
    }
  }
}
```

### 3. Session Events Integration

To enhance analytics and monitoring, we can implement session event handling:

```typescript
// core/shared/api/headers/providers/sessionEventsProvider.ts
import { SessionHeaderProvider } from './sessionHeaderProvider';
import { EventEmitter } from '@/core/shared/utils/events';

/**
 * Events emitted by the session provider
 */
export type SessionEvents = {
  'session:created': { sessionId: string, timestamp: string };
  'session:ended': { sessionId: string, duration: number, timestamp: string };
  'request:sent': { requestId: string, sessionId: string, url: string, timestamp: string };
  'request:completed': { requestId: string, sessionId: string, duration: number, status: number, timestamp: string };
};

/**
 * Event emitter for session-related events
 */
export const sessionEvents = new EventEmitter<SessionEvents>();

/**
 * Session provider with event tracking
 */
export class SessionEventsProvider extends SessionHeaderProvider {
  id = 'session-events';
  private requestTimestamps: Map<string, number> = new Map();
  
  constructor() {
    super();
    this.setupResponseInterceptors();
  }
  
  /**
   * Override getHeaders to add event tracking
   */
  async getHeaders(): Promise<Record<string, string | undefined>> {
    const headers = await super.getHeaders();
    const requestId = headers[API_HEADERS.REQUEST_ID];
    const sessionId = headers[API_HEADERS.SESSION_ID];
    
    if (requestId && sessionId) {
      // Record request start time
      this.requestTimestamps.set(requestId, Date.now());
      
      // Emit request sent event
      sessionEvents.emit('request:sent', {
        requestId,
        sessionId,
        url: this.getCurrentUrl() || 'unknown',
        timestamp: new Date().toISOString(),
      });
    }
    
    return headers;
  }
  
  /**
   * Setup response interceptors to track request completion
   */
  private setupResponseInterceptors(): void {
    // This would be integrated with the API client in a real implementation
    // For demonstration purposes, here's the logic that would be used
    
    /*
    apiClient.client.interceptors.response.use(
      // Success interceptor
      (response) => {
        this.trackRequestCompletion(
          response.config.headers[API_HEADERS.REQUEST_ID],
          response.config.headers[API_HEADERS.SESSION_ID],
          response.status
        );
        return response;
      },
      // Error interceptor
      (error) => {
        if (error.response) {
          this.trackRequestCompletion(
            error.config.headers[API_HEADERS.REQUEST_ID],
            error.config.headers[API_HEADERS.SESSION_ID],
            error.response.status
          );
        }
        return Promise.reject(error);
      }
    );
    */
  }
  
  /**
   * Track request completion and emit events
   */
  private trackRequestCompletion(requestId: string, sessionId: string, status: number): void {
    if (!requestId || !sessionId) return;
    
    const startTime = this.requestTimestamps.get(requestId);
    if (!startTime) return;
    
    // Calculate duration
    const duration = Date.now() - startTime;
    
    // Clear from tracking map
    this.requestTimestamps.delete(requestId);
    
    // Emit completion event
    sessionEvents.emit('request:completed', {
      requestId,
      sessionId,
      duration,
      status,
      timestamp: new Date().toISOString(),
    });
  }
  
  /**
   * Get the current URL (simplified implementation)
   */
  private getCurrentUrl(): string | null {
    // In a real app, this might come from navigation state or another source
    return null;
  }
  
  /**
   * Override resetSession to emit session events
   */
  async resetSession(): Promise<string> {
    // Get current session ID before reset
    const oldSessionId = await this.getOrCreateSessionId();
    const duration = await this.getSessionDuration() || 0;
    
    // Emit session ended event
    if (oldSessionId) {
      sessionEvents.emit('session:ended', {
        sessionId: oldSessionId,
        duration,
        timestamp: new Date().toISOString(),
      });
    }
    
    // Create new session
    const newSessionId = await super.resetSession();
    
    // Emit session created event
    sessionEvents.emit('session:created', {
      sessionId: newSessionId,
      timestamp: new Date().toISOString(),
    });
    
    return newSessionId;
  }
}
```

## Integration with Application State

To enhance session management with application state awareness:

```typescript
// core/domains/session/store.ts
import { create } from 'zustand';
import { persist } from 'zustand/middleware';
import { SessionHeaderProvider } from '@/core/shared/api/headers/providers/sessionHeaderProvider';

interface SessionState {
  isActive: boolean;
  lastActiveTime: string | null;
  inactivityTimeout: number; // milliseconds
  
  markActive: () => void;
  checkSessionTimeout: () => boolean;
  resetInactivityTimer: () => void;
  setInactivityTimeout: (timeout: number) => void;
}

export const useSessionStore = create<SessionState>()(
  persist(
    (set, get) => ({
      isActive: true,
      lastActiveTime: new Date().toISOString(),
      inactivityTimeout: 30 * 60 * 1000, // 30 minutes by default
      
      markActive: () => set({ 
        isActive: true, 
        lastActiveTime: new Date().toISOString() 
      }),
      
      checkSessionTimeout: () => {
        const { lastActiveTime, inactivityTimeout } = get();
        if (!lastActiveTime) return false;
        
        const lastActive = new Date(lastActiveTime).getTime();
        const now = Date.now();
        
        return (now - lastActive) > inactivityTimeout;
      },
      
      resetInactivityTimer: () => set({ 
        lastActiveTime: new Date().toISOString() 
      }),
      
      setInactivityTimeout: (timeout) => set({ 
        inactivityTimeout: timeout 
      }),
    }),
    {
      name: 'session-state',
      partialize: (state) => ({ 
        inactivityTimeout: state.inactivityTimeout
      }),
    }
  )
);

/**
 * Custom hook for session timeout management
 */
export function useSessionTimeout(provider: SessionHeaderProvider) {
  const { 
    checkSessionTimeout, 
    resetInactivityTimer, 
    setInactivityTimeout 
  } = useSessionStore();
  
  /**
   * Check for session timeout and reset if needed
   * @returns true if session was reset, false otherwise
   */
  const checkAndResetSession = async (): Promise<boolean> => {
    if (checkSessionTimeout()) {
      // Session timed out, reset
      await provider.resetSession();
      resetInactivityTimer();
      return true;
    }
    
    // Session still valid
    resetInactivityTimer();
    return false;
  };
  
  return {
    checkAndResetSession,
    setInactivityTimeout,
  };
}
```

## Testing Session Headers

### 1. Unit Testing the Provider

```typescript
// __tests__/core/shared/api/headers/providers/sessionHeaderProvider.test.ts
import { SessionHeaderProvider } from '@/core/shared/api/headers/providers/sessionHeaderProvider';
import { API_HEADERS } from '@/core/shared/constants/headers';
import { storage } from '@/core/shared/utils/storage';

// Mock dependencies
jest.mock('@/core/shared/utils/storage');

describe('SessionHeaderProvider', () => {
  let provider: SessionHeaderProvider;
  
  beforeEach(() => {
    // Reset mocks
    jest.clearAllMocks();
    
    // Reset storage mock
    (storage.getItem as jest.Mock).mockReset();
    (storage.setItem as jest.Mock).mockReset();
    
    // Create provider instance
    provider = new SessionHeaderProvider();
  });
  
  it('should create a new session ID if none exists', async () => {
    // Setup storage to return no existing session
    (storage.getItem as jest.Mock).mockResolvedValue(null);
    
    const headers = await provider.getHeaders();
    
    // Verify session ID was created and stored
    expect(headers[API_HEADERS.SESSION_ID]).toMatch(/^sess-/);
    expect(storage.setItem).toHaveBeenCalledWith(
      'current_session_id',
      headers[API_HEADERS.SESSION_ID]
    );
    expect(storage.setItem).toHaveBeenCalledWith(
      'session_start_time',
      expect.any(String)
    );
  });
  
  it('should reuse existing session ID', async () => {
    // Setup storage to return existing session
    const existingSessionId = 'sess-existing-id';
    (storage.getItem as jest.Mock).mockResolvedValue(existingSessionId);
    
    const headers = await provider.getHeaders();
    
    // Verify existing session ID was used
    expect(headers[API_HEADERS.SESSION_ID]).toBe(existingSessionId);
    expect(storage.setItem).not.toHaveBeenCalledWith(
      'current_session_id',
      expect.any(String)
    );
  });
  
  it('should generate unique request ID for each call', async () => {
    // Setup storage to return existing session
    (storage.getItem as jest.Mock).mockResolvedValue('sess-existing-id');
    
    const headers1 = await provider.getHeaders();
    const headers2 = await provider.getHeaders();
    
    // Verify request IDs are different
    expect(headers1[API_HEADERS.REQUEST_ID]).not.toBe(headers2[API_HEADERS.REQUEST_ID]);
    expect(headers1[API_HEADERS.REQUEST_ID]).toMatch(/^req-/);
    expect(headers2[API_HEADERS.REQUEST_ID]).toMatch(/^req-/);
  });
  
  it('should reset session and create new ID', async () => {
    // Setup existing session
    const existingSessionId = 'sess-existing-id';
    (storage.getItem as jest.Mock).mockResolvedValue(existingSessionId);
    
    // First get headers to establish session
    await provider.getHeaders();
    
    // Clear mock calls
    (storage.setItem as jest.Mock).mockClear();
    
    // Reset session
    const newSessionId = await provider.resetSession();
    
    // Verify new session ID
    expect(newSessionId).not.toBe(existingSessionId);
    expect(newSessionId).toMatch(/^sess-/);
    expect(storage.setItem).toHaveBeenCalledWith(
      'current_session_id',
      newSessionId
    );
    
    // Get headers and verify new session used
    const headers = await provider.getHeaders();
    expect(headers[API_HEADERS.SESSION_ID]).toBe(newSessionId);
  });
  
  it('should calculate session duration', async () => {
    // Setup mock for session start time (10 seconds ago)
    const now = Date.now();
    const startTime = new Date(now - 10000).toISOString();
    (storage.getItem as jest.Mock).mockResolvedValue(startTime);
    
    // Mock Date.now to return consistent value
    const originalDateNow = Date.now;
    Date.now = jest.fn(() => now);
    
    // Get session duration
    const duration = await provider.getSessionDuration();
    
    // Verify duration is approximately 10 seconds
    expect(duration).toBeCloseTo(10000);
    
    // Restore Date.now
    Date.now = originalDateNow;
  });
});
```

### 2. Integration Testing with API Client

```typescript
// __tests__/integration/api/sessionHeadersIntegration.test.ts
import { authenticatedApi } from '@/core/shared/api/client';
import { SessionHeaderProvider } from '@/core/shared/api/headers/providers/sessionHeaderProvider';
import { API_HEADERS } from '@/core/shared/constants/headers';
import MockAdapter from 'axios-mock-adapter';

describe('Session Headers Integration', () => {
  let mockAxios: MockAdapter;
  let sessionProvider: SessionHeaderProvider;
  
  beforeEach(() => {
    // Setup mock for the Axios instance
    mockAxios = new MockAdapter((authenticatedApi as any).client);
    
    // Create session provider instance
    sessionProvider = new SessionHeaderProvider();
    
    // Register session header provider for testing
    authenticatedApi.registerHeaderProvider(sessionProvider);
  });
  
  afterEach(() => {
    mockAxios.restore();
  });
  
  it('should include session headers in API requests', async () => {
    // Setup mock response
    mockAxios.onGet('/test-endpoint').reply((config) => {
      // Check that session headers are present
      expect(config.headers[API_HEADERS.SESSION_ID]).toBeDefined();
      expect(config.headers[API_HEADERS.SESSION_ID]).toMatch(/^sess-/);
      expect(config.headers[API_HEADERS.REQUEST_ID]).toBeDefined();
      expect(config.headers[API_HEADERS.REQUEST_ID]).toMatch(/^req-/);
      
      return [200, { success: true }];
    });
    
    // Make request
    await authenticatedApi.get('/test-endpoint');
    
    // Verification is done in the mock response
    expect(mockAxios.history.get.length).toBe(1);
  });
  
  it('should maintain session ID across multiple requests', async () => {
    let sessionId: string | undefined;
    
    // First request
    mockAxios.onGet('/first-request').reply((config) => {
      sessionId = config.headers[API_HEADERS.SESSION_ID];
      return [200, { success: true }];
    });
    
    await authenticatedApi.get('/first-request');
    
    // Second request
    mockAxios.onGet('/second-request').reply((config) => {
      expect(config.headers[API_HEADERS.SESSION_ID]).toBe(sessionId);
      return [200, { success: true }];
    });
    
    await authenticatedApi.get('/second-request');
    
    // Verification
    expect(mockAxios.history.get.length).toBe(2);
  });
  
  it('should use new session ID after reset', async () => {
    let sessionId: string | undefined;
    
    // First request
    mockAxios.onGet('/first-request').reply((config) => {
      sessionId = config.headers[API_HEADERS.SESSION_ID];
      return [200, { success: true }];
    });
    
    await authenticatedApi.get('/first-request');
    
    // Reset session
    await sessionProvider.resetSession();
    
    // Second request
    mockAxios.onGet('/second-request').reply((config) => {
      expect(config.headers[API_HEADERS.SESSION_ID]).not.toBe(sessionId);
      expect(config.headers[API_HEADERS.SESSION_ID]).toMatch(/^sess-/);
      return [200, { success: true }];
    });
    
    await authenticatedApi.get('/second-request');
  });
});
```

## Security and Privacy Considerations

When implementing session tracking, consider these security and privacy best practices:

1. **Session IDs**:
   * (Do ✅) Use cryptographically secure random values for session IDs
   * (Don't ❌) Include sensitive information in session IDs
   * (Do ✅) Consider session expiration based on inactivity and absolute time

2. **Correlation Context**:
   * (Do ✅) Keep correlation IDs free of sensitive data
   * (Do ✅) Validate correlation IDs received from external sources
   * (Consider 🤔) Implementing length and format restrictions

3. **Logging**:
   * (Do ✅) Include session and request IDs in all application logs
   * (Do ✅) Ensure logs with session IDs don't contain PII
   * (Consider 🤔) Implementing log retention policies for session data

4. **Privacy**:
   * (Do ✅) Disclose session tracking in privacy policies
   * (Do ✅) Ensure compliance with relevant privacy regulations
   * (Consider 🤔) Providing options to opt out of non-essential tracking

## Performance Considerations

1. **Header Size**:
   * Keep session and request IDs reasonably sized to minimize header overhead
   * Consider the cumulative impact of all tracking headers on request size

2. **Storage Impact**:
   * Session data storage is minimal, but still implement proper cleanup
   * Monitor storage usage if tracking large volumes of request data

3. **Overhead**:
   * The overhead of generating and processing session headers is negligible
   * The benefits for debugging and monitoring outweigh the minimal performance cost

## Best Practices

1. **Session Lifecycle**:
   * (Do ✅) Create new sessions on login or authentication changes
   * (Do ✅) Reset sessions after prolonged inactivity
   * (Consider 🤔) Aligning session timeouts with authentication token lifetimes

2. **Request Correlation**:
   * (Do ✅) Use consistent header formats across all services
   * (Do ✅) Propagate correlation IDs through all system components
   * (Consider 🤔) Adopting an established standard like W3C Trace Context

3. **Analytics Integration**:
   * (Do ✅) Include session IDs in analytics events for journey mapping
   * (Do ✅) Measure session duration and request counts
   * (Consider 🤔) Implementing session stitching across devices

4. **Debugging**:
   * (Do ✅) Make session and request IDs easily accessible in debugging tools
   * (Do ✅) Include correlation IDs in error reports
   * (Consider 🤔) Creating developer tools to track request flows

## Migration Considerations

If you're transitioning from another session tracking approach, follow these guidelines to migrate successfully:

### From Manual Header Addition

If you've been manually adding session headers in each API call:

1. **Identify existing headers** - Document all session-related headers currently in use
2. **Create a compatible provider** - Implement a `SessionHeaderProvider` that produces the same header names and formats
3. **Gradual transition** - First add the provider to your API client while maintaining the manual code
4. **Validate** - Verify that both methods produce the same results
5. **Remove manual code** - Once validated, remove all manual session header code

### From Server-Side Sessions Only

If your backend manages sessions without client-side tracking:

1. **Coordination** - Work with backend teams to align on header naming and format
2. **Compatibility layer** - Create a provider that works with your current backend expectations
3. **Enhanced tracking** - Gradually add client-side features like request timing

### From a Different Header Format

If you need to change header formats or names:

1. **Compatibility period** - Configure your backend to accept both old and new header formats
2. **Transition clients** - Update client applications to use the new header provider
3. **Monitoring** - Track usage of old header formats to ensure complete transition
4. **Finalize** - Remove support for old header formats once all clients have migrated

## Related Documents

* [](/docs/api/headers/header-customization) - Core header customization patterns
* [Device Identification Headers](/docs/api/headers/header-customization/device-identification) - Device header implementation
* [API Client Architecture](/docs/api/client-architecture) - Base API client implementation
* [Error Handling](/docs/api/error-handling) - Error handling architecture
* [Monitoring and Analytics](/docs/monitoring/application-monitoring) - Monitoring implementation

## Summary

Session tracking headers provide essential context for maintaining continuity across API requests, enabling powerful debugging, monitoring, and analytics capabilities. By implementing robust session tracking using the `HeaderProvider` pattern, you can create a consistent context across your application's interactions with backend services, enhancing both development workflows and user experience.

Key takeaways:

* Use `SessionHeaderProvider` to attach session context to all API requests
* Generate unique request IDs for each API call while maintaining session continuity
* Consider enhanced implementations for distributed tracing and event tracking
* Integrate with application state for more sophisticated session management
* Balance comprehensive tracking with performance and privacy considerations

Implementing these patterns will create a consistent foundation for request correlation, enabling more effective debugging, monitoring, and user journey analysis across your entire application ecosystem.


# UTA API Integration: User-Agent Headers
URL: https://dev.updatetheapp.com/docs/api/headers/user-agent-headers
Documentation: https://dev.updatetheapp.com/docs/api/headers/user-agent-headers

Implementation guide for custom User-Agent headers in API requests
        
***

title: User-Agent Headers
description: Implementation guide for custom User-Agent headers in API requests
-------------------------------------------------------------------------------

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Callout } from 'fumadocs-ui/components/callout';

# User-Agent Headers

## Overview

This document outlines our approach to implementing and managing custom User-Agent headers in API requests. The User-Agent header provides valuable information about the client application, device, and environment to backend services, supporting analytics, troubleshooting, and client-specific optimizations.

Our implementation builds upon the established [](/docs/api/headers/header-customization) architecture, extending it with specific patterns for creating, standardizing, and managing User-Agent headers across all API clients.

<Mermaid
  chart={`
flowchart TD
  subgraph Client[React Native App]
    AppConfig[App Configuration]
    DeviceInfo[Device Information]
    EnvInfo[Environment Information]
    UAProvider[User-Agent Provider]
    HeaderSystem[Header Provider System]
    ApiClient[API Client]
  end
  
  subgraph Server[Backend Services]
    ApiEndpoint[API Endpoint]
    UAParser[User-Agent Parser]
    Analytics[Analytics System]
    ClientOptimization[Client-Specific Optimizations]
  end
  
  AppConfig -->|App version, name| UAProvider
  DeviceInfo -->|Device model, OS| UAProvider
  EnvInfo -->|Environment details| UAProvider
  
  UAProvider -->|User-Agent string| HeaderSystem
  HeaderSystem -->|Apply headers| ApiClient
  ApiClient -->|HTTP Request| ApiEndpoint
  
  ApiEndpoint -->|Extract User-Agent| UAParser
  UAParser -->|Client metadata| Analytics
  UAParser -->|Client capabilities| ClientOptimization
`}
/>

## Quick Start

To quickly implement custom User-Agent headers in your application, follow these steps:

1. **Define User-Agent constants**:
   ```typescript
   // core/shared/constants/headers.ts
   export const API_HEADERS = {
     // Other headers...
     USER_AGENT: 'User-Agent',
     DEVICE_TYPE: 'X-Device-Type'
   };
   ```

2. **Create a basic User-Agent provider**:
   ```typescript
   // core/shared/api/headers/providers/userAgentHeaderProvider.ts
   import { HeaderProvider } from '../types';
   import { API_HEADERS } from '@/core/shared/constants/headers';
   import DeviceInfo from 'react-native-device-info';
   import { Platform } from 'react-native';
   import { AppConfig } from '@/core/shared/config/appConfig';

   export class UserAgentHeaderProvider implements HeaderProvider {
     id = 'user-agent';
     priority = 95; // High priority
     
     async getHeaders() {
       const appName = AppConfig.APP_NAME;
       const appVersion = DeviceInfo.getVersion();
       const device = await DeviceInfo.getModel();
       const osName = Platform.OS;
       const osVersion = await DeviceInfo.getSystemVersion();
       
       const userAgent = `${appName}/${appVersion} (${device}; ${osName} ${osVersion})`;
       
       return {
         'User-Agent': userAgent,
         [API_HEADERS.DEVICE_TYPE]: Platform.OS
       };
     }
   }
   ```

3. **Register with your API client**:
   ```typescript
   // core/shared/api/client.ts
   import { UserAgentHeaderProvider } from './headers/providers/userAgentHeaderProvider';

   // Create and register the provider
   const userAgentProvider = new UserAgentHeaderProvider();
   apiClient.registerHeaderProvider(userAgentProvider);
   ```

4. **Verify implementation**:
   ```typescript
   // Anywhere in your app
   console.log('Current User-Agent:', 
     await apiClient.getLastRequestHeader('User-Agent'));
   ```

For more advanced features like extensions, caching, and domain-specific customizations, continue reading the sections below.

## Purpose & Scope

This guide establishes:

* A standardized format for User-Agent headers in our application
* Implementation patterns for dynamic User-Agent generation
* Methods for extending the base User-Agent with feature-specific information
* Testing strategies for User-Agent implementations
* Analytics and monitoring considerations

This document is intended for developers working on API integrations who need to implement proper client identification and versioning across API requests.

## Prerequisites

To effectively use this guide, you should be familiar with:

* [](/docs/api/headers/header-customization) - Our core architecture for header management
* [API Client Architecture](/docs/api/client-architecture) - The standard API client structure
* [Domain Architecture Guide](/docs/architecture/domain-architecture) - For understanding domain vs. shared code organization

## User-Agent Format Specification

Our custom User-Agent follows a structured format that provides comprehensive client information while maintaining readability:

```
AppName/AppVersion (Device; OS OSVersion; Environment) Extension/ExtensionVersion
```

Where:

* `AppName`: The name of our application (e.g., "MyApp")
* `AppVersion`: Semantic version of the application (e.g., "1.2.3")
* `Device`: Device model information (e.g., "iPhone13,4")
* `OS`: Operating system name (e.g., "iOS")
* `OSVersion`: Operating system version (e.g., "15.4.1")
* `Environment`: Optional environment identifier (e.g., "DEV", "STAGING", "PROD")
* `Extension`: Optional component or library identifier
* `ExtensionVersion`: Version of the extension component

Examples:

```
MyApp/1.2.3 (iPhone13,4; iOS 15.4.1; PROD)
MyApp/1.0.0-beta.2 (SM-G998B; Android 12; DEV) Analytics/2.1.0
```

<Callout type="info">
  This structured format allows server-side systems to easily parse and extract client information for analytics, feature toggling, client-specific optimizations, and debugging.
</Callout>

## Core Components

### 1. User-Agent Provider

Building on the `HeaderProvider` interface from the [Header Customization](/docs/api/headers/header-customization/headers/header-customization) document, we implement a specialized provider for User-Agent headers:

```typescript
// core/shared/api/headers/providers/userAgentHeaderProvider.ts
import { HeaderProvider } from '../types';
import { API_HEADERS } from '@/core/shared/constants/headers';
import DeviceInfo from 'react-native-device-info';
import { Platform } from 'react-native';
import { AppConfig } from '@/core/shared/config/appConfig';

export class UserAgentHeaderProvider implements HeaderProvider {
  id = 'user-agent';
  priority = 95; // High priority - should be applied before most other headers
  
  // Optional extensions to the base User-Agent
  private extensions: Array<{name: string, version: string}> = [];
  
  /**
   * Registers an extension to be included in the User-Agent string
   * @param name Extension name
   * @param version Extension version
   */
  public registerExtension(name: string, version: string): void {
    this.extensions = this.extensions.filter(ext => ext.name !== name);
    this.extensions.push({ name, version });
  }
  
  /**
   * Builds the complete User-Agent string based on app, device, and extensions
   */
  private async buildUserAgent(): Promise<string> {
    // Get app information
    const appName = AppConfig.APP_NAME;
    const appVersion = DeviceInfo.getVersion();
    const buildNumber = DeviceInfo.getBuildNumber();
    
    // Get device and OS information
    const deviceId = DeviceInfo.getModel();
    const deviceType = Platform.OS;
    const osVersion = DeviceInfo.getSystemVersion();
    
    // Get environment
    const environment = AppConfig.ENVIRONMENT;
    
    // Build the core User-Agent string
    let userAgent = `${appName}/${appVersion}+${buildNumber} (${deviceId}; ${deviceType} ${osVersion}; ${environment})`;
    
    // Add extensions if present
    if (this.extensions.length > 0) {
      const extensionsString = this.extensions
        .map(ext => `${ext.name}/${ext.version}`)
        .join(' ');
      userAgent += ` ${extensionsString}`;
    }
    
    return userAgent;
  }
  
  async getHeaders(): Promise<Record<string, string | undefined>> {
    const userAgent = await this.buildUserAgent();
    
    return {
      'User-Agent': userAgent,
      // Optionally include a custom header as well
      [API_HEADERS.DEVICE_TYPE]: Platform.OS,
    };
  }
}

// Export a singleton instance for global use
export const userAgentProvider = new UserAgentHeaderProvider();
```

### 2. Adding User-Agent Headers to API Constants

Extend the existing header constants to include User-Agent related headers:

```typescript
// core/shared/constants/headers.ts
export const API_HEADERS = {
  // ... existing headers from API Header Customization

  // User-Agent related headers
  USER_AGENT: 'User-Agent',
  CLIENT_VERSION: 'X-Client-Version',
  CLIENT_TYPE: 'X-Client-Type',
  CLIENT_CHANNEL: 'X-Client-Channel',
  
  // ... other headers
} as const;
```

### 3. Configuration Provider

Create a central configuration source for User-Agent components:

```typescript
// core/shared/config/appConfig.ts
import { Platform } from 'react-native';

export enum Environment {
  DEVELOPMENT = 'DEV',
  STAGING = 'STAGING',
  PRODUCTION = 'PROD',
}

export const AppConfig = {
  APP_NAME: 'MyApp',
  APP_BUNDLE_ID: Platform.select({
    ios: 'com.company.myapp',
    android: 'com.company.myapp',
  }),
  ENVIRONMENT: __DEV__ ? Environment.DEVELOPMENT : Environment.PRODUCTION,
  
  // Function to override environment (useful for testing)
  setEnvironment: (env: Environment) => {
    AppConfig.ENVIRONMENT = env;
  },
} as const;
```

## Implementation Patterns

### 1. Basic Implementation with API Clients

Register the User-Agent provider with API clients during initialization:

```typescript
// core/shared/api/clients.ts
import { PublicApiClient, AuthenticatedApiClient } from '@/core/shared/api/client';
import { userAgentProvider } from '@/core/shared/api/headers/providers/userAgentHeaderProvider';

// Create API client instances
const apiConfig = {
  baseURL: process.env.API_BASE_URL,
  timeout: 30000,
};

// Initialize API clients
export const publicApi = new PublicApiClient(apiConfig);
export const authenticatedApi = new AuthenticatedApiClient(apiConfig);

// Register the User-Agent provider with all API clients
// Casting to 'any' here because registerHeaderProvider is protected in BaseApiClient
(publicApi as any).registerHeaderProvider(userAgentProvider);
(authenticatedApi as any).registerHeaderProvider(userAgentProvider);
```

### 2. Feature-Specific Extensions

Extend the User-Agent with feature-specific information:

```typescript
// features/analytics/services/analyticsService.ts
import { userAgentProvider } from '@/core/shared/api/headers/providers/userAgentHeaderProvider';

export class AnalyticsService {
  constructor() {
    // Register the analytics extension in the User-Agent
    userAgentProvider.registerExtension('Analytics', '2.1.0');
  }
  
  // Analytics service methods...
}

// Initialize the service
export const analyticsService = new AnalyticsService();
```

### 3. Dynamic User-Agent Composition

For User-Agent properties that change during app usage:

```typescript
// core/domains/tenant/store.ts
import { create } from 'zustand';
import { userAgentProvider } from '@/core/shared/api/headers/providers/userAgentHeaderProvider';

interface TenantState {
  tenantId: string | null;
  workspace: string | null;
  setTenant: (id: string | null, workspace: string | null) => void;
}

export const useTenantStore = create<TenantState>((set) => ({
  tenantId: null,
  workspace: null,
  setTenant: (tenantId, workspace) => {
    set({ tenantId, workspace });
    
    // Update the User-Agent extension when tenant changes
    if (tenantId && workspace) {
      userAgentProvider.registerExtension('Tenant', `${workspace}@${tenantId}`);
    }
  },
}));
```

### 4. Enhanced User-Agent Provider with Caching

For performance optimization, especially on slower devices:

```typescript
// Enhanced version with caching
export class CachedUserAgentHeaderProvider extends UserAgentHeaderProvider {
  private cachedUserAgent: string | null = null;
  private cacheExpiry: number = 0;
  private readonly CACHE_DURATION = 60 * 60 * 1000; // 1 hour in milliseconds
  
  async getHeaders(): Promise<Record<string, string | undefined>> {
    // Only rebuild the User-Agent string if the cache has expired
    if (!this.cachedUserAgent || Date.now() > this.cacheExpiry) {
      this.cachedUserAgent = await this.buildUserAgent();
      this.cacheExpiry = Date.now() + this.CACHE_DURATION;
    }
    
    return {
      'User-Agent': this.cachedUserAgent,
      [API_HEADERS.DEVICE_TYPE]: Platform.OS,
    };
  }
  
  // When an extension is registered, invalidate the cache
  public registerExtension(name: string, version: string): void {
    super.registerExtension(name, version);
    this.cachedUserAgent = null; // Force rebuild on next getHeaders call
  }
}
```

## Testing User-Agent Implementation

<Tabs items={["Unit Tests", "Integration Tests"]}>
  <Tab>
    ```typescript
    // __tests__/core/shared/api/headers/providers/userAgentHeaderProvider.test.ts
    import { UserAgentHeaderProvider } from '@/core/shared/api/headers/providers/userAgentHeaderProvider';
    import DeviceInfo from 'react-native-device-info';
    import { Platform } from 'react-native';
    import { AppConfig, Environment } from '@/core/shared/config/appConfig';

    // Mock external dependencies
    jest.mock('react-native-device-info');
    jest.mock('react-native/Libraries/Utilities/Platform', () => ({
      OS: 'ios',
      select: jest.fn(obj => obj.ios)
    }));

    describe('UserAgentHeaderProvider', () => {
      beforeEach(() => {
        // Setup mocks with default test values
        (DeviceInfo.getVersion as jest.Mock).mockReturnValue('1.2.3');
        (DeviceInfo.getBuildNumber as jest.Mock).mockReturnValue('100');
        (DeviceInfo.getModel as jest.Mock).mockReturnValue('iPhone13,4');
        (DeviceInfo.getSystemVersion as jest.Mock).mockReturnValue('15.4.1');
        
        // Reset AppConfig to default test state
        AppConfig.ENVIRONMENT = Environment.DEVELOPMENT;
      });
      
      it('should generate properly formatted User-Agent string', async () => {
        const provider = new UserAgentHeaderProvider();
        const headers = await provider.getHeaders();
        
        expect(headers['User-Agent']).toMatch(/^MyApp\/1\.2\.3\+100 \(iPhone13,4; ios 15\.4\.1; DEV\)$/);
      });
      
      it('should include registered extensions in User-Agent', async () => {
        const provider = new UserAgentHeaderProvider();
        provider.registerExtension('Testing', '1.0.0');
        
        const headers = await provider.getHeaders();
        
        expect(headers['User-Agent']).toMatch(/Testing\/1\.0\.0$/);
      });
      
      it('should include multiple extensions in order', async () => {
        const provider = new UserAgentHeaderProvider();
        provider.registerExtension('Extension1', '1.0.0');
        provider.registerExtension('Extension2', '2.0.0');
        
        const headers = await provider.getHeaders();
        
        expect(headers['User-Agent']).toMatch(/Extension1\/1\.0\.0 Extension2\/2\.0\.0$/);
      });
      
      it('should replace extension with same name', async () => {
        const provider = new UserAgentHeaderProvider();
        provider.registerExtension('Extension', '1.0.0');
        provider.registerExtension('Extension', '1.1.0');
        
        const headers = await provider.getHeaders();
        
        expect(headers['User-Agent']).toMatch(/Extension\/1\.1\.0$/);
        expect(headers['User-Agent']).not.toMatch(/Extension\/1\.0\.0/);
      });
      
      it('should use production environment in User-Agent when set', async () => {
        AppConfig.ENVIRONMENT = Environment.PRODUCTION;
        
        const provider = new UserAgentHeaderProvider();
        const headers = await provider.getHeaders();
        
        expect(headers['User-Agent']).toMatch(/; PROD\)/);
      });
    });
    ```
  </Tab>

  <Tab>
    ```typescript
    // __tests__/core/shared/api/clients.test.ts
    import { publicApi, authenticatedApi } from '@/core/shared/api/clients';
    import { userAgentProvider } from '@/core/shared/api/headers/providers/userAgentHeaderProvider';
    import MockAdapter from 'axios-mock-adapter';

    describe('API Clients with User-Agent', () => {
      let mockPublicAxios: MockAdapter;
      let mockAuthAxios: MockAdapter;
      
      beforeEach(() => {
        // Setup axios mocks for both clients
        mockPublicAxios = new MockAdapter((publicApi as any).client);
        mockAuthAxios = new MockAdapter((authenticatedApi as any).client);
        
        // Clear any existing extensions
        (userAgentProvider as any).extensions = [];
      });
      
      afterEach(() => {
        mockPublicAxios.restore();
        mockAuthAxios.restore();
      });
      
      it('should include User-Agent header in public API requests', async () => {
        mockPublicAxios.onGet('/test-endpoint').reply(config => {
          expect(config.headers['User-Agent']).toBeDefined();
          expect(config.headers['User-Agent']).toMatch(/^MyApp\/.*\(.*; .*; .*\)$/);
          return [200, {}];
        });
        
        await publicApi.get('/test-endpoint');
        // Assertion happens in the mock handler
      });
      
      it('should include User-Agent header in authenticated API requests', async () => {
        mockAuthAxios.onGet('/protected-endpoint').reply(config => {
          expect(config.headers['User-Agent']).toBeDefined();
          expect(config.headers['User-Agent']).toMatch(/^MyApp\/.*\(.*; .*; .*\)$/);
          return [200, {}];
        });
        
        await authenticatedApi.get('/protected-endpoint');
        // Assertion happens in the mock handler
      });
      
      it('should update User-Agent when extensions are registered', async () => {
        // Add an extension
        userAgentProvider.registerExtension('TestFeature', '1.0.0');
        
        mockPublicAxios.onGet('/feature-endpoint').reply(config => {
          expect(config.headers['User-Agent']).toMatch(/TestFeature\/1\.0\.0$/);
          return [200, {}];
        });
        
        await publicApi.get('/feature-endpoint');
        // Assertion happens in the mock handler
      });
    });
    ```
  </Tab>
</Tabs>

## Server-Side User-Agent Handling

While server-side implementation is beyond the scope of this document, understanding how your User-Agent is processed is valuable for client-side developers.

### Expected Server-Side Processing

```typescript
// Server-side pseudocode for User-Agent parsing
function parseUserAgent(userAgentString) {
  // Regular expression for our custom format
  const regex = /^([^\/]+)\/([^\s]+)\s+\(([^;]+);\s*([^;]+)\s+([^;]+);\s*([^\)]+)\)(?:\s+(.+))?$/;
  const match = userAgentString.match(regex);
  
  if (!match) return null;
  
  return {
    app: {
      name: match[1],
      version: match[2],
    },
    device: {
      model: match[3],
      os: match[4],
      osVersion: match[5],
    },
    environment: match[6],
    extensions: match[7] ? parseExtensions(match[7]) : [],
  };
}

function parseExtensions(extensionsString) {
  // Split space-separated extensions and parse each one
  return extensionsString.split(' ').map(extension => {
    const [name, version] = extension.split('/');
    return { name, version };
  });
}
```

## Best Practices

### User-Agent Construction

1. **(Do ✅) Follow the Standardized Format**: Adhere to the specified format for consistency and reliable parsing.

2. **(Do ✅) Include Essential Information**: Always include app name, version, device model, OS, and OS version.

3. **(Do ✅) Use Semantic Versioning**: Follow semantic versioning for all version strings (X.Y.Z format).

4. **(Consider 🤔) Include Build Number**: For more precise version tracking, include build number after the semantic version.

5. **(Don't ❌) Include Sensitive Information**: Never include user identifiers, authentication tokens, or other sensitive data.

### Feature Extensions

1. **(Do ✅) Use Descriptive Extension Names**: Choose clear, concise names that identify the feature or module.

2. **(Do ✅) Version Extensions Separately**: Each extension should have its own version that can evolve independently.

3. **(Do ✅) Register Extensions Early**: Register extensions during module initialization to ensure they're included in all requests.

4. **(Don't ❌) Over-extend**: Limit extensions to important modules that require tracking. Too many extensions make the User-Agent unwieldy.

### Performance Considerations

1. **(Consider 🤔) Implement Caching**: For better performance, cache the User-Agent string and rebuild only when necessary.

2. **(Do ✅) Lazy-load Device Information**: Some device information is expensive to collect; consider lazy-loading these values.

3. **(Consider 🤔) Use Async Factory Pattern**: If initialization is complex, consider an async factory pattern for the provider.

## Analytics and Monitoring

### Tracking Client Distribution

The User-Agent header can be utilized by analytics systems to track client distribution metrics:

* App version adoption rates
* OS version distribution
* Device type popularity
* Environment usage (useful for pre-release testing)

### Error Correlation

User-Agents can help correlate errors with specific client configurations:

* Identify version-specific bugs
* Discover device-specific issues
* Monitor error rates across different OS versions

## Design Principles

### Core Architectural Principles

We've designed our User-Agent implementation around these key principles to ensure it meets both technical and business needs:

1. **Standardization**
   * Consistent User-Agent format across all API clients helps create a unified approach
   * Predictable extension mechanism makes it easy for teams to add their components
   * Reliable parsing patterns enable straightforward server-side analysis

2. **Extensibility**
   * Modules can register their own extensions, allowing feature teams to work independently
   * Format accommodates future additions without requiring architectural changes
   * Dynamic composition based on application state provides contextual information

3. **Performance**
   * Efficient generation with caching minimizes impact on application responsiveness
   * Minimal impact on API request overhead keeps network operations fast
   * Optimized for mobile environments where resources and battery life matter

### Trade-offs and Design Decisions

| Decision                                  | Benefits                                                           | Drawbacks                                               | Rationale                                                                                    |
| ----------------------------------------- | ------------------------------------------------------------------ | ------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| Custom format vs. standard browser format | Tailored for mobile app needs, structured for easy parsing         | Less familiar to developers used to browser User-Agents | Mobile apps have different identification needs than browsers                                |
| Extension mechanism                       | Modular, allows features to self-identify                          | Increases User-Agent length                             | The benefits of feature-specific tracking outweigh the minimal size increase                 |
| Singleton provider instance               | Consistent User-Agent across all clients, simpler state management | Less flexibility for different clients                  | Consistency in client identification is more important than per-client customization         |
| Caching User-Agent string                 | Improved performance, especially on slower devices                 | Potential staleness if device properties change         | Device properties rarely change during app execution; performance gains justify minimal risk |

## Migration Considerations

If you're transitioning to this structured User-Agent approach, consider the following migration paths:

### From Default User-Agent

If you're currently using the default React Native User-Agent or no User-Agent at all:

1. **Document current backend dependencies** - Identify any server-side code that may depend on existing User-Agent patterns
2. **Create a mapping** - Develop a mapping between existing User-Agent data and your new format
3. **Implement dual processing** - Configure backend services to handle both formats during transition
4. **Roll out incrementally** - Deploy to a subset of users first to verify backend compatibility
5. **Monitor for errors** - Watch for unexpected behaviors related to User-Agent parsing

### From Unstructured Custom User-Agent

If you already use a custom User-Agent but want to standardize it:

1. **Parse and map** - Analyze your current format and map fields to the new structure
2. **Server-side updates** - Update any server-side parsing logic to handle the new format
3. **Maintain compatibility** - Consider including legacy identifiers alongside new format initially
4. **Version your format** - Include format version markers if making significant structural changes
5. **Staggered deployment** - Deploy to internal users first, then beta users, then production

### From Multiple User-Agent Strategies

If different API clients currently use different User-Agent strategies:

1. **Inventory current approaches** - Document all existing User-Agent implementations
2. **Unified provider** - Implement the central UserAgentHeaderProvider
3. **Progressive migration** - Convert one client at a time to the new provider
4. **Validate each migration** - Test each API client thoroughly after conversion
5. **Remove legacy code** - Clean up old User-Agent code after full migration

## Related Documents

* [](/docs/api/headers/header-customization) - The foundation for our header management architecture
* [API Client Architecture](/docs/api/client-architecture) - Core API client implementation patterns
* [Authentication Architecture](/docs/api/authentication) - Token management and session handling
* [Multi-API Setup](/docs/api/multi-api-setup) - For service-specific configurations

## Summary

Implementing a standardized User-Agent format provides valuable insights for analytics, debugging, and client-specific optimizations. By following the patterns in this document, you can ensure consistent, informative client identification across all API requests while maintaining flexibility for feature-specific extensions.

Key takeaways:

* Use the structured User-Agent format to provide comprehensive client information
* Implement the `UserAgentHeaderProvider` to generate and manage User-Agent headers
* Register the provider with all API clients to ensure consistent application
* Allow features to extend the User-Agent with their own identifiers
* Consider performance optimizations like caching for mobile environments
* Leverage User-Agent data for analytics and error correlation

This consistent approach to User-Agent implementation enhances the overall API integration architecture by providing valuable context to backend services while maintaining the flexibility needed in a complex mobile application.


# UTA UI Development: Getting Started
URL: https://dev.updatetheapp.com/docs/ui-development/getting-started
Documentation: https://dev.updatetheapp.com/docs/ui-development/getting-started

Quick start guide to building your first UI component following our standardized architecture
        
***

title: Getting Started
description: Quick start guide to building your first UI component following our standardized architecture
----------------------------------------------------------------------------------------------------------

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Callout } from 'fumadocs-ui/components/callout';
import { Steps, Step } from 'fumadocs-ui/components/steps';

# Getting Started with UI Development

## Overview

This guide will help you build your first UI component in our React Native application within 15 minutes. You'll create a working component that follows our [three-layer architecture](/docs/ui-development/architecture#three-layer-architecture) and all established standards.

<Callout type="info">
  **Time to First Component**: \~15 minutes

  By the end of this guide, you'll have:

  * Created a foundation component
  * Applied design tokens
  * Added TypeScript types
  * Written basic tests
  * Integrated it into a feature
</Callout>

## Prerequisites

Before starting, ensure you have:

* **Development environment** set up (see [Development Setup](/docs/development-setup))
* **Basic knowledge** of React Native and TypeScript
* **Access to** the project repository

## Your First Component: IconButton

We'll create an `IconButton` component - a button that displays an icon with optional text. This example demonstrates all key concepts of our UI architecture.

<Steps>
  <Step>
    ### Determine Component Category

    First, decide where your component belongs using our decision tree:

    ```
    Is IconButton specific to one feature?
    └─ NO → Is it a basic UI building block?
        └─ YES → Place in ui/foundation/
    ```

    Since `IconButton` is a reusable UI element with no business logic, it belongs in the **foundation layer**.
  </Step>

  <Step>
    ### Create Component Structure

    Create the folder and files following our [file naming conventions](/docs/coding-standards/file-naming-conventions):

    ```bash
    # Create component directory
    mkdir -p ui/foundation/IconButton

    # Create component files
    touch ui/foundation/IconButton/IconButton.tsx
    touch ui/foundation/IconButton/types.ts
    touch ui/foundation/IconButton/index.ts
    touch ui/foundation/IconButton/IconButton.test.tsx
    ```
  </Step>

  <Step>
    ### Define TypeScript Interface

    Start with the types to establish the component's API:

    ```typescript
    // ui/foundation/IconButton/types.ts
    import type { TouchableOpacityProps } from 'react-native';
    import type { IconName } from '@/ui/foundation/Icon/types';

    export interface IconButtonProps extends Omit<TouchableOpacityProps, 'style'> {
      /**
       * Icon to display in the button
       */
      icon: IconName;
      
      /**
       * Optional text to display alongside the icon
       */
      label?: string;
      
      /**
       * Visual style variant
       * @default 'primary'
       */
      variant?: 'primary' | 'secondary' | 'ghost';
      
      /**
       * Size of the button
       * @default 'medium'
       */
      size?: 'small' | 'medium' | 'large';
      
      /**
       * Whether the button is in a loading state
       */
      loading?: boolean;
      
      /**
       * Custom style overrides
       */
      style?: ViewStyle;
    }
    ```
  </Step>

  <Step>
    ### Implement the Component

    Now implement the component using design tokens:

    ```typescript
    // ui/foundation/IconButton/IconButton.tsx
    import React from 'react';
    import { TouchableOpacity, Text, ActivityIndicator, View } from 'react-native';
    import { Icon } from '@/ui/foundation/Icon';
    import { theme } from '@/core/shared/styles/theme';
    import { spacing } from '@/core/shared/styles/spacing';
    import { typography } from '@/core/shared/styles/typography';
    import type { IconButtonProps } from './types';

    export function IconButton({
      icon,
      label,
      variant = 'primary',
      size = 'medium',
      loading = false,
      disabled = false,
      onPress,
      style,
      ...props
    }: IconButtonProps) {
      // Size configurations using design tokens
      const sizeConfig = {
        small: {
          padding: spacing.xs,
          iconSize: 16,
          fontSize: typography.sizes.small,
        },
        medium: {
          padding: spacing.sm,
          iconSize: 20,
          fontSize: typography.sizes.body,
        },
        large: {
          padding: spacing.md,
          iconSize: 24,
          fontSize: typography.sizes.large,
        },
      };

      // Variant styles using design tokens
      const variantStyles = {
        primary: {
          backgroundColor: theme.colors.primary[500],
          color: theme.colors.white,
        },
        secondary: {
          backgroundColor: theme.colors.secondary[500],
          color: theme.colors.white,
        },
        ghost: {
          backgroundColor: 'transparent',
          color: theme.colors.primary[500],
        },
      };

      const config = sizeConfig[size];
      const colors = variantStyles[variant];

      return (
        <TouchableOpacity
          disabled={disabled || loading}
          onPress={onPress}
          style={[
            {
              flexDirection: 'row',
              alignItems: 'center',
              justifyContent: 'center',
              padding: config.padding,
              borderRadius: theme.radii.md,
              backgroundColor: colors.backgroundColor,
              opacity: disabled ? 0.5 : 1,
            },
            style,
          ]}
          accessibilityRole="button"
          accessibilityLabel={label || `${icon} button`}
          accessibilityState={{ disabled, busy: loading }}
          {...props}
        >
          {loading ? (
            <ActivityIndicator size="small" color={colors.color} />
          ) : (
            <>
              <Icon 
                name={icon} 
                size={config.iconSize} 
                color={colors.color} 
              />
              {label && (
                <Text
                  style={{
                    marginLeft: spacing.xs,
                    color: colors.color,
                    fontSize: config.fontSize,
                    fontFamily: typography.families.medium,
                  }}
                >
                  {label}
                </Text>
              )}
            </>
          )}
        </TouchableOpacity>
      );
    }
    ```
  </Step>

  <Step>
    ### Add Barrel Export

    Create clean exports for easy importing:

    ```typescript
    // ui/foundation/IconButton/index.ts
    export { IconButton } from './IconButton';
    export type { IconButtonProps } from './types';
    ```
  </Step>

  <Step>
    ### Write Basic Tests

    Add tests to ensure your component works correctly:

    ```typescript
    // ui/foundation/IconButton/IconButton.test.tsx
    import React from 'react';
    import { render, fireEvent } from '@testing-library/react-native';
    import { IconButton } from './IconButton';

    describe('IconButton', () => {
      it('renders with icon', () => {
        const { getByLabelText } = render(
          <IconButton icon="home" />
        );
        
        expect(getByLabelText('home button')).toBeTruthy();
      });

      it('renders with icon and label', () => {
        const { getByText } = render(
          <IconButton icon="home" label="Home" />
        );
        
        expect(getByText('Home')).toBeTruthy();
      });

      it('calls onPress when pressed', () => {
        const onPress = jest.fn();
        const { getByLabelText } = render(
          <IconButton icon="home" onPress={onPress} />
        );
        
        fireEvent.press(getByLabelText('home button'));
        expect(onPress).toHaveBeenCalled();
      });

      it('does not call onPress when disabled', () => {
        const onPress = jest.fn();
        const { getByLabelText } = render(
          <IconButton icon="home" onPress={onPress} disabled />
        );
        
        fireEvent.press(getByLabelText('home button'));
        expect(onPress).not.toHaveBeenCalled();
      });

      it('shows loading indicator when loading', () => {
        const { getByTestId } = render(
          <IconButton icon="home" loading testID="button" />
        );
        
        expect(getByTestId('button').findByType('ActivityIndicator')).toBeTruthy();
      });
    });
    ```
  </Step>

  <Step>
    ### Use in a Feature

    Now let's use the component in a feature:

    ```typescript
    // features/product-catalog/components/ProductActions/ProductActions.tsx
    import React from 'react';
    import { View } from 'react-native';
    import { IconButton } from '@/ui/foundation/IconButton';
    import { useAddToCart } from '@/core/domains/cart/hooks';
    import { spacing } from '@/core/shared/styles/spacing';

    interface ProductActionsProps {
      productId: string;
    }

    export function ProductActions({ productId }: ProductActionsProps) {
      const { mutate: addToCart, isLoading } = useAddToCart();
      
      const handleAddToCart = () => {
        addToCart({ productId, quantity: 1 });
      };
      
      return (
        <View style={{ flexDirection: 'row', gap: spacing.sm }}>
          <IconButton
            icon="heart"
            variant="ghost"
            size="medium"
            onPress={() => console.log('Add to favorites')}
          />
          
          <IconButton
            icon="shopping-cart"
            label="Add to Cart"
            variant="primary"
            size="medium"
            loading={isLoading}
            onPress={handleAddToCart}
          />
        </View>
      );
    }
    ```
  </Step>
</Steps>

## Component Checklist

Before considering your component complete, verify:

<Tabs items={["✅ Required", "🎯 Best Practices", "🚀 Advanced"]}>
  <Tab>
    * [ ] **Correct folder placement** (`ui/foundation/`, `ui/patterns/`, or `ui/business/`)
    * [ ] **TypeScript interfaces** with proper documentation
    * [ ] **Design tokens only** - no hardcoded colors, spacing, or sizes
    * [ ] **Accessibility support** with proper roles and labels
    * [ ] **Basic tests** covering main functionality
    * [ ] **Barrel exports** in index.ts
    * [ ] **No business logic** in foundation/pattern components
  </Tab>

  <Tab>
    * [ ] **Props documentation** with JSDoc comments
    * [ ] **Memoization** for performance where appropriate
    * [ ] **Error boundaries** for complex components
    * [ ] **Platform-specific** handling if needed
    * [ ] **Storybook story** for component playground
    * [ ] **Visual regression tests** for UI consistency
  </Tab>

  <Tab>
    * [ ] **Performance metrics** tracked
    * [ ] **Bundle size** optimized
    * [ ] **Lazy loading** for heavy components
    * [ ] **Custom hooks** extracted for reusable logic
    * [ ] **Compound components** pattern for flexibility
    * [ ] **Ref forwarding** for advanced integrations
  </Tab>
</Tabs>

## Common Patterns

### Using Design Tokens

Always use design tokens for visual properties:

```typescript
// ✅ GOOD - Using design tokens
const styles = {
  container: {
    backgroundColor: theme.colors.surface,
    padding: spacing.md,
    borderRadius: theme.radii.lg,
  }
};

// ❌ BAD - Hardcoded values
const styles = {
  container: {
    backgroundColor: '#FFFFFF',
    padding: 16,
    borderRadius: 8,
  }
};
```

### Component Composition

Build complex components from simpler ones:

```typescript
// ui/patterns/Card/Card.tsx
import { Surface } from '@/ui/foundation/Surface';
import { Text } from '@/ui/foundation/Text';
import { IconButton } from '@/ui/foundation/IconButton';

export function Card({ title, onClose, children }) {
  return (
    <Surface elevation="medium">
      <View style={styles.header}>
        <Text variant="heading">{title}</Text>
        <IconButton 
          icon="close" 
          variant="ghost" 
          size="small"
          onPress={onClose}
        />
      </View>
      {children}
    </Surface>
  );
}
```

For more Button component examples including all variants, states, and testing patterns, see the [Button Reference Implementation](/docs/reference-implementations/ui/foundation/Button).

## Next Steps

Now that you've created your first component:

1. **Explore existing components** in `ui/foundation/` for examples
2. **Read the [UI Architecture Standards](/docs/ui-development/architecture/standards)** for detailed guidelines
3. **Study [Component Patterns](/docs/ui-development/component-patterns)** for advanced techniques
4. **Learn about [Theme Management](/docs/ui-development/theme-management)** for customization

## Troubleshooting

<Callout type="warning">
  **Common Issues**

  **Import errors**: Ensure you're using the correct import paths:

  * `@/ui/foundation/...` for foundation components
  * `@/core/shared/...` for utilities and tokens
  * `@/core/domains/...` for business logic

  **TypeScript errors**: Check that all props are properly typed and exported

  **Style issues**: Verify you're using design tokens, not hardcoded values
</Callout>

## Quick Reference

### File Structure

```
ComponentName/
├── ComponentName.tsx      # Implementation
├── types.ts              # TypeScript interfaces
├── index.ts              # Exports
└── ComponentName.test.tsx # Tests
```

### Import Order

```typescript
// 1. React imports
import React from 'react';
import { View, Text } from 'react-native';

// 2. Internal imports
import { Icon } from '@/ui/foundation/Icon';
import { theme } from '@/core/shared/styles/theme';

// 3. Types
import type { ComponentProps } from './types';
```

### Design Token Usage

```typescript
// Colors
theme.colors.primary[500]
theme.colors.textPrimary

// Spacing  
spacing.xs // 4
spacing.sm // 8
spacing.md // 16

// Typography
typography.sizes.body
typography.families.regular

// Radii
theme.radii.sm // 4
theme.radii.md // 8
```

***

**Congratulations!** 🎉 You've successfully created your first component following our UI architecture. Continue exploring the documentation to master advanced patterns and best practices.


# UTA UI Development: UI Architecture Standards
URL: https://dev.updatetheapp.com/docs/ui-development/architecture/standards
Documentation: https://dev.updatetheapp.com/docs/ui-development/architecture/standards

Mandatory standards for UI folder organization, component development patterns, and quality requirements across all frontend projects.
        
***

title: UI Architecture Standards\
description: Mandatory standards for UI folder organization, component development patterns, and quality requirements across all frontend projects.
---------------------------------------------------------------------------------------------------------------------------------------------------

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Callout } from 'fumadocs-ui/components/callout';

# UI Architecture Standards

## Overview

This document outlines our recommended standards for UI folder organization, component development patterns, and quality requirements across frontend projects. Following these standards helps ensure consistency, maintainability, and scalability of our UI architecture.

<Callout type="info">
  **Why UI Standards Matter**

  Through our development experience, we've found that consistent UI architecture significantly improves team collaboration, speeds up development, and creates a better foundation for AI collaboration. These standards have evolved through practical application and solving real-world challenges in our applications.
</Callout>

## Purpose & Scope

This guide is designed to help all developers working on UI components:

<Tabs items={["What You'll Learn", "Who This Is For", "When To Apply"]}>
  <Tab>
    * UI folder structure best practices and organization
    * Component development patterns and their benefits
    * Integration approaches with our existing architecture
    * Testing and performance standards for quality
    * Quality assurance techniques for consistent UI
  </Tab>

  <Tab>
    * **Frontend developers** building components at any level
    * **UI/UX designers** collaborating on component implementation
    * **Full-stack developers** integrating UI with backend services
    * **New team members** getting up to speed on our UI practices
    * **AI collaborators** helping with component development
  </Tab>

  <Tab>
    These standards are particularly valuable when:

    * Starting new projects or features
    * Refactoring existing UI components
    * Onboarding new team members
    * Creating design systems
    * Preparing codebases for AI collaboration
  </Tab>
</Tabs>

## 1. UI Folder Structure

<Callout type="info">
  Our three-tiered UI architecture (foundation, patterns, business) is designed to create clear separation between different types of components. This approach makes components more reusable, easier to test, and creates a natural progression from simple to complex UI elements.
</Callout>

### Recommended UI Organization

We recommend following this folder structure for optimal organization and discoverability:

<Mermaid
  chart={`
flowchart TD
ui["ui/"] --> foundation["foundation/\nBasic building blocks"]
ui --> patterns["patterns/\nComposed components"]
ui --> business["business/\nDomain-aware components"]

foundation --> Button["Button/"]
foundation --> Input["Input/"]
foundation --> Text["Text/"]
foundation --> Card["Card/"]
foundation --> otherF["[other-foundation]/"]

patterns --> Modal["Modal/"]
patterns --> Form["Form/"]
patterns --> DataTable["DataTable/"]
patterns --> otherP["[other-patterns]/"]

business --> ProductCard["ProductCard/"]
business --> UserAvatar["UserAvatar/"]
business --> otherB["[other-business]/"]

style foundation fill:#e1f5fe,stroke:#01579b,stroke-width:2px
style patterns fill:#f3e5f5,stroke:#4a148c,stroke-width:2px
style business fill:#e8f5e8,stroke:#1b5e20,stroke-width:2px
`}
/>

This structure provides several benefits:

* **Clear responsibility boundaries** between different component types
* **Predictable imports** that make component discovery easier
* **Logical progression** from simple (foundation) to complex (business) components
* **Easier ownership** with different teams potentially owning different layers

### Component Placement Guidelines

Deciding where to place a component in our architecture is important for maintainability and reusability. The following guidelines can help you make these decisions:

#### Foundation Components

**(Do ✅) Place basic UI building blocks in the foundation layer**

Foundation components are the atomic building blocks of our UI system:

```typescript
// ui/foundation/Button/Button.tsx
import { theme } from '@/core/shared/styles/theme';

export const Button = ({ 
  variant = 'primary',
  size = 'medium',
  children,
  ...props
}: ButtonProps) => {
  return (
    <TouchableOpacity
      style={[styles.base, styles[variant], styles[size]]}
      {...props}
    >
      <Text style={styles[`${variant}Text`]}>{children}</Text>
    </TouchableOpacity>
  );
};
```

Foundation components should be:

* Single-purpose, atomic UI elements
* Free from business logic or domain knowledge
* Highly reusable across many contexts
* Used by 3+ other components OR fundamental to the design system
* Examples: Button, Input, Text, Card, Icon

**(Consider 🤔) Creating a foundation component when you see the same UI pattern repeated**

If you find yourself creating similar UI elements in multiple places, consider extracting them into foundation components.

**(Don't ❌) Include business logic or domain-specific behavior in foundation components**

```typescript
// DON'T do this in foundation components
import { useProducts } from '@/core/domains/products';

// Wrong: Foundation components shouldn't fetch data or know about domains
export const Button = ({ productId, ...props }) => {
  const { data: product } = useProducts(productId);
  
  return (
    <TouchableOpacity {...props}>
      {product ? product.name : 'Loading...'} {/* Domain-specific logic */}
    </TouchableOpacity>
  );
};
```

#### Pattern Components

**(Do ✅) Use pattern components for complex UI compositions**

Pattern components combine multiple foundation components to create more complex, reusable UI patterns:

```typescript
// ui/patterns/Form/Form.tsx
import { Button } from '@/ui/foundation/Button';
import { Input } from '@/ui/foundation/Input';
import { Text } from '@/ui/foundation/Text';

export const Form = ({ 
  fields, 
  onSubmit,
  submitLabel = 'Submit',
  ...props 
}: FormProps) => {
  const [values, setValues] = useState({});
  
  return (
    <View {...props}>
      {fields.map((field) => (
        <View key={field.name}>
          <Text>{field.label}</Text>
          <Input
            value={values[field.name]}
            onChangeText={(text) => setValues({
              ...values,
              [field.name]: text
            })}
          />
        </View>
      ))}
      <Button onPress={() => onSubmit(values)}>
        {submitLabel}
      </Button>
    </View>
  );
};
```

Pattern components should be:

* Composed of multiple foundation components
* Handling complex UI behavior but no domain-specific logic
* Reusable across different features and contexts
* Examples: Modal, Form, DataTable, Carousel, Tabs

**(Consider 🤔) Extracting common UI interaction patterns into pattern components**

When you notice the same combination of foundation components appearing together with similar behavior, consider creating a pattern component.

**(Don't ❌) Mix domain-specific logic with pattern components**

```typescript
// DON'T do this in pattern components
import { useProducts } from '@/core/domains/products';

// Wrong: Pattern components shouldn't be tied to specific domains
export const ProductsTable = () => {
  const { data: products } = useProducts(); // Domain-specific data fetching
  
  return (
    <DataTable 
      data={products}
      columns={['name', 'price', 'category']} // Domain-specific fields
    />
  );
};
```

Instead, create a generic `DataTable` pattern component and let business components or features handle the domain-specific aspects.

#### Business Components

**(Do ✅) Create business components for domain-specific UI needs**

Business components integrate with specific domains and display domain-specific data:

```typescript
// ui/business/ProductCard/ProductCard.tsx
import { Card } from '@/ui/foundation/Card';
import { Text } from '@/ui/foundation/Text';
import { Button } from '@/ui/foundation/Button';
import { useAddToCart } from '@/core/domains/cart';

export const ProductCard = ({ product }: ProductCardProps) => {
  const addToCart = useAddToCart();
  
  return (
    <Card>
      <Text variant="heading">{product.name}</Text>
      <Text variant="body">${product.price}</Text>
      <Button 
        onPress={() => addToCart.mutate({ productId: product.id })}
      >
        Add to Cart
      </Button>
    </Card>
  );
};
```

Business components should:

* Integrate with specific domain logic and APIs
* Use hooks from the domains layer
* Display domain-specific data in a consistent way
* Examples: ProductCard, UserAvatar, OrderSummary, PaymentForm

**(Consider 🤔) Creating business components when the same domain entity UI appears in multiple features**

When multiple features need to display the same type of domain entity in a consistent way, a business component helps maintain consistency and reduces duplication.

**(Don't ❌) Make business components too specific to a single feature context**

Business components should be reusable across different features that work with the same domain entity:

```typescript
// DON'T do this - too feature-specific
export const ProductDetailPageCard = ({ /* specific to one page */ }) => {
  // Implementation tied to one specific feature's needs
};

// INSTEAD - create components that work across features
export const ProductCard = ({ product, variant = 'default' }) => {
  // Implementation that works in product listings, search results, favorites, etc.
};
```

* Mixing component types within same folder

## 2. Component Development Standards

<Callout type="info">
  Well-structured components make code more maintainable, testable, and easier to understand. These standards represent patterns we've found effective across many projects.
</Callout>

### 2.1 Component File Organization

**(Do ✅) Organize each component in a dedicated folder with consistent structure**

A well-organized component structure makes it easier to find files and understand their purpose:

```
Button/
├── Button.tsx        # Main component implementation
├── Button.test.tsx  # Unit and integration tests
├── types.ts         # TypeScript interfaces and types
├── styles.ts        # Component styles (when separated)
└── index.ts         # Barrel export for clean imports
```

This structure provides several benefits:

* **Separation of concerns**: Each file has a clear, single responsibility
* **Testing clarity**: Tests are co-located with the component they test
* **Import simplicity**: Barrel exports create clean import statements
* **Discoverability**: Consistent structure makes finding things predictable

**(Do ✅) Type Definitions:**

```typescript
// ui/foundation/Button/types.ts
import type { TouchableOpacityProps } from 'react-native';

export interface ButtonProps extends TouchableOpacityProps {
  variant?: 'primary' | 'secondary' | 'ghost';
  size?: 'small' | 'medium' | 'large';
  children: React.ReactNode;
}
```

**(Do ✅) Barrel Export:**

```typescript
// ui/foundation/Button/index.ts
export { Button } from './Button';
export type { ButtonProps } from './types';
```

### 2.3 Design Token Integration

<Callout type="info">
  Design tokens are the foundation of a consistent visual language. They help maintain a cohesive look and feel across the application and make theme changes much simpler to implement.
</Callout>

**(Do ✅) Always use design tokens for visual properties**

Design tokens provide a single source of truth for visual styles and enable easier theming and maintenance:

```typescript
import { theme } from '@/core/shared/styles/theme';
import { typography } from '@/core/shared/styles/typography';
import { spacing } from '@/core/shared/styles/spacing';

// Good: Using design tokens for all visual properties
const styles = StyleSheet.create({
  container: {
    backgroundColor: theme.colors.surface,
    padding: spacing.md,
    borderRadius: theme.radii.md,
    borderWidth: theme.borders.thin,
    borderColor: theme.colors.border,
  },
  text: {
    color: theme.colors.textPrimary,
    fontSize: typography.size.body,
    fontFamily: typography.families.regular,
    fontWeight: typography.weights.medium,
    lineHeight: typography.lineHeights.normal,
  },
});
```

This approach provides several benefits:

* **Consistency**: All components use the same visual values
* **Themability**: Changing theme is centralized in token files
* **Maintainability**: Visual changes can be made in one place
* **Design alignment**: Tokens match design system specifications

**(Consider 🤔) Creating component-specific token extensions when needed**

For specialized components, consider extending the token system in a structured way:

```typescript
// ui/foundation/Card/tokens.ts
import { theme } from '@/core/shared/styles/theme';

export const cardTokens = {
  elevation: {
    low: theme.elevation.low,
    medium: theme.elevation.medium,
    high: theme.elevation.high,
  },
  padding: {
    compact: theme.spacing.sm,
    default: theme.spacing.md,
    spacious: theme.spacing.lg,
  }
};
```

**(Don't ❌) Use arbitrary hardcoded values for visual properties**

Hardcoded values create inconsistency and make maintenance difficult:

```typescript
// DON'T do this: Hardcoded values with no connection to design system
const styles = StyleSheet.create({
  container: {
    backgroundColor: '#F5F5F5',  // Hardcoded color
    padding: 16,                // Arbitrary spacing
    borderRadius: 8,            // Arbitrary radius
    marginBottom: 24,           // Arbitrary margin
  },
  text: {
    color: '#333333',           // Hardcoded color
    fontSize: 16,               // Arbitrary size
    fontFamily: 'Roboto',       // Hardcoded font
    lineHeight: 24,             // Arbitrary line height
  },
});
```

This creates several problems:

* **Inconsistency**: Different components use different values
* **Maintenance challenges**: Changes require updating many files
* **Theme limitations**: Dark mode and other themes become difficult to implement
* **Design drift**: No guarantee that values match design specifications

### Domain Integration Rules

**(Do ✅) Business components can import from domains:**

```typescript
// ui/business/ProductCard/ProductCard.tsx
import { useProduct } from '@/core/domains/products/hooks';  // ✅ Allowed
import type { Product } from '@/core/domains/products/types'; // ✅ Allowed
```

**(Don't ❌) Foundation/Pattern components cannot import domains:**

```typescript
// ui/foundation/Button/Button.tsx
import { useAuth } from '@/core/domains/auth/hooks';  // ❌ Not allowed
```

### Feature Integration Rules

**(Do ✅) Features can import any UI components:**

```typescript
// features/product-catalog/screens/ProductList.tsx
import { Button } from '@/ui/foundation/Button';        // ✅ Allowed
import { DataTable } from '@/ui/patterns/DataTable';    // ✅ Allowed
import { ProductCard } from '@/ui/business/ProductCard'; // ✅ Allowed
```

**(Don't ❌) UI components cannot import from features:**

```typescript
// ui/foundation/Button/Button.tsx
import { ProductService } from '@/features/catalog/services'; // ❌ Not allowed
```

## 3. Integration with Existing Architecture

### Domain Integration Rules

**(Do ✅) Business components can import from domains:**

```typescript
// ui/business/ProductCard/ProductCard.tsx
import { useProduct } from '@/core/domains/products/hooks';  // ✅ Allowed
import type { Product } from '@/core/domains/products/types'; // ✅ Allowed
```

**(Don't ❌) Foundation/Pattern components cannot import domains:**

```typescript
// ui/foundation/Button/Button.tsx
import { useAuth } from '@/core/domains/auth/hooks';  // ❌ Not allowed
```

### Feature Integration Rules

**(Do ✅) Features can import any UI components:**

```typescript
// features/product-catalog/screens/ProductList.tsx
import { Button } from '@/ui/foundation/Button';        // ✅ Allowed
import { DataTable } from '@/ui/patterns/DataTable';    // ✅ Allowed
import { ProductCard } from '@/ui/business/ProductCard'; // ✅ Allowed
```

**(Don't ❌) UI components cannot import from features:**

```typescript
// ui/foundation/Button/Button.tsx
import { ProductService } from '@/features/catalog/services'; // ❌ Not allowed
```

## 4. Naming Conventions (Enforced)

### Component Naming

* **Files**: PascalCase (e.g., `Button.tsx`, `ProductCard.tsx`)
* **Folders**: PascalCase (e.g., `Button/`, `DataTable/`)
* **Props Interfaces**: ComponentName + Props (e.g., `ButtonProps`, `ModalProps`)

### Consistent Export Patterns

```typescript
// Always use named exports for components
export const Button = ...;           // ✅ Named export
export default Button;               // ❌ Avoid default exports

// Always export types
export type { ButtonProps } from './types';  // ✅ Type export
```

## 5. Accessibility Requirements

### Required Accessibility Features

Every component **must** implement these accessibility features:

#### 1. Semantic Roles

```typescript
// Button component
<TouchableOpacity
  accessibilityRole="button"
  accessibilityLabel="Save changes"
  accessibilityHint="Saves your current changes to the profile"
>

// Text Input component
<TextInput
  accessibilityRole="text"
  accessibilityLabel="Email address"
  accessibilityHint="Enter your email address for account recovery"
>
```

#### 2. State Communication

```typescript
// Button states
<TouchableOpacity
  accessibilityState={{
    disabled: isDisabled,
    busy: isLoading,
    selected: isSelected,
  }}
>

// Input states
<TextInput
  accessibilityState={{
    disabled: isDisabled,
    invalid: hasError,
  }}
>
```

#### 3. Dynamic Content

```typescript
// Loading states
{isLoading && (
  <View
    accessibilityRole="progressbar"
    accessibilityLabel="Loading content"
    accessibilityValue={{ 
      now: progress, 
      min: 0, 
      max: 100 
    }}
  >
)}

// Error states
{error && (
  <Text
    accessibilityRole="alert"
    accessibilityLiveRegion="polite"
  >
    {error}
  </Text>
)}
```

## 6. Testing Requirements

### Required Test Patterns

**(Do ✅) Every component must have:**

* Render test
* Props validation test
* User interaction test (if applicable)
* Accessibility test

```typescript
// ComponentName.test.tsx template
import { render, fireEvent } from '@testing-library/react-native';
import { Button } from './Button';

describe('Button', () => {
  it('renders correctly', () => {
    const { getByText } = render(<Button>Test</Button>);
    expect(getByText('Test')).toBeTruthy();
  });

  it('handles press events', () => {
    const onPress = jest.fn();
    const { getByText } = render(<Button onPress={onPress}>Test</Button>);
    fireEvent.press(getByText('Test'));
    expect(onPress).toHaveBeenCalled();
  });

  it('has correct accessibility role', () => {
    const { getByRole } = render(<Button>Test</Button>);
    expect(getByRole('button')).toBeTruthy();
  });
});
```

### Testing Coverage Requirements

* **Unit Tests**: 80%+ coverage required
* **Accessibility Tests**: All accessibility features must be tested
* **Visual Regression Tests**: Required for all visual states
* **Integration Tests**: Required for complex business components

## 7. Performance Requirements

**(Do ✅) Performance Standards:**

* Use React.memo for components with complex props
* Implement proper prop comparison for expensive re-renders
* Avoid inline styles in render methods
* Use StyleSheet.create for static styles

**(Don't ❌) Performance Anti-Patterns:**

* Creating style objects in render
* Missing memoization for expensive computations
* Unnecessary re-renders from prop drilling

## 8. Documentation Requirements

**(Do ✅) Every component must have:**

* JSDoc comments for component and props
* Usage examples in comments
* Accessibility notes

```typescript
/**
 * Primary button component for user actions
 * 
 * @example
 * <Button variant="primary" onPress={handleSave}>
 *   Save Changes
 * </Button>
 */
export const Button: React.FC<ButtonProps> = ({ ... }) => {
  // Implementation
};
```

## 9. Quality Control and Enforcement

### Required Checks Before Merge

* [ ] Component in correct folder (foundation/patterns/business)
* [ ] Uses design tokens (no hardcoded values)
* [ ] Proper TypeScript interfaces
* [ ] Barrel exports implemented
* [ ] Unit tests included
* [ ] Accessibility features complete
* [ ] Documentation complete
* [ ] Performance optimizations applied

### ESLint Rules Integration

```javascript
// Recommended ESLint rules
{
  "no-restricted-imports": [
    "error",
    {
      "patterns": [
        {
          "group": ["../features/*"],
          "message": "UI components cannot import from features"
        }
      ]
    }
  ]
}
```

### Code Review Checklist

**Architecture Compliance**

* Component placed in correct folder
* Follows naming conventions
* Proper import/export patterns
* No architecture rule violations

**Design Token Usage**

* All colors use theme tokens
* Typography follows token system
* Spacing uses consistent tokens
* No hardcoded values

**Accessibility**

* Proper semantic roles
* Screen reader support
* Keyboard navigation
* Focus management

**Performance**

* Appropriate memoization
* Efficient re-rendering
* Bundle size impact
* Runtime performance

## 10. Migration and Adoption

### Project Migration Steps

1. Create ui/ folder with foundation/patterns/business structure
2. Move existing components to appropriate folders
3. Update all imports across the project
4. Add missing TypeScript interfaces
5. Integrate design tokens
6. Add required tests

### Legacy Component Handling

* **Deprecation Period**: 3 months for existing components
* **Migration Support**: Provide migration guides
* **Backward Compatibility**: Maintain during transition
* **Documentation**: Clear migration paths

## 11. Enforcement and Compliance

### Automated Checks

* ESLint rules for import restrictions
* TypeScript strict mode compliance
* Test coverage requirements (80%+)
* Design token usage validation

### Manual Review Process

* Architecture compliance review
* Accessibility audit
* Performance assessment
* Documentation review

### Non-Compliance Consequences

* **Warning Phase**: First violation gets warning and guidance
* **Blocking Phase**: Second violation blocks merge until fixed
* **Training Phase**: Repeated violations require team training

## Related Documents

* [UI Architecture Overview](/docs/ui-development/architecture) - Complete architecture guide
* [Foundation Components Guide](/docs/ui-development/architecture/foundation-guide) - Component development patterns
* [Component Development Workflow](/docs/ui-development/architecture/development-workflow) - Step-by-step development process
* [AI Collaboration Guide](/docs/ui-development/architecture/ai-collaboration) - AI consistency patterns
* [Core Architecture Reference](/docs/architecture/core-architecture) - System architecture
* [Domain Architecture Guide](/docs/architecture/domain-architecture) - Domain integration patterns
* [Project Structure Reference](/docs/architecture/project-structure) - File organization
* [File Naming Conventions](/docs/coding-standards/file-naming-conventions) - Naming standards
* [Communication Patterns](/docs/features/communication-patterns) - Cross-feature integration

These standards ensure consistent, maintainable, and high-quality UI components across all frontend projects.


# UTA UI Development: AI Collaboration Guide for UI Development
URL: https://dev.updatetheapp.com/docs/ui-development/architecture/ai-collaboration
Documentation: https://dev.updatetheapp.com/docs/ui-development/architecture/ai-collaboration

Standardized AI prompts, patterns, and quality validation for consistent UI component development across all projects.
        
***

title: AI Collaboration Guide for UI Development
description: Standardized AI prompts, patterns, and quality validation for consistent UI component development across all projects.
-----------------------------------------------------------------------------------------------------------------------------------

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Callout } from 'fumadocs-ui/components/callout';
import { Steps, Step } from 'fumadocs-ui/components/steps';

# AI Collaboration Guide for UI Development

## Overview

This guide provides standardized AI prompts, patterns, and quality validation techniques to help create consistent UI components across projects. It aims to enhance collaboration between developers and AI assistants while maintaining architectural standards and code quality.

<Callout type="info">
  **Why AI Collaboration Patterns Matter**

  We've found that AI tools can significantly accelerate UI development, but consistency requires thoughtful prompting. These patterns have evolved through extensive experimentation to solve common challenges:

  * **Consistency**: Ensuring all AI-generated components follow the same standards
  * **Quality**: Maintaining high-quality code regardless of who (or what) wrote it
  * **Learning curve**: Reducing the time needed to effectively collaborate with AI
  * **Maintainability**: Creating components that integrate seamlessly with existing code
</Callout>

## Purpose & Scope

<Tabs items={["What You'll Learn", "Who This Is For", "When To Apply"]}>
  <Tab>
    This guide will help you:

    * Craft effective, consistent AI prompts for predictable results
    * Ensure AI-generated components align with our architectural standards
    * Validate and improve AI-generated code quality
    * Create components that seamlessly integrate with existing codebase
    * Develop a workflow that combines human expertise with AI capabilities
  </Tab>

  <Tab>
    This guide is valuable for:

    * **UI developers** working with AI tools on component development
    * **Team leads** establishing AI collaboration workflows
    * **New team members** learning our component patterns
    * **Technical writers** documenting component usage
    * **AI systems** being instructed on our development patterns
  </Tab>

  <Tab>
    These patterns are particularly useful when:

    * Creating new UI components from scratch
    * Extending existing components with new features
    * Refactoring components to follow our architecture
    * Documenting components for team use
    * Onboarding new team members to our UI development approach
  </Tab>
</Tabs>

## Core AI Collaboration Principles

Our approach to AI collaboration is built on four key principles that help maintain quality and consistency:

### 1. Predictable Structure

We help AI understand our three-layer architecture by being explicit about component categories and their characteristics:

<Mermaid
  chart={`
flowchart TD
AI[AI Assistant] --> Structure["Predictable Structure"]
Structure --> Foundation["Foundation Layer\nBasic, single-purpose components"]
Structure --> Patterns["Patterns Layer\nComposed, complex components"]
Structure --> Business["Business Layer\nDomain-aware components"]

style AI fill:#f9f,stroke:#333,stroke-width:2px
style Structure fill:#ffd,stroke:#333,stroke-width:2px
style Foundation fill:#e1f5fe,stroke:#01579b,stroke-width:2px
style Patterns fill:#f3e5f5,stroke:#4a148c,stroke-width:2px
style Business fill:#e8f5e8,stroke:#1b5e20,stroke-width:2px
`}
/>

By consistently using these structural concepts in our prompts, AI can better understand which type of component we're creating and what standards should apply.

### 2. Consistent Prompting

Standardized prompts provide a common language between developers and AI systems, leading to more predictable results and reducing miscommunication.

**(Consider 🤔) Using the template prompts provided in this guide**

These templates were developed through iterative testing to produce high-quality, compliant components consistently.

### 3. Quality Validation

All AI-generated components benefit from validation against our quality standards, covering areas like accessibility, performance, and testing.

**(Do ✅) Review AI-generated code against our quality checklist**

This helps catch common issues before integration and ensures all code meets our standards, regardless of its origin.

### 4. Architectural Compliance

Our prompts explicitly guide AI to follow established architecture patterns, ensuring generated code fits seamlessly into our codebase.

## Standard AI Prompts for UI Components

### Foundation Component Creation

#### Basic Foundation Component

```
Create a foundation [ComponentName] component following our UI architecture standards:

Requirements:
- Location: ui/foundation/[ComponentName]/
- Use design tokens from core/shared/styles/theme
- Include TypeScript props interface with JSDoc comments
- Add accessibility support with proper roles and states
- Include unit tests with rendering, interaction, and accessibility coverage
- Create barrel export in index.ts
- Follow our established naming conventions

Component should:
- Accept variant, size, and disabled props as minimum
- Use theme colors, spacing, and typography tokens exclusively
- Handle loading and error states appropriately
- Include proper accessibility labels and hints
- Be memoized for performance if props are complex

Example structure:
- variant?: 'primary' | 'secondary' | 'ghost'
- size?: 'small' | 'medium' | 'large'
- disabled?: boolean
- loading?: boolean
- children: React.ReactNode
```

#### Interactive Foundation Component

```
Create a foundation [ComponentName] component for user interaction:

Props interface should include:
- variant: Visual style variants (primary, secondary, ghost, danger)
- size: Component sizing options (small, medium, large)
- disabled: Disabled state handling
- loading: Loading state with spinner/indicator
- onPress/onChange: Event handlers
- children/value: Content props

Implementation requirements:
- Use TouchableOpacity/TextInput/Pressable as base
- Integrate theme tokens for all colors, spacing, and typography
- Add accessibility role and state communication
- Handle disabled/loading states visually and functionally
- Include proper TypeScript types with JSDoc
- Add comprehensive test coverage (render, interaction, accessibility)
- Use React.memo for performance optimization
```

### Pattern Component Creation

#### Composed Pattern Component

```
Create a pattern [ComponentName] component following our UI architecture standards:

Requirements:
- Location: ui/patterns/[ComponentName]/
- Compose using foundation components from ui/foundation/
- Use design tokens for any additional styling
- Include complex UI behavior but remain domain-agnostic
- Add proper TypeScript interfaces with comprehensive JSDoc
- Include unit tests covering all interactions and states
- Create barrel exports

Component should:
- Be composed from 2+ foundation components
- Handle complex user interactions (multi-step, validation, etc.)
- Remain reusable across different features
- Include loading, error, and success states
- Have comprehensive prop interfaces
- Be optimized for performance with proper memoization

Example: Modal component using Card, Button, Text from foundation
Example: Form component using Input, Button, Text from foundation
```

#### Data Display Pattern

```
Create a pattern [ComponentName] component for data display:

Props interface should include:
- data: Array or object of data to display
- loading: Loading state handling
- error: Error state handling
- onAction: Callback for user actions
- variant: Display style options
- pagination: Pagination controls if applicable

Implementation requirements:
- Use foundation components for all UI elements
- Handle empty states gracefully
- Include sorting/filtering if applicable
- Add accessibility support for data tables/lists
- Implement virtualization for large datasets
- Include comprehensive loading and error states
- Add proper TypeScript interfaces for data structures
```

### Business Component Creation

#### Domain-Aware Business Component

```
Create a business [ComponentName] component following our UI architecture standards:

Requirements:
- Location: ui/business/[ComponentName]/
- Accept [Domain] objects as props (e.g., Product, User, Order)
- Use foundation/pattern components for all UI rendering
- Integrate with domain hooks from core/domains/[domain]/hooks
- Include domain-specific logic and calculations
- Add proper TypeScript interfaces for domain objects
- Include comprehensive tests including domain integration

Component should:
- Accept domain entities as primary props
- Use domain hooks for data fetching (useProduct, useUser, etc.)
- Contain business logic specific to the domain
- Render using foundation/pattern components only
- Handle domain-specific states (out of stock, expired, etc.)
- Include domain-specific actions (add to cart, save profile, etc.)
- Be reusable across multiple features

Example: ProductCard accepting Product object and using useProduct hook
Example: UserAvatar accepting User object and using useUser hook
```

#### Entity Management Component

```
Create a business [ComponentName] component for [Domain] entity management:

Domain integration:
- Import hooks from core/domains/[domain]/hooks
- Import types from core/domains/[domain]/types
- Use domain API methods through hooks
- Handle domain-specific validation
- Include domain-specific error handling

Props interface should include:
- [entity]Id: Identifier for the entity
- on[Action]: Callback functions for entity actions
- variant: Display/behavior variants
- permissions: User permission handling
- editable: Edit mode support

Implementation requirements:
- Use domain hooks for data fetching and mutations
- Implement optimistic updates where appropriate
- Handle domain-specific loading and error states
- Include proper form validation for entity editing
- Add accessibility support for all interactions
- Include comprehensive tests with domain mock data
```

## AI Quality Validation Prompts

### Pre-Implementation Validation

```
Review this component requirement and provide feedback:

Component: [ComponentName]
Category: [foundation/patterns/business]
Purpose: [Brief description]

Please validate:
1. Is the component category correct based on the requirements?
2. Are there any missing requirements for this component type?
3. What accessibility considerations should be included?
4. What testing scenarios should be covered?
5. Are there any performance considerations?
6. Does this fit well with our three-layer architecture?

Provide specific recommendations for any issues found.
```

### Post-Implementation Review

```
Review this [ComponentName] component for compliance with our UI architecture standards:

Please check:
1. **Architecture Compliance**: 
   - Component placed in correct folder (foundation/patterns/business)
   - Follows proper import/export patterns
   - No architecture rule violations

2. **Design Token Usage**:
   - All colors use theme.colors.* tokens
   - Typography uses typography.* tokens  
   - Spacing uses theme.spacing.* tokens
   - No hardcoded values anywhere

3. **TypeScript Quality**:
   - Proper interfaces with JSDoc comments
   - Correct prop typing and defaults
   - Proper component typing

4. **Accessibility Implementation**:
   - Appropriate accessibilityRole set
   - Proper accessibilityLabel and accessibilityHint
   - Correct accessibilityState usage
   - Screen reader compatibility

5. **Performance Optimization**:
   - Appropriate use of React.memo
   - Proper memoization of expensive calculations
   - Efficient re-rendering patterns

6. **Testing Coverage**:
   - Unit tests for all functionality
   - Accessibility tests included
   - Integration tests if applicable

Provide specific feedback on any issues found with code examples for fixes.
```

### Code Migration Validation

```
Help me migrate this existing component to follow our UI architecture standards:

Current component: [Paste component code]

Please:
1. Analyze the current component and determine correct category (foundation/patterns/business)
2. Identify what needs to be updated to meet our standards
3. Check for hardcoded values that should use design tokens
4. Identify missing accessibility features
5. Suggest performance optimizations
6. Recommend additional tests needed
7. Provide the updated component code following our patterns

Focus on maintaining existing functionality while improving architecture compliance.
```

## AI-Assisted Development Workflows

### New Component Development Flow

#### Step 1: Requirements Analysis

```
Help me design a [ComponentName] component:

Context:
- Purpose: [Describe what the component does]
- Usage: [Describe where it will be used]
- User interactions: [Describe how users interact with it]
- Data requirements: [Describe what data it needs]

Please help me:
1. Determine the correct component category (foundation/patterns/business)
2. Define the props interface with proper TypeScript types
3. Identify required accessibility features
4. Suggest design token usage patterns
5. Outline testing requirements
6. Identify potential performance considerations

Provide a complete component specification ready for implementation.
```

#### Step 2: Implementation

```
Implement the [ComponentName] component based on this specification:

[Paste specification from Step 1]

Requirements:
- Follow our UI architecture standards exactly
- Use design tokens from core/shared/styles/ for all styling
- Include comprehensive TypeScript interfaces
- Add full accessibility support
- Handle all specified states and interactions
- Include proper error handling
- Optimize for performance
- Follow our established patterns and conventions

Create:
1. Component implementation file
2. TypeScript interfaces file
3. Barrel export file
4. Comprehensive unit tests
```

#### Step 3: Quality Assurance

```
Perform a quality review of this implemented component:

[Paste implementation]

Check against our standards:
- Architecture rule compliance
- Design token usage (no hardcoded values)
- TypeScript interface completeness
- Accessibility feature implementation
- Performance optimization
- Testing coverage
- Documentation quality

Provide a detailed quality report with any issues found and specific fixes needed.
```

### Maintenance and Enhancement Flow

#### Bug Fix Assistance

```
Help me fix this issue in [ComponentName]:

Issue description: [Describe the bug]
Current behavior: [What's happening now]
Expected behavior: [What should happen]
Component code: [Paste relevant code]

Please:
1. Identify the root cause of the issue
2. Provide a fix that maintains our architecture standards
3. Ensure the fix doesn't break existing functionality
4. Suggest additional tests to prevent regression
5. Check if similar issues might exist in related components

Provide the corrected code with explanation of changes.
```

#### Feature Enhancement

```
Help me add [feature] to the existing [ComponentName] component:

Current component: [Paste component code]
New feature requirements: [Describe what needs to be added]

Requirements:
- Maintain backward compatibility with existing props
- Follow our architecture standards
- Use design tokens for any new styling
- Add proper TypeScript types for new features
- Include accessibility support for new functionality
- Add comprehensive tests for new features
- Update documentation as needed

Provide the enhanced component with all changes clearly marked.
```

## AI Prompt Templates by Use Case

### Component Creation Templates

#### Quick Foundation Component

```
Create a foundation [ComponentName] that:
- Uses design tokens from core/shared/styles/
- Has variant and size props
- Includes accessibility support
- Has comprehensive TypeScript types
- Includes unit tests
```

#### Complex Pattern Component

```
Create a pattern [ComponentName] that:
- Composes [list foundation components]
- Handles [specific interactions]
- Manages [specific states]
- Remains domain-agnostic
- Includes comprehensive props interface
```

#### Business Domain Component

```
Create a business [ComponentName] that:
- Works with [Domain] entities
- Uses [specific domain hooks]
- Contains [specific business logic]
- Integrates with our domain architecture
- Handles [domain-specific scenarios]
```

### Testing Templates

#### Comprehensive Test Generation

```
Generate comprehensive tests for [ComponentName]:

Component behavior:
- Props: [list all props and expected behaviors]
- Interactions: [list all user interactions]
- States: [list all visual/logical states]
- Accessibility: [list all a11y features]

Test requirements:
- Unit tests with @testing-library/react-native
- Accessibility tests for all a11y features
- Visual regression tests for all states
- Integration tests for complex behavior
- Mock any external dependencies properly
```

#### Accessibility Test Focus

```
Generate accessibility-focused tests for [ComponentName]:

Please test:
- Proper accessibility roles and labels
- Screen reader announcements
- Keyboard navigation support
- State change announcements
- Focus management
- High contrast mode compatibility
- Large text scaling support

Use @testing-library/react-native patterns and include both automated and manual testing guidance.
```

### Refactoring Templates

#### Architecture Compliance Update

```
Refactor this component to follow our UI architecture standards:

Current code: [paste code]

Updates needed:
- Move to correct folder structure
- Update to use design tokens
- Add missing accessibility features
- Improve TypeScript interfaces
- Add comprehensive tests
- Optimize performance
- Update documentation

Maintain all existing functionality while improving compliance.
```

#### Performance Optimization

```
Optimize this component for performance:

Component code: [paste code]

Focus on:
- Proper memoization strategies
- Efficient re-rendering patterns
- Bundle size optimization
- Runtime performance improvements
- Memory usage optimization

Provide optimized code with explanations of improvements made.
```

## Quality Assurance Integration

### Pre-Merge Checklist for AI-Generated Code

Use this prompt to validate any AI-generated component:

```
Validate this component against our UI architecture standards:

Component: [paste component code]

Checklist:
- [ ] Correct folder placement (foundation/patterns/business)
- [ ] Uses design tokens exclusively (no hardcoded values)
- [ ] Proper TypeScript interfaces with JSDoc
- [ ] Comprehensive accessibility support
- [ ] Includes unit tests (render, interaction, accessibility)
- [ ] Performance optimized (memoization where needed)
- [ ] Follows naming conventions
- [ ] Proper barrel exports
- [ ] Documentation complete
- [ ] Integration with existing architecture

Provide pass/fail status for each item with specific fixes for any failures.
```

### Continuous Quality Monitoring

```
Review our recent AI-generated components for consistency:

Components to review: [list recent components]

Check for:
1. Pattern consistency across components
2. Design token usage compliance
3. Accessibility implementation consistency
4. TypeScript interface patterns
5. Testing pattern adherence
6. Performance optimization consistency

Identify any inconsistencies and provide standardization recommendations.
```

## Integration with Development Workflow

### Workflow Integration Points

Our AI collaboration patterns integrate seamlessly with the existing development workflow:

#### Planning Phase Integration

```
Combine with existing planning processes:
- Requirements gathering (existing workflow)
- AI-assisted component specification (this guide)
- Design review (existing workflow)  
- Implementation planning (this guide + existing workflow)
```

#### Development Phase Integration

```
Enhanced development process:
- Component structure creation (existing standards)
- AI-assisted implementation (this guide)
- Design token integration (existing architecture)
- Code review process (existing workflow + AI validation)
```

#### Quality Assurance Integration

```
Comprehensive QA process:
- Automated testing (existing standards)
- AI-assisted test generation (this guide)
- Manual review process (existing workflow)
- Performance validation (existing standards)
```

For complete development workflow details, see [Component Development Workflow](/docs/ui-development/architecture/development-workflow).

## Troubleshooting Common AI Issues

### Issue: AI Not Using Design Tokens

**Problem**: AI generates hardcoded values instead of theme tokens
**Solution**: Use this corrective prompt:

```
The component you generated uses hardcoded values. Please update it to use design tokens:

Replace all hardcoded values with:
- Colors: theme.colors.[semantic-name][shade]
- Spacing: theme.spacing.[size]
- Typography: typography.sizes.[size], typography.weights.[weight]
- Border radius: theme.radii.[size]

Show the corrected component with all hardcoded values replaced.
```

### Issue: AI Missing Accessibility Features

**Problem**: AI generates components without proper accessibility
**Solution**: Use this enhancement prompt:

```
Add comprehensive accessibility support to this component:

Component: [paste code]

Add:
- Appropriate accessibilityRole
- Descriptive accessibilityLabel
- Helpful accessibilityHint
- Proper accessibilityState for all states
- accessibilityLiveRegion for dynamic content
- Keyboard navigation support

Provide the updated component with full accessibility implementation.
```

### Issue: AI Creating Wrong Component Category

**Problem**: AI places components in wrong folders or mixes concerns
**Solution**: Use this correction prompt:

```
This component is in the wrong category. Please recategorize and fix:

Current: [describe current implementation]
Issue: [explain why it's wrong category]

Correct approach:
- Category: [foundation/patterns/business]
- Location: ui/[category]/[ComponentName]/
- Concerns: [what it should and shouldn't do]

Provide the corrected component in the right category with proper separation of concerns.
```

## Related Documents

* [UI Architecture Standards](/docs/ui-development/architecture/standards) - Mandatory development standards
* [UI Architecture Overview](/docs/ui-development/architecture) - Complete architecture guide
* [Foundation Components Guide](/docs/ui-development/architecture/foundation-guide) - Component development patterns
* [Component Development Workflow](/docs/ui-development/architecture/development-workflow) - Step-by-step development process
* [Core Architecture Reference](/docs/architecture/core-architecture) - System architecture
* [Project Structure Reference](/docs/architecture/project-structure) - File organization

This guide ensures consistent, high-quality AI collaboration for UI component development across all projects.


# UTA UI Development: Foundation Components Guide
URL: https://dev.updatetheapp.com/docs/ui-development/architecture/foundation-guide
Documentation: https://dev.updatetheapp.com/docs/ui-development/architecture/foundation-guide

Comprehensive guide to creating, implementing, and maintaining foundation components with design token integration and AI collaboration patterns.
        
***

title: Foundation Components Guide
description: Comprehensive guide to creating, implementing, and maintaining foundation components with design token integration and AI collaboration patterns.
--------------------------------------------------------------------------------------------------------------------------------------------------------------

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Callout } from 'fumadocs-ui/components/callout';
import { Steps, Step } from 'fumadocs-ui/components/steps';

# Foundation Components Guide

## Overview

This guide explores patterns and practices for creating foundation components - the atomic building blocks of our design system. Foundation components serve as pure presentation components that form the basis for all other UI elements in our applications.

<Callout type="info">
  **Why Foundation Components Matter**

  Foundation components solve several critical challenges in React Native development:

  * **Consistency**: They ensure visual and behavioral consistency across the application
  * **Efficiency**: They reduce duplication by centralizing common UI elements
  * **Maintainability**: Changes to foundation components automatically propagate throughout the app
  * **Collaboration**: They create a shared vocabulary between designers and developers
  * **Accessibility**: They encapsulate accessibility best practices in reusable units
</Callout>

## Purpose & Scope

<Tabs items={["What You'll Learn", "Who This Is For", "Prerequisites"]}>
  <Tab>
    This guide will help you:

    * Understand what makes an effective foundation component
    * Implement components that integrate with our design token system
    * Create accessible, reusable, and performant UI building blocks
    * Maintain consistency through established patterns
    * Follow patterns that work well with AI collaboration
  </Tab>

  <Tab>
    This guide is valuable for:

    * **UI developers** building foundation components
    * **Design system maintainers** establishing UI standards
    * **Feature developers** using foundation components
    * **Designers** collaborating on component implementation
    * **QA engineers** testing component functionality
  </Tab>

  <Tab>
    To get the most from this guide, you should be familiar with:

    * Basic React and React Native concepts
    * TypeScript fundamentals
    * [UI Architecture Overview](/docs/ui-development/architecture) (recommended first)
    * [Design Token System](/docs/ui-development/theme-management) (helpful context)
  </Tab>
</Tabs>

## Foundation Component Principles

### Core Characteristics

Effective foundation components generally share these key characteristics:

1. **Single Responsibility**: Each component focuses on one clear purpose, making it easier to understand, test, and maintain

2. **No Business Logic**: Foundation components remain free from domain knowledge or business rules, ensuring they're reusable across different contexts

3. **Design Token Driven**: Styling comes from centralized design tokens rather than hardcoded values, enabling consistent theming and easier updates

4. **Highly Reusable**: These components are designed to be used across multiple patterns, features, and projects

5. **Accessible by Default**: Accessibility is built in from the start, not added as an afterthought

6. **Predictable API**: Consistent prop patterns and naming conventions make components intuitive to use

## Guide Structure

This comprehensive guide is organized into focused sections to help you master foundation component development:

### 📱 [Interactive Elements](/docs/ui-development/architecture/foundation-guide/interactive-elements)

Components that respond to user input - buttons, inputs, switches, and other controls. Learn how to build accessible, responsive interactive components.

### 🎨 [Display Components](/docs/ui-development/architecture/foundation-guide/display-components)

Visual elements that present information - text, cards, images, and containers. Master typography, layout, and visual hierarchy.

### 🎯 [Design Token Integration](/docs/ui-development/architecture/foundation-guide/design-tokens)

Deep dive into using design tokens for colors, typography, spacing, and shadows. Ensure consistency across your component library.

### ♿ [Accessibility Patterns](/docs/ui-development/architecture/foundation-guide/accessibility-patterns)

Comprehensive accessibility implementation including roles, states, focus management, and testing strategies.

### 🧪 [Testing & Performance](/docs/ui-development/architecture/foundation-guide/testing-performance)

Testing strategies, visual regression, performance optimization, and memoization patterns for reliable components.

### 🤖 [AI Collaboration & Documentation](/docs/ui-development/architecture/foundation-guide/ai-collaboration-docs)

Effective AI prompts, documentation standards, and maintenance strategies for sustainable component development.

## Foundation Component Categories

<Callout type="info">
  Foundation components form the basis of our entire UI system. By grouping them into logical categories, we can ensure consistent patterns across similar component types and make them easier to discover and use.
</Callout>

The foundation layer includes these primary categories:

* **Interactive Elements**: Components that handle user interaction
* **Display Elements**: Components that present information
* **Layout Components**: Components that structure content
* **Feedback Components**: Components that communicate state

Each category follows consistent patterns while addressing its specific requirements.

## Best Practices Summary

When building foundation components:

* ✅ **Start with the interface**: Define clear TypeScript types
* ✅ **Use design tokens**: Never hardcode colors, spacing, or typography
* ✅ **Build accessible**: Include proper roles, states, and labels
* ✅ **Test thoroughly**: Cover all states, interactions, and edge cases
* ✅ **Document clearly**: Provide examples and usage guidelines
* ✅ **Optimize performance**: Use memoization appropriately

## Component Architecture

Foundation components follow a consistent architectural pattern that aligns with our [Three-Layer Architecture](/docs/ui-development/architecture#three-layer-architecture):

* **Props Layer**: Well-defined TypeScript interfaces
* **Implementation Layer**: React Native components with hooks
* **Style Layer**: Design token integration
* **Test Layer**: Comprehensive test coverage

This architecture ensures components are predictable, maintainable, and easy to understand.

## Getting Started

<Steps>
  <Step>
    #### Review Core Principles

    Understand the characteristics that define effective foundation components
  </Step>

  <Step>
    #### Explore Component Categories

    Browse the different types of foundation components and their patterns
  </Step>

  <Step>
    #### Learn Token Integration

    Master the use of design tokens for consistent styling
  </Step>

  <Step>
    #### Implement Accessibility

    Ensure your components work for all users
  </Step>

  <Step>
    #### Test Comprehensively

    Write tests that ensure reliability and catch regressions
  </Step>
</Steps>

## Next Steps

* Start with [Interactive Elements](/docs/ui-development/architecture/foundation-guide/interactive-elements) to learn about building user controls
* Review our [Component Examples Library](/docs/reference-implementations/ui) for implementation references
* Check the [Component Development Workflow](/docs/ui-development/architecture/development-workflow) for the complete development process

## Related Documents

* [UI Architecture Overview](/docs/ui-development/architecture) - Understanding the three-layer architecture
* [Component Development Workflow](/docs/ui-development/architecture/development-workflow) - Step-by-step development process
* [Component Patterns](/docs/ui-development/development/component-patterns) - Higher-level composition patterns
* [Design Token System](/docs/ui-development/theme-management) - Theme and token management
* [Component Examples Library](/docs/reference-implementations/ui) - Implementation examples


# UTA UI Development: Interactive Elements
URL: https://dev.updatetheapp.com/docs/ui-development/architecture/foundation-guide/interactive-elements
Documentation: https://dev.updatetheapp.com/docs/ui-development/architecture/foundation-guide/interactive-elements

Foundation components that respond to user input - buttons, inputs, switches, and other interactive controls.
        
***

title: Interactive Elements
description: Foundation components that respond to user input - buttons, inputs, switches, and other interactive controls.
--------------------------------------------------------------------------------------------------------------------------

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Callout } from 'fumadocs-ui/components/callout';

# Interactive Elements

## Overview

Interactive elements are foundation components that respond to user input such as taps, swipes, or keyboard actions. They form the basis of all user interactions in our applications and must be built with careful attention to accessibility, performance, and user experience.

<Callout type="info">
  **Key Principles for Interactive Components**

  All interactive elements should:

  * Provide clear visual feedback for all states (default, hover, pressed, disabled)
  * Meet minimum touch target sizes (44×44 points)
  * Include comprehensive keyboard support
  * Communicate state changes to assistive technologies
  * Handle loading and error states gracefully
</Callout>

## Button Components

The Button is perhaps the most fundamental interactive component in any UI system. It serves as the primary way users trigger actions in our applications.

<Callout type="info">
  **📋 Complete Implementation Available**

  See our [Button Reference Implementation](/docs/reference-implementations/ui/foundation/Button) for a production-ready example with TypeScript types, accessibility features, testing patterns, and usage examples. Perfect for copy-pasting into your project!
</Callout>

### Component Interface

<Tabs items={["TypeScript Interface", "Props Documentation", "Usage Examples"]}>
  <Tab>
    ```typescript
    // ui/foundation/Button/types.ts
    import type { TouchableOpacityProps } from 'react-native';

    export interface ButtonProps extends Omit<TouchableOpacityProps, 'style'> {
      /**
       * Visual style variant of the button
       * @default 'primary'
       */
      variant?: 'primary' | 'secondary' | 'ghost' | 'danger';
      
      /**
       * Size of the button
       * @default 'medium'
       */
      size?: 'small' | 'medium' | 'large';
      
      /**
       * When true, shows a loading spinner and disables interaction
       * @default false
       */
      loading?: boolean;
      
      /**
       * Optional icon to display before text
       */
      icon?: React.ReactNode;
      
      /**
       * Optional icon to display after text
       */
      iconRight?: React.ReactNode;
      
      /**
       * When true, button expands to fill its container width
       * @default false
       */
      fullWidth?: boolean;
      
      /**
       * Button content (typically text)
       */
      children: React.ReactNode;
      
      /**
       * Optional custom styles (use sparingly, prefer variants)
       */
      style?: ViewStyle;
    }
    ```
  </Tab>

  <Tab>
    **Button Props Reference**

    | Prop        | Type                                              | Default     | Description           |
    | ----------- | ------------------------------------------------- | ----------- | --------------------- |
    | `variant`   | `'primary' \| 'secondary' \| 'ghost' \| 'danger'` | `'primary'` | Visual style variant  |
    | `size`      | `'small' \| 'medium' \| 'large'`                  | `'medium'`  | Button size           |
    | `loading`   | `boolean`                                         | `false`     | Shows loading spinner |
    | `disabled`  | `boolean`                                         | `false`     | Disables interaction  |
    | `icon`      | `ReactNode`                                       | -           | Icon before text      |
    | `iconRight` | `ReactNode`                                       | -           | Icon after text       |
    | `fullWidth` | `boolean`                                         | `false`     | Full container width  |
    | `onPress`   | `() => void`                                      | -           | Press handler         |
    | `children`  | `ReactNode`                                       | -           | Button content        |

    **Inherited Props**

    Button also accepts all standard `TouchableOpacity` props except `style`.
  </Tab>

  <Tab>
    ```tsx
    // Basic usage
    <Button onPress={handleSave}>
      Save Changes
    </Button>

    // With variant and size
    <Button 
      variant="secondary" 
      size="large"
      onPress={handleCancel}
    >
      Cancel
    </Button>

    // With loading state
    <Button 
      loading={isSaving}
      onPress={handleSave}
    >
      {isSaving ? 'Saving...' : 'Save'}
    </Button>

    // With icons
    <Button 
      icon={<SaveIcon />}
      variant="primary"
      onPress={handleSave}
    >
      Save Document
    </Button>

    // Danger variant for destructive actions
    <Button 
      variant="danger"
      onPress={handleDelete}
    >
      Delete Account
    </Button>

    // Full width button
    <Button 
      fullWidth
      size="large"
      onPress={handleSubmit}
    >
      Submit Application
    </Button>
    ```
  </Tab>
</Tabs>

### Implementation Guidelines

<Callout type="info">
  **Implementation Considerations**

  Buttons appear simple but require careful implementation to handle all scenarios effectively:

  * **Accessibility**: Ensure proper roles, states, and labels
  * **Loading states**: Prevent multiple submissions while actions are pending
  * **Touch feedback**: Provide appropriate visual feedback on press
  * **Variants**: Support different visual styles for different contexts
  * **Composition**: Allow composition with icons and other elements
</Callout>

#### Design Token Integration

Buttons should use design tokens for all visual properties:

```typescript
// ui/foundation/Button/Button.tsx
import { theme } from '@/core/shared/styles/theme';
import { spacing } from '@/core/shared/styles/spacing';
import { typography } from '@/core/shared/styles/typography';

// Style implementation using design tokens
const getStyles = (variant: ButtonVariant, size: ButtonSize) => ({
  container: {
    backgroundColor: theme.colors[variant].background,
    borderRadius: theme.radii.md,
    padding: spacing[size],
    alignItems: 'center',
    justifyContent: 'center',
    flexDirection: 'row',
  },
  text: {
    color: theme.colors[variant].text,
    fontSize: typography.size[size],
    fontFamily: typography.families.medium,
  },
});
```

#### Loading State Implementation

Loading states should always:

* Disable the button to prevent multiple submissions
* Show a visual indicator (typically a spinner)
* Maintain the button's size to prevent layout shifts
* Provide appropriate accessibility updates

### Button Best Practices

**(Do ✅) Follow these Button component best practices**

* Use semantic colors based on button purpose (e.g., danger for destructive actions)
* Include appropriate touch targets (minimum 44×44 points)
* Maintain sufficient contrast ratios between text and background
* Use consistent spacing between buttons when grouped
* Always include a visible focus state for keyboard navigation
* Provide clear, action-oriented button text

**(Don't ❌) Make these common Button component mistakes**

* Using ambiguous or generic text like "Click Here" or "Submit"
* Placing too many buttons with equal visual weight in proximity
* Using buttons when links would be more appropriate (navigation vs. action)
* Creating custom one-off button styles instead of using variants
* Omitting loading states for asynchronous actions
* Making touch targets too small for comfortable interaction

### Complete Button Implementation

For a complete implementation of the Button component with all variants, states, accessibility features, and testing patterns, see the [Button Reference Implementation](/docs/reference-implementations/ui/foundation/Button).

The Button example demonstrates:

* ✅ All visual variants (primary, secondary, ghost, danger)
* ✅ Size variations (small, medium, large)
* ✅ Loading and disabled states
* ✅ Icon support (left and right)
* ✅ Full accessibility implementation
* ✅ Design token integration
* ✅ TypeScript interfaces
* ✅ Comprehensive testing patterns

## Input Components

Input components handle text entry and form interactions. They must balance functionality with accessibility and user experience across different platforms and input methods.

### Input Interface

For a complete implementation of the Input component with all variants, validation, accessibility features, and testing patterns, see the [Input Reference Implementation](/docs/reference-implementations/ui/foundation/Input).

The Input example demonstrates:

* ✅ Multiple variants (outlined, filled)
* ✅ Size variations (small, medium, large)
* ✅ Validation with error messages
* ✅ Helper text support
* ✅ Icon support (left and right)
* ✅ Focus state management
* ✅ Full accessibility implementation
* ✅ Comprehensive testing patterns

### Input Best Practices

**(Do ✅) Input component best practices**

* Provide clear labels for all inputs
* Show validation feedback inline and immediately
* Support autofill and password managers
* Include helper text for complex inputs
* Make error messages specific and actionable
* Support platform-specific input behaviors

**(Don't ❌) Common input mistakes**

* Validating only on form submission
* Using placeholder text as the only label
* Making error messages vague or technical
* Ignoring platform keyboard differences
* Forgetting to handle secure text entry
* Using tiny touch targets for input fields

## Switch Components

Switches provide binary on/off controls for settings and preferences.

### Switch Interface

```typescript
export interface SwitchProps {
  /**
   * Current value of the switch
   */
  value: boolean;
  
  /**
   * Called when switch value changes
   */
  onValueChange: (value: boolean) => void;
  
  /**
   * Disabled state
   * @default false
   */
  disabled?: boolean;
  
  /**
   * Size variant
   * @default 'medium'
   */
  size?: 'small' | 'medium' | 'large';
  
  /**
   * Color when switch is on
   * @default theme.colors.primary[500]
   */
  activeColor?: string;
  
  /**
   * Accessibility label
   */
  accessibilityLabel: string;
}
```

### Switch Implementation Considerations

* **Visual feedback**: Smooth animations for state changes
* **Touch targets**: Ensure adequate size for easy interaction
* **Color contrast**: Maintain visibility in both states
* **Platform consistency**: Match iOS and Android patterns
* **Accessibility**: Clear state announcements

## Checkbox Components

Checkboxes allow users to select multiple options from a set.

### Checkbox Interface

```typescript
export interface CheckboxProps {
  /**
   * Whether checkbox is checked
   */
  checked: boolean;
  
  /**
   * Called when checkbox is pressed
   */
  onChange: (checked: boolean) => void;
  
  /**
   * Indeterminate state (partial selection)
   * @default false
   */
  indeterminate?: boolean;
  
  /**
   * Disabled state
   * @default false
   */
  disabled?: boolean;
  
  /**
   * Label text
   */
  label?: string;
  
  /**
   * Size variant
   * @default 'medium'
   */
  size?: 'small' | 'medium' | 'large';
  
  /**
   * Error state
   * @default false
   */
  error?: boolean;
}
```

### Checkbox Best Practices

* Support indeterminate state for parent-child relationships
* Include clear touch targets beyond the checkbox itself
* Provide visual feedback for all states
* Support keyboard navigation (Space to toggle)
* Group related checkboxes appropriately

## Radio Button Components

Radio buttons allow single selection from a group of options.

### RadioButton Interface

```typescript
export interface RadioButtonProps {
  /**
   * Whether radio is selected
   */
  selected: boolean;
  
  /**
   * Called when radio is pressed
   */
  onPress: () => void;
  
  /**
   * Value of this radio option
   */
  value: string;
  
  /**
   * Display label
   */
  label: string;
  
  /**
   * Disabled state
   * @default false
   */
  disabled?: boolean;
  
  /**
   * Size variant
   * @default 'medium'
   */
  size?: 'small' | 'medium' | 'large';
}

export interface RadioGroupProps {
  /**
   * Currently selected value
   */
  value: string;
  
  /**
   * Called when selection changes
   */
  onChange: (value: string) => void;
  
  /**
   * Group name for accessibility
   */
  name: string;
  
  /**
   * Radio options
   */
  children: React.ReactNode;
}
```

## Slider Components

Sliders allow users to select values from a continuous range.

### Slider Interface

```typescript
export interface SliderProps {
  /**
   * Current value
   */
  value: number;
  
  /**
   * Value change handler
   */
  onValueChange: (value: number) => void;
  
  /**
   * Minimum value
   * @default 0
   */
  minimumValue?: number;
  
  /**
   * Maximum value
   * @default 100
   */
  maximumValue?: number;
  
  /**
   * Step interval
   * @default 1
   */
  step?: number;
  
  /**
   * Show value label
   * @default false
   */
  showValueLabel?: boolean;
  
  /**
   * Disabled state
   * @default false
   */
  disabled?: boolean;
}
```

## General Best Practices for Interactive Elements

### Accessibility Requirements

All interactive elements must:

1. **Provide proper roles**
   ```tsx
   accessibilityRole="button"
   accessibilityRole="switch"
   accessibilityRole="checkbox"
   ```

2. **Communicate states**
   ```tsx
   accessibilityState={{
     disabled: isDisabled,
     checked: isChecked,
     selected: isSelected,
     busy: isLoading,
   }}
   ```

3. **Include descriptive labels**
   ```tsx
   accessibilityLabel="Save changes"
   accessibilityHint="Double tap to save your profile changes"
   ```

### Performance Considerations

* Use `React.memo` for components that receive stable props
* Memoize style calculations with `useMemo`
* Debounce rapid interactions when appropriate
* Optimize animation performance with `useNativeDriver`

### Testing Interactive Elements

```typescript
// Example test structure
describe('Interactive Component', () => {
  it('responds to user interaction', () => {
    const onPress = jest.fn();
    const { getByRole } = render(
      <Button onPress={onPress}>Test</Button>
    );
    
    fireEvent.press(getByRole('button'));
    expect(onPress).toHaveBeenCalledTimes(1);
  });
  
  it('respects disabled state', () => {
    const onPress = jest.fn();
    const { getByRole } = render(
      <Button disabled onPress={onPress}>Test</Button>
    );
    
    fireEvent.press(getByRole('button'));
    expect(onPress).not.toHaveBeenCalled();
  });
});
```

## Summary

Interactive elements form the foundation of user interaction in your application. By following these patterns and best practices, you can create components that are:

* **Accessible**: Work for all users regardless of abilities
* **Performant**: Respond quickly to user input
* **Consistent**: Behave predictably across the application
* **Maintainable**: Easy to update and extend

## Next Steps

* Explore [Display Components](/docs/ui-development/architecture/foundation-guide/display-components) for presenting information
* Learn about [Design Token Integration](/docs/ui-development/architecture/foundation-guide/design-tokens) for consistent styling
* Review [Accessibility Patterns](/docs/ui-development/architecture/foundation-guide/accessibility-patterns) for inclusive design

## Related Documents

* [Button Reference Implementation](/docs/reference-implementations/ui/foundation/Button)
* [Input Reference Implementation](/docs/reference-implementations/ui/foundation/Input)
* [Component Development Workflow](/docs/ui-development/architecture/development-workflow)
* [Accessibility Guidelines](/docs/ui-development/architecture/foundation-guide/accessibility-patterns)


# UTA UI Development: Display Components
URL: https://dev.updatetheapp.com/docs/ui-development/architecture/foundation-guide/display-components
Documentation: https://dev.updatetheapp.com/docs/ui-development/architecture/foundation-guide/display-components

Visual elements that present information - text, cards, images, and containers for content presentation.
        
***

title: Display Components
description: Visual elements that present information - text, cards, images, and containers for content presentation.
---------------------------------------------------------------------------------------------------------------------

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Callout } from 'fumadocs-ui/components/callout';

# Display Components

## Overview

Display components are foundation elements that present information to users without direct interaction. They focus on visual presentation, typography, layout, and content organization while maintaining consistency through design tokens.

<Callout type="info">
  **Key Principles for Display Components**

  All display components should:

  * Use design tokens for all visual properties
  * Support responsive sizing and scaling
  * Maintain proper visual hierarchy
  * Ensure content accessibility
  * Handle loading and error states gracefully
</Callout>

## Text Component

The Text component is the foundation for all typography in your application. It ensures consistent text rendering across platforms while supporting various typographic styles.

### Text Interface

<Tabs items={["TypeScript Interface", "Usage Examples", "Best Practices"]}>
  <Tab>
    ```typescript
    // ui/foundation/Text/types.ts
    import type { TextProps as RNTextProps } from 'react-native';

    export interface TextProps extends RNTextProps {
      /**
       * Typography variant
       * @default 'body'
       */
      variant?: 'heading' | 'subheading' | 'body' | 'caption' | 'label';
      
      /**
       * Size variant
       * @default 'medium'
       */
      size?: 'small' | 'medium' | 'large' | 'xlarge';
      
      /**
       * Text color
       * @default 'primary'
       */
      color?: 'primary' | 'secondary' | 'disabled' | 'error' | 'success' | 'warning' | string;
      
      /**
       * Font weight
       * @default 'normal'
       */
      weight?: 'normal' | 'medium' | 'semibold' | 'bold';
      
      /**
       * Text alignment
       * @default 'left'
       */
      align?: 'left' | 'center' | 'right' | 'justify';
      
      /**
       * Text content
       */
      children: React.ReactNode;
    }
    ```
  </Tab>

  <Tab>
    ```tsx
    // Basic text usage
    <Text>Default body text</Text>

    // Heading variants
    <Text variant="heading" size="xlarge">
      Main Heading
    </Text>

    <Text variant="subheading" size="large">
      Section Title
    </Text>

    // Colored text
    <Text color="error">
      Error message text
    </Text>

    <Text color="success" weight="semibold">
      ✓ Operation successful
    </Text>

    // Caption text
    <Text variant="caption" color="secondary">
      Last updated 2 hours ago
    </Text>

    // Custom styling while maintaining tokens
    <Text
      variant="body"
      size="medium"
      style={{ marginTop: theme.spacing.md }}
    >
      Text with custom spacing
    </Text>
    ```
  </Tab>

  <Tab>
    **(Do ✅) Text component best practices**

    * Use semantic variants (heading, body, caption) for proper hierarchy
    * Apply color tokens for consistency
    * Use weight variations sparingly for emphasis
    * Ensure sufficient contrast ratios for readability
    * Test text truncation and wrapping behavior
    * Include proper accessibility roles for semantic text

    **(Don't ❌) Common text mistakes**

    * Hardcoding font sizes or colors
    * Using too many font weights (stick to 2-3 max)
    * Ignoring platform-specific rendering differences
    * Forgetting numberOfLines for potentially long text
    * Using Text for non-text content (icons, images)
    * Missing language/locale considerations
  </Tab>
</Tabs>

### Text Implementation

```typescript
// ui/foundation/Text/Text.tsx
import React from 'react';
import { Text as RNText } from 'react-native';
import { theme } from '@/core/shared/styles/theme';
import { typography } from '@/core/shared/styles/typography';
import type { TextProps } from './types';

export const Text: React.FC<TextProps> = ({
  variant = 'body',
  size = 'medium',
  color = 'primary',
  weight = 'normal',
  align = 'left',
  children,
  style,
  ...props
}) => {
  const getVariantStyles = () => {
    switch (variant) {
      case 'heading':
        return {
          fontWeight: typography.weights.bold,
          lineHeight: typography.lineHeights.tight,
        };
      case 'subheading':
        return {
          fontWeight: typography.weights.semibold,
          lineHeight: typography.lineHeights.normal,
        };
      case 'body':
        return {
          fontWeight: typography.weights.normal,
          lineHeight: typography.lineHeights.normal,
        };
      case 'caption':
        return {
          fontWeight: typography.weights.normal,
          lineHeight: typography.lineHeights.normal,
          fontSize: typography.sizes.small,
        };
    }
  };

  const getColorValue = () => {
    switch (color) {
      case 'primary':
        return theme.colors.text.primary;
      case 'secondary':
        return theme.colors.text.secondary;
      case 'disabled':
        return theme.colors.text.disabled;
      case 'error':
        return theme.colors.error[500];
      case 'success':
        return theme.colors.success[500];
      case 'warning':
        return theme.colors.warning[500];
      default:
        return typeof color === 'string' ? color : theme.colors.text.primary;
    }
  };

  const textStyles = {
    ...getVariantStyles(),
    fontSize: variant === 'caption' ? typography.sizes.small : typography.sizes[size],
    fontWeight: typography.weights[weight],
    color: getColorValue(),
    textAlign: align,
  };

  return (
    <RNText 
      style={[textStyles, style]}
      accessibilityRole="text"
      {...props}
    >
      {children}
    </RNText>
  );
};
```

## Card Component

Cards are containers that group related content and actions, providing visual boundaries and consistent spacing.

### Card Interface

<Tabs items={["TypeScript Interface", "Usage Examples", "Composition Patterns"]}>
  <Tab>
    ```typescript
    // ui/foundation/Card/types.ts
    import type { ViewProps } from 'react-native';

    export interface CardProps extends ViewProps {
      /**
       * Visual variant
       * @default 'elevated'
       */
      variant?: 'elevated' | 'outlined' | 'filled';
      
      /**
       * Padding size
       * @default 'medium'
       */
      padding?: 'none' | 'small' | 'medium' | 'large' | number;
      
      /**
       * Card content
       */
      children: React.ReactNode;
    }
    ```
  </Tab>

  <Tab>
    ```tsx
    // Basic card
    <Card>
      <Text variant="heading">Card Title</Text>
      <Text>Card content goes here</Text>
    </Card>

    // Outlined variant
    <Card variant="outlined" padding="large">
      <ProductInfo />
    </Card>

    // Filled variant for emphasis
    <Card variant="filled" padding="small">
      <ImportantNotice />
    </Card>

    // Card with custom padding
    <Card padding={24}>
      <CustomContent />
    </Card>

    // Nested cards (use sparingly)
    <Card variant="elevated">
      <Text variant="heading">Parent Card</Text>
      <Card variant="outlined" padding="small">
        <Text>Nested content</Text>
      </Card>
    </Card>
    ```
  </Tab>

  <Tab>
    **Common Card Patterns**

    ```tsx
    // Product card pattern
    <Card variant="elevated">
      <Image source={product.image} />
      <View style={styles.content}>
        <Text variant="heading" size="medium">
          {product.name}
        </Text>
        <Text variant="body" color="secondary">
          {product.description}
        </Text>
        <Text variant="heading" size="small" color="primary">
          ${product.price}
        </Text>
      </View>
    </Card>

    // List item card
    <Card variant="outlined" padding="medium">
      <View style={styles.row}>
        <Avatar source={user.avatar} />
        <View style={styles.info}>
          <Text variant="subheading">{user.name}</Text>
          <Text variant="caption" color="secondary">
            {user.role}
          </Text>
        </View>
        <ChevronRight />
      </View>
    </Card>

    // Stats card
    <Card variant="filled">
      <Text variant="caption" color="secondary">
        Total Revenue
      </Text>
      <Text variant="heading" size="xlarge">
        $24,500
      </Text>
      <Text variant="caption" color="success">
        ↑ 12% from last month
      </Text>
    </Card>
    ```
  </Tab>
</Tabs>

### Card Implementation

```typescript
// ui/foundation/Card/Card.tsx
import React from 'react';
import { View } from 'react-native';
import { theme } from '@/core/shared/styles/theme';
import { shadows } from '@/core/shared/styles/shadows';
import type { CardProps } from './types';

export const Card: React.FC<CardProps> = ({
  variant = 'elevated',
  padding = 'medium',
  children,
  style,
  ...props
}) => {
  const getVariantStyles = () => {
    switch (variant) {
      case 'elevated':
        return {
          backgroundColor: theme.colors.surface,
          ...shadows.medium,
        };
      case 'outlined':
        return {
          backgroundColor: theme.colors.surface,
          borderWidth: 1,
          borderColor: theme.colors.border.default,
        };
      case 'filled':
        return {
          backgroundColor: theme.colors.surface.secondary,
        };
    }
  };

  const getPaddingValue = () => {
    switch (padding) {
      case 'none':
        return 0;
      case 'small':
        return theme.spacing.sm;
      case 'medium':
        return theme.spacing.md;
      case 'large':
        return theme.spacing.lg;
      default:
        return typeof padding === 'number' ? padding : theme.spacing.md;
    }
  };

  const cardStyles = {
    ...getVariantStyles(),
    borderRadius: theme.radii.lg,
    padding: getPaddingValue(),
  };

  return (
    <View 
      style={[cardStyles, style]}
      {...props}
    >
      {children}
    </View>
  );
};
```

## Image Component

The Image component extends React Native's Image with consistent sizing, loading states, and accessibility features.

### Image Interface

```typescript
export interface ImageProps extends RNImageProps {
  /**
   * Image dimensions preset
   * @default 'medium'
   */
  size?: 'small' | 'medium' | 'large' | 'full' | { width: number; height: number };
  
  /**
   * Border radius variant
   * @default 'none'
   */
  rounded?: 'none' | 'small' | 'medium' | 'large' | 'full';
  
  /**
   * Aspect ratio
   */
  aspectRatio?: number;
  
  /**
   * Fallback component for loading/error
   */
  fallback?: React.ReactNode;
  
  /**
   * Alt text for accessibility
   */
  alt: string;
}
```

### Image Best Practices

* Always provide meaningful alt text
* Use consistent sizing presets
* Handle loading and error states
* Optimize image sizes for performance
* Consider lazy loading for lists
* Test on various screen densities

## Icon Component

Icons are essential for visual communication and UI enhancement.

### Icon Interface

```typescript
export interface IconProps {
  /**
   * Icon name from the icon set
   */
  name: string;
  
  /**
   * Icon size
   * @default 24
   */
  size?: number | 'small' | 'medium' | 'large';
  
  /**
   * Icon color
   * @default theme.colors.text.primary
   */
  color?: string;
  
  /**
   * Accessibility label
   */
  accessibilityLabel?: string;
}
```

### Icon Usage Guidelines

* Use semantic names for icons
* Maintain consistent sizing
* Ensure sufficient contrast
* Provide labels for standalone icons
* Group related icons visually
* Consider platform-specific icons

## Badge Component

Badges display small amounts of information, typically numbers or status indicators.

### Badge Interface

```typescript
export interface BadgeProps {
  /**
   * Badge content
   */
  children: React.ReactNode;
  
  /**
   * Visual variant
   * @default 'default'
   */
  variant?: 'default' | 'primary' | 'success' | 'warning' | 'error';
  
  /**
   * Size variant
   * @default 'medium'
   */
  size?: 'small' | 'medium' | 'large';
  
  /**
   * Dot indicator only
   * @default false
   */
  dot?: boolean;
}
```

## Avatar Component

Avatars represent users or entities with images or initials.

### Avatar Interface

```typescript
export interface AvatarProps {
  /**
   * Image source
   */
  source?: ImageSourcePropType;
  
  /**
   * Fallback text (initials)
   */
  name?: string;
  
  /**
   * Size variant
   * @default 'medium'
   */
  size?: 'small' | 'medium' | 'large' | 'xlarge' | number;
  
  /**
   * Shape variant
   * @default 'circle'
   */
  shape?: 'circle' | 'square';
  
  /**
   * Online status indicator
   */
  status?: 'online' | 'offline' | 'away' | 'busy';
}
```

## General Best Practices for Display Components

### Performance Optimization

* Use `React.memo` for components with stable props
* Implement lazy loading for images in lists
* Optimize image assets before bundling
* Cache computed styles with `StyleSheet.create`
* Minimize re-renders with proper prop design

### Accessibility Considerations

* Provide alternative text for all images
* Ensure text has sufficient contrast
* Support Dynamic Type scaling
* Include proper semantic markup
* Test with screen readers

### Testing Display Components

```typescript
describe('Display Component Tests', () => {
  it('renders with correct styles', () => {
    const { getByText } = render(
      <Text variant="heading" color="primary">
        Test Heading
      </Text>
    );
    
    const text = getByText('Test Heading');
    expect(text.props.style).toMatchObject({
      fontSize: typography.sizes.large,
      color: theme.colors.text.primary,
    });
  });
  
  it('applies design tokens correctly', () => {
    const { getByTestId } = render(
      <Card variant="elevated" testID="test-card">
        <Text>Content</Text>
      </Card>
    );
    
    const card = getByTestId('test-card');
    expect(card.props.style).toMatchObject({
      backgroundColor: theme.colors.surface,
      borderRadius: theme.radii.lg,
    });
  });
});
```

## Summary

Display components are the visual building blocks of your application. They should:

* **Be Consistent**: Use design tokens exclusively
* **Be Flexible**: Support common variations and patterns
* **Be Accessible**: Include proper semantics and alternatives
* **Be Performant**: Optimize for smooth rendering
* **Be Testable**: Enable easy visual regression testing

## Next Steps

* Learn about [Design Token Integration](/docs/ui-development/architecture/foundation-guide/design-tokens) for consistent styling
* Explore [Accessibility Patterns](/docs/ui-development/architecture/foundation-guide/accessibility-patterns) for inclusive design
* Review [Testing & Performance](/docs/ui-development/architecture/foundation-guide/testing-performance) optimization strategies

## Related Documents

* [Typography System](/docs/ui-development/styling/typography)
* [Color System](/docs/ui-development/styling/colors)
* [Layout Components](/docs/ui-development/architecture/foundation-guide/layout-components)
* [Component Examples Library](/docs/reference-implementations/ui)


# UTA UI Development: Design Token Integration
URL: https://dev.updatetheapp.com/docs/ui-development/architecture/foundation-guide/design-tokens
Documentation: https://dev.updatetheapp.com/docs/ui-development/architecture/foundation-guide/design-tokens

Deep dive into using design tokens for colors, typography, spacing, and shadows to ensure consistency across your component library.
        
***

title: Design Token Integration
description: Deep dive into using design tokens for colors, typography, spacing, and shadows to ensure consistency across your component library.
-------------------------------------------------------------------------------------------------------------------------------------------------

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Callout } from 'fumadocs-ui/components/callout';

# Design Token Integration

## Overview

Design tokens are the visual atoms of your design system - the smallest pieces of your visual language. They ensure consistency across your entire component library by centralizing design decisions into reusable values.

<Callout type="info">
  **Why Design Tokens Matter**

  Design tokens provide:

  * **Consistency**: Single source of truth for design values
  * **Maintainability**: Update once, changes propagate everywhere
  * **Theming**: Easy switching between light/dark modes
  * **Platform Unity**: Same visual language across iOS and Android
  * **Design-Dev Sync**: Shared vocabulary between designers and developers
</Callout>

## Token Categories

Our design system uses these primary token categories:

1. **Color Tokens**: Brand colors, semantic colors, and surfaces
2. **Typography Tokens**: Font families, sizes, weights, and line heights
3. **Spacing Tokens**: Consistent spacing scale
4. **Radius Tokens**: Border radius values
5. **Shadow Tokens**: Elevation and depth
6. **Motion Tokens**: Animation durations and easings

## Color Token Usage

### Color Token Structure

<Tabs items={["Token Structure", "Implementation", "Best Practices"]}>
  <Tab>
    ```typescript
    // core/shared/styles/theme/colors.ts
    export const colors = {
      // Brand colors
      primary: {
        50: '#e3f2fd',
        100: '#bbdefb',
        200: '#90caf9',
        300: '#64b5f6',
        400: '#42a5f5',
        500: '#2196f3', // Main brand color
        600: '#1e88e5',
        700: '#1976d2',
        800: '#1565c0',
        900: '#0d47a1',
      },
      
      // Semantic colors
      success: {
        light: '#4caf50',
        main: '#2e7d32',
        dark: '#1b5e20',
      },
      
      error: {
        light: '#ef5350',
        main: '#d32f2f',
        dark: '#c62828',
      },
      
      // Text colors
      text: {
        primary: 'rgba(0, 0, 0, 0.87)',
        secondary: 'rgba(0, 0, 0, 0.60)',
        disabled: 'rgba(0, 0, 0, 0.38)',
        inverse: '#ffffff',
      },
      
      // Surface colors
      surface: {
        background: '#f5f5f5',
        paper: '#ffffff',
        elevated: '#ffffff',
      },
      
      // Border colors
      border: {
        default: 'rgba(0, 0, 0, 0.12)',
        focus: '#2196f3',
        error: '#d32f2f',
      },
    };
    ```
  </Tab>

  <Tab>
    ```typescript
    // ✅ Correct: Use semantic color tokens
    const buttonStyles = {
      backgroundColor: theme.colors.primary[500],    // Primary action color
      borderColor: theme.colors.border.default,     // Default border
      color: theme.colors.text.primary,             // Primary text
    };

    // ✅ Correct: Use state-based colors
    const getButtonColor = (state: 'default' | 'hover' | 'pressed') => {
      switch (state) {
        case 'hover':
          return theme.colors.primary[600];
        case 'pressed':
          return theme.colors.primary[700];
        default:
          return theme.colors.primary[500];
      }
    };

    // ❌ Wrong: Hardcoded colors
    const buttonStyles = {
      backgroundColor: '#3b82f6',  // Don't do this
      color: '#000000',            // Use tokens instead
    };

    // Component implementation
    export const Button = ({ variant, ...props }) => {
      const styles = {
        backgroundColor: theme.colors[variant][500],
        color: theme.colors[variant].contrast || theme.colors.text.inverse,
      };
      
      return <TouchableOpacity style={styles} {...props} />;
    };
    ```
  </Tab>

  <Tab>
    **(Do ✅) Color token best practices**

    * Use semantic tokens (primary, error, success) over raw colors
    * Apply opacity through RGBA values, not opacity styles
    * Test color contrast for accessibility (4.5:1 minimum)
    * Use consistent color scales (50-900)
    * Define inverse colors for dark backgrounds
    * Create aliases for common use cases

    **(Don't ❌) Color token mistakes**

    * Never hardcode hex/rgb values in components
    * Don't create one-off color variations
    * Avoid using colors outside the token system
    * Don't mix opacity methods (RGBA vs opacity prop)
    * Never assume color meanings across cultures
    * Don't forget platform-specific color behaviors
  </Tab>
</Tabs>

### Theme-Aware Colors

```typescript
// Support for light/dark themes
const useThemeColors = () => {
  const isDark = useColorScheme() === 'dark';
  
  return {
    background: isDark ? colors.dark.background : colors.light.background,
    text: isDark ? colors.dark.text : colors.light.text,
    surface: isDark ? colors.dark.surface : colors.light.surface,
  };
};

// Component using theme-aware colors
export const ThemedCard = ({ children }) => {
  const colors = useThemeColors();
  
  return (
    <View style={{ backgroundColor: colors.surface }}>
      <Text style={{ color: colors.text }}>{children}</Text>
    </View>
  );
};
```

## Typography Token Usage

### Typography Token Structure

<Tabs items={["Token Structure", "Implementation", "Responsive Typography"]}>
  <Tab>
    ```typescript
    // core/shared/styles/theme/typography.ts
    export const typography = {
      // Font families
      families: {
        regular: 'Inter-Regular',
        medium: 'Inter-Medium',
        semibold: 'Inter-SemiBold',
        bold: 'Inter-Bold',
        mono: 'JetBrainsMono-Regular',
      },
      
      // Font sizes
      sizes: {
        xs: 12,
        sm: 14,
        md: 16,
        lg: 18,
        xl: 20,
        '2xl': 24,
        '3xl': 30,
        '4xl': 36,
      },
      
      // Font weights
      weights: {
        normal: '400',
        medium: '500',
        semibold: '600',
        bold: '700',
      },
      
      // Line heights
      lineHeights: {
        tight: 1.25,
        normal: 1.5,
        relaxed: 1.75,
        loose: 2,
      },
      
      // Letter spacing
      letterSpacing: {
        tight: -0.5,
        normal: 0,
        wide: 0.5,
      },
    };
    ```
  </Tab>

  <Tab>
    ```typescript
    // ✅ Correct: Use typography tokens
    const textStyles = {
      fontSize: typography.sizes.large,
      fontWeight: typography.weights.semibold,
      lineHeight: typography.lineHeights.normal,
      fontFamily: typography.families.regular,
    };

    // ✅ Correct: Create text variants
    const textVariants = {
      heading: {
        fontSize: typography.sizes['2xl'],
        fontWeight: typography.weights.bold,
        lineHeight: typography.lineHeights.tight,
        fontFamily: typography.families.bold,
      },
      body: {
        fontSize: typography.sizes.md,
        fontWeight: typography.weights.normal,
        lineHeight: typography.lineHeights.normal,
        fontFamily: typography.families.regular,
      },
      caption: {
        fontSize: typography.sizes.sm,
        fontWeight: typography.weights.normal,
        lineHeight: typography.lineHeights.normal,
        fontFamily: typography.families.regular,
      },
    };

    // Component implementation
    export const Text = ({ variant = 'body', ...props }) => {
      const styles = textVariants[variant];
      return <RNText style={styles} {...props} />;
    };
    ```
  </Tab>

  <Tab>
    ```typescript
    // Responsive typography with scaling
    import { PixelRatio } from 'react-native';

    const scaleFont = (size: number) => {
      const scale = PixelRatio.getFontScale();
      return size * scale;
    };

    // Create responsive variants
    const responsiveTypography = {
      sizes: Object.entries(typography.sizes).reduce(
        (acc, [key, value]) => ({
          ...acc,
          [key]: scaleFont(value),
        }),
        {}
      ),
    };

    // Dynamic type support
    const useDynamicType = () => {
      const [fontScale, setFontScale] = useState(1);
      
      useEffect(() => {
        const updateScale = () => {
          setFontScale(PixelRatio.getFontScale());
        };
        
        const subscription = AccessibilityInfo.addEventListener(
          'change',
          updateScale
        );
        
        return () => subscription.remove();
      }, []);
      
      return fontScale;
    };
    ```
  </Tab>
</Tabs>

## Spacing Token Usage

### Spacing Scale

<Tabs items={["Token Structure", "Implementation", "Layout Patterns"]}>
  <Tab>
    ```typescript
    // core/shared/styles/theme/spacing.ts
    export const spacing = {
      // Base unit: 4px
      xxs: 2,   // 2px
      xs: 4,    // 4px - base unit
      sm: 8,    // 8px
      md: 16,   // 16px - default
      lg: 24,   // 24px
      xl: 32,   // 32px
      '2xl': 48, // 48px
      '3xl': 64, // 64px
      '4xl': 80, // 80px
    };

    // Semantic spacing
    export const semanticSpacing = {
      // Component spacing
      componentPadding: {
        small: spacing.sm,
        medium: spacing.md,
        large: spacing.lg,
      },
      
      // Layout spacing
      layoutMargin: {
        small: spacing.sm,
        medium: spacing.md,
        large: spacing.xl,
      },
      
      // Grid spacing
      gridGap: {
        small: spacing.xs,
        medium: spacing.sm,
        large: spacing.md,
      },
    };
    ```
  </Tab>

  <Tab>
    ```typescript
    // ✅ Correct: Use spacing tokens
    const layoutStyles = {
      padding: theme.spacing.md,
      marginVertical: theme.spacing.lg,
      gap: theme.spacing.sm,
    };

    // ✅ Correct: Responsive spacing
    const getSpacing = (size: 'compact' | 'comfortable' | 'spacious') => {
      switch (size) {
        case 'compact':
          return theme.spacing.sm;
        case 'spacious':
          return theme.spacing.xl;
        default:
          return theme.spacing.md;
      }
    };

    // ✅ Correct: Consistent spacing in lists
    const ListItem = ({ children, last }) => (
      <View
        style={{
          paddingVertical: theme.spacing.sm,
          paddingHorizontal: theme.spacing.md,
          marginBottom: last ? 0 : theme.spacing.xs,
        }}
      >
        {children}
      </View>
    );

    // ❌ Wrong: Hardcoded spacing
    const badStyles = {
      padding: 16,        // Use tokens
      margin: '12px',     // No strings
      gap: 8,            // Use consistent scale
    };
    ```
  </Tab>

  <Tab>
    ```typescript
    // Common layout patterns with spacing

    // Card layout
    const CardLayout = ({ children }) => (
      <View style={{
        padding: theme.spacing.md,
        borderRadius: theme.radii.md,
      }}>
        {children}
      </View>
    );

    // Form layout
    const FormLayout = ({ children }) => (
      <View style={{
        padding: theme.spacing.lg,
        gap: theme.spacing.md,
      }}>
        {children}
      </View>
    );

    // Section layout
    const SectionLayout = ({ title, children }) => (
      <View>
        <Text style={{ marginBottom: theme.spacing.sm }}>
          {title}
        </Text>
        <View style={{ gap: theme.spacing.xs }}>
          {children}
        </View>
      </View>
    );

    // Grid layout helper
    const createGrid = (columns: number, gap: number = theme.spacing.sm) => ({
      flexDirection: 'row',
      flexWrap: 'wrap',
      marginHorizontal: -gap / 2,
      marginVertical: -gap / 2,
    });
    ```
  </Tab>
</Tabs>

## Radius Token Usage

```typescript
// Border radius tokens
export const radii = {
  none: 0,
  sm: 4,
  md: 8,
  lg: 12,
  xl: 16,
  full: 9999, // For circular elements
};

// Usage in components
const cardStyles = {
  borderRadius: theme.radii.lg,
};

const avatarStyles = {
  borderRadius: theme.radii.full,
};

const chipStyles = {
  borderRadius: theme.radii.full,
};
```

## Shadow Token Usage

<Tabs items={["Token Structure", "Platform Implementation", "Elevation System"]}>
  <Tab>
    ```typescript
    // core/shared/styles/theme/shadows.ts
    export const shadows = {
      // Elevation levels
      none: {
        shadowColor: 'transparent',
        shadowOffset: { width: 0, height: 0 },
        shadowOpacity: 0,
        shadowRadius: 0,
        elevation: 0,
      },
      
      sm: {
        shadowColor: '#000',
        shadowOffset: { width: 0, height: 1 },
        shadowOpacity: 0.05,
        shadowRadius: 2,
        elevation: 2,
      },
      
      md: {
        shadowColor: '#000',
        shadowOffset: { width: 0, height: 2 },
        shadowOpacity: 0.1,
        shadowRadius: 4,
        elevation: 4,
      },
      
      lg: {
        shadowColor: '#000',
        shadowOffset: { width: 0, height: 4 },
        shadowOpacity: 0.15,
        shadowRadius: 8,
        elevation: 8,
      },
      
      xl: {
        shadowColor: '#000',
        shadowOffset: { width: 0, height: 8 },
        shadowOpacity: 0.2,
        shadowRadius: 16,
        elevation: 16,
      },
    };
    ```
  </Tab>

  <Tab>
    ```typescript
    import { Platform } from 'react-native';

    // Platform-aware shadow implementation
    const getShadow = (elevation: keyof typeof shadows) => {
      const shadow = shadows[elevation];
      
      if (Platform.OS === 'android') {
        return {
          elevation: shadow.elevation,
        };
      }
      
      return {
        shadowColor: shadow.shadowColor,
        shadowOffset: shadow.shadowOffset,
        shadowOpacity: shadow.shadowOpacity,
        shadowRadius: shadow.shadowRadius,
      };
    };

    // Component with shadows
    export const ElevatedCard = ({ elevation = 'md', children }) => (
      <View style={[
        styles.card,
        getShadow(elevation),
      ]}>
        {children}
      </View>
    );

    // Dynamic elevation
    export const InteractiveCard = ({ children }) => {
      const [pressed, setPressed] = useState(false);
      
      return (
        <Pressable
          onPressIn={() => setPressed(true)}
          onPressOut={() => setPressed(false)}
          style={[
            styles.card,
            getShadow(pressed ? 'sm' : 'md'),
          ]}
        >
          {children}
        </Pressable>
      );
    };
    ```
  </Tab>

  <Tab>
    ```typescript
    // Elevation system for depth hierarchy
    const elevationSystem = {
      // Ground level - no elevation
      ground: shadows.none,
      
      // Raised elements - slight elevation
      raised: shadows.sm,
      
      // Floating elements - medium elevation
      floating: shadows.md,
      
      // Modal/overlay - high elevation
      modal: shadows.lg,
      
      // Popover/tooltip - highest elevation
      popover: shadows.xl,
    };

    // Usage examples
    const ComponentElevation = {
      Button: elevationSystem.raised,
      Card: elevationSystem.floating,
      Modal: elevationSystem.modal,
      Dropdown: elevationSystem.popover,
      BottomSheet: elevationSystem.modal,
      FAB: elevationSystem.floating,
    };

    // Elevation context
    const ElevationContext = createContext('ground');

    export const ElevationProvider = ({ level, children }) => (
      <ElevationContext.Provider value={level}>
        {children}
      </ElevationContext.Provider>
    );
    ```
  </Tab>
</Tabs>

## Token Organization Best Practices

### File Structure

```
core/shared/styles/
├── theme/
│   ├── index.ts          # Main theme export
│   ├── colors.ts         # Color tokens
│   ├── typography.ts     # Typography tokens
│   ├── spacing.ts        # Spacing scale
│   ├── shadows.ts        # Shadow/elevation tokens
│   ├── radii.ts         # Border radius tokens
│   └── motion.ts        # Animation tokens
├── tokens.ts            # Token type definitions
└── utils.ts            # Token utilities
```

### Creating Custom Tokens

```typescript
// Extend existing tokens
const customColors = {
  ...theme.colors,
  brand: {
    primary: '#FF6B6B',
    secondary: '#4ECDC4',
  },
};

// Create semantic aliases
const semanticColors = {
  interactive: {
    default: theme.colors.primary[500],
    hover: theme.colors.primary[600],
    pressed: theme.colors.primary[700],
    disabled: theme.colors.gray[300],
  },
};

// Component-specific tokens
const buttonTokens = {
  sizes: {
    small: {
      padding: theme.spacing.sm,
      fontSize: theme.typography.sizes.sm,
    },
    medium: {
      padding: theme.spacing.md,
      fontSize: theme.typography.sizes.md,
    },
    large: {
      padding: theme.spacing.lg,
      fontSize: theme.typography.sizes.lg,
    },
  },
};
```

## Token Validation

```typescript
// Validate token usage in development
const validateToken = (value: any, tokenType: string) => {
  if (__DEV__) {
    const validTokens = Object.values(theme[tokenType]);
    if (!validTokens.includes(value)) {
      console.warn(
        `Invalid ${tokenType} token: ${value}. Use one of:`,
        validTokens
      );
    }
  }
  return value;
};

// Type-safe token access
const getToken = <T extends keyof typeof theme>(
  tokenType: T,
  tokenName: keyof typeof theme[T]
): typeof theme[T][keyof typeof theme[T]] => {
  return theme[tokenType][tokenName];
};
```

## Summary

Design tokens are the foundation of a consistent design system. By using them properly:

* **Maintain Consistency**: Every component uses the same visual language
* **Enable Theming**: Switch themes by changing token values
* **Improve Maintainability**: Update design decisions in one place
* **Enhance Developer Experience**: Clear, predictable values
* **Support Accessibility**: Built-in support for dynamic type and high contrast

Remember: If you find yourself hardcoding a value, there should be a token for it!

## Next Steps

* Review [Accessibility Patterns](/docs/ui-development/architecture/foundation-guide/accessibility-patterns) for inclusive design
* Explore [Testing & Performance](/docs/ui-development/architecture/foundation-guide/testing-performance) with tokens
* Learn about [AI Collaboration](/docs/ui-development/architecture/foundation-guide/ai-collaboration-docs) for token usage

## Related Documents

* [Theme Management](/docs/ui-development/theme-management) - Complete theming guide
* [Color System](/docs/ui-development/styling/colors) - Color theory and usage
* [Typography System](/docs/ui-development/styling/typography) - Type scale and usage
* [Spacing System](/docs/ui-development/styling/spacing) - Layout and spacing guide


# UTA UI Development: Accessibility Patterns
URL: https://dev.updatetheapp.com/docs/ui-development/architecture/foundation-guide/accessibility-patterns
Documentation: https://dev.updatetheapp.com/docs/ui-development/architecture/foundation-guide/accessibility-patterns

Comprehensive accessibility implementation including roles, states, focus management, and testing strategies for inclusive component design.
        
***

title: Accessibility Patterns
description: Comprehensive accessibility implementation including roles, states, focus management, and testing strategies for inclusive component design.
---------------------------------------------------------------------------------------------------------------------------------------------------------

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Callout } from 'fumadocs-ui/components/callout';
import { Steps, Step } from 'fumadocs-ui/components/steps';

# Accessibility Patterns

## Overview

Accessibility ensures that all users, regardless of their abilities, can effectively use your application. React Native provides built-in accessibility features that, when properly implemented, create inclusive experiences for users with visual, motor, or cognitive disabilities.

<Callout type="info">
  **Accessibility is Not Optional**

  Making your components accessible:

  * **Expands your user base** to include users with disabilities
  * **Improves usability** for all users in various contexts
  * **Ensures legal compliance** with accessibility regulations
  * **Demonstrates social responsibility** and inclusive design
  * **Often improves** overall app quality and structure
</Callout>

## Core Accessibility Concepts

### The Accessibility Tree

React Native creates an accessibility tree parallel to the view hierarchy. Screen readers and other assistive technologies use this tree to understand and interact with your app.

```typescript
// Regular view tree
<View>
  <Text>Hello</Text>
  <Button onPress={handlePress}>Click me</Button>
</View>

// Accessibility tree representation
<group>
  <text>Hello</text>
  <button>Click me</button>
</group>
```

### Platform Differences

<Tabs items={["iOS (VoiceOver)", "Android (TalkBack)", "Cross-Platform"]}>
  <Tab>
    **iOS VoiceOver Specifics**

    * Gestures: Swipe to navigate, double-tap to activate
    * Rotor: Two-finger rotation to change navigation mode
    * Magic Tap: Two-finger double-tap for primary action
    * Escape: Two-finger Z gesture to go back

    ```typescript
    // iOS-specific accessibility
    <View
      accessibilityRole="button"
      accessibilityLabel="Save document"
      accessibilityHint="Double tap to save your changes"
      accessibilityActions={[
        { name: 'magicTap', label: 'Quick save' }
      ]}
      onAccessibilityAction={(event) => {
        if (event.actionName === 'magicTap') {
          quickSave();
        }
      }}
    />
    ```
  </Tab>

  <Tab>
    **Android TalkBack Specifics**

    * Gestures: Swipe to navigate, double-tap to activate
    * Reading controls: Swipe up/down to change reading granularity
    * Local gestures: Draw L-shape for local menu
    * Global gestures: Draw specific shapes for global actions

    ```typescript
    // Android-specific accessibility
    <View
      accessibilityRole="button"
      accessibilityLabel="Save document"
      accessibilityHint="Double tap to save your changes"
      importantForAccessibility="yes"
      accessibilityLiveRegion="polite"
    />
    ```
  </Tab>

  <Tab>
    **Cross-Platform Best Practices**

    ```typescript
    // Works well on both platforms
    <TouchableOpacity
      accessibilityRole="button"
      accessibilityLabel="Save"
      accessibilityHint="Saves your current changes"
      accessibilityState={{
        disabled: isLoading,
        busy: isLoading,
      }}
      onPress={handleSave}
      disabled={isLoading}
    >
      <Text>Save</Text>
    </TouchableOpacity>
    ```
  </Tab>
</Tabs>

## Required Accessibility Features

Every foundation component must implement these accessibility features:

### 1. Semantic Roles

<Tabs items={["Basic Roles", "Complex Roles", "Custom Roles"]}>
  <Tab>
    ```typescript
    // Button component
    <TouchableOpacity
      accessibilityRole="button"
      accessibilityLabel="Save changes"
      accessibilityHint="Saves your current changes to the profile"
    >

    // Text Input component
    <TextInput
      accessibilityRole="text"
      accessibilityLabel="Email address"
      accessibilityHint="Enter your email address for account recovery"
    >

    // Image component
    <Image
      accessibilityRole="image"
      accessibilityLabel="User profile photo"
      alt="Profile photo of John Smith"
    >

    // Link component
    <TouchableOpacity
      accessibilityRole="link"
      accessibilityLabel="Terms of Service"
      accessibilityHint="Opens terms of service in browser"
    >
    ```
  </Tab>

  <Tab>
    ```typescript
    // Header
    <View accessibilityRole="header">
      <Text>Settings</Text>
    </View>

    // Navigation
    <View accessibilityRole="tabbar">
      <Tab accessibilityRole="tab" />
    </View>

    // List
    <FlatList
      accessibilityRole="list"
      renderItem={({ item }) => (
        <View accessibilityRole="listitem">
          {item.content}
        </View>
      )}
    />

    // Progress indicator
    <View
      accessibilityRole="progressbar"
      accessibilityValue={{
        min: 0,
        max: 100,
        now: progress,
        text: `${progress}% complete`
      }}
    />
    ```
  </Tab>

  <Tab>
    ```typescript
    // Custom component roles
    export const CustomSwitch = ({ value, onValueChange }) => (
      <TouchableOpacity
        accessibilityRole="switch"
        accessibilityState={{ checked: value }}
        accessibilityLabel="Enable notifications"
        accessibilityValue={{ text: value ? 'On' : 'Off' }}
        onPress={() => onValueChange(!value)}
      >
        {/* Custom switch implementation */}
      </TouchableOpacity>
    );

    // Composite components
    export const SearchBar = ({ value, onChangeText }) => (
      <View
        accessibilityRole="search"
        accessible={true}
        accessibilityLabel="Search products"
      >
        <TextInput
          value={value}
          onChangeText={onChangeText}
          placeholder="Search..."
        />
        <TouchableOpacity
          accessibilityRole="button"
          accessibilityLabel="Clear search"
        >
          <Icon name="close" />
        </TouchableOpacity>
      </View>
    );
    ```
  </Tab>
</Tabs>

### 2. State Communication

```typescript
// Button states
<TouchableOpacity
  accessibilityState={{
    disabled: isDisabled,
    busy: isLoading,
    selected: isSelected,
  }}
>

// Input states
<TextInput
  accessibilityState={{
    disabled: isDisabled,
    invalid: hasError,
  }}
>

// Expandable states
<TouchableOpacity
  accessibilityState={{
    expanded: isExpanded,
  }}
  accessibilityLabel={`Settings menu ${isExpanded ? 'expanded' : 'collapsed'}`}
>

// Multi-state components
<View
  accessibilityState={{
    checked: isChecked,
    disabled: isDisabled,
    busy: isProcessing,
  }}
>
```

### 3. Dynamic Content

<Tabs items={["Live Regions", "Announcements", "Loading States"]}>
  <Tab>
    ```typescript
    // Live region for dynamic updates
    <View accessibilityLiveRegion="polite">
      <Text>{searchResultCount} results found</Text>
    </View>

    // Assertive announcements for urgent updates
    <View accessibilityLiveRegion="assertive">
      <Text>Error: Invalid email address</Text>
    </View>

    // None for decorative content
    <View accessibilityLiveRegion="none">
      <AnimatedBackground />
    </View>
    ```
  </Tab>

  <Tab>
    ```typescript
    import { AccessibilityInfo } from 'react-native';

    // Announce messages to screen readers
    const announceMessage = (message: string) => {
      AccessibilityInfo.announceForAccessibility(message);
    };

    // Example usage
    const handleSubmit = async () => {
      try {
        await submitForm();
        announceMessage('Form submitted successfully');
      } catch (error) {
        announceMessage(`Error: ${error.message}`);
      }
    };

    // Delayed announcements
    const handleDelete = () => {
      deleteItem();
      setTimeout(() => {
        announceMessage('Item deleted');
      }, 300);
    };
    ```
  </Tab>

  <Tab>
    ```typescript
    // Loading states
    {isLoading && (
      <View
        accessibilityRole="progressbar"
        accessibilityLabel="Loading content"
        accessibilityValue={{ 
          now: progress, 
          min: 0, 
          max: 100 
        }}
      >
        <ActivityIndicator />
      </View>
    )}

    // Error states
    {error && (
      <Text
        accessibilityRole="alert"
        accessibilityLiveRegion="assertive"
      >
        {error}
      </Text>
    )}

    // Success states
    {success && (
      <View
        accessibilityLiveRegion="polite"
        accessible={true}
      >
        <Icon name="check" accessibilityLabel="Success" />
        <Text>Operation completed</Text>
      </View>
    )}
    ```
  </Tab>
</Tabs>

## Focus Management

### Focus Control

<Steps>
  <Step>
    #### Programmatic Focus

    ```typescript
    import { findNodeHandle, AccessibilityInfo } from 'react-native';

    const MyComponent = () => {
      const inputRef = useRef(null);
      
      const focusInput = () => {
        const handle = findNodeHandle(inputRef.current);
        if (handle) {
          AccessibilityInfo.setAccessibilityFocus(handle);
        }
      };
      
      return (
        <View>
          <Button onPress={focusInput} title="Focus input" />
          <TextInput ref={inputRef} />
        </View>
      );
    };
    ```
  </Step>

  <Step>
    #### Focus Order

    ```typescript
    // Control tab order with accessibilityViewIsModal
    <Modal>
      <View accessibilityViewIsModal={true}>
        {/* Focus trapped within modal */}
        <TextInput accessibilityLabel="Name" />
        <TextInput accessibilityLabel="Email" />
        <Button title="Submit" />
      </View>
    </Modal>

    // Group related elements
    <View accessible={true} accessibilityLabel="User information">
      <Text>John Doe</Text>
      <Text>john@example.com</Text>
    </View>
    ```
  </Step>

  <Step>
    #### Focus Restoration

    ```typescript
    const MyList = () => {
      const [items, setItems] = useState([...]);
      const focusedItemRef = useRef(null);
      
      const deleteItem = (index: number) => {
        // Store reference to next item
        if (index < items.length - 1) {
          focusedItemRef.current = items[index + 1].id;
        }
        
        setItems(items.filter((_, i) => i !== index));
      };
      
      useEffect(() => {
        // Restore focus after deletion
        if (focusedItemRef.current) {
          const handle = findNodeHandle(refs[focusedItemRef.current]);
          AccessibilityInfo.setAccessibilityFocus(handle);
          focusedItemRef.current = null;
        }
      }, [items]);
    };
    ```
  </Step>
</Steps>

## Accessibility Testing

### Testing Patterns

<Tabs items={["Unit Tests", "Integration Tests", "Manual Testing"]}>
  <Tab>
    ```typescript
    // ui/foundation/Button/Button.test.tsx
    import { render, fireEvent } from '@testing-library/react-native';
    import { Button } from './Button';

    describe('Button Accessibility', () => {
      it('has correct accessibility role', () => {
        const { getByRole } = render(<Button>Test</Button>);
        expect(getByRole('button')).toBeTruthy();
      });

      it('communicates disabled state', () => {
        const { getByRole } = render(<Button disabled>Test</Button>);
        const button = getByRole('button');
        expect(button.props.accessibilityState.disabled).toBe(true);
      });

      it('communicates loading state', () => {
        const { getByRole } = render(<Button loading>Test</Button>);
        const button = getByRole('button');
        expect(button.props.accessibilityState.busy).toBe(true);
      });

      it('has accessible label', () => {
        const { getByLabelText } = render(
          <Button accessibilityLabel="Save changes">Save</Button>
        );
        expect(getByLabelText('Save changes')).toBeTruthy();
      });
      
      it('provides hint for complex actions', () => {
        const { getByRole } = render(
          <Button 
            accessibilityHint="Double tap to save all changes"
          >
            Save All
          </Button>
        );
        const button = getByRole('button');
        expect(button.props.accessibilityHint).toBe(
          'Double tap to save all changes'
        );
      });
    });
    ```
  </Tab>

  <Tab>
    ```typescript
    // Test accessibility in context
    describe('Form Accessibility', () => {
      it('announces validation errors', async () => {
        const announceForAccessibility = jest.spyOn(
          AccessibilityInfo,
          'announceForAccessibility'
        );
        
        const { getByLabelText, getByRole } = render(<LoginForm />);
        
        // Submit with invalid data
        fireEvent.press(getByRole('button', { name: 'Login' }));
        
        await waitFor(() => {
          expect(announceForAccessibility).toHaveBeenCalledWith(
            'Error: Please enter a valid email address'
          );
        });
      });
      
      it('maintains focus after error', async () => {
        const setAccessibilityFocus = jest.spyOn(
          AccessibilityInfo,
          'setAccessibilityFocus'
        );
        
        const { getByLabelText } = render(<LoginForm />);
        const emailInput = getByLabelText('Email');
        
        // Trigger validation error
        fireEvent.changeText(emailInput, 'invalid');
        fireEvent.blur(emailInput);
        
        expect(setAccessibilityFocus).toHaveBeenCalled();
      });
    });
    ```
  </Tab>

  <Tab>
    **Manual Testing Checklist**

    **Screen Reader Testing**

    * [ ] Enable VoiceOver (iOS) or TalkBack (Android)
    * [ ] Navigate using swipe gestures only
    * [ ] Verify all content is announced
    * [ ] Check announcement order is logical
    * [ ] Test all interactive elements
    * [ ] Verify state changes are announced

    **Keyboard Testing** (External keyboard)

    * [ ] Tab through all interactive elements
    * [ ] Verify focus indicators are visible
    * [ ] Test Enter/Space activation
    * [ ] Check Escape key handling
    * [ ] Verify no keyboard traps

    **Visual Testing**

    * [ ] Test with increased text size (200%)
    * [ ] Verify color contrast ratios
    * [ ] Check focus indicators contrast
    * [ ] Test with color filters
    * [ ] Verify no color-only information

    **Motion Testing**

    * [ ] Test with reduced motion enabled
    * [ ] Verify no essential information in animations
    * [ ] Check for motion alternatives
  </Tab>
</Tabs>

## Component-Specific Patterns

### Form Components

```typescript
// Accessible form field
export const FormField = ({ label, error, ...props }) => {
  const inputId = useId();
  const errorId = useId();
  
  return (
    <View>
      <Text nativeID={inputId}>{label}</Text>
      <TextInput
        accessibilityLabel={label}
        accessibilityLabelledBy={inputId}
        accessibilityDescribedBy={error ? errorId : undefined}
        accessibilityState={{ invalid: !!error }}
        {...props}
      />
      {error && (
        <Text
          nativeID={errorId}
          accessibilityRole="alert"
          accessibilityLiveRegion="assertive"
          style={styles.error}
        >
          {error}
        </Text>
      )}
    </View>
  );
};
```

### List Components

```typescript
// Accessible list with actions
export const AccessibleList = ({ items, onDelete }) => {
  return (
    <FlatList
      accessibilityRole="list"
      data={items}
      renderItem={({ item, index }) => (
        <View
          accessibilityRole="listitem"
          accessible={true}
          accessibilityLabel={`${item.name}, ${index + 1} of ${items.length}`}
          accessibilityActions={[
            { name: 'delete', label: 'Delete item' }
          ]}
          onAccessibilityAction={(event) => {
            if (event.actionName === 'delete') {
              onDelete(item.id);
            }
          }}
        >
          <Text>{item.name}</Text>
        </View>
      )}
    />
  );
};
```

### Modal Components

```typescript
// Accessible modal
export const AccessibleModal = ({ visible, onClose, children }) => {
  const previousFocusRef = useRef(null);
  
  useEffect(() => {
    if (visible) {
      // Store current focus
      previousFocusRef.current = findNodeHandle(
        AccessibilityInfo.currentlyFocusedField()
      );
    } else if (previousFocusRef.current) {
      // Restore focus when closing
      AccessibilityInfo.setAccessibilityFocus(previousFocusRef.current);
    }
  }, [visible]);
  
  return (
    <Modal
      visible={visible}
      onRequestClose={onClose}
      accessible={true}
      accessibilityViewIsModal={true}
    >
      <View>
        <View accessible={true} accessibilityRole="header">
          <Text>Modal Title</Text>
          <TouchableOpacity
            accessibilityRole="button"
            accessibilityLabel="Close modal"
            onPress={onClose}
          >
            <Icon name="close" />
          </TouchableOpacity>
        </View>
        {children}
      </View>
    </Modal>
  );
};
```

## Best Practices Summary

<Callout type="success">
  **Accessibility Excellence**

  Remember these key principles:

  * **Test with real assistive technologies** - Simulators aren't enough
  * **Provide context** - Labels should make sense out of context
  * **Be consistent** - Similar elements should behave similarly
  * **Avoid redundancy** - Don't repeat visual information
  * **Design for everyone** - Accessibility benefits all users
</Callout>

<Tabs items={["Do's", "Don'ts", "Quick Wins"]}>
  <Tab>
    **(Do ✅) Accessibility best practices**

    * Always provide `accessibilityLabel` for interactive elements
    * Use semantic `accessibilityRole` values
    * Communicate state changes with `accessibilityState`
    * Test with actual screen readers on devices
    * Provide hints for complex interactions
    * Group related content with `accessible={true}`
    * Use `accessibilityLiveRegion` for dynamic content
    * Maintain logical focus order
    * Provide text alternatives for images
    * Ensure sufficient color contrast (4.5:1 minimum)
  </Tab>

  <Tab>
    **(Don't ❌) Common accessibility mistakes**

    * Don't rely on placeholder text as labels
    * Don't use color as the only indicator
    * Don't create keyboard traps
    * Don't auto-focus without user action
    * Don't ignore platform differences
    * Don't skip accessibility testing
    * Don't make assumptions about user abilities
    * Don't use vague labels like "Click here"
    * Don't forget loading and error states
    * Don't break native accessibility features
  </Tab>

  <Tab>
    **Quick Accessibility Wins**

    1. **Add labels to all buttons**
       ```tsx
       accessibilityLabel="Save document"
       ```

    2. **Group related content**
       ```tsx
       accessible={true}
       accessibilityLabel="User: John Doe, Admin"
       ```

    3. **Announce dynamic changes**
       ```tsx
       AccessibilityInfo.announceForAccessibility('Saved')
       ```

    4. **Hide decorative elements**
       ```tsx
       accessible={false}
       importantForAccessibility="no"
       ```

    5. **Use semantic HTML roles**
       ```tsx
       accessibilityRole="header"
       accessibilityRole="button"
       ```
  </Tab>
</Tabs>

## Next Steps

* Implement [Testing & Performance](/docs/ui-development/architecture/foundation-guide/testing-performance) strategies
* Review [AI Collaboration](/docs/ui-development/architecture/foundation-guide/ai-collaboration-docs) for accessibility
* Explore platform-specific [Accessibility APIs](https://reactnative.dev/docs/accessibility)

## Related Documents

* [WCAG 2.1 Guidelines](https://www.w3.org/WAI/WCAG21/quickref/)
* [React Native Accessibility Docs](https://reactnative.dev/docs/accessibility)
* [iOS Accessibility Guidelines](https://developer.apple.com/accessibility/)
* [Android Accessibility Guidelines](https://developer.android.com/guide/topics/ui/accessibility)


# UTA UI Development: Testing & Performance
URL: https://dev.updatetheapp.com/docs/ui-development/architecture/foundation-guide/testing-performance
Documentation: https://dev.updatetheapp.com/docs/ui-development/architecture/foundation-guide/testing-performance

Testing strategies, visual regression, performance optimization, and memoization patterns for reliable foundation components.
        
***

title: Testing & Performance
description: Testing strategies, visual regression, performance optimization, and memoization patterns for reliable foundation components.
------------------------------------------------------------------------------------------------------------------------------------------

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Callout } from 'fumadocs-ui/components/callout';
import { Steps, Step } from 'fumadocs-ui/components/steps';

# Testing & Performance

## Overview

Robust testing and performance optimization are critical for building reliable, fast foundation components. This guide covers comprehensive testing strategies and performance patterns that ensure your components meet quality standards and provide excellent user experiences.

<Callout type="info">
  **Quality and Speed Matter**

  Well-tested and performant components:

  * **Reduce bugs** through comprehensive test coverage
  * **Improve user experience** with fast, responsive interfaces
  * **Enable confident refactoring** with regression protection
  * **Lower maintenance costs** through early issue detection
  * **Scale better** as your application grows
</Callout>

## Testing Strategies

### Component Testing Structure

Foundation components require comprehensive testing to ensure reliability and accessibility. Here's a complete testing structure:

<Tabs items={["Test Organization", "Test Setup", "Coverage Requirements"]}>
  <Tab>
    ```
    ui/foundation/Button/
    ├── Button.tsx              # Component implementation
    ├── Button.test.tsx         # Unit tests
    ├── Button.visual.test.tsx  # Visual regression tests
    ├── Button.perf.test.tsx    # Performance tests
    └── __snapshots__/          # Snapshot files
    ```

    **Test File Organization**

    ```typescript
    // Button.test.tsx structure
    describe('Button Component', () => {
      // Rendering tests
      describe('Rendering', () => {
        it('renders with default props', () => {});
        it('renders all variants correctly', () => {});
      });
      
      // Interaction tests
      describe('Interactions', () => {
        it('handles press events', () => {});
        it('prevents interaction when disabled', () => {});
      });
      
      // State tests
      describe('States', () => {
        it('shows loading state', () => {});
        it('communicates disabled state', () => {});
      });
      
      // Accessibility tests
      describe('Accessibility', () => {
        it('has proper role and labels', () => {});
        it('announces state changes', () => {});
      });
    });
    ```
  </Tab>

  <Tab>
    ```typescript
    // test-utils/setup.ts
    import '@testing-library/jest-native/extend-expect';
    import { ReactTestInstance } from 'react-test-renderer';

    // Mock native modules
    jest.mock('react-native/Libraries/Animated/NativeAnimatedHelper');

    // Custom render with providers
    export const renderWithProviders = (
      ui: React.ReactElement,
      options?: RenderOptions
    ) => {
      const Wrapper = ({ children }) => (
        <ThemeProvider>
          <SafeAreaProvider>
            {children}
          </SafeAreaProvider>
        </ThemeProvider>
      );
      
      return render(ui, { wrapper: Wrapper, ...options });
    };

    // Custom matchers
    expect.extend({
      toHaveDesignToken(received: ReactTestInstance, token: string) {
        const hasToken = received.props.style?.includes(theme[token]);
        return {
          pass: hasToken,
          message: () => 
            `Expected component to ${hasToken ? 'not ' : ''}use design token ${token}`,
        };
      },
    });
    ```
  </Tab>

  <Tab>
    **Coverage Targets by Component Type**

    | Component Type | Statement | Branch | Function | Line |
    | -------------- | --------- | ------ | -------- | ---- |
    | Foundation     | 90%+      | 85%+   | 90%+     | 90%+ |
    | Pattern        | 85%+      | 80%+   | 85%+     | 85%+ |
    | Business       | 80%+      | 75%+   | 80%+     | 80%+ |

    **Critical Areas Requiring 100% Coverage**

    * Accessibility features
    * Error boundaries
    * State management logic
    * Event handlers
    * Conditional rendering

    ```json
    // jest.config.js coverage configuration
    {
      "coverageThreshold": {
        "global": {
          "branches": 80,
          "functions": 80,
          "lines": 80,
          "statements": 80
        },
        "ui/foundation/**": {
          "branches": 85,
          "functions": 90,
          "lines": 90,
          "statements": 90
        }
      }
    }
    ```
  </Tab>
</Tabs>

### Unit Testing Patterns

<Tabs items={["Rendering Tests", "Interaction Tests", "State Tests"]}>
  <Tab>
    ```typescript
    import { render } from '@testing-library/react-native';
    import { Button } from './Button';
    import { theme } from '@/core/shared/styles/theme';

    describe('Button Rendering', () => {
      it('renders with required props', () => {
        const { getByText } = render(
          <Button onPress={jest.fn()}>Click me</Button>
        );
        
        expect(getByText('Click me')).toBeTruthy();
      });
      
      it('applies correct variant styles', () => {
        const variants = ['primary', 'secondary', 'ghost', 'danger'] as const;
        
        variants.forEach(variant => {
          const { getByTestId, unmount } = render(
            <Button variant={variant} testID={`button-${variant}`}>
              Test
            </Button>
          );
          
          const button = getByTestId(`button-${variant}`);
          expect(button.props.style).toMatchObject({
            backgroundColor: theme.colors[variant][500],
          });
          
          unmount();
        });
      });
      
      it('renders with icons', () => {
        const Icon = () => <Text>Icon</Text>;
        const { getByText } = render(
          <Button icon={<Icon />} iconRight={<Icon />}>
            Content
          </Button>
        );
        
        expect(getByText('Content')).toBeTruthy();
        expect(getAllByText('Icon')).toHaveLength(2);
      });
      
      it('applies size variations correctly', () => {
        const sizes = {
          small: theme.spacing.sm,
          medium: theme.spacing.md,
          large: theme.spacing.lg,
        };
        
        Object.entries(sizes).forEach(([size, padding]) => {
          const { getByTestId } = render(
            <Button size={size} testID={`button-${size}`}>
              Test
            </Button>
          );
          
          expect(getByTestId(`button-${size}`).props.style).toMatchObject({
            padding,
          });
        });
      });
    });
    ```
  </Tab>

  <Tab>
    ```typescript
    import { render, fireEvent, waitFor } from '@testing-library/react-native';
    import { Button } from './Button';

    describe('Button Interactions', () => {
      it('calls onPress when pressed', () => {
        const onPress = jest.fn();
        const { getByText } = render(
          <Button onPress={onPress}>Press me</Button>
        );
        
        fireEvent.press(getByText('Press me'));
        expect(onPress).toHaveBeenCalledTimes(1);
      });
      
      it('prevents interaction when disabled', () => {
        const onPress = jest.fn();
        const { getByText } = render(
          <Button onPress={onPress} disabled>
            Disabled
          </Button>
        );
        
        fireEvent.press(getByText('Disabled'));
        expect(onPress).not.toHaveBeenCalled();
      });
      
      it('prevents interaction when loading', () => {
        const onPress = jest.fn();
        const { getByTestId } = render(
          <Button onPress={onPress} loading testID="loading-button">
            Loading
          </Button>
        );
        
        fireEvent.press(getByTestId('loading-button'));
        expect(onPress).not.toHaveBeenCalled();
      });
      
      it('handles long press events', () => {
        const onLongPress = jest.fn();
        const { getByText } = render(
          <Button onLongPress={onLongPress}>
            Long press me
          </Button>
        );
        
        fireEvent(getByText('Long press me'), 'longPress');
        expect(onLongPress).toHaveBeenCalledTimes(1);
      });
      
      it('provides haptic feedback on press', () => {
        const hapticSpy = jest.spyOn(Haptics, 'impact');
        const { getByText } = render(
          <Button onPress={jest.fn()} haptic>
            Press me
          </Button>
        );
        
        fireEvent.press(getByText('Press me'));
        expect(hapticSpy).toHaveBeenCalledWith(
          Haptics.ImpactFeedbackStyle.Light
        );
      });
    });
    ```
  </Tab>

  <Tab>
    ```typescript
    import { render, act } from '@testing-library/react-native';
    import { Button } from './Button';

    describe('Button States', () => {
      it('shows loading spinner when loading', () => {
        const { getByTestId, queryByTestId, rerender } = render(
          <Button loading={false}>Content</Button>
        );
        
        expect(queryByTestId('button-spinner')).toBeNull();
        
        rerender(<Button loading={true}>Content</Button>);
        
        expect(getByTestId('button-spinner')).toBeTruthy();
      });
      
      it('updates opacity when disabled', () => {
        const { getByTestId, rerender } = render(
          <Button testID="button" disabled={false}>
            Button
          </Button>
        );
        
        expect(getByTestId('button').props.style.opacity).toBe(1);
        
        rerender(
          <Button testID="button" disabled={true}>
            Button
          </Button>
        );
        
        expect(getByTestId('button').props.style.opacity).toBe(0.6);
      });
      
      it('maintains size during loading state', async () => {
        const { getByTestId, rerender } = render(
          <Button testID="button" loading={false}>
            Save Changes
          </Button>
        );
        
        const initialHeight = getByTestId('button').props.style.height;
        
        rerender(
          <Button testID="button" loading={true}>
            Save Changes
          </Button>
        );
        
        await waitFor(() => {
          expect(getByTestId('button').props.style.height).toBe(initialHeight);
        });
      });
    });
    ```
  </Tab>
</Tabs>

### Accessibility Testing

```typescript
describe('Button Accessibility', () => {
  it('has correct accessibility role', () => {
    const { getByRole } = render(<Button>Test</Button>);
    expect(getByRole('button')).toBeTruthy();
  });

  it('communicates disabled state', () => {
    const { getByRole } = render(<Button disabled>Test</Button>);
    const button = getByRole('button');
    expect(button.props.accessibilityState.disabled).toBe(true);
  });

  it('communicates loading state', () => {
    const { getByRole } = render(<Button loading>Test</Button>);
    const button = getByRole('button');
    expect(button.props.accessibilityState.busy).toBe(true);
  });

  it('has accessible label', () => {
    const { getByLabelText } = render(
      <Button accessibilityLabel="Save changes">Save</Button>
    );
    expect(getByLabelText('Save changes')).toBeTruthy();
  });
  
  it('announces press action', () => {
    const announceForAccessibility = jest.spyOn(
      AccessibilityInfo,
      'announceForAccessibility'
    );
    
    const { getByRole } = render(
      <Button onPress={() => announceForAccessibility('Saved!')}>
        Save
      </Button>
    );
    
    fireEvent.press(getByRole('button'));
    expect(announceForAccessibility).toHaveBeenCalledWith('Saved!');
  });
});
```

### Visual Regression Testing

<Tabs items={["Snapshot Testing", "Visual Testing", "Platform Testing"]}>
  <Tab>
    ```typescript
    // Button.visual.test.tsx
    import React from 'react';
    import renderer from 'react-test-renderer';
    import { Button } from './Button';

    describe('Button Visual Tests', () => {
      it('matches snapshot for all variants', () => {
        const variants = ['primary', 'secondary', 'ghost', 'danger'] as const;
        
        variants.forEach(variant => {
          const tree = renderer.create(
            <Button variant={variant}>Test Button</Button>
          ).toJSON();
          
          expect(tree).toMatchSnapshot(`button-${variant}`);
        });
      });
      
      it('matches snapshot for all sizes', () => {
        const sizes = ['small', 'medium', 'large'] as const;
        
        sizes.forEach(size => {
          const tree = renderer.create(
            <Button size={size}>Test Button</Button>
          ).toJSON();
          
          expect(tree).toMatchSnapshot(`button-${size}`);
        });
      });
      
      it('matches snapshot for different states', () => {
        const states = [
          { loading: true },
          { disabled: true },
          { fullWidth: true },
        ];
        
        states.forEach((state, index) => {
          const tree = renderer.create(
            <Button {...state}>Test Button</Button>
          ).toJSON();
          
          expect(tree).toMatchSnapshot(`button-state-${index}`);
        });
      });
    });
    ```
  </Tab>

  <Tab>
    ```typescript
    // Using Storybook for visual testing
    import type { Meta, StoryObj } from '@storybook/react-native';
    import { Button } from './Button';

    const meta: Meta<typeof Button> = {
      title: 'Foundation/Button',
      component: Button,
      argTypes: {
        variant: {
          control: { type: 'select' },
          options: ['primary', 'secondary', 'ghost', 'danger'],
        },
        size: {
          control: { type: 'select' },
          options: ['small', 'medium', 'large'],
        },
      },
    };

    export default meta;
    type Story = StoryObj<typeof meta>;

    export const Default: Story = {
      args: {
        children: 'Button',
      },
    };

    export const AllVariants: Story = {
      render: () => (
        <View style={{ gap: 16 }}>
          <Button variant="primary">Primary</Button>
          <Button variant="secondary">Secondary</Button>
          <Button variant="ghost">Ghost</Button>
          <Button variant="danger">Danger</Button>
        </View>
      ),
    };

    export const States: Story = {
      render: () => (
        <View style={{ gap: 16 }}>
          <Button>Default</Button>
          <Button disabled>Disabled</Button>
          <Button loading>Loading</Button>
        </View>
      ),
    };
    ```
  </Tab>

  <Tab>
    ```typescript
    import { Platform } from 'react-native';

    describe('Platform-specific visual tests', () => {
      it('renders iOS-specific styles', () => {
        Platform.OS = 'ios';
        const tree = renderer.create(
          <Button>iOS Button</Button>
        ).toJSON();
        
        expect(tree).toMatchSnapshot('button-ios');
      });
      
      it('renders Android-specific styles', () => {
        Platform.OS = 'android';
        const tree = renderer.create(
          <Button>Android Button</Button>
        ).toJSON();
        
        expect(tree).toMatchSnapshot('button-android');
      });
      
      it('handles platform-specific shadows', () => {
        const platforms = ['ios', 'android'] as const;
        
        platforms.forEach(platform => {
          Platform.OS = platform;
          const { getByTestId } = render(
            <Button elevated testID="elevated-button">
              Elevated
            </Button>
          );
          
          const button = getByTestId('elevated-button');
          
          if (platform === 'ios') {
            expect(button.props.style).toHaveProperty('shadowColor');
            expect(button.props.style).toHaveProperty('shadowOffset');
          } else {
            expect(button.props.style).toHaveProperty('elevation');
          }
        });
      });
    });
    ```
  </Tab>
</Tabs>

## Performance Optimization

### Memoization Patterns

<Tabs items={["React.memo", "useMemo Hooks", "useCallback Hooks"]}>
  <Tab>
    ```typescript
    import React from 'react';

    // Basic memoization
    export const Button = React.memo<ButtonProps>(({ 
      variant = 'primary',
      size = 'medium',
      loading = false,
      disabled = false,
      children,
      onPress,
      ...props 
    }) => {
      // Component implementation
    });

    // Custom comparison function
    export const Button = React.memo<ButtonProps>(
      (props) => {
        // Component implementation
      },
      (prevProps, nextProps) => {
        // Return true if props are equal (skip re-render)
        return (
          prevProps.variant === nextProps.variant &&
          prevProps.size === nextProps.size &&
          prevProps.loading === nextProps.loading &&
          prevProps.disabled === nextProps.disabled &&
          prevProps.children === nextProps.children
          // Note: Exclude onPress as it might be recreated
        );
      }
    );

    // Memoizing compound components
    const ButtonIcon = React.memo(({ icon, position }) => (
      <View style={position === 'left' ? styles.iconLeft : styles.iconRight}>
        {icon}
      </View>
    ));

    const ButtonContent = React.memo(({ children, loading }) => {
      if (loading) return <ActivityIndicator />;
      return <Text>{children}</Text>;
    });
    ```
  </Tab>

  <Tab>
    ```typescript
    // Memoize expensive style calculations
    const useButtonStyles = (variant: string, size: string, disabled: boolean) => {
      return useMemo(() => {
        const baseStyles = {
          paddingHorizontal: theme.spacing[size],
          paddingVertical: theme.spacing[size] / 2,
          borderRadius: theme.radii.md,
          flexDirection: 'row',
          alignItems: 'center',
          justifyContent: 'center',
        };
        
        const variantStyles = {
          backgroundColor: theme.colors[variant][500],
          borderColor: theme.colors[variant][600],
        };
        
        const stateStyles = disabled ? {
          opacity: 0.6,
          backgroundColor: theme.colors.gray[300],
        } : {};
        
        return StyleSheet.create({
          container: {
            ...baseStyles,
            ...variantStyles,
            ...stateStyles,
          },
        });
      }, [variant, size, disabled]);
    };

    // Memoize complex computations
    const useIconSize = (buttonSize: string) => {
      return useMemo(() => {
        switch (buttonSize) {
          case 'small': return 16;
          case 'large': return 24;
          default: return 20;
        }
      }, [buttonSize]);
    };

    // Memoize transformed data
    const useFormattedLabel = (label: string, loading: boolean) => {
      return useMemo(() => {
        if (loading) return 'Loading...';
        return label.trim().toUpperCase();
      }, [label, loading]);
    };
    ```
  </Tab>

  <Tab>
    ```typescript
    // Memoize event handlers
    const Button = ({ onPress, onLongPress, id, ...props }) => {
      const handlePress = useCallback(() => {
        Haptics.impact(Haptics.ImpactFeedbackStyle.Light);
        onPress?.(id);
      }, [onPress, id]);
      
      const handleLongPress = useCallback(() => {
        Haptics.impact(Haptics.ImpactFeedbackStyle.Medium);
        onLongPress?.(id);
      }, [onLongPress, id]);
      
      return (
        <TouchableOpacity
          onPress={handlePress}
          onLongPress={handleLongPress}
          {...props}
        />
      );
    };

    // Memoize animation callbacks
    const AnimatedButton = ({ onPress }) => {
      const scale = useSharedValue(1);
      
      const handlePressIn = useCallback(() => {
        'worklet';
        scale.value = withSpring(0.95);
      }, []);
      
      const handlePressOut = useCallback(() => {
        'worklet';
        scale.value = withSpring(1);
        runOnJS(onPress)();
      }, [onPress]);
      
      const animatedStyle = useAnimatedStyle(() => ({
        transform: [{ scale: scale.value }],
      }));
      
      return (
        <AnimatedTouchable
          onPressIn={handlePressIn}
          onPressOut={handlePressOut}
          style={animatedStyle}
        />
      );
    };
    ```
  </Tab>
</Tabs>

### StyleSheet Optimization

```typescript
// Static styles - created once
const staticStyles = StyleSheet.create({
  container: {
    flexDirection: 'row',
    alignItems: 'center',
    justifyContent: 'center',
  },
  text: {
    textAlign: 'center',
  },
  icon: {
    marginHorizontal: theme.spacing.xs,
  },
});

// Dynamic styles - use factory pattern
const createButtonStyles = memoize((variant: string, size: string) => 
  StyleSheet.create({
    button: {
      backgroundColor: theme.colors[variant][500],
      padding: theme.spacing[size],
      borderRadius: theme.radii[size],
    },
  })
);

// Flatten styles for performance
const Button = ({ variant, size, style, ...props }) => {
  const dynamicStyles = createButtonStyles(variant, size);
  
  // Flatten only what's needed
  const flattenedStyle = useMemo(
    () => StyleSheet.flatten([
      staticStyles.container,
      dynamicStyles.button,
      style,
    ]),
    [dynamicStyles, style]
  );
  
  return <TouchableOpacity style={flattenedStyle} {...props} />;
};
```

### List Performance

<Steps>
  <Step>
    #### Use FlatList Optimizations

    ```typescript
    const OptimizedList = ({ data }) => {
      const renderItem = useCallback(({ item }) => (
        <MemoizedListItem item={item} />
      ), []);
      
      const keyExtractor = useCallback((item) => item.id, []);
      
      const getItemLayout = useCallback((data, index) => ({
        length: ITEM_HEIGHT,
        offset: ITEM_HEIGHT * index,
        index,
      }), []);
      
      return (
        <FlatList
          data={data}
          renderItem={renderItem}
          keyExtractor={keyExtractor}
          getItemLayout={getItemLayout}
          maxToRenderPerBatch={10}
          updateCellsBatchingPeriod={100}
          windowSize={10}
          removeClippedSubviews={true}
          initialNumToRender={10}
        />
      );
    };
    ```
  </Step>

  <Step>
    #### Implement Virtualization

    ```typescript
    import { VirtualizedList } from 'react-native';

    const VirtualizedComponent = ({ items }) => {
      const getItem = useCallback((data, index) => data[index], []);
      const getItemCount = useCallback((data) => data.length, []);
      
      return (
        <VirtualizedList
          data={items}
          getItem={getItem}
          getItemCount={getItemCount}
          renderItem={renderItem}
          keyExtractor={keyExtractor}
          // Virtualization config
          maxToRenderPerBatch={5}
          updateCellsBatchingPeriod={50}
          initialNumToRender={10}
          windowSize={21}
        />
      );
    };
    ```
  </Step>

  <Step>
    #### Use FlashList for Better Performance

    ```typescript
    import { FlashList } from '@shopify/flash-list';

    const PerformantList = ({ data }) => {
      return (
        <FlashList
          data={data}
          renderItem={renderItem}
          estimatedItemSize={100}
          // Performance optimizations
          drawDistance={200}
          recycleItems={true}
          overrideItemLayout={(layout, item) => {
            if (item.type === 'header') {
              layout.size = 60;
              layout.span = 2;
            }
          }}
        />
      );
    };
    ```
  </Step>
</Steps>

### Animation Performance

```typescript
// Use native driver for better performance
const fadeIn = useCallback(() => {
  Animated.timing(opacity, {
    toValue: 1,
    duration: 300,
    useNativeDriver: true, // Critical for performance
  }).start();
}, [opacity]);

// Use Reanimated for complex animations
const AnimatedComponent = () => {
  const translateY = useSharedValue(0);
  
  const animatedStyle = useAnimatedStyle(() => ({
    transform: [{ translateY: translateY.value }],
  }));
  
  const startAnimation = useCallback(() => {
    'worklet';
    translateY.value = withSpring(100, {
      damping: 15,
      stiffness: 100,
    });
  }, []);
  
  return (
    <Animated.View style={animatedStyle}>
      {/* Content */}
    </Animated.View>
  );
};

// Batch animations
const batchedAnimation = useCallback(() => {
  Animated.parallel([
    Animated.timing(opacity, { toValue: 1, useNativeDriver: true }),
    Animated.timing(scale, { toValue: 1, useNativeDriver: true }),
  ]).start();
}, [opacity, scale]);
```

## Performance Testing

<Tabs items={["Render Performance", "Memory Testing", "Bundle Size"]}>
  <Tab>
    ```typescript
    // Button.perf.test.tsx
    import { measurePerformance } from '@testing-library/react-native-performance';

    describe('Button Performance', () => {
      it('renders within performance budget', async () => {
        const { renderTime } = await measurePerformance(
          <Button>Test Button</Button>
        );
        
        expect(renderTime).toBeLessThan(16); // 60fps threshold
      });
      
      it('re-renders efficiently', async () => {
        const scenario = async (screen) => {
          const button = screen.getByRole('button');
          
          await screen.rerender(
            <Button variant="secondary">Test Button</Button>
          );
          
          await screen.rerender(
            <Button variant="danger">Test Button</Button>
          );
        };
        
        const { renderCount, renderTime } = await measurePerformance(
          <Button>Test Button</Button>,
          { scenario }
        );
        
        expect(renderCount).toBe(3); // Initial + 2 re-renders
        expect(renderTime.median).toBeLessThan(8);
      });
      
      it('handles rapid interactions efficiently', async () => {
        const onPress = jest.fn();
        const scenario = async (screen) => {
          const button = screen.getByRole('button');
          
          // Simulate rapid taps
          for (let i = 0; i < 10; i++) {
            fireEvent.press(button);
            await wait(50);
          }
        };
        
        const { renderTime } = await measurePerformance(
          <Button onPress={onPress}>Tap me</Button>,
          { scenario }
        );
        
        expect(renderTime.max).toBeLessThan(16);
      });
    });
    ```
  </Tab>

  <Tab>
    ```typescript
    // Memory leak testing
    describe('Memory Management', () => {
      it('cleans up resources on unmount', async () => {
        const { unmount } = render(
          <Button onPress={() => startAnimation()}>
            Animated Button
          </Button>
        );
        
        const initialMemory = await getMemoryUsage();
        
        // Trigger animations and interactions
        fireEvent.press(screen.getByRole('button'));
        await wait(500);
        
        unmount();
        
        // Force garbage collection
        if (global.gc) global.gc();
        await wait(100);
        
        const finalMemory = await getMemoryUsage();
        expect(finalMemory).toBeLessThanOrEqual(initialMemory * 1.1);
      });
      
      it('handles large lists without memory leaks', async () => {
        const largeData = Array.from({ length: 1000 }, (_, i) => ({
          id: i,
          title: `Item ${i}`,
        }));
        
        const { unmount } = render(
          <FlatList
            data={largeData}
            renderItem={({ item }) => <Button>{item.title}</Button>}
            keyExtractor={(item) => item.id.toString()}
          />
        );
        
        const memoryBefore = await getMemoryUsage();
        
        // Scroll through list
        await scrollToEnd();
        await scrollToTop();
        
        unmount();
        if (global.gc) global.gc();
        
        const memoryAfter = await getMemoryUsage();
        expect(memoryAfter).toBeLessThan(memoryBefore * 1.2);
      });
    });
    ```
  </Tab>

  <Tab>
    ```typescript
    // Bundle size analysis
    import { analyzeBundle } from 'react-native-bundle-analyzer';

    describe('Bundle Size', () => {
      it('keeps component bundle size small', async () => {
        const analysis = await analyzeBundle({
          entry: './ui/foundation/Button/index.ts',
        });
        
        expect(analysis.size).toBeLessThan(5 * 1024); // 5KB max
        expect(analysis.gzipSize).toBeLessThan(2 * 1024); // 2KB gzipped
      });
      
      it('tree shakes unused code', async () => {
        const fullBundle = await analyzeBundle({
          entry: './ui/index.ts',
        });
        
        const usedBundle = await analyzeBundle({
          entry: './test-app.ts', // imports only Button
        });
        
        // Should only include Button code, not all components
        expect(usedBundle.size).toBeLessThan(fullBundle.size * 0.1);
      });
      
      it('identifies heavy dependencies', async () => {
        const analysis = await analyzeBundle({
          entry: './ui/foundation/Button/index.ts',
          detailed: true,
        });
        
        // Check for unexpected large dependencies
        analysis.modules.forEach(module => {
          if (module.size > 1024) { // 1KB
            console.warn(`Large dependency: ${module.name} (${module.size}B)`);
          }
        });
        
        expect(analysis.modules.every(m => m.size < 2048)).toBe(true);
      });
    });
    ```
  </Tab>
</Tabs>

## Testing Best Practices

<Callout type="success">
  **Testing Excellence**

  Great tests are:

  * **Fast**: Run quickly to encourage frequent execution
  * **Reliable**: No flaky tests that fail intermittently
  * **Maintainable**: Easy to understand and update
  * **Comprehensive**: Cover all critical paths
  * **Isolated**: Test one thing at a time
</Callout>

<Tabs items={["Do's", "Don'ts", "Tips"]}>
  <Tab>
    **(Do ✅) Testing best practices**

    * Write tests before or alongside implementation
    * Test behavior, not implementation details
    * Use descriptive test names that explain the scenario
    * Mock external dependencies consistently
    * Test edge cases and error conditions
    * Keep tests DRY with shared utilities
    * Run tests in CI/CD pipeline
    * Monitor and maintain test coverage
    * Test accessibility features
    * Profile performance regularly
  </Tab>

  <Tab>
    **(Don't ❌) Testing anti-patterns**

    * Don't test React Native internals
    * Don't write brittle tests tied to implementation
    * Don't ignore flaky tests - fix them
    * Don't skip tests for "simple" components
    * Don't mock everything - test integration
    * Don't forget cleanup in tests
    * Don't test styling details in unit tests
    * Don't write tests after bugs are found
    * Don't ignore performance budgets
    * Don't test private methods directly
  </Tab>

  <Tab>
    **Testing Tips & Tricks**

    1. **Use data-testid sparingly**
       ```tsx
       // Only when semantic queries don't work
       <View testID="complex-component-root">
       ```

    2. **Create test utilities**
       ```tsx
       const renderButton = (props = {}) =>
         render(<Button {...defaultProps} {...props} />);
       ```

    3. **Test loading states**
       ```tsx
       await waitFor(() => {
         expect(queryByTestId('spinner')).toBeTruthy();
       });
       ```

    4. **Mock timers for animations**
       ```tsx
       jest.useFakeTimers();
       act(() => {
         jest.runAllTimers();
       });
       ```

    5. **Use testing playground**
       ```tsx
       screen.logTestingPlaygroundURL();
       ```
  </Tab>
</Tabs>

## Summary

Comprehensive testing and performance optimization ensure your foundation components are reliable, fast, and maintainable. Key takeaways:

* **Test everything**: Aim for high coverage while focusing on critical paths
* **Optimize intelligently**: Measure before optimizing
* **Automate quality**: Use CI/CD to enforce standards
* **Monitor continuously**: Track performance metrics over time
* **Learn from failures**: Each bug is an opportunity to improve tests

## Next Steps

* Explore [AI Collaboration & Documentation](/docs/ui-development/architecture/foundation-guide/ai-collaboration-docs)
* Review [Component Examples](/docs/reference-implementations/ui) for testing patterns
* Set up [Performance Monitoring](/docs/monitoring/performance) in production

## Related Documents

* [React Native Testing Library](https://callstack.github.io/react-native-testing-library/)
* [Jest Documentation](https://jestjs.io/docs/tutorial-react-native)
* [React DevTools Profiler](https://react.dev/reference/react-devtools/profiler)
* [Performance Monitoring Guide](/docs/monitoring/performance)


# UTA UI Development: AI Collaboration & Documentation
URL: https://dev.updatetheapp.com/docs/ui-development/architecture/foundation-guide/ai-collaboration-docs
Documentation: https://dev.updatetheapp.com/docs/ui-development/architecture/foundation-guide/ai-collaboration-docs

Effective AI prompts, documentation standards, and maintenance strategies for sustainable foundation component development.
        
***

title: AI Collaboration & Documentation
description: Effective AI prompts, documentation standards, and maintenance strategies for sustainable foundation component development.
----------------------------------------------------------------------------------------------------------------------------------------

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Callout } from 'fumadocs-ui/components/callout';
import { Steps, Step } from 'fumadocs-ui/components/steps';

# AI Collaboration & Documentation

## Overview

AI assistants can significantly accelerate foundation component development while maintaining high quality standards. This guide provides structured approaches for leveraging AI effectively and maintaining comprehensive documentation that ensures your components remain understandable and maintainable over time.

<Callout type="info">
  **AI as a Development Partner**

  When used effectively, AI can help:

  * **Generate boilerplate** code following established patterns
  * **Implement accessibility** features consistently
  * **Write comprehensive tests** covering edge cases
  * **Create documentation** that stays in sync with code
  * **Suggest optimizations** based on best practices
</Callout>

## Effective AI Prompts for Components

### Component Generation Prompts

<Tabs items={["Basic Component", "Complex Component", "Test Generation"]}>
  <Tab>
    **Basic Component Prompt Structure:**

    Start your AI prompts with clear requirements:

    **Component Features:**

    * TypeScript with proper interfaces
    * Variants: primary, secondary, ghost, danger
    * Sizes: small, medium, large
    * Loading state with spinner
    * Disabled state
    * Icon support (left and right)

    **Technical Requirements:**

    * Use design tokens from theme
    * Implement full accessibility
    * Memoize with React.memo
    * Include proper TypeScript types
    * Follow foundation component patterns

    **Code Structure:**

    * Export from index.ts
    * Separate types in types.ts
    * Component in main file
    * Include JSDoc comments
  </Tab>

  <Tab>
    **Complex Component Prompt Structure:**

    For advanced components like DataTable:

    **Features List:**

    * Sortable columns
    * Pagination
    * Row selection (single/multi)
    * Search/filter functionality
    * Loading and empty states
    * Responsive design

    **Technical Requirements:**

    * Built on foundation components
    * Use React Query for data fetching
    * Virtualized list for performance
    * Full keyboard navigation
    * Screen reader announcements
    * Touch and mouse support

    **API Design Specification:**

    * Define clear interfaces
    * Specify callback functions
    * Include optional features
    * Provide usage examples
  </Tab>

  <Tab>
    **Test Generation Prompt Structure:**

    Request comprehensive test coverage:

    **Unit Tests:**

    * Rendering with all prop combinations
    * Interaction handling
    * State changes
    * Style application

    **Accessibility Tests:**

    * Correct roles and states
    * Label and hint presence
    * Focus management
    * State announcements

    **Visual Regression Tests:**

    * Snapshots for all variants
    * Platform-specific rendering
    * Different states and sizes

    **Performance Tests:**

    * Render time benchmarks
    * Re-render optimization
    * Memory leak detection
  </Tab>
</Tabs>

### Optimization Prompts

When requesting code optimizations, structure your prompt to focus on:

1. **Performance improvements** (memoization, render optimization)
2. **Accessibility enhancements**
3. **Type safety improvements**
4. **Design token usage**
5. **Test coverage gaps**
6. **Documentation completeness**

### Documentation Prompts

For comprehensive component documentation, request:

1. Component overview and purpose
2. Props documentation with types and defaults
3. Usage examples for common scenarios
4. Accessibility features and requirements
5. Performance considerations
6. Related components
7. Migration guides for updates

## Documentation Standards

### Component Documentation Structure

<Steps>
  <Step>
    #### Component Header Documentation

    Include comprehensive JSDoc comments with:

    **Component Description:**

    * Clear purpose statement
    * Key features overview
    * Accessibility highlights

    **Usage Examples:**

    * Basic usage pattern
    * Common configurations
    * Integration examples

    **Reference Links:**

    * Props interface
    * Design guidelines
    * Related components

    **Metadata:**

    * Version since
    * Author information
  </Step>

  <Step>
    #### Props Documentation

    Document each prop with:

    **Type Information:**

    * TypeScript interface
    * Default values
    * Required vs optional

    **Usage Examples:**

    * Basic usage
    * Advanced configurations
    * Edge cases

    **Behavior Notes:**

    * Platform differences
    * Performance implications
    * Accessibility impact
  </Step>

  <Step>
    #### Usage Documentation

    Provide comprehensive examples:

    **Basic Usage:**

    * Simple component usage
    * Essential props
    * Common patterns

    **Advanced Usage:**

    * Complex configurations
    * Integration patterns
    * Custom styling

    **Form Integration:**

    * State management
    * Validation patterns
    * Error handling
  </Step>
</Steps>

### Inline Documentation

<Tabs items={["Code Comments", "Type Documentation", "Example Comments"]}>
  <Tab>
    **Effective Code Comments:**

    **Explain Why, Not What:**

    * Reason for implementation choices
    * Performance considerations
    * Accessibility requirements
    * Platform-specific behavior

    **Document Non-Obvious Logic:**

    * Complex calculations
    * State management decisions
    * Optimization techniques
    * Workarounds and fixes

    **Provide Context:**

    * Link to external resources
    * Reference design decisions
    * Explain constraints
    * Note future improvements
  </Tab>

  <Tab>
    **Type Documentation Best Practices:**

    **Interface Documentation:**

    * Clear property descriptions
    * Default value notation
    * Usage examples
    * Constraint specifications

    **Animation Configurations:**

    * Duration specifications
    * Scale factor ranges
    * Easing function options
    * Performance considerations

    **Ref Handle Documentation:**

    * Method descriptions
    * Return value types
    * Usage scenarios
    * Performance implications
  </Tab>

  <Tab>
    **Example Comment Patterns:**

    **Good vs Bad Examples:**

    * Show incorrect usage patterns
    * Demonstrate correct implementations
    * Highlight common mistakes
    * Provide better alternatives

    **Error Handling:**

    * Show proper error handling
    * Demonstrate user feedback
    * Include recovery strategies
    * Handle edge cases

    **Design System Usage:**

    * Use design tokens
    * Follow component variants
    * Maintain consistency
    * Avoid custom styling
  </Tab>
</Tabs>

## AI-Assisted Development Workflow

<Steps>
  <Step>
    #### Define Requirements

    Before engaging AI, clearly define:

    * Component purpose and use cases
    * Technical requirements
    * Design system constraints
    * Performance requirements
    * Testing requirements
  </Step>

  <Step>
    #### Generate Initial Implementation

    Use AI to create the initial component structure with:

    * Clear requirements list
    * Technical constraints
    * Example API/interface
    * Reference existing patterns
  </Step>

  <Step>
    #### Review and Refine

    * Check generated code against style guide
    * Verify accessibility implementation
    * Ensure proper TypeScript types
    * Validate design token usage
    * Test component behavior
  </Step>

  <Step>
    #### Generate Tests

    Have AI create comprehensive tests covering:

    * All props and states
    * User interactions
    * Accessibility features
    * Edge cases
    * Performance benchmarks
  </Step>

  <Step>
    #### Create Documentation

    Use AI to generate documentation including:

    * API reference
    * Usage examples
    * Best practices
    * Common pitfalls
    * Migration guides
  </Step>

  <Step>
    #### Iterate Based on Feedback

    * Run tests and fix failures
    * Address linting issues
    * Optimize performance
    * Enhance accessibility
    * Update documentation
  </Step>
</Steps>

## Maintenance Documentation

### Component Changelog

Track component evolution with structured changelogs:

**Version Format:** \[2.0.0] - 2024-01-15

**Categories:**

* **Breaking Changes:** API modifications requiring updates
* **Added:** New features and capabilities
* **Fixed:** Bug fixes and corrections
* **Performance:** Optimization improvements

**Change Documentation:**

* Clear description of changes
* Impact on existing usage
* Migration instructions
* Performance implications

### Migration Guides

Provide clear migration paths:

**Breaking Changes Documentation:**

* Prop name changes
* API modifications
* Behavior differences
* Required updates

**Migration Examples:**

* Before/after code samples
* Step-by-step instructions
* Common pitfalls
* Testing recommendations

**New Features:**

* Usage examples
* Integration patterns
* Best practices
* Performance benefits

## Documentation Best Practices

<Callout type="success">
  **Documentation Excellence**

  Great documentation is:

  * **Accurate**: Always in sync with implementation
  * **Complete**: Covers all features and edge cases
  * **Clear**: Easy to understand for all skill levels
  * **Practical**: Includes real-world examples
  * **Maintainable**: Easy to update as code evolves
</Callout>

<Tabs items={["Do's", "Don'ts", "Quick Tips"]}>
  <Tab>
    **Documentation Best Practices:**

    * Write documentation as you code
    * Include "why" not just "what"
    * Provide complete, runnable examples
    * Document edge cases and limitations
    * Keep examples up to date
    * Use consistent terminology
    * Include visual examples where helpful
    * Document performance implications
    * Add links to related resources
    * Version your documentation
  </Tab>

  <Tab>
    **Documentation Anti-Patterns:**

    * Don't document obvious code
    * Don't use vague descriptions
    * Don't forget to update docs when code changes
    * Don't assume knowledge without stating prerequisites
    * Don't mix concerns in examples
    * Don't use outdated API in examples
    * Don't skip error handling in examples
    * Don't ignore accessibility in examples
    * Don't write novels - be concise
    * Don't use complex examples for simple features
  </Tab>

  <Tab>
    **Quick Documentation Tips:**

    **Start with Why:**
    Explain the reasoning behind implementation choices and decisions.

    **Show, Don't Just Tell:**
    Provide concrete examples rather than abstract descriptions.

    **Document the Non-Obvious:**
    Explain platform-specific requirements and performance considerations.

    **Link to Context:**
    Reference design system documentation and related resources.

    **Warn About Gotchas:**
    Highlight potential issues and provide alternatives.
  </Tab>
</Tabs>

## AI Prompt Templates

### Component Generation Template

**Basic Template Structure:**

**Core Requirements:**

* TypeScript with exported interfaces
* Foundation component structure
* Design tokens from theme
* Full accessibility support
* React.memo optimization

**Props Definition:**
List specific props with types and descriptions

**Features List:**
Enumerate specific functionality requirements

**File Structure:**
Define organization and naming conventions

### Test Generation Template

**Test Structure Requirements:**

* Unit tests for functionality
* Visual tests for appearance
* Performance tests for optimization

**Coverage Requirements:**

* All props combinations
* All interactive states
* Accessibility features
* Platform differences
* Edge cases

**Test Utilities:**

* Custom render functions
* Accessibility assertions
* Design token matchers
* Performance benchmarks

## Summary

Effective AI collaboration and comprehensive documentation ensure your foundation components are:

* **Quickly developed** with AI assistance
* **Well documented** for team understanding
* **Easily maintained** with clear guidelines
* **Consistently implemented** across the codebase
* **Continuously improved** through iteration

Remember: AI is a tool to augment your development, not replace thoughtful design and engineering decisions.

## Related Documents

* [Component Development Workflow](/docs/ui-development/architecture/development-workflow)
* [Testing Patterns](/docs/ui-development/architecture/foundation-guide/testing-performance)
* [Component Examples](/docs/reference-implementations/ui)


# UTA UI Development: Component Development Workflow
URL: https://dev.updatetheapp.com/docs/ui-development/architecture/development-workflow
Documentation: https://dev.updatetheapp.com/docs/ui-development/architecture/development-workflow

Step-by-step workflow for creating, testing, and maintaining UI components with AI collaboration patterns and quality assurance processes.
        
***

title: Component Development Workflow
description: Step-by-step workflow for creating, testing, and maintaining UI components with AI collaboration patterns and quality assurance processes.
-------------------------------------------------------------------------------------------------------------------------------------------------------

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Callout } from 'fumadocs-ui/components/callout';
import { Steps, Step } from 'fumadocs-ui/components/steps';
import { Card, Cards } from 'fumadocs-ui/components/card';

# Component Development Workflow

## Overview

This document outlines a structured approach to creating, testing, and maintaining UI components in our React Native applications. It integrates AI collaboration patterns, quality assurance processes, and maintenance procedures designed to create consistency and quality across projects.

<Callout type="info">
  **Why a Structured Workflow Matters**

  A consistent component development workflow addresses several common challenges in UI development:

  * **Consistency**: Ensures all components follow the same patterns regardless of who creates them
  * **Quality**: Establishes checkpoints to verify components meet our standards
  * **Efficiency**: Reduces decision fatigue by providing clear next steps
  * **Onboarding**: Helps new team members understand our development process
  * **Collaboration**: Creates a shared understanding between designers, developers, and QA
</Callout>

## Purpose & Scope

<Tabs items={["What You'll Learn", "Who This Is For", "When To Apply"]}>
  <Tab>
    This workflow guide will help you:

    * Understand the lifecycle of component development from planning to maintenance
    * Follow a structured process that promotes quality and consistency
    * Integrate AI assistance effectively at different stages of development
    * Apply appropriate testing strategies for different component types
    * Create components that meet our accessibility and performance standards
    * Document components effectively for team use
  </Tab>

  <Tab>
    This guide is valuable for:

    * **UI developers** creating new components
    * **Feature teams** extending existing components
    * **Design system maintainers** reviewing component implementations
    * **QA engineers** validating component quality
    * **New team members** learning our development approach
    * **AI collaborators** assisting in component creation
  </Tab>

  <Tab>
    This workflow is especially useful when:

    * Starting a new component from scratch
    * Making significant changes to existing components
    * Adapting components for new platforms or environments
    * Preparing components for shared use across teams
    * Setting up development processes for new projects
  </Tab>
</Tabs>

## Development Workflow Overview

Our component development process follows a structured lifecycle that ensures quality, consistency, and maintainability. This workflow has evolved through our team's experience and reflects patterns that have proven successful across multiple projects.

<Mermaid
  chart={`
flowchart TD
subgraph Planning["1. Planning Phase"]
  Requirements["Define Requirements"]
  Category["Determine Category"]
  Design["Design Review"]
end

subgraph Development["2. Development Phase"]
  Structure["Create Structure"]
  Implement["Implement Component"]
  Tokens["Apply Design Tokens"]
  A11y["Add Accessibility"]
end

subgraph Testing["3. Testing Phase"]
  UnitTests["Unit Tests"]
  VisualTests["Visual Tests"]
  A11yTests["Accessibility Tests"]
  Integration["Integration Tests"]
end

subgraph Review["4. Review Phase"]
  SelfReview["Self Review"]
  PeerReview["Peer Review"]
  QAReview["QA Review"]
end

subgraph Deployment["5. Deployment Phase"]
  Docs["Update Documentation"]
  Export["Add Exports"]
  Publish["Publish Component"]
end

subgraph Maintenance["6. Maintenance Phase"]
  Monitor["Monitor Usage"]
  Versioning["Manage Versions"]
  Updates["Apply Updates"]
end

Planning --> Development
Development --> Testing
Testing --> Review
Review --> Deployment
Deployment --> Maintenance

%% Feedback loops
Review -->|Issues Found| Development
Testing -->|Failures| Development
Deployment -->|Integration Issues| Development

style Planning fill:#e3f2fd,stroke:#1976d2,stroke-width:2px
style Development fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px
style Testing fill:#fff8e1,stroke:#ff8f00,stroke-width:2px
style Review fill:#e8f5e8,stroke:#388e3c,stroke-width:2px
style Deployment fill:#e1f5fe,stroke:#0288d1,stroke-width:2px
style Maintenance fill:#ffebee,stroke:#c62828,stroke-width:2px
`}
/>

## Workflow Phases

The component development workflow is divided into six distinct phases, each with specific goals, activities, and deliverables. Select a phase below to learn more:

<Cards>
  <Card href="/docs/ui-development/architecture/development-workflow/planning-requirements" title="1. Planning & Requirements">
    Define component requirements, determine category, and review designs before implementation.
  </Card>

  <Card href="/docs/ui-development/architecture/development-workflow/development-phase" title="2. Development Phase">
    Create component structure, implement functionality, and apply design tokens and accessibility.
  </Card>

  <Card href="/docs/ui-development/architecture/development-workflow/testing-strategies" title="3. Testing Strategies">
    Apply appropriate testing strategies for unit, visual, accessibility, and integration testing.
  </Card>

  <Card href="/docs/ui-development/architecture/development-workflow/review-process" title="4. Review Process">
    Complete self-review, peer review, and QA review phases to ensure component quality.
  </Card>

  <Card href="/docs/ui-development/architecture/development-workflow/deployment-integration" title="5. Deployment & Integration">
    Finalize documentation, integrate into features, and deploy components to production.
  </Card>

  <Card href="/docs/ui-development/architecture/development-workflow/post-deployment" title="6. Post-Deployment">
    Monitor component performance, gather feedback, and maintain components over time.
  </Card>

  <Card href="/docs/ui-development/architecture/development-workflow/maintenance-lifecycle" title="7. Maintenance Lifecycle">
    Manage versions, apply updates, and perform long-term component maintenance.
  </Card>

  <Card href="/docs/ui-development/architecture/development-workflow/ai-collaboration" title="8. AI Collaboration">
    Leverage AI assistance effectively throughout the component development process.
  </Card>
</Cards>

## Quick Start Guide

<Steps>
  <Step>
    ### Determine Your Starting Point

    * **New Component**: Start with [Planning & Requirements](/docs/ui-development/architecture/development-workflow/planning-requirements)
    * **Existing Component Enhancement**: Review the current implementation, then jump to [Development Phase](/docs/ui-development/architecture/development-workflow/development-phase)
    * **Bug Fix or Minor Update**: Go directly to [Testing Strategies](/docs/ui-development/architecture/development-workflow/testing-strategies)
  </Step>

  <Step>
    ### Follow the Workflow

    Progress through each phase sequentially, using the checklists and guidelines provided. Don't skip phases unless you have a specific reason.
  </Step>

  <Step>
    ### Use AI Collaboration

    At each phase, leverage the [AI Collaboration patterns](/docs/ui-development/architecture/development-workflow/ai-collaboration) to enhance your productivity and ensure quality.
  </Step>

  <Step>
    ### Document Your Work

    Throughout the process, maintain clear documentation of decisions, trade-offs, and implementation details for future reference.
  </Step>
</Steps>

## Best Practices Summary

<Tabs items={["Do's", "Don'ts", "Tips"]}>
  <Tab>
    **(Do ✅) Best Practices**

    * Follow the workflow phases in order for new components
    * Use the provided checklists to ensure nothing is missed
    * Collaborate with designers early in the planning phase
    * Write tests alongside your implementation
    * Document decisions and trade-offs
    * Leverage AI assistance for routine tasks
    * Review similar existing components before starting
    * Consider accessibility from the beginning
  </Tab>

  <Tab>
    **(Don't ❌) Common Mistakes**

    * Skip the planning phase and jump straight to coding
    * Ignore existing patterns and create unique implementations
    * Leave testing until the end
    * Forget to update documentation
    * Create components without considering reusability
    * Omit accessibility features
    * Bypass code reviews
    * Neglect performance considerations
  </Tab>

  <Tab>
    **(Consider 🤔) Pro Tips**

    * Start with the simplest working version, then enhance
    * Create a component story/playground early for testing
    * Use visual regression testing for UI consistency
    * Pair with a designer during implementation
    * Get early feedback through draft PRs
    * Consider creating a component RFC for complex components
    * Automate repetitive tasks with scripts
    * Keep a personal checklist of common issues
  </Tab>
</Tabs>

## Related Documents

* [UI Architecture Overview](/docs/ui-development/architecture) - Understanding the three-layer architecture
* [Foundation Components Guide](/docs/ui-development/architecture/foundation-guide) - Building atomic UI components
* [Component Patterns](/docs/ui-development/development/component-patterns) - Common patterns and best practices
* [Testing Patterns](/docs/ui-development/development/testing-patterns) - Comprehensive testing strategies
* [AI Collaboration Guide](/docs/ui-development/architecture/ai-collaboration) - Working effectively with AI

## Getting Help

If you encounter challenges during the component development process:

1. **Check Existing Components**: Look for similar components that have already been implemented
2. **Consult the Team**: Reach out to other developers who have built similar components
3. **Review Documentation**: Ensure you've read all relevant guides and standards
4. **Use AI Assistance**: Leverage AI for specific technical questions or implementation help
5. **Ask in Team Channels**: Post questions in your team's communication channels

Remember, the goal of this workflow is to help you create high-quality components efficiently. Don't hesitate to ask for help when needed!


# UTA UI Development: Planning & Requirements Phase
URL: https://dev.updatetheapp.com/docs/ui-development/architecture/development-workflow/planning-requirements
Documentation: https://dev.updatetheapp.com/docs/ui-development/architecture/development-workflow/planning-requirements

Define component requirements, determine category, and review designs before implementation.
        
***

title: Planning & Requirements Phase
description: Define component requirements, determine category, and review designs before implementation.
---------------------------------------------------------------------------------------------------------

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Callout } from 'fumadocs-ui/components/callout';
import { Steps, Step } from 'fumadocs-ui/components/steps';

# Planning & Requirements Phase

## Overview

The planning phase is crucial for successful component development. It helps avoid costly rework, ensures consistent implementation, and aligns the component with both user needs and our design system. Studies show that addressing requirements issues early can reduce development costs by up to 100x compared to fixing them after deployment.

<Callout type="info">
  **Why Planning Matters**

  The planning phase is crucial for successful component development. It helps avoid costly rework, ensures consistent implementation, and aligns the component with both user needs and our design system. Studies show that addressing requirements issues early can reduce development costs by up to 100x compared to fixing them after deployment.
</Callout>

## Step 1: Define Component Requirements

Before writing any code, it's important to clearly understand the component's purpose, behavior, and constraints. This step creates alignment between design, development, and product teams while ensuring the component will meet user needs.

<Tabs items={["Requirements Checklist", "Practical Example", "Common Pitfalls"]}>
  <Tab>
    When defining requirements, consider these key aspects:

    * **Primary Purpose**: What core user need does this component address?
    * **Usage Context**: In what screens/features will this component appear?
    * **Data Requirements**: What information will this component display or collect?
    * **Visual Requirements**: How should it look in different states and platforms?
    * **Interaction Requirements**: How will users interact with it? What feedback should it provide?
    * **Accessibility Requirements**: What specific a11y features are needed? (Screen reader support, keyboard navigation, etc.)
    * **Performance Requirements**: Are there specific performance thresholds it must meet?
    * **Platform Considerations**: Are there platform-specific behaviors to account for?
  </Tab>

  <Tab>
    **Example: Button Component Requirements**

    ```markdown
    ## Button Component Requirements

    **Primary Purpose**:
    Enable users to trigger actions throughout the application with clear visual feedback.

    **Usage Context**:
    - Primary actions on screens
    - Form submissions
    - Navigation triggers
    - Confirmation dialogs

    **Visual Requirements**:
    - Support primary, secondary, ghost, and danger variants
    - Support small, medium, and large sizes
    - Show appropriate loading states
    - Visual feedback for all interactive states (hover, pressed, disabled)

    **Accessibility Requirements**:
    - Minimum touch target of 44×44pt
    - Support for screen readers (proper labels)
    - Visual focus indicators for keyboard navigation
    - Color contrast ratio of at least 4.5:1
    ```
  </Tab>

  <Tab>
    **(Don't ❌) Common Requirements Pitfalls**

    * **Vague specifications**: "Make it look good" doesn't provide enough guidance
    * **Omitting edge cases**: Failing to define behavior for loading/error states
    * **Platform inconsistencies**: Not accounting for iOS vs Android differences
    * **Missing accessibility requirements**: Forgetting screen reader support
    * **Overloading components**: Trying to make one component do too many things

    **(Do ✅) Best Practices**

    * Document requirements in a shared location accessible to designers and developers
    * Include visual references from the design system
    * Reference existing components with similar functionality
    * Specify all possible states (normal, hover, active, disabled, loading, error)
    * Explicitly note platform-specific behaviors
  </Tab>
</Tabs>

### AI Collaboration: Requirements Definition

<Callout type="info">
  **Working with AI Collaborators**

  AI can be particularly helpful during the requirements definition phase by identifying patterns from similar components, suggesting comprehensive prop types, and raising considerations you might otherwise overlook. Using structured prompts ensures consistent and thorough AI assistance.
</Callout>

<Tabs items={["Recommended Prompt", "Example Interaction", "Best Practices"]}>
  <Tab>
    ```markdown
    # Component Requirements Definition

    ## Component Context
    - **Component Name**: [Name of the component]
    - **Purpose**: [Describe what the component does and the user need it addresses]
    - **Usage Context**: [Describe where it will be used in the application]
    - **User Interactions**: [Describe how users will interact with it]
    - **Design Reference**: [Link to design or mockup if available]

    ## Please help me identify:
    1. Complete set of props with types and default values
    2. All possible visual states (default, hover, active, disabled, loading, error)
    3. Accessibility requirements specific to this component
    4. Performance considerations and optimizations
    5. Integration points with our existing component architecture
    6. Edge cases I should account for
    7. Testing strategies for this component

    ## Additional Context
    - Our project uses TypeScript and React Native
    - We follow a design token system for styling
    - We prioritize accessibility and cross-platform consistency
    ```
  </Tab>

  <Tab>
    **Example: Button Component**

    **You:** *\[Provide the prompt with Button component details]*

    **AI Response:**

    ```typescript
    // Recommended props structure for Button component
    interface ButtonProps {
      /** Text content of the button */
      children: React.ReactNode;
      
      /** Visual style variant */
      variant?: 'primary' | 'secondary' | 'ghost' | 'danger';
      
      /** Size preset */
      size?: 'small' | 'medium' | 'large';
      
      /** Function called when button is pressed */
      onPress: () => void;
      
      /** Shows loading spinner and disables interactions */
      loading?: boolean;
      
      /** Disables the button */
      disabled?: boolean;
      
      /** Optional icon to display before text */
      leftIcon?: React.ReactNode;
      
      /** Optional icon to display after text */
      rightIcon?: React.ReactNode;
      
      /** When true, button expands to fill container width */
      fullWidth?: boolean;
      
      /** Optional test ID for automated testing */
      testID?: string;
      
      /** Accessibility label for screen readers */
      accessibilityLabel?: string;
    }
    ```

    *The AI would then continue with a comprehensive breakdown of states, accessibility requirements, etc.*
  </Tab>

  <Tab>
    **(Do ✅) Effective AI Collaboration**

    * Provide specific design context rather than vague instructions
    * Reference existing components with similar functionality
    * Include links to designs or screenshots when available
    * Be explicit about your project's technical constraints
    * Use follow-up questions to refine the AI's suggestions

    **(Don't ❌) Common AI Collaboration Mistakes**

    * Using vague prompts like "Create a button component"
    * Accepting suggestions without evaluating them against design system standards
    * Failing to provide context about your existing architecture
    * Omitting information about special requirements (a11y, performance, etc.)
    * Neglecting to validate AI suggestions against real-world constraints
  </Tab>
</Tabs>

## Step 2: Determine Component Category

<Callout type="info">
  **Why Component Categorization Matters**

  Properly categorizing components helps maintain a clean architecture, improves reusability, and ensures components are built at the right level of abstraction. This organization makes it easier for developers to find existing components, understand their intended use cases, and maintain consistent standards across the codebase.
</Callout>

Our component architecture uses a three-tier system that separates components based on their complexity, composition, and relationship to business domains. The following decision tree will help you determine the appropriate category for your component:

<Mermaid
  chart={`
flowchart TD
Start[New Component] --> Domain{Contains domain<br/>logic or business rules?}

Domain -->|Yes| Business[Business Component<br/>ui/business/]
Domain -->|No| Compose{Composed of multiple<br/>foundation components?}

Compose -->|Yes| Pattern[Pattern Component<br/>ui/patterns/]
Compose -->|No| Foundation[Foundation Component<br/>ui/foundation/]

Business --> BusinessEx[Examples:<br/>ProductCard, UserAvatar<br/>OrderStatus, PriceDisplay]
Pattern --> PatternEx[Examples:<br/>Modal, Form, DataTable<br/>SearchBox, Pagination]
Foundation --> FoundationEx[Examples:<br/>Button, Input, Text<br/>Card, Icon, Badge]

style Business fill:#4caf50,stroke:#1b5e20,stroke-width:2px
style Pattern fill:#9c27b0,stroke:#4a148c,stroke-width:2px
style Foundation fill:#2196f3,stroke:#0d47a1,stroke-width:2px
`}
/>

<Tabs items={["Decision Guide", "Category Characteristics", "Examples & Anti-patterns"]}>
  <Tab>
    Use these questions to determine the appropriate category for your component:

    1. **Does it contain business logic or domain-specific rules?**
       * If yes → **Business Component**
       * Example: A ProductCard that formats prices according to business rules

    2. **Does it accept domain-specific objects as props?**
       * If yes → **Business Component**
       * Example: A UserProfile that takes a User object with specific properties

    3. **Is it composed of multiple foundation components working together?**
       * If yes → **Pattern Component**
       * Example: A Form that combines Input, Select, and Button components

    4. **Does it implement complex UI behaviors or interactions?**
       * If yes → **Pattern Component**
       * Example: A Modal with focus trapping and keyboard interactions

    5. **Is it a single-purpose, atomic UI element?**
       * If yes → **Foundation Component**
       * Example: A Button that handles basic press interactions
  </Tab>

  <Tab>
    **Business Components**

    * Encapsulate domain knowledge and business rules
    * Often specific to a particular feature or domain
    * May have dependencies on specific data models
    * Usually placed in feature-specific directories
    * Examples: `ProductCard`, `OrderHistory`, `PaymentMethod`

    **Pattern Components**

    * Combine multiple foundation components into reusable patterns
    * Implement complex UI behaviors and interactions
    * Remain domain-agnostic (no business logic)
    * Highly reusable across different features
    * Examples: `Form`, `Modal`, `DataTable`, `Accordion`

    **Foundation Components**

    * Single-purpose, atomic UI elements
    * Highly reusable across the entire application
    * Simple, focused functionality
    * No dependencies on other components
    * Examples: `Button`, `Input`, `Text`, `Icon`, `Divider`
  </Tab>

  <Tab>
    **(Do ✅) Component Categorization Best Practices**

    * Keep foundation components as pure and simple as possible
    * Extract business logic from pattern components into business components
    * Use composition instead of inheritance for component relationships
    * Document the intended use cases for each component category
    * Follow the standard folder structure for each category

    **(Don't ❌) Common Categorization Mistakes**

    * Creating a foundation component that depends on business logic
    * Building extremely complex foundation components with multiple responsibilities
    * Placing components in the wrong category folders
    * Duplicating similar components across different categories
    * Creating "hybrid" components that don't clearly fit one category
  </Tab>
</Tabs>

## Step 3: Design and API Review

<Callout type="info">
  **The Value of Pre-Implementation Reviews**

  Taking time to review component designs and APIs before starting implementation helps identify potential issues early, ensures alignment with design standards, and prevents costly rework. This collaborative review process also promotes knowledge sharing and improves the overall quality of the component library.
</Callout>

Before writing code, it's valuable to thoroughly review both the visual design and the programmatic API of your component. This ensures the component will be both visually correct and developer-friendly.

<Tabs items={["Design Review Process", "API Design Principles", "Review Checklists"]}>
  <Tab>
    A good design review follows these steps:

    1. **Gather All Design Assets**
       * Design mockups and prototypes
       * Design system documentation
       * Existing similar components

    2. **Review with Cross-Functional Team**
       * Include designers, developers, and accessibility specialists
       * Review on multiple device sizes if applicable
       * Validate interaction patterns against established patterns

    3. **Document Decisions and Edge Cases**
       * Note any approved deviations from standards
       * Document responsive behavior expectations
       * Record special handling for edge cases

    4. **Validate Technical Feasibility**
       * Ensure the design can be implemented efficiently
       * Identify any technical constraints or challenges
       * Discuss alternatives if necessary
  </Tab>

  <Tab>
    When designing the component's API, consider these principles:

    **(Do ✅) API Design Best Practices**

    * **Consistent Naming**: Follow established naming patterns from other components
    * **Prop Defaults**: Provide sensible defaults for optional props
    * **Flexible Composition**: Allow for composition with other components when appropriate
    * **Controlled Components**: For form elements, support both controlled and uncontrolled modes
    * **Clear Documentation**: Document each prop with purpose and example usage
    * **Forward Refs**: When appropriate, forward refs to the underlying DOM elements

    **(Don't ❌) API Design Anti-patterns**

    * **Prop Overloading**: Avoid single props that do multiple unrelated things
    * **Excessive Props**: Don't create too many configuration options
    * **Leaky Abstractions**: Hide implementation details when possible
    * **Inconsistent Naming**: Don't use names that differ from established patterns
    * **Implicit Behaviors**: Make component behavior obvious from the API
  </Tab>

  <Tab>
    **Design Review Checklist**

    <Steps>
      <Step>
        #### Visual Design Review

        * Does the component align with our design system?
        * Are all visual states defined (normal, hover, focus, active, disabled)?
        * Is the visual hierarchy appropriate?
        * Does it handle content overflow gracefully?
        * Is text legible at all supported sizes?
      </Step>

      <Step>
        #### Interaction Design Review

        * Are all interactions clearly defined?
        * Does it provide appropriate feedback for user actions?
        * Are transitions and animations specified if needed?
        * Is the component behavior consistent with similar components?
        * Are all error and edge case states handled?
      </Step>

      <Step>
        #### Responsive Behavior Review

        * How does the component adapt to different screen sizes?
        * Are touch targets appropriate for mobile devices (minimum 44×44pt)?
        * Are there platform-specific considerations (iOS vs Android)?
        * How does the component handle orientation changes?
      </Step>

      <Step>
        #### Accessibility Review

        * Does the design maintain sufficient color contrast (4.5:1)?
        * Are focus states clearly visible?
        * Is the component usable with screen readers?
        * Can it be operated by keyboard alone?
        * Does it handle text scaling for users with vision impairments?
      </Step>
    </Steps>

    **API Design Checklist**

    <Steps>
      <Step>
        #### Props and Types Review

        * Are all necessary props defined?
        * Are prop types and default values appropriate?
        * Are required vs. optional props clearly distinguished?
        * Do prop names follow consistent naming conventions?
      </Step>

      <Step>
        #### Component Interface Review

        * Is the component interface intuitive and developer-friendly?
        * Does it compose well with other components?
        * Are there any unnecessary props that could be simplified?
        * Does it handle forwarded refs appropriately?
      </Step>

      <Step>
        #### Events and Callbacks Review

        * Are all necessary event handlers exposed?
        * Do callback prop names follow conventions (onEvent, handleEvent)?
        * Is event data structured consistently?
      </Step>

      <Step>
        #### Documentation Review

        * Is each prop documented with description and examples?
        * Are usage examples clear and comprehensive?
        * Are any special considerations or limitations documented?
      </Step>
    </Steps>
  </Tab>
</Tabs>

## Planning Phase Summary

The planning phase sets the foundation for successful component development. By thoroughly defining requirements, properly categorizing components, and reviewing designs before implementation, you can:

* Avoid costly rework later in the development process
* Ensure alignment between design and development teams
* Create components that are consistent with existing patterns
* Build in accessibility and performance from the start
* Create clear documentation that helps other developers

## Next Steps

Once you've completed the planning phase:

1. **Document Your Decisions**: Record all requirements, categorization decisions, and API designs in a shared location
2. **Get Sign-off**: Ensure all stakeholders agree with the plan before proceeding
3. **Prepare for Development**: Set up your development environment and gather necessary resources
4. **Move to Development Phase**: Proceed to the [Development Phase](/docs/ui-development/architecture/development-workflow/development-phase) to begin implementation

## Related Documents

* [UI Architecture Overview](/docs/ui-development/architecture) - Understanding the three-layer architecture
* [Foundation Components Guide](/docs/ui-development/architecture/foundation-guide) - Building atomic UI components
* [Component Patterns](/docs/ui-development/development/component-patterns) - Common patterns and best practices
* [AI Collaboration Guide](/docs/ui-development/architecture/ai-collaboration) - Working effectively with AI


# UTA UI Development: Development Phase
URL: https://dev.updatetheapp.com/docs/ui-development/architecture/development-workflow/development-phase
Documentation: https://dev.updatetheapp.com/docs/ui-development/architecture/development-workflow/development-phase

Create component structure, implement functionality, apply design tokens, and add accessibility.
        
***

title: Development Phase
description: Create component structure, implement functionality, apply design tokens, and add accessibility.
-------------------------------------------------------------------------------------------------------------

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Callout } from 'fumadocs-ui/components/callout';
import { Steps, Step } from 'fumadocs-ui/components/steps';

# Development Phase

## Overview

The development phase is where our planning transforms into actual code. Following a structured approach helps ensure components are consistent, maintainable, and aligned with our quality standards. Each step in this phase builds upon the previous one, creating a systematic workflow that promotes high-quality outcomes.

<Callout type="info">
  **The Development Phase**

  The development phase is where our planning transforms into actual code. Following a structured approach helps ensure components are consistent, maintainable, and aligned with our quality standards. Each step in this phase builds upon the previous one, creating a systematic workflow that promotes high-quality outcomes.
</Callout>

## Step 4: Create Component Structure

Every component in our system follows a consistent file structure that promotes maintainability, clear separation of concerns, and testability. This structure allows developers to quickly understand where to find specific functionality and how to extend components.

<Tabs items={["Standard Structure", "File Responsibilities", "Creation Process"]}>
  <Tab>
    The standard file structure for components follows this pattern:

    ```
    ui/[category]/[ComponentName]/
    ├── [ComponentName].tsx     # Main component implementation
    ├── types.ts                # TypeScript interfaces and types
    ├── index.ts                # Public exports
    ├── [ComponentName].test.tsx # Unit tests
    ├── hooks.ts                # Custom hooks (if needed)
    ├── utils.ts                # Helper functions (if needed)
    └── styles.ts               # Component-specific styles (if needed)
    ```

    This structure scales well from simple components to complex ones, allowing you to add files only when necessary while maintaining a consistent organization.
  </Tab>

  <Tab>
    Each file in the component structure has a specific responsibility:

    * **\[ComponentName].tsx**: The main React component implementation
    * **types.ts**: TypeScript interfaces, types, and constants related to the component
    * **index.ts**: Exports the component and any public utilities
    * **\[ComponentName].test.tsx**: Unit and integration tests
    * **hooks.ts**: Custom hooks used by the component
    * **utils.ts**: Helper functions and business logic
    * **styles.ts**: Component-specific styles using design tokens

    **(Do ✅) File Organization Best Practices**

    * Keep files focused on a single responsibility
    * Extract complex logic to utils.ts or hooks.ts
    * Export only what's needed from index.ts
    * Use relative imports for files within the component directory

    **(Don't ❌) Common File Organization Mistakes**

    * Putting everything in the main component file
    * Mixing business logic with UI rendering
    * Creating overly complex utility functions
    * Defining styles inline instead of in styles.ts
  </Tab>

  <Tab>
    <Steps>
      <Step>
        #### Create the component directory

        ```bash
        mkdir -p ui/[category]/[ComponentName]
        ```

        For example, for a Button foundation component:

        ```bash
        mkdir -p ui/foundation/Button
        ```
      </Step>

      <Step>
        #### Create required files

        ```bash
        # Create the minimum required files
        touch ui/[category]/[ComponentName]/[ComponentName].tsx
        touch ui/[category]/[ComponentName]/types.ts
        touch ui/[category]/[ComponentName]/index.ts
        ```
      </Step>

      <Step>
        #### Add testing and supporting files

        ```bash
        # Add test file (recommended for all components)
        touch ui/[category]/[ComponentName]/[ComponentName].test.tsx

        # Add optional files as needed
        touch ui/[category]/[ComponentName]/hooks.ts  # If component has custom hooks
        touch ui/[category]/[ComponentName]/utils.ts  # If component has helper functions
        touch ui/[category]/[ComponentName]/styles.ts # If component has complex styling
        ```
      </Step>
    </Steps>
  </Tab>
</Tabs>

### AI Collaboration: Structure Creation

<Callout type="info">
  AI can be particularly helpful in scaffolding component structure, generating boilerplate code, and ensuring files follow team conventions. The prompt below helps AI create a consistent component structure.
</Callout>

<Tabs items={["AI Prompt", "Example Output"]}>
  <Tab>
    ```markdown
    # Create Component Structure

    Please create the file structure for a new React Native component with the following details:

    ## Component Information
    - Name: [ComponentName]
    - Category: [foundation/patterns/business]
    - Purpose: [Brief description of component purpose]

    ## File Structure
    Please create the following files with appropriate boilerplate code:

    1. ui/[category]/[ComponentName]/[ComponentName].tsx
    2. ui/[category]/[ComponentName]/types.ts
    3. ui/[category]/[ComponentName]/index.ts
    4. ui/[category]/[ComponentName]/[ComponentName].test.tsx

    ## Requirements
    - Use TypeScript for all files
    - Follow our project's naming conventions (PascalCase for components)
    - Include JSDoc comments for all props and functions
    - Implement proper type exports in types.ts
    - Create barrel exports in index.ts
    - Set up basic Jest tests in the test file
    ```
  </Tab>

  <Tab>
    **Example AI Response for Button Component:**

    ```typescript
    // ui/foundation/Button/Button.tsx
    import React from 'react';
    import { TouchableOpacity, Text } from 'react-native';
    import { ButtonProps } from './types';
    import { theme } from '@/core/shared/styles/theme';

    /**
     * Button component for triggering actions
     */
    export const Button: React.FC<ButtonProps> = ({
      children,
      variant = 'primary',
      size = 'medium',
      disabled = false,
      loading = false,
      onPress,
      ...rest
    }) => {
      // Component implementation would go here
      return (
        <TouchableOpacity
          onPress={onPress}
          disabled={disabled || loading}
          {...rest}>
          <Text>{children}</Text>
        </TouchableOpacity>
      );
    };
    ```

    ```typescript
    // ui/foundation/Button/types.ts
    import { TouchableOpacityProps } from 'react-native';

    export type ButtonVariant = 'primary' | 'secondary' | 'ghost' | 'danger';
    export type ButtonSize = 'small' | 'medium' | 'large';

    export interface ButtonProps extends Omit<TouchableOpacityProps, 'style'> {
      /**
       * Button visual variant
       * @default 'primary'
       */
      variant?: ButtonVariant;
      
      /**
       * Button size preset
       * @default 'medium'
       */
      size?: ButtonSize;
      
      /**
       * Whether the button is in loading state
       * @default false
       */
      loading?: boolean;
      
      /**
       * Button content
       */
      children: React.ReactNode;
    }
    ```

    ```typescript
    // ui/foundation/Button/index.ts
    export * from './Button';
    export * from './types';
    ```

    ```typescript
    // ui/foundation/Button/Button.test.tsx
    import React from 'react';
    import { render, fireEvent } from '@testing-library/react-native';
    import { Button } from './Button';

    describe('Button', () => {
      it('renders correctly', () => {
        const { getByText } = render(<Button>Press me</Button>);
        expect(getByText('Press me')).toBeTruthy();
      });
      
      it('calls onPress when pressed', () => {
        const onPressMock = jest.fn();
        const { getByText } = render(
          <Button onPress={onPressMock}>Press me</Button>
        );
        
        fireEvent.press(getByText('Press me'));
        expect(onPressMock).toHaveBeenCalledTimes(1);
      });
      
      it('does not call onPress when disabled', () => {
        const onPressMock = jest.fn();
        const { getByText } = render(
          <Button onPress={onPressMock} disabled>
            Press me
          </Button>
        );
        
        fireEvent.press(getByText('Press me'));
        expect(onPressMock).not.toHaveBeenCalled();
      });
    });
    ```
  </Tab>
</Tabs>

## Step 5: Implement Component

<Callout type="info">
  Component implementation is where planning becomes reality. Following consistent patterns makes components predictable for other developers to use and extend. Implementation should focus on accessibility, performance, and maintainability from the start rather than as an afterthought.
</Callout>

### Component Implementation Principles

<Tabs items={["Implementation Guidelines", "Code Patterns", "Common Pitfalls"]}>
  <Tab>
    When implementing components, follow these key principles:

    **(Do ✅) Core Implementation Practices**

    * **Design Token Usage**: Always use design tokens from our central theme for colors, spacing, typography, etc.
    * **Prop Defaults**: Provide sensible defaults for optional props
    * **Component Composition**: Build components that compose well with others
    * **Accessibility First**: Implement accessibility features from the beginning
    * **Performance Awareness**: Be mindful of re-renders and optimization opportunities
    * **Test Coverage**: Write tests for all key functionality and edge cases

    **(Don't ❌) Implementation Anti-patterns**

    * **Hardcoded Values**: Avoid hardcoded colors, sizes, or spacing values
    * **Overly Complex Components**: Keep components focused on a single responsibility
    * **Direct DOM Manipulation**: Use React's declarative approach instead
    * **Poor Type Safety**: Ensure props have proper TypeScript types
    * **Missing Accessibility**: Don't skip accessibility attributes

    **Implementation Flow**

    1. Set up component props and default values
    2. Implement core rendering logic
    3. Apply styling using design tokens
    4. Add accessibility features
    5. Implement interactions and state management
    6. Optimize for performance
    7. Add comprehensive tests
  </Tab>

  <Tab>
    Here are examples of recommended code patterns for different component types:

    **Foundation Component Pattern**

    ```typescript
    // ui/foundation/Button/Button.tsx
    import React from 'react';
    import { TouchableOpacity, Text, View } from 'react-native';
    import { ButtonProps } from './types';
    import { getStyles } from './styles';

    export const Button = React.forwardRef<View, ButtonProps>((
      {
        children,
        variant = 'primary',
        size = 'medium',
        disabled = false,
        loading = false,
        icon,
        onPress,
        accessibilityLabel,
        testID,
        ...rest
      },
      ref
    ) => {
      const styles = getStyles({ variant, size, disabled });
      
      return (
        <TouchableOpacity
          ref={ref}
          style={styles.container}
          onPress={onPress}
          disabled={disabled || loading}
          accessibilityRole="button"
          accessibilityLabel={accessibilityLabel || typeof children === 'string' ? children : undefined}
          accessibilityState={{ disabled: disabled || loading }}
          testID={testID}
          {...rest}
        >
          {loading && <ActivityIndicator color={styles.spinner.color} />}
          {!loading && icon && <View style={styles.iconContainer}>{icon}</View>}
          {typeof children === 'string' ? (
            <Text style={styles.text}>{children}</Text>
          ) : (
            children
          )}
        </TouchableOpacity>
      );
    });

    Button.displayName = 'Button';
    ```

    **Pattern Component Example**

    ```typescript
    // ui/patterns/Form/Form.tsx
    import React from 'react';
    import { View } from 'react-native';
    import { FormProps, FormContextValue } from './types';
    import { FormContext } from './context';
    import { getStyles } from './styles';

    export const Form = ({
      children,
      onSubmit,
      initialValues = {},
      validate,
      ...rest
    }: FormProps) => {
      const [values, setValues] = React.useState(initialValues);
      const [errors, setErrors] = React.useState({});
      const styles = getStyles();
      
      // Form implementation with context for state management
      const contextValue: FormContextValue = {
        values,
        errors,
        setFieldValue: (name, value) => {
          setValues(prev => ({ ...prev, [name]: value }));
        },
        // Additional context methods would go here
      };
      
      return (
        <FormContext.Provider value={contextValue}>
          <View style={styles.container} {...rest}>
            {children}
          </View>
        </FormContext.Provider>
      );
    };
    ```
  </Tab>

  <Tab>
    These are common implementation issues to avoid:

    **1. Style Inconsistency**

    ```typescript
    // ❌ Bad: Hardcoded styles and values
    <View style={{ 
      backgroundColor: '#0066CC', // Hardcoded color
      padding: 12,               // Hardcoded spacing
      borderRadius: 4            // Hardcoded border radius
    }}>
      <Text style={{ fontSize: 16, fontWeight: 'bold', color: 'white' }}>
        {children}
      </Text>
    </View>

    // ✅ Good: Using design tokens
    <View style={{
      backgroundColor: theme.colors.primary.background,
      padding: spacing.md,
      borderRadius: theme.radii.md
    }}>
      <Text style={{
        fontSize: typography.size.md,
        fontFamily: typography.families.bold,
        color: theme.colors.primary.text
      }}>
        {children}
      </Text>
    </View>
    ```

    **2. Missing Accessibility**

    ```typescript
    // ❌ Bad: No accessibility support
    <TouchableOpacity onPress={onPress}>
      <Text>{children}</Text>
    </TouchableOpacity>

    // ✅ Good: Proper accessibility support
    <TouchableOpacity
      onPress={onPress}
      accessibilityRole="button"
      accessibilityLabel={accessibilityLabel || children}
      accessibilityState={{ disabled: disabled }}
      accessible={true}
    >
      <Text>{children}</Text>
    </TouchableOpacity>
    ```

    **3. Prop Handling**

    ```typescript
    // ❌ Bad: Poor props handling
    function Button(props) {
      return (
        <TouchableOpacity onPress={props.onPress}>
          <Text>{props.children}</Text>
        </TouchableOpacity>
      );
    }

    // ✅ Good: Proper props destructuring with defaults
    function Button({
      children,
      onPress,
      variant = 'primary',
      disabled = false,
      ...rest
    }) {
      // Implementation
    }
    ```
  </Tab>
</Tabs>

## Step 6: Apply Design Tokens

<Callout type="info">
  Design tokens are the visual building blocks of our UI system. Using tokens consistently creates a cohesive user experience and makes it easier to update the design system globally.
</Callout>

<Tabs items={["Token Usage Guide", "Implementation Examples", "Best Practices"]}>
  <Tab>
    Design tokens are centralized design variables that represent the visual properties of our UI. They ensure consistency across the application and enable global style updates with minimal code changes.

    **Key Token Categories**

    * **Colors**: Brand colors, UI states, text colors, backgrounds
    * **Typography**: Font families, sizes, weights, line heights
    * **Spacing**: Margins, padding, gaps
    * **Sizing**: Component dimensions, icon sizes
    * **Borders**: Border widths, radii
    * **Shadows**: Elevation levels, drop shadows
    * **Animation**: Durations, easing functions

    **Token Structure**

    Our tokens are organized hierarchically, from primitive values to semantic tokens:

    1. **Base Tokens**: Raw values (hex colors, pixel values)
    2. **Semantic Tokens**: Purpose-based tokens (primary, danger, success)
    3. **Component Tokens**: Component-specific tokens

    **Token Import Path**

    ```typescript
    // Import all token categories
    import { theme } from '@/core/shared/styles/theme';

    // Or import specific token categories
    import { colors } from '@/core/shared/styles/colors';
    import { spacing } from '@/core/shared/styles/spacing';
    import { typography } from '@/core/shared/styles/typography';
    ```
  </Tab>

  <Tab>
    **Example: Button Component with Design Tokens**

    ```typescript
    // ui/foundation/Button/styles.ts
    import { StyleSheet } from 'react-native';
    import { theme } from '@/core/shared/styles/theme';

    export const getStyles = ({ variant, size, disabled }) => {
      return StyleSheet.create({
        container: {
          backgroundColor: disabled 
            ? theme.colors.disabled.background 
            : theme.colors[variant].background,
          borderRadius: theme.radii.md,
          paddingHorizontal: theme.spacing[size],
          paddingVertical: theme.spacing.xs,
          flexDirection: 'row',
          alignItems: 'center',
          justifyContent: 'center',
          opacity: disabled ? 0.7 : 1,
        },
        text: {
          color: disabled 
            ? theme.colors.disabled.text 
            : theme.colors[variant].text,
          fontSize: theme.typography.size[size],
          fontFamily: theme.typography.families.medium,
          textAlign: 'center',
        },
        iconContainer: {
          marginRight: theme.spacing.xs,
        },
        spinner: {
          color: theme.colors[variant].text,
        },
      });
    };
    ```

    **Example: Card Component with Design Tokens**

    ```typescript
    // ui/foundation/Card/styles.ts
    import { StyleSheet } from 'react-native';
    import { theme } from '@/core/shared/styles/theme';

    export const getStyles = ({ variant }) => {
      return StyleSheet.create({
        container: {
          backgroundColor: theme.colors.surface,
          borderRadius: theme.radii.lg,
          padding: theme.spacing.md,
          ...theme.shadows[variant],
        },
        title: {
          fontFamily: theme.typography.families.bold,
          fontSize: theme.typography.size.lg,
          color: theme.colors.text.primary,
          marginBottom: theme.spacing.sm,
        },
        content: {
          fontFamily: theme.typography.families.regular,
          fontSize: theme.typography.size.md,
          color: theme.colors.text.secondary,
        },
      });
    };
    ```
  </Tab>

  <Tab>
    **(Do ✅) Design Token Best Practices**

    * **Use Semantic Tokens**: Prefer `theme.colors.primary` over raw values like `#0066CC`
    * **Extract Common Styles**: Create style functions for reused patterns
    * **Dynamic Token Selection**: Use props to determine which tokens to apply
    * **Consistent Usage Patterns**: Use the same token patterns across similar components
    * **Platform Adaptations**: Use platform-specific tokens when necessary

    **(Don't ❌) Common Token Mistakes**

    * **Hardcoded Values**: Never use raw color codes, pixel values, or font names
    * **Bypassing the System**: Don't create one-off values outside the token system
    * **Mixing Token Sources**: Don't mix design tokens with hardcoded values
    * **Inconsistent Token Usage**: Don't use different token patterns for similar components
    * **Inline Styles**: Avoid using tokens directly in inline styles; use StyleSheet instead

    **Performance Considerations**

    * Extract style generators outside component functions to prevent recreation on each render
    * Memoize complex style calculations for components that render frequently
    * Consider using `StyleSheet.create()` for style optimization
  </Tab>
</Tabs>

### AI Collaboration: Design Token Implementation

```markdown
# Design Token Implementation

Please help me implement design token-based styling for a [ComponentName] component:

## Component Information
- Component: [ComponentName]
- Category: [foundation/pattern/business]
- Visual States: [list states: default, hover, active, disabled, etc.]

## Design Token Requirements
- Use our theme tokens from @/core/shared/styles/theme
- Create a separate styles.ts file with a getStyles function
- Support the following variants: [list variants]
- Support the following sizes: [list sizes]
- Handle states properly (disabled, focused, etc.)

## Implementation Needs
- Generate the styles.ts file with proper TypeScript types
- Show how to apply these styles in the component
- Demonstrate dynamic style selection based on props
- Add responsive considerations if applicable
```

## Step 7: Implement Accessibility

<Callout type="info">
  Accessibility is a core requirement for all our components, not an optional feature. Implementing accessibility features from the start ensures our components are usable by everyone, including people with disabilities.
</Callout>

<Tabs items={["Accessibility Requirements", "Implementation Examples", "Testing Approach"]}>
  <Tab>
    All components must meet these accessibility requirements:

    1. **Screen Reader Support**
       * Appropriate accessibility roles
       * Meaningful accessibility labels
       * Proper state announcements

    2. **Keyboard Navigation**
       * Focusable interactive elements
       * Visible focus indicators
       * Logical tab order

    3. **Touch Targets**
       * Minimum size of 44×44 points for touch targets
       * Adequate spacing between interactive elements

    4. **Visual Design**
       * Color contrast ratio of at least 4.5:1 for text
       * Not relying on color alone to convey information
       * Support for text scaling and zooming

    5. **Motion and Animation**
       * Respecting reduced motion preferences
       * No flashing content that could trigger seizures
  </Tab>

  <Tab>
    **Example: Accessible Button Component**

    ```typescript
    import React from 'react';
    import { TouchableOpacity, Text, AccessibilityState } from 'react-native';
    import { ButtonProps } from './types';

    export const Button = ({
      children,
      onPress,
      disabled = false,
      loading = false,
      accessibilityLabel,
      accessibilityHint,
      ...rest
    }: ButtonProps) => {
      // Determine accessibility state
      const accessibilityState: AccessibilityState = {
        disabled: disabled || loading,
        busy: loading
      };
      
      // Determine appropriate label
      const label = accessibilityLabel || 
        (typeof children === 'string' ? children : undefined);
      
      // Add loading state to label if needed
      const fullAccessibilityLabel = loading 
        ? `${label}, loading` 
        : label;
      
      return (
        <TouchableOpacity
          // Core accessibility props
          accessible={true}
          accessibilityRole="button"
          accessibilityLabel={fullAccessibilityLabel}
          accessibilityHint={accessibilityHint}
          accessibilityState={accessibilityState}
          
          // Ensure adequate touch target size
          hitSlop={{ top: 8, bottom: 8, left: 8, right: 8 }}
          
          // Core button props
          onPress={onPress}
          disabled={disabled || loading}
          {...rest}
        >
          <Text>{children}</Text>
        </TouchableOpacity>
      );
    };
    ```

    **Example: Accessible Form Field**

    ```typescript
    import React from 'react';
    import { View, TextInput, Text } from 'react-native';
    import { InputProps } from './types';

    export const Input = ({
      label,
      value,
      onChangeText,
      error,
      required = false,
      ...rest
    }: InputProps) => {
      const inputId = React.useId();
      
      return (
        <View>
          <Text
            nativeID={`${inputId}-label`}
            accessibilityRole="text"
          >
            {label}{required && ' *'}
          </Text>
          
          <TextInput
            value={value}
            onChangeText={onChangeText}
            
            // Associate with label
            accessibilityLabel={label}
            accessibilityLabelledBy={`${inputId}-label`}
            
            // Communicate validation state
            accessibilityState={{
              invalid: !!error,
              required
            }}
            
            // Communicate error
            accessibilityErrorMessage={error}
            
            {...rest}
          />
          
          {error && (
            <Text
              accessibilityRole="alert"
              nativeID={`${inputId}-error`}
            >
              {error}
            </Text>
          )}
        </View>
      );
    };
    ```
  </Tab>

  <Tab>
    **Manual Testing Process**

    1. **Screen Reader Testing**
       * Enable VoiceOver (iOS) or TalkBack (Android)
       * Navigate through the component
       * Verify all relevant information is announced
       * Test all interactive states (default, focused, disabled, loading)

    2. **Keyboard Navigation Testing**
       * Connect a keyboard to your device
       * Verify the component can be focused using Tab
       * Verify the component can be activated using Enter/Space
       * Check that focus order is logical

    3. **Touch Target Testing**
       * Verify interactive areas are large enough (44×44pts minimum)
       * Check spacing between interactive elements
       * Test edge cases like small screens

    **Automated Testing Approach**

    ```typescript
    import { render } from '@testing-library/react-native';
    import { Button } from './Button';

    describe('Button accessibility', () => {
      it('has correct accessibility role', () => {
        const { getByRole } = render(<Button>Press me</Button>);
        const button = getByRole('button');
        expect(button).toBeTruthy();
      });
      
      it('has correct accessibility label', () => {
        const { getByA11yLabel } = render(<Button>Press me</Button>);
        expect(getByA11yLabel('Press me')).toBeTruthy();
      });
      
      it('communicates disabled state', () => {
        const { getByA11yState } = render(
          <Button disabled>Press me</Button>
        );
        expect(getByA11yState({ disabled: true })).toBeTruthy();
      });
      
      it('communicates loading state', () => {
        const { getByA11yState } = render(
          <Button loading>Press me</Button>
        );
        expect(getByA11yState({ busy: true })).toBeTruthy();
      });
    });
    ```
  </Tab>
</Tabs>

### AI Collaboration: Accessibility Implementation

```markdown
# Accessibility Implementation

Please help me implement accessibility features for a [ComponentName] component:

## Component Information
- Component: [ComponentName]
- Category: [foundation/pattern/business]
- Purpose: [brief description of component purpose]
- Interactive Elements: [describe interactive parts]

## Accessibility Requirements
- Screen reader support needs
- Keyboard navigation requirements
- Touch target considerations
- State communication needs (loading, error, disabled, etc.)

## Implementation Needs
- Add appropriate accessibilityRole
- Implement accessibilityLabel and accessibilityHint
- Configure accessibilityState for different component states
- Add proper focus management if applicable
- Ensure appropriate touch target sizes

Please provide a complete implementation showing all necessary accessibility attributes and any special handling required.
```

## Development Phase Summary

The development phase transforms your planning into working code. By following this structured approach, you ensure:

* Consistent component structure across the codebase
* Proper implementation with design tokens and accessibility
* Components that are maintainable and extensible
* Code that follows established patterns and best practices

## Next Steps

Once you've completed the development phase:

1. **Test Your Implementation**: Write comprehensive tests for your component
2. **Review Your Code**: Use the self-review checklist before requesting team review
3. **Document Your Component**: Create clear documentation for other developers
4. **Move to Testing Phase**: Proceed to the [Testing Strategies](/docs/ui-development/architecture/development-workflow/testing-strategies) phase

## Related Documents

* [Component Patterns](/docs/ui-development/development/component-patterns) - Common patterns and best practices
* [Foundation Components Guide](/docs/ui-development/architecture/foundation-guide) - Building atomic UI components
* [Testing Patterns](/docs/ui-development/development/testing-patterns) - Comprehensive testing strategies
* [AI Collaboration Guide](/docs/ui-development/architecture/ai-collaboration) - Working effectively with AI


# UTA UI Development: Testing Strategies
URL: https://dev.updatetheapp.com/docs/ui-development/architecture/development-workflow/testing-strategies
Documentation: https://dev.updatetheapp.com/docs/ui-development/architecture/development-workflow/testing-strategies

Write unit tests, visual tests, accessibility tests, and integration tests for your components.
        
***

title: Testing Strategies
description: Write unit tests, visual tests, accessibility tests, and integration tests for your components.
------------------------------------------------------------------------------------------------------------

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Callout } from 'fumadocs-ui/components/callout';
import { Steps, Step } from 'fumadocs-ui/components/steps';

# Testing Strategies

## Overview

Testing is an essential part of the component development process. A well-tested component is more reliable, easier to maintain, and less likely to cause issues when used in different contexts. This guide covers comprehensive testing strategies for React Native components.

<Callout type="info">
  **Why Testing Matters**

  Testing is an essential part of the component development process. A well-tested component is more reliable, easier to maintain, and less likely to cause issues when used in different contexts.
</Callout>

## Step 8: Implement Component Tests

Our testing approach ensures component quality through multiple levels of verification, from unit tests to accessibility compliance.

<Tabs items={["Testing Strategy", "Test Implementation Examples", "Test Coverage Goals"]}>
  <Tab>
    Our testing approach includes multiple levels to ensure component quality:

    1. **Unit Testing**
       * Test individual functions and methods
       * Verify prop handling and default values
       * Test component state management

    2. **Component Testing**
       * Test component rendering
       * Verify component interactions
       * Test different prop combinations

    3. **Integration Testing**
       * Test interaction with other components
       * Verify context and provider integration
       * Test real-world usage scenarios

    4. **Accessibility Testing**
       * Verify screen reader compatibility
       * Test keyboard navigation
       * Check WCAG compliance

    5. **Visual Testing**
       * Snapshot testing for UI regressions
       * Platform-specific rendering verification
       * Theme and style verification
  </Tab>

  <Tab>
    **Unit Test Example**

    ```typescript
    // ui/foundation/Button/Button.test.tsx
    import React from 'react';
    import { render, fireEvent } from '@testing-library/react-native';
    import { Button } from './Button';

    describe('Button', () => {
      it('renders correctly with default props', () => {
        const { getByText } = render(<Button>Press Me</Button>);
        expect(getByText('Press Me')).toBeTruthy();
      });
      
      it('calls onPress when pressed', () => {
        const onPressMock = jest.fn();
        const { getByText } = render(
          <Button onPress={onPressMock}>Press Me</Button>
        );
        
        fireEvent.press(getByText('Press Me'));
        expect(onPressMock).toHaveBeenCalledTimes(1);
      });
      
      it('applies correct styles based on variant', () => {
        const { getByTestId } = render(
          <Button variant="secondary" testID="test-button">Press Me</Button>
        );
        
        const button = getByTestId('test-button');
        // Check style properties based on theme tokens
        expect(button.props.style).toMatchObject({
          backgroundColor: expect.any(String), // theme.colors.secondary
        });
      });
      
      it('does not call onPress when disabled', () => {
        const onPressMock = jest.fn();
        const { getByText } = render(
          <Button onPress={onPressMock} disabled>
            Press Me
          </Button>
        );
        
        fireEvent.press(getByText('Press Me'));
        expect(onPressMock).not.toHaveBeenCalled();
      });
    });
    ```

    **Snapshot Test Example**

    ```typescript
    // ui/foundation/Card/Card.test.tsx
    import React from 'react';
    import { render } from '@testing-library/react-native';
    import { Card } from './Card';

    describe('Card', () => {
      it('matches snapshot with default props', () => {
        const { toJSON } = render(
          <Card>
            <Text>Card Content</Text>
          </Card>
        );
        expect(toJSON()).toMatchSnapshot();
      });
      
      it('matches snapshot with custom props', () => {
        const { toJSON } = render(
          <Card variant="elevated" padding="large">
            <Text>Card Content</Text>
          </Card>
        );
        expect(toJSON()).toMatchSnapshot();
      });
    });
    ```
  </Tab>

  <Tab>
    **(Do ✅) Testing Best Practices**

    * **Test Component API**: Verify all props work as expected
    * **Test User Interactions**: Test all interactive elements
    * **Test Edge Cases**: Test empty states, loading states, error states
    * **Test Accessibility**: Verify screen reader support and keyboard navigation
    * **Keep Tests Focused**: Each test should verify a single aspect of the component
    * **Use Descriptive Test Names**: Make it clear what each test is verifying
    * **Mock External Dependencies**: Isolate component tests from external services

    **(Don't ❌) Testing Anti-patterns**

    * **Testing Implementation Details**: Focus on behavior, not implementation
    * **Brittle Tests**: Avoid tests that break with minor changes
    * **Overlapping Tests**: Don't test the same functionality multiple times
    * **Missing Key Scenarios**: Don't ignore important user flows
    * **Testing Library Internals**: Don't test third-party libraries

    **Test Coverage Goals**

    * **Foundation Components**: 90-100% coverage
    * **Pattern Components**: 80-100% coverage
    * **Business Components**: 70-90% coverage
    * **Core Functionality**: 100% coverage
    * **Edge Cases**: 90-100% coverage
  </Tab>
</Tabs>

## Types of Component Tests

### 1. Rendering Tests

Verify that components render correctly with different prop combinations:

```typescript
// ui/foundation/Badge/Badge.test.tsx
import React from 'react';
import { render } from '@testing-library/react-native';
import { Badge } from './Badge';

describe('Badge Rendering', () => {
  it('renders with default props', () => {
    const { getByText } = render(<Badge>New</Badge>);
    expect(getByText('New')).toBeTruthy();
  });

  it('renders all variants correctly', () => {
    const variants = ['primary', 'success', 'warning', 'error'] as const;
    
    variants.forEach(variant => {
      const { getByTestId } = render(
        <Badge variant={variant} testID={`badge-${variant}`}>
          Test
        </Badge>
      );
      
      const badge = getByTestId(`badge-${variant}`);
      expect(badge).toBeTruthy();
      // Verify variant-specific styles are applied
    });
  });

  it('renders with custom props', () => {
    const { getByTestId } = render(
      <Badge 
        size="large" 
        rounded 
        testID="custom-badge"
      >
        Custom
      </Badge>
    );
    
    const badge = getByTestId('custom-badge');
    expect(badge).toBeTruthy();
  });
});
```

### 2. Interaction Tests

Test user interactions and event handling:

```typescript
// ui/patterns/Accordion/Accordion.test.tsx
import React from 'react';
import { render, fireEvent, waitFor } from '@testing-library/react-native';
import { Accordion } from './Accordion';

describe('Accordion Interactions', () => {
  const mockItems = [
    { title: 'Section 1', content: 'Content 1' },
    { title: 'Section 2', content: 'Content 2' },
  ];

  it('expands and collapses sections on press', async () => {
    const { getByText, queryByText } = render(
      <Accordion items={mockItems} />
    );
    
    // Initially collapsed
    expect(queryByText('Content 1')).toBeNull();
    
    // Expand section
    fireEvent.press(getByText('Section 1'));
    await waitFor(() => {
      expect(getByText('Content 1')).toBeTruthy();
    });
    
    // Collapse section
    fireEvent.press(getByText('Section 1'));
    await waitFor(() => {
      expect(queryByText('Content 1')).toBeNull();
    });
  });

  it('handles multiple sections correctly', () => {
    const { getByText } = render(
      <Accordion items={mockItems} allowMultiple />
    );
    
    // Expand both sections
    fireEvent.press(getByText('Section 1'));
    fireEvent.press(getByText('Section 2'));
    
    // Both should be visible
    expect(getByText('Content 1')).toBeTruthy();
    expect(getByText('Content 2')).toBeTruthy();
  });
});
```

### 3. State Management Tests

Test component state and lifecycle:

```typescript
// ui/patterns/Form/Form.test.tsx
import React from 'react';
import { render, fireEvent, act } from '@testing-library/react-native';
import { Form, FormField } from './Form';

describe('Form State Management', () => {
  it('manages form values correctly', () => {
    const onSubmit = jest.fn();
    const { getByPlaceholderText, getByText } = render(
      <Form onSubmit={onSubmit}>
        <FormField 
          name="email" 
          placeholder="Email"
        />
        <FormField 
          name="password" 
          placeholder="Password"
          secureTextEntry
        />
        <Button onPress={() => {}}>Submit</Button>
      </Form>
    );
    
    // Update form fields
    fireEvent.changeText(
      getByPlaceholderText('Email'), 
      'test@example.com'
    );
    fireEvent.changeText(
      getByPlaceholderText('Password'), 
      'password123'
    );
    
    // Submit form
    fireEvent.press(getByText('Submit'));
    
    expect(onSubmit).toHaveBeenCalledWith({
      email: 'test@example.com',
      password: 'password123'
    });
  });

  it('validates form fields', async () => {
    const validate = (values: any) => {
      const errors: any = {};
      if (!values.email) errors.email = 'Email is required';
      return errors;
    };
    
    const { getByText, getByTestId } = render(
      <Form validate={validate}>
        <FormField 
          name="email" 
          testID="email-field"
        />
        <Button onPress={() => {}}>Submit</Button>
      </Form>
    );
    
    // Try to submit without filling required field
    fireEvent.press(getByText('Submit'));
    
    await waitFor(() => {
      expect(getByText('Email is required')).toBeTruthy();
    });
  });
});
```

### 4. Accessibility Tests

Ensure components are accessible to all users:

```typescript
// ui/foundation/Button/Button.accessibility.test.tsx
import React from 'react';
import { render } from '@testing-library/react-native';
import { Button } from './Button';

describe('Button Accessibility', () => {
  it('has correct accessibility role', () => {
    const { getByRole } = render(<Button>Press me</Button>);
    const button = getByRole('button');
    expect(button).toBeTruthy();
  });
  
  it('has correct accessibility label', () => {
    const { getByLabelText } = render(
      <Button accessibilityLabel="Save changes">Save</Button>
    );
    expect(getByLabelText('Save changes')).toBeTruthy();
  });
  
  it('uses button text as label when no accessibilityLabel provided', () => {
    const { getByLabelText } = render(<Button>Click here</Button>);
    expect(getByLabelText('Click here')).toBeTruthy();
  });
  
  it('communicates disabled state', () => {
    const { getByRole } = render(
      <Button disabled>Press me</Button>
    );
    const button = getByRole('button');
    expect(button.props.accessibilityState.disabled).toBe(true);
  });
  
  it('communicates loading state', () => {
    const { getByRole } = render(
      <Button loading>Press me</Button>
    );
    const button = getByRole('button');
    expect(button.props.accessibilityState.busy).toBe(true);
  });

  it('has adequate touch target size', () => {
    const { getByRole } = render(<Button>Tap</Button>);
    const button = getByRole('button');
    const { height, width } = button.props.style;
    
    // Minimum 44x44 points for touch targets
    expect(height).toBeGreaterThanOrEqual(44);
    expect(width).toBeGreaterThanOrEqual(44);
  });
});
```

### 5. Visual Regression Tests

Catch unintended visual changes:

```typescript
// ui/foundation/Card/Card.visual.test.tsx
import React from 'react';
import { render } from '@testing-library/react-native';
import { Card } from './Card';

describe('Card Visual Regression', () => {
  const variants = ['default', 'elevated', 'outlined'] as const;
  const sizes = ['small', 'medium', 'large'] as const;

  variants.forEach(variant => {
    sizes.forEach(size => {
      it(`matches snapshot for ${variant} variant with ${size} size`, () => {
        const { toJSON } = render(
          <Card variant={variant} size={size}>
            <Text>Card Content</Text>
            <Text>Additional content for testing</Text>
          </Card>
        );
        
        expect(toJSON()).toMatchSnapshot();
      });
    });
  });

  it('matches snapshot with all props', () => {
    const { toJSON } = render(
      <Card
        variant="elevated"
        size="large"
        padding="medium"
        onPress={() => {}}
      >
        <Text>Interactive Card</Text>
      </Card>
    );
    
    expect(toJSON()).toMatchSnapshot();
  });
});
```

### 6. Performance Tests

Ensure components perform well:

```typescript
// ui/patterns/VirtualizedList/VirtualizedList.performance.test.tsx
import React from 'react';
import { render, measure } from '@testing-library/react-native';
import { VirtualizedList } from './VirtualizedList';

describe('VirtualizedList Performance', () => {
  const generateItems = (count: number) => 
    Array.from({ length: count }, (_, i) => ({
      id: `item-${i}`,
      title: `Item ${i}`,
    }));

  it('renders large lists efficiently', async () => {
    const items = generateItems(1000);
    
    const renderTime = await measure(() => {
      render(
        <VirtualizedList
          data={items}
          renderItem={({ item }) => <Text>{item.title}</Text>}
          keyExtractor={item => item.id}
        />
      );
    });
    
    // Should render in under 100ms
    expect(renderTime).toBeLessThan(100);
  });

  it('handles rapid scrolling without lag', async () => {
    const items = generateItems(5000);
    const { getByTestId } = render(
      <VirtualizedList
        testID="list"
        data={items}
        renderItem={({ item }) => <Text>{item.title}</Text>}
        keyExtractor={item => item.id}
      />
    );
    
    const list = getByTestId('list');
    
    // Simulate rapid scrolling
    const scrollPerformance = await measure(() => {
      for (let i = 0; i < 10; i++) {
        fireEvent.scroll(list, {
          nativeEvent: {
            contentOffset: { y: i * 1000 },
          },
        });
      }
    });
    
    // Should handle scrolling smoothly
    expect(scrollPerformance).toBeLessThan(50);
  });
});
```

## Test Organization

### Test File Structure

Organize tests alongside components for easy maintenance:

```
ui/foundation/Button/
├── Button.tsx
├── Button.test.tsx              # Main component tests
├── Button.accessibility.test.tsx # Accessibility-specific tests
├── Button.visual.test.tsx       # Visual regression tests
├── Button.performance.test.tsx  # Performance tests (if needed)
└── __snapshots__/              # Jest snapshots
```

### Test Utilities

Create shared test utilities for common scenarios:

```typescript
// ui/test-utils/render.tsx
import React from 'react';
import { render as rtlRender } from '@testing-library/react-native';
import { ThemeProvider } from '@/core/shared/contexts/ThemeContext';

export function render(
  ui: React.ReactElement,
  options?: any
) {
  const Wrapper = ({ children }: { children: React.ReactNode }) => (
    <ThemeProvider>
      {children}
    </ThemeProvider>
  );

  return rtlRender(ui, { wrapper: Wrapper, ...options });
}

// Re-export everything
export * from '@testing-library/react-native';
```

### Mock Utilities

Create consistent mocks for common dependencies:

```typescript
// ui/test-utils/mocks.ts
export const mockNavigation = {
  navigate: jest.fn(),
  goBack: jest.fn(),
  setOptions: jest.fn(),
};

export const mockTheme = {
  colors: {
    primary: { 
      500: '#3b82f6',
      600: '#2563eb',
    },
    // ... other colors
  },
  spacing: {
    xs: 4,
    sm: 8,
    md: 16,
    lg: 24,
  },
  // ... other theme properties
};
```

## AI Collaboration: Test Implementation

Use AI to help generate comprehensive test suites:

```markdown
# Component Test Implementation

Please help me create tests for a [ComponentName] component:

## Component Information
- Component: [ComponentName]
- Category: [foundation/pattern/business]
- Key Props: [list main props]
- User Interactions: [describe key interactions]

## Testing Requirements
- Unit tests for props and rendering
- Interaction tests for user actions
- Snapshot tests for UI verification
- Accessibility tests
- Edge case tests

## Implementation Needs
- Set up test boilerplate with proper imports
- Create comprehensive test cases
- Implement proper mocks for dependencies
- Show how to test each key component feature
- Include examples for async behavior testing if needed

Please provide a complete test implementation for this component.
```

## Testing Best Practices Summary

<Tabs items={["Do's", "Don'ts", "Tips"]}>
  <Tab>
    **(Do ✅) Testing Best Practices**

    * Write tests alongside implementation
    * Test from the user's perspective
    * Cover all component states and variations
    * Include accessibility in your test suite
    * Use descriptive test names that explain the scenario
    * Mock external dependencies appropriately
    * Keep tests focused and isolated
    * Test error scenarios and edge cases
  </Tab>

  <Tab>
    **(Don't ❌) Testing Anti-patterns**

    * Test implementation details that may change
    * Write tests that depend on component internals
    * Create overly complex test setups
    * Skip testing "simple" components
    * Ignore accessibility testing
    * Write tests after bugs are found
    * Test third-party library functionality
    * Rely solely on snapshot tests
  </Tab>

  <Tab>
    **(Consider 🤔) Testing Pro Tips**

    * Use test.each for testing multiple scenarios
    * Create custom matchers for common assertions
    * Set up continuous integration for test runs
    * Monitor test coverage trends over time
    * Review tests during code reviews
    * Refactor tests when they become hard to maintain
    * Use visual regression testing for UI-heavy components
    * Consider property-based testing for complex logic
  </Tab>
</Tabs>

## Next Steps

After completing your component tests:

1. **Run the Full Test Suite**: Ensure all tests pass consistently
2. **Check Coverage**: Verify you meet coverage requirements
3. **Review Test Quality**: Ensure tests are meaningful and maintainable
4. **Move to Review Phase**: Proceed to the [Review Process](/docs/ui-development/architecture/development-workflow/review-process) phase

## Related Documents

* [Testing Patterns](/docs/ui-development/development/testing-patterns) - Comprehensive testing strategies
* [Component Patterns](/docs/ui-development/development/component-patterns) - Component implementation patterns
* [Accessibility Guide](/docs/ui-development/accessibility) - Accessibility testing requirements
* [AI Collaboration Guide](/docs/ui-development/architecture/ai-collaboration) - AI-assisted test generation


# UTA UI Development: Component Review Process
URL: https://dev.updatetheapp.com/docs/ui-development/architecture/development-workflow/review-process
Documentation: https://dev.updatetheapp.com/docs/ui-development/architecture/development-workflow/review-process

Self-review, peer review, and QA testing procedures to ensure UI component quality.
        
***

title: Component Review Process
description: Self-review, peer review, and QA testing procedures to ensure UI component quality.
------------------------------------------------------------------------------------------------

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Callout } from 'fumadocs-ui/components/callout';
import { Steps, Step } from 'fumadocs-ui/components/steps';

# Component Review Process

## Overview

The review process ensures components meet quality standards before deployment. Through systematic reviews at multiple levels, we maintain high code quality and catch issues early.

<Callout type="info">
  **Quality Gates**

  The review process acts as quality gates, ensuring components are production-ready before deployment. Each review level catches different types of issues, from code quality to user experience problems.
</Callout>

## Purpose & Scope

<Tabs items={["What You'll Learn", "Who This Is For", "When To Apply"]}>
  <Tab>
    * Comprehensive self-review techniques
    * Peer review best practices
    * QA testing procedures
    * Review documentation templates
  </Tab>

  <Tab>
    * UI component developers
    * Code reviewers
    * QA engineers
    * Team leads managing code quality
  </Tab>

  <Tab>
    This process should be followed:

    * Before submitting any new component
    * When making significant changes to existing components
    * As part of standard development workflow
  </Tab>
</Tabs>

## Step 1: Self Review

Before submitting for review, complete a thorough self-review:

<Tabs items={["Checklist Overview", "Code Quality Check", "Testing Verification"]}>
  <Tab>
    **Self Review Checklist**

    A comprehensive self-review catches issues early and saves time during peer review. Use this checklist to ensure your component is ready:

    **Code Quality**

    * [ ] Component follows our architecture rules
    * [ ] All props have proper TypeScript types
    * [ ] JSDoc comments are comprehensive and accurate
    * [ ] No hardcoded values - all styling uses design tokens
    * [ ] Performance optimizations applied (React.memo, useMemo)
    * [ ] Error boundaries and error handling implemented

    **Functionality**

    * [ ] All required functionality implemented
    * [ ] Edge cases handled appropriately
    * [ ] Loading and error states work correctly
    * [ ] Component handles all prop combinations
    * [ ] Default values work as expected

    **Testing**

    * [ ] All tests pass
    * [ ] Test coverage meets requirements (80%+)
    * [ ] Accessibility tests included
    * [ ] Visual regression tests added
    * [ ] Integration tests work

    **Documentation**

    * [ ] Component props documented with examples
    * [ ] Usage examples provided
    * [ ] Integration patterns documented
    * [ ] Migration notes added if applicable
  </Tab>

  <Tab>
    **Code Quality Verification**

    Run these commands to verify code quality:

    ```bash
    # TypeScript type checking
    npx tsc --noEmit

    # Linting check
    npm run lint:ui

    # Format check
    npm run format:check

    # Bundle size check
    npm run analyze:bundle -- --component=ComponentName
    ```

    **Common Issues to Check**

    1. **Architecture Compliance**
       * Component in correct category folder
       * Proper file structure maintained
       * Exports follow conventions

    2. **Design Token Usage**
       ```typescript
       // ❌ Bad: Hardcoded values
       style={{ color: '#333', padding: 16 }}

       // ✅ Good: Design tokens
       style={{ 
         color: theme.colors.text.primary,
         padding: theme.spacing.md 
       }}
       ```

    3. **TypeScript Quality**
       * No `any` types without justification
       * Proper generic constraints
       * Exhaustive type checking
  </Tab>

  <Tab>
    **Test Coverage Verification**

    Ensure comprehensive test coverage:

    ```bash
    # Run tests with coverage
    npm test -- --coverage --testPathPattern=ComponentName

    # Check coverage thresholds
    # Foundation: 90-100%
    # Patterns: 80-100%
    # Business: 70-90%
    ```

    **Key Testing Areas**

    1. **Unit Tests**
       * All props tested
       * State changes verified
       * Event handlers called correctly

    2. **Accessibility Tests**
       * Screen reader compatibility
       * Keyboard navigation
       * Focus management
       * WCAG compliance

    3. **Visual Tests**
       * Snapshot tests for all variants
       * Platform-specific rendering
       * Theme variations

    4. **Integration Tests**
       * Works with providers
       * Navigation integration
       * State management compatibility
  </Tab>
</Tabs>

## Step 2: Peer Review

Submit component for peer review with clear context:

<Tabs items={["Review Template", "Focus Areas", "Review Process"]}>
  <Tab>
    **Peer Review Template**

    Use this template when creating your pull request:

    ```markdown
    ## Component Review: [ComponentName]

    ### Overview
    - **Type**: [Foundation/Pattern/Business] Component
    - **Purpose**: [Brief description of what the component does]
    - **Dependencies**: [List of key dependencies]
    - **New/Modified**: [New component or modification to existing]

    ### Changes
    - [List of key changes or features implemented]
    - [Design requirements addressed]
    - [Edge cases handled]

    ### Technical Details
    - **Architecture**: [Description of component architecture]
    - **Props API**: [Key props and their purpose]
    - **State Management**: [How state is managed]
    - **Performance Considerations**: [Optimizations applied]

    ### Testing
    - **Coverage**: [Test coverage percentage]
    - **Key Scenarios**: [Main test cases]
    - **Edge Cases**: [Unusual scenarios tested]
    - **Accessibility**: [a11y test results]

    ### Self-Review Checklist
    - [ ] Architecture compliance verified
    - [ ] All design tokens used (no hardcoded values)
    - [ ] TypeScript types complete and accurate
    - [ ] Tests pass with good coverage
    - [ ] Accessibility requirements met
    - [ ] Documentation complete
    - [ ] No console warnings/errors

    ### Screenshots/Videos
    [Add screenshots or videos showing the component in action]

    ### Questions for Reviewers
    1. [Specific question about implementation]
    2. [Question about API design]
    3. [Question about accessibility approach]

    ### Related Issues
    - Resolves #[issue-number]
    - Related to #[issue-number]
    ```
  </Tab>

  <Tab>
    **Code Review Focus Areas**

    Reviewers should pay special attention to these areas:

    **1. Architecture Compliance**

    * Component placed in correct folder
    * Follows naming conventions
    * Proper import/export patterns
    * No architecture rule violations

    **2. Design Token Usage**

    * All colors use theme tokens
    * Typography follows token system
    * Spacing uses consistent tokens
    * No hardcoded values

    **3. Accessibility**

    * Proper semantic roles
    * Screen reader support
    * Keyboard navigation
    * Focus management

    **4. Performance**

    * Appropriate memoization
    * Efficient re-rendering
    * Bundle size impact
    * Runtime performance

    **5. API Design**

    * Consistent with existing components
    * Intuitive prop names
    * Proper TypeScript types
    * Good defaults
    * Extensibility considered
  </Tab>

  <Tab>
    **Review Process Flow**

    <Steps>
      <Step>
        #### Submit PR with Complete Context

        * Use the review template
        * Include all relevant information
        * Add screenshots/videos
        * Link related issues
      </Step>

      <Step>
        #### Initial Review (24-48 hours)

        * Reviewers examine code quality
        * Architecture compliance checked
        * API design reviewed
        * Performance considerations assessed
      </Step>

      <Step>
        #### Address Feedback (Iterative)

        * Respond to all comments
        * Make requested changes
        * Explain design decisions
        * Update tests as needed
      </Step>

      <Step>
        #### Final Approval

        * All comments addressed
        * Tests passing
        * Documentation complete
        * Ready for QA review
      </Step>
    </Steps>

    **(Do ✅) Good Review Practices**

    * Provide constructive feedback
    * Suggest specific improvements
    * Acknowledge good patterns
    * Ask clarifying questions
    * Consider the bigger picture

    **(Don't ❌) Review Anti-patterns**

    * Nitpick without substance
    * Block on personal preferences
    * Ignore the PR template
    * Rush through reviews
    * Approve without testing
  </Tab>
</Tabs>

## Step 3: QA Review

Components undergo QA testing across devices and scenarios:

<Tabs items={["QA Checklist", "Testing Scenarios", "Issue Reporting"]}>
  <Tab>
    **QA Testing Checklist**

    **Cross-Platform Testing**

    * [ ] iOS device testing (iPhone SE, iPhone 14 Pro, iPad)
    * [ ] Android device testing (Small, Medium, Large screens)
    * [ ] Web browser testing (if applicable)

    **Visual Testing**

    * [ ] Dark/light theme switching
    * [ ] RTL language support
    * [ ] Different text sizes
    * [ ] Font scaling
    * [ ] Color contrast meets WCAG

    **Interaction Testing**

    * [ ] Touch/click interactions
    * [ ] Swipe/drag gestures
    * [ ] Keyboard navigation
    * [ ] Screen reader functionality

    **Performance Testing**

    * [ ] Load time \< 100ms
    * [ ] Smooth animations (60fps)
    * [ ] No jank on interaction
    * [ ] No memory leaks

    **Integration Testing**

    * [ ] Works within features
    * [ ] Integrates with navigation
    * [ ] State management integration
    * [ ] API integration (business components)
    * [ ] Theme switching works
  </Tab>

  <Tab>
    **Testing Scenarios**

    **Visual Testing**

    ```markdown
    1. Component renders correctly in all states:
       - Default state
       - Hover/pressed states
       - Disabled state
       - Loading state
       - Error state

    2. Theme compatibility:
       - Light theme
       - Dark theme
       - Custom themes
       - High contrast mode

    3. Text handling:
       - Short text
       - Long text
       - Multi-line text
       - Different font sizes
       - RTL languages
       - Special characters

    4. Layout testing:
       - Different screen sizes
       - Landscape/portrait
       - Inside scroll views
       - Within nested components
       - With/without flex containers
    ```

    **Accessibility Testing**

    ```markdown
    1. Screen reader support:
       - VoiceOver (iOS)
       - TalkBack (Android)
       - Labels read correctly
       - Actions described properly

    2. Keyboard navigation:
       - Tab order logical
       - Focus visible and clear
       - Keyboard actions work
       - No keyboard traps

    3. Touch targets:
       - At least 44x44pt
       - Clear tap feedback
       - No overlapping targets
       - Edge case handling
    ```

    **Performance Testing**

    ```markdown
    1. Rendering performance:
       - Initial render time
       - Re-render time
       - Animation smoothness
       - Multiple instances on screen

    2. Data handling:
       - Empty data
       - Single item
       - Maximum items
       - Long text content
       - Special characters

    2. Network conditions:
       - Fast connection
       - Slow 3G
       - Offline mode
       - Request failures

    3. Device constraints:
       - Low memory
       - Battery saver mode
       - Limited storage
       - Background/foreground
    ```
  </Tab>

  <Tab>
    **Issue Reporting Template**

    When reporting issues, follow this template:

    ```markdown
    ## Component Issue Report

    **Component Name**: [Name]
    **Component Version**: [Version]
    **Environment**:
    - Platform: iOS/Android/Web
    - Device/OS: [Device model / OS version]
    - Screen size: [Size in points/pixels]

    **Issue Description**:
    [Clear description of the problem]

    **Expected Behavior**:
    [What should happen]

    **Actual Behavior**:
    [What actually happens]

    **Reproduction Steps**:
    1. [Step 1]
    2. [Step 2]
    3. [Step 3]

    **Visual Evidence**:
    [Screenshots or videos]

    **Severity**:
    [Critical/High/Medium/Low]

    **Impact**:
    [How this affects users]

    **Suggested Fix**:
    [If you have ideas]
    ```

    **Issue Prioritization Criteria**

    * **P0 (Critical)**: Crashes, unusable component, data loss
    * **P1 (High)**: Major functional issue, serious visual problems
    * **P2 (Medium)**: Minor functional issues, visual inconsistencies
    * **P3 (Low)**: Cosmetic issues, enhancements, edge cases
  </Tab>
</Tabs>

## Next Steps

After completing the review process:

1. Proceed with [final documentation and deployment](/docs/ui-development/architecture/development-workflow/deployment-integration)
2. Prepare for feature integration
3. Document any learnings from the review process

## Related Documents

* [Development Phase](/docs/ui-development/architecture/development-workflow/development-phase) - Implementation details
* [Deployment Integration](/docs/ui-development/architecture/development-workflow/deployment-integration) - Next steps after review
* [Testing Strategies](/docs/ui-development/architecture/development-workflow/testing-strategies) - Comprehensive testing
* [UI Architecture Standards](/docs/ui-development/architecture/standards) - Quality requirements


# UTA UI Development: Component Deployment & Integration
URL: https://dev.updatetheapp.com/docs/ui-development/architecture/development-workflow/deployment-integration
Documentation: https://dev.updatetheapp.com/docs/ui-development/architecture/development-workflow/deployment-integration

Completing documentation, integrating into features, and deploying UI components into production.
        
***

title: Component Deployment & Integration
description: Completing documentation, integrating into features, and deploying UI components into production.
--------------------------------------------------------------------------------------------------------------

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Callout } from 'fumadocs-ui/components/callout';
import { Steps, Step } from 'fumadocs-ui/components/steps';

# Component Deployment & Integration

## Overview

After passing all review stages, components must be properly documented, integrated into features, and deployed. This document covers the processes for smooth integration and reliable deployment.

<Callout type="info">
  **Consistent Integration**

  Consistent deployment and integration practices ensure that components behave reliably across all features and environments. These steps bridge the gap between development and production use.
</Callout>

## Purpose & Scope

<Tabs items={["What You'll Learn", "Who This Is For", "When To Apply"]}>
  <Tab>
    * Documentation requirements and best practices
    * Feature integration patterns
    * Component release processes
    * Versioning and change management
  </Tab>

  <Tab>
    * UI component developers
    * Feature developers
    * Documentation writers
    * Release managers
  </Tab>

  <Tab>
    Follow these processes:

    * After component review is complete
    * Before merging to main branch
    * When preparing releases
    * When updating production applications
  </Tab>
</Tabs>

## Step 1: Final Documentation

Documentation is a critical part of component deployment:

<Tabs items={["Documentation Requirements", "Storybook Integration", "Examples"]}>
  <Tab>
    **Documentation Checklist**

    All components must include:

    **Component Documentation**

    * [ ] Purpose and use cases
    * [ ] Complete props API with types and descriptions
    * [ ] Code examples for common scenarios
    * [ ] Accessibility considerations
    * [ ] Performance notes

    **Integration Guides**

    * [ ] Basic usage examples
    * [ ] Advanced usage patterns
    * [ ] Feature integration examples
    * [ ] Common pitfalls to avoid

    **Implementation Notes**

    * [ ] Architecture decisions
    * [ ] Key dependencies
    * [ ] Browser/device compatibility
    * [ ] Known limitations

    **Changelog**

    * [ ] Version history
    * [ ] Breaking changes
    * [ ] Deprecation notices
  </Tab>

  <Tab>
    **Storybook Integration**

    Each component should have Storybook stories:

    ```typescript
    // ui/foundation/Button/Button.stories.tsx
    import { Meta, StoryObj } from '@storybook/react';
    import { Button } from './Button';

    const meta: Meta<typeof Button> = {
      title: 'UI/Foundation/Button',
      component: Button,
      parameters: {
        layout: 'centered',
      },
      tags: ['autodocs'],
      argTypes: {
        variant: {
          control: 'select',
          options: ['primary', 'secondary', 'ghost'],
          description: 'Button style variant'
        },
        size: {
          control: 'select',
          options: ['small', 'medium', 'large'],
          description: 'Button size variant'
        },
        disabled: {
          control: 'boolean',
          description: 'Disable button interactions'
        }
      }
    };

    export default meta;
    type Story = StoryObj<typeof Button>;

    export const Primary: Story = {
      args: {
        variant: 'primary',
        children: 'Primary Button',
        size: 'medium',
      },
    };

    export const Secondary: Story = {
      args: {
        variant: 'secondary',
        children: 'Secondary Button',
        size: 'medium',
      },
    };

    export const Small: Story = {
      args: {
        variant: 'primary',
        children: 'Small Button',
        size: 'small',
      },
    };

    export const Disabled: Story = {
      args: {
        variant: 'primary',
        children: 'Disabled Button',
        size: 'medium',
        disabled: true,
      },
    };
    ```
  </Tab>

  <Tab>
    **Documentation Example**

    Here's how to document your component:

    **Component README Structure:**

    * Component purpose and description
    * Installation and import instructions
    * Basic usage examples
    * Props API documentation
    * Accessibility notes
    * Advanced usage patterns

    **Props Documentation Format:**

    | Prop       | Type                                  | Default     | Description                 |
    | ---------- | ------------------------------------- | ----------- | --------------------------- |
    | `variant`  | `'primary' \| 'secondary' \| 'ghost'` | `'primary'` | Visual style variant        |
    | `size`     | `'small' \| 'medium' \| 'large'`      | `'medium'`  | Size variant                |
    | `disabled` | `boolean`                             | `false`     | Disables button interaction |
    | `loading`  | `boolean`                             | `false`     | Shows loading indicator     |
    | `onPress`  | `() => void`                          | -           | Callback when pressed       |

    **Accessibility Guidelines:**

    * Use semantic HTML elements
    * Include focus indicators
    * Support screen readers
    * Provide proper ARIA labels
    * Test with assistive technology

    **Code Examples Structure:**

    * Basic usage example
    * Props demonstration
    * Integration patterns
    * Edge cases and error handling
  </Tab>
</Tabs>

## Step 2: Feature Integration

Integrate the component into relevant features:

<Tabs items={["Integration Process", "Feature Adaptation", "Migration"]}>
  <Tab>
    **Feature Integration Process**

    <Steps>
      <Step>
        #### Identify Integration Points

        * Review features needing the component
        * Identify existing components to replace
        * Define integration goals
      </Step>

      <Step>
        #### Feature Branch Integration

        * Create feature integration branch
        * Add component to feature
        * Adapt feature code as needed
        * Test integration thoroughly
      </Step>

      <Step>
        #### Shared Component Updates

        * Identify any common needs across features
        * Extract shared patterns to component
        * Ensure backward compatibility
      </Step>

      <Step>
        #### Cross-Feature Testing

        * Test with all integrated features
        * Verify no regressions
        * Document feature-specific usage
      </Step>
    </Steps>
  </Tab>

  <Tab>
    **Feature Adaptation Examples**

    **1. Simple Integration**

    ```typescript
    // Before: features/product-catalog/screens/ProductList.tsx
    import { TouchableOpacity, Text } from 'react-native';

    function ProductListScreen() {
      return (
        <View>
          {/* Old button implementation */}
          <TouchableOpacity 
            style={styles.button}
            onPress={handleLoadMore}
          >
            <Text style={styles.buttonText}>Load More</Text>
          </TouchableOpacity>
        </View>
      );
    }

    // After: features/product-catalog/screens/ProductList.tsx
    import { Button } from '@/ui/foundation/Button';

    function ProductListScreen() {
      return (
        <View>
          {/* New component integration */}
          <Button 
            variant="primary"
            onPress={handleLoadMore}
          >
            Load More
          </Button>
        </View>
      );
    }
    ```

    **2. Complex Integration with Props Mapping**

    ```typescript
    // Before: features/checkout/components/SubmitOrder.tsx
    function SubmitOrderButton({ isProcessing, canSubmit, onSubmitOrder }) {
      return (
        <TouchableOpacity
          style={[
            styles.submitButton,
            !canSubmit && styles.disabledButton,
            isProcessing && styles.processingButton
          ]}
          disabled={!canSubmit || isProcessing}
          onPress={onSubmitOrder}
        >
          {isProcessing ? (
            <ActivityIndicator color="#fff" />
          ) : (
            <Text style={styles.submitText}>
              {canSubmit ? 'Place Order' : 'Complete Required Fields'}
            </Text>
          )}
        </TouchableOpacity>
      );
    }

    // After: features/checkout/components/SubmitOrder.tsx
    import { Button } from '@/ui/foundation/Button';

    function SubmitOrderButton({ isProcessing, canSubmit, onSubmitOrder }) {
      return (
        <Button
          variant="primary"
          size="large"
          disabled={!canSubmit}
          loading={isProcessing}
          onPress={onSubmitOrder}
        >
          {canSubmit ? 'Place Order' : 'Complete Required Fields'}
        </Button>
      );
    }
    ```
  </Tab>

  <Tab>
    **Migration Strategy**

    **1. Progressive Migration**

    For large applications, use a phased approach:

    ```typescript
    // Step 1: Create adapter that works with both old and new
    // features/shared/ButtonAdapter.tsx
    import { Button } from '@/ui/foundation/Button';

    export const ButtonAdapter = ({ 
      useNewComponent = false,
      style, 
      textStyle,
      title,
      ...props 
    }) => {
      // Use new component when specified
      if (useNewComponent) {
        return (
          <Button {...props}>
            {title}
          </Button>
        );
      }
      
      // Fall back to old implementation
      return (
        <TouchableOpacity style={style} {...props}>
          <Text style={textStyle}>{title}</Text>
        </TouchableOpacity>
      );
    };

    // Step 2: Update features one by one with adapter
    // features/some-feature/SomeScreen.tsx
    import { ButtonAdapter } from '../shared/ButtonAdapter';

    function SomeScreen() {
      return (
        <ButtonAdapter
          useNewComponent={true} // Toggle feature by feature
          title="Submit"
          onPress={handleSubmit}
          // New component props
          variant="primary"
          // Legacy props for old implementation
          style={styles.button}
          textStyle={styles.buttonText}
        />
      );
    }

    // Step 3: Once migration is complete, remove adapter
    ```

    **2. Feature Flag Approach**

    Use feature flags for safer rollout:

    ```typescript
    // core/config/featureFlags.ts
    export const featureFlags = {
      useNewButtonComponents: true,
      useNewFormComponents: false
    };

    // features/some-feature/SomeScreen.tsx
    import { featureFlags } from '@/core/config/featureFlags';

    function SomeScreen() {
      if (featureFlags.useNewButtonComponents) {
        return <Button variant="primary" onPress={handleSubmit}>Submit</Button>;
      }
      
      // Fall back to old implementation
      return (
        <TouchableOpacity style={styles.button} onPress={handleSubmit}>
          <Text style={styles.buttonText}>Submit</Text>
        </TouchableOpacity>
      );
    }
    ```
  </Tab>
</Tabs>

## Step 3: Release Process

Deploy component through proper release channels:

<Tabs items={["Version Management", "Release Process", "Changelog"]}>
  <Tab>
    **Version Management**

    Follow semantic versioning for components:

    * **MAJOR (2.0.0)**: Breaking changes
    * **MINOR (1.1.0)**: New features, backward compatible
    * **PATCH (1.0.1)**: Bug fixes, backward compatible

    **Component Version Tracking**

    ```typescript
    // ui/foundation/Button/Button.tsx

    /**
     * Button component
     * @version 1.2.0
     * @since 1.0.0
     * @lastUpdated 2023-08-15
     */
    export const Button = ({ ... }) => { ... };
    ```

    **Version History**

    ```typescript
    // ui/foundation/Button/CHANGELOG.md
    # Button Component Changelog

    ## 1.2.0 (2023-08-15)

    Features:
    - Added loading state
    - Added icon support

    ## 1.1.0 (2023-07-20)

    Features:
    - Added ghost variant
    - Added size prop

    ## 1.0.0 (2023-07-01)

    Initial release
    ```
  </Tab>

  <Tab>
    **Component Release Process**

    <Steps>
      <Step>
        #### Pre-release Checklist

        * All reviews passed
        * Tests passing at 100%
        * Documentation complete
        * Storybook stories added
        * Performance benchmarks meet targets
      </Step>

      <Step>
        #### Release Preparation

        * Update version numbers
        * Update changelog
        * Create release branch
        * Prepare release notes
      </Step>

      <Step>
        #### CI/CD Pipeline

        * Run automated tests
        * Build package
        * Publish to internal registry
        * Deploy to staging environment
      </Step>

      <Step>
        #### Final Validation

        * Smoke test in staging
        * Verify documentation
        * Confirm integrations work
        * Get final approval
      </Step>

      <Step>
        #### Production Deployment

        * Merge to main branch
        * Publish to production registry
        * Tag release in git
        * Announce to team
      </Step>
    </Steps>
  </Tab>

  <Tab>
    **Changelog Best Practices**

    **Template Structure**

    Your changelog should follow this format:

    * **Header**: Component name and changelog title
    * **Unreleased section**: For upcoming changes
    * **Version sections**: For each release with date
    * **Categories**: Added, Changed, Fixed, Removed
    * **Clear descriptions**: What changed and why

    **Version Example:**

    * `[1.2.0] - 2023-08-15` format for versions
    * Group changes by type (Added, Changed, Fixed)
    * Include specific details about each change
    * Reference any breaking changes clearly

    **Breaking Changes Documentation**

    When introducing breaking changes:

    * **List all breaking changes**: Be comprehensive
    * **Explain the impact**: What will break
    * **Provide migration examples**: Before/after code
    * **Include timeline**: When support ends
    * **Update documentation**: Reflect new patterns

    **Migration Guide Format:**

    * **Before/After examples**: Show exact changes needed
    * **Step-by-step instructions**: Clear migration path
    * **Common pitfalls**: What to watch out for
    * **Testing recommendations**: How to verify migration
    * **Support resources**: Where to get help
  </Tab>
</Tabs>

## Next Steps

After deployment:

1. Continue to [monitoring and maintenance](/docs/ui-development/architecture/development-workflow/post-deployment)
2. Collect initial usage feedback
3. Plan for iterative improvements

## Related Documents

* [Review Process](/docs/ui-development/architecture/development-workflow/review-process) - Pre-deployment quality checks
* [Post-Deployment](/docs/ui-development/architecture/development-workflow/post-deployment) - Monitoring and maintenance
* [Release Workflow](/docs/development-workflow/release-workflow) - General release process
* [Documentation Standards](/docs/coding-standards/documentation) - Documentation requirements


# UTA UI Development: Post-Deployment Monitoring & Maintenance
URL: https://dev.updatetheapp.com/docs/ui-development/architecture/development-workflow/post-deployment
Documentation: https://dev.updatetheapp.com/docs/ui-development/architecture/development-workflow/post-deployment

Monitoring component performance, gathering feedback, and maintaining UI components over time.
        
***

title: Post-Deployment Monitoring & Maintenance
description: Monitoring component performance, gathering feedback, and maintaining UI components over time.
-----------------------------------------------------------------------------------------------------------

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Callout } from 'fumadocs-ui/components/callout';
import { Steps, Step } from 'fumadocs-ui/components/steps';

# Post-Deployment Monitoring & Maintenance

## Overview

After deployment, components require ongoing monitoring and maintenance to ensure continued performance, reliability, and relevance. This document covers best practices for the post-deployment lifecycle.

<Callout type="info">
  **Long-term Success**

  The difference between good and great components often lies in post-deployment care. Continuous monitoring, refinement, and maintenance ensure components remain valuable and performant over time.
</Callout>

## Purpose & Scope

<Tabs items={["What You'll Learn", "Who This Is For", "When To Apply"]}>
  <Tab>
    * Performance monitoring techniques
    * Usage analytics integration
    * Maintenance scheduling
    * Component deprecation process
  </Tab>

  <Tab>
    * UI component maintainers
    * Performance engineers
    * Product managers
    * Support engineers
  </Tab>

  <Tab>
    These practices apply:

    * After component deployment
    * During regular maintenance cycles
    * When planning component updates
    * Before component deprecation
  </Tab>
</Tabs>

## Step 1: Performance Monitoring

Implement proper monitoring to ensure components perform well in production:

<Tabs items={["Monitoring Setup", "Performance Metrics", "Instrumentation"]}>
  <Tab>
    **Performance Monitoring Setup**

    Implement these monitoring practices for all production components:

    **1. Performance Metrics Collection**

    * Initial render timing
    * Re-render timing
    * Memory usage
    * Interaction responsiveness

    **2. Error Tracking**

    * JS exceptions
    * Render errors
    * API interaction failures
    * Boundary catches

    **3. Usage Analytics**

    * Feature adoption
    * Interaction patterns
    * Configuration distribution
    * A/B test results

    **4. User Feedback**

    * Satisfaction surveys
    * Issue reports
    * Feature requests
    * Usability feedback
  </Tab>

  <Tab>
    **Key Performance Metrics**

    Track these metrics for each component:

    **Rendering Performance**

    * **Time to First Render**: \< 50ms target
    * **Re-render Time**: \< 16ms target (60fps)
    * **Interaction Response**: \< 100ms target
    * **Animation Smoothness**: 60fps target

    **Resource Usage**

    * **Memory Footprint**: Component-specific baseline
    * **Bundle Size Impact**: \< 5KB increase target
    * **API Call Efficiency**: \< 2 calls per interaction
    * **State Update Frequency**: Minimized to essential changes

    **User Experience**

    * **Time to Interactive**: When component is fully usable
    * **Input Latency**: Delay between user action and response
    * **Perceived Performance**: User rating of speed
    * **Error Rate**: Percentage of interactions with errors

    **Create component-specific baselines and alert on deviations of >20%.**
  </Tab>

  <Tab>
    **Component Instrumentation**

    Add performance tracking to components:

    ```typescript
    // ui/foundation/Button/Button.tsx
    import { useEffect } from 'react';
    import { Performance } from '@/core/shared/monitoring';

    export const Button = (props) => {
      // Mark render start
      const renderStart = Performance.now();
      
      useEffect(() => {
        // Track render time
        const renderTime = Performance.now() - renderStart;
        Performance.trackMetric(
          'ComponentRender', 
          renderTime,
          {
            component: 'Button',
            variant: props.variant,
          }
        );
        
        // Track interaction performance
        return () => {
          Performance.trackInteraction(
            'ComponentName.renderTime',
            'ComponentName.render'
          );
        };
      }, []);
    };
    ```

    **Error Monitoring**

    ```typescript
    // Add error boundary
    export class ComponentErrorBoundary extends Component {
      componentDidCatch(error: Error, errorInfo: ErrorInfo) {
        // Log to monitoring service
        ErrorReporter.log({
          error,
          errorInfo,
          component: 'ComponentName',
          version: '1.2.0',
        });
      }
      
      render() {
        if (this.state.hasError) {
          return <FallbackComponent />;
        }
        return this.props.children;
      }
    }
    ```

    **Usage Analytics**

    ```typescript
    // Track component usage
    export const ComponentName = (props) => {
      useEffect(() => {
        Analytics.track('ComponentUsed', {
          component: 'ComponentName',
          variant: props.variant,
          size: props.size,
        });
      }, [props.variant, props.size]);
    };
    ```

    **Monitoring Dashboard**

    Track key metrics:

    * Render performance (p50, p90, p99)
    * Error rates
    * Usage frequency
    * Props distribution
    * Platform breakdown
  </Tab>
</Tabs>

## Step 2: Ongoing Maintenance

Establish regular maintenance processes:

<Tabs items={["Maintenance Schedule", "Issue Management", "Deprecation"]}>
  <Tab>
    **Ongoing Maintenance**

    **Regular Tasks**

    **Weekly**

    * [ ] Check error reports
    * [ ] Review performance metrics
    * [ ] Triage new issues

    **Monthly**

    * [ ] Update dependencies
    * [ ] Review usage patterns
    * [ ] Update documentation
    * [ ] Performance optimization

    **Quarterly**

    * [ ] Architecture review
    * [ ] Accessibility audit
    * [ ] API consistency check
    * [ ] Deprecation planning

    **Issue Tracking**

    ```markdown
    ## Component Issue Template

    **Component**: ComponentName
    **Version**: 1.2.0
    **Severity**: High/Medium/Low

    **Description**:
    [Clear description of the issue]

    **Impact**:
    - Affected users: [percentage]
    - Frequency: [occurrences/day]
    - Platforms: [iOS/Android/Both]

    **Proposed Solution**:
    [Description of fix]

    **Timeline**:
    - Investigation: [date]
    - Fix development: [date]
    - Testing: [date]
    - Release: [date]
    ```
  </Tab>

  <Tab>
    **Issue Management Workflow**

    <Steps>
      <Step>
        #### Issue Triage

        * Categorize by component
        * Assign severity and priority
        * Evaluate impact scope
        * Determine if hotfix needed
      </Step>

      <Step>
        #### Investigation

        * Reproduce issue
        * Identify root cause
        * Document in issue tracker
        * Create test case
      </Step>

      <Step>
        #### Resolution Planning

        * Design fix approach
        * Estimate effort
        * Add to sprint/backlog
        * Set target release
      </Step>

      <Step>
        #### Implementation

        * Develop fix
        * Add/update tests
        * Document changes
        * Update changelog
      </Step>

      <Step>
        #### Verification

        * Review code
        * Test fix
        * Regression testing
        * Performance verification
      </Step>

      <Step>
        #### Release

        * Merge to main
        * Version bump
        * Release notes
        * Communication to users
      </Step>
    </Steps>

    **Prioritization Framework**

    | Priority | Description                          | Response Time | Resolution Time |
    | -------- | ------------------------------------ | ------------- | --------------- |
    | P0       | Critical issue, broken functionality | 2 hours       | 24 hours        |
    | P1       | High impact, major limitation        | 24 hours      | 1 week          |
    | P2       | Medium impact, functional workaround | 3 days        | 2 weeks         |
    | P3       | Low impact, cosmetic                 | 1 week        | Next release    |
  </Tab>

  <Tab>
    **Deprecation Process**

    When retiring components:

    1. **Announce** (3 months before)
       * Reason for deprecation
       * Migration path
       * Timeline

    2. **Add Warnings** (2 months before)
       ```typescript
       console.warn(
         'ComponentName is deprecated and will be removed in v2.0.0. ' +
         'Please migrate to NewComponent.'
       );
       ```

    3. **Support Period** (1 month)
       * Only critical fixes
       * Help with migration
       * Answer questions

    4. **Remove** (On schedule)
       * Remove from codebase
       * Update documentation
       * Final announcement

    **Deprecation Documentation Structure**

    Your deprecation notice should include:

    **Header Information:**

    * Component name and status
    * Removal date
    * Replacement component

    **Reason for Deprecation:**

    * Technical limitations
    * Performance issues
    * Design system changes
    * Accessibility concerns

    **Migration Instructions:**

    * Before/after code examples
    * Prop mapping changes
    * Behavior differences
    * Testing recommendations

    **Support Timeline:**

    * Announcement date
    * Warning implementation
    * Support end date
    * Removal date

    **Contact Information:**

    * Team responsible
    * Support channels
    * Documentation links
  </Tab>
</Tabs>

## Summary

Post-deployment monitoring and maintenance ensures components:

* Perform reliably in production
* Continue to meet evolving needs
* Maintain compatibility with the platform
* Provide consistent value over time

## Next Steps

1. Set up monitoring for your components
2. Establish regular maintenance schedules
3. Create deprecation plans for legacy components
4. Document performance baselines

## Related Documents

* [Deployment Integration](/docs/ui-development/architecture/development-workflow/deployment-integration) - Pre-monitoring deployment processes
* [Performance Standards](/docs/ui-development/performance) - Component performance requirements
* [Analytics Integration](/docs/features/analytics) - Usage tracking implementation
* [Deprecation Policy](/docs/coding-standards/deprecation-policy) - Component retirement process


# UTA UI Development: Maintenance and Lifecycle
URL: https://dev.updatetheapp.com/docs/ui-development/architecture/development-workflow/maintenance-lifecycle
Documentation: https://dev.updatetheapp.com/docs/ui-development/architecture/development-workflow/maintenance-lifecycle

Regular maintenance tasks, component evolution, deprecation processes, and troubleshooting common issues.
        
***

title: Maintenance and Lifecycle
description: Regular maintenance tasks, component evolution, deprecation processes, and troubleshooting common issues.
----------------------------------------------------------------------------------------------------------------------

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Callout } from 'fumadocs-ui/components/callout';
import { Steps, Step } from 'fumadocs-ui/components/steps';

# Maintenance and Lifecycle

## Overview

Component maintenance is an ongoing process that ensures components remain reliable, performant, and aligned with evolving requirements. This guide covers the complete lifecycle of components from initial release through eventual deprecation.

<Callout type="info">
  **Living Components**

  Components are living entities that evolve with your application. Regular maintenance ensures they continue to meet user needs while maintaining quality standards.
</Callout>

## Component Lifecycle Management

<Tabs items={["Lifecycle Overview", "Maintenance Schedule", "Tracking Tools"]}>
  <Tab>
    **Component Lifecycle Phases**

    Components go through distinct phases during their lifetime:

    1. **Introduction** (0-3 months)
       * Initial release and adoption
       * Rapid iteration based on feedback
       * Documentation refinement
       * Performance baseline establishment

    2. **Growth** (3-12 months)
       * Feature additions
       * API stabilization
       * Widespread adoption
       * Pattern establishment

    3. **Maturity** (12+ months)
       * Stable API
       * Optimization focus
       * Minimal breaking changes
       * Comprehensive documentation

    4. **Decline** (When needed)
       * Replacement planning
       * Migration preparation
       * Deprecation warnings
       * Support reduction

    5. **Deprecation** (3-6 month process)
       * Official deprecation announcement
       * Migration guide publication
       * Limited maintenance
       * Final removal
  </Tab>

  <Tab>
    **Regular Maintenance Tasks**

    **Weekly Tasks**

    * [ ] Monitor error reports and crash analytics
    * [ ] Review performance metrics dashboards
    * [ ] Triage new issues and bug reports
    * [ ] Check automated test results
    * [ ] Review usage analytics

    **Monthly Tasks**

    * [ ] Update component dependencies
    * [ ] Review and merge dependency updates
    * [ ] Analyze usage patterns and metrics
    * [ ] Update documentation for clarity
    * [ ] Performance optimization if needed
    * [ ] Review accessibility compliance

    **Quarterly Tasks**

    * [ ] Comprehensive architecture review
    * [ ] Full accessibility audit
    * [ ] Performance benchmarking
    * [ ] API consistency check
    * [ ] Design token compliance review
    * [ ] Breaking change planning

    **Annual Tasks**

    * [ ] Major architecture assessment
    * [ ] Technology stack evaluation
    * [ ] Long-term roadmap planning
    * [ ] Deprecation planning for legacy components
    * [ ] Team knowledge sharing sessions
  </Tab>

  <Tab>
    **Tracking and Monitoring Tools**

    **Component Health Dashboard**

    ```typescript
    // Example monitoring setup
    import { ComponentMonitor } from '@/core/monitoring';

    ComponentMonitor.track({
      component: 'ComponentName',
      metrics: {
        renderTime: true,
        errorRate: true,
        usageCount: true,
        propUsage: true,
      },
      alerts: {
        errorRateThreshold: 0.01, // 1%
        renderTimeThreshold: 50, // ms
      },
    });
    ```

    **Key Metrics to Track**

    1. **Performance Metrics**
       * Render time (p50, p90, p99)
       * Re-render frequency
       * Memory usage
       * Bundle size impact

    2. **Quality Metrics**
       * Error rate
       * Crash frequency
       * Test coverage
       * TypeScript strictness

    3. **Usage Metrics**
       * Adoption rate
       * Feature usage
       * Prop combinations
       * Platform distribution

    4. **Developer Experience**
       * Time to implement
       * Support tickets
       * Documentation views
       * API satisfaction
  </Tab>
</Tabs>

## Evolution and Updates

### Managing Component Changes

<Tabs items={["Update Types", "Version Strategy", "Communication"]}>
  <Tab>
    **Types of Updates**

    **Patch Updates (0.0.X)**

    * Bug fixes
    * Performance improvements
    * Documentation updates
    * Dependency updates (non-breaking)

    ```json
    // Example: 1.2.3 → 1.2.4
    {
      "version": "1.2.4",
      "changes": [
        "Fixed memory leak in animation cleanup",
        "Improved TypeScript definitions",
        "Updated accessibility labels"
      ]
    }
    ```

    **Minor Updates (0.X.0)**

    * New features (backward compatible)
    * New props or options
    * Deprecation warnings
    * Performance enhancements

    ```json
    // Example: 1.2.4 → 1.3.0
    {
      "version": "1.3.0",
      "changes": [
        "Added 'size' prop with small/medium/large options",
        "Added loading state support",
        "Deprecated 'isLarge' prop (use size='large')",
        "30% render performance improvement"
      ]
    }
    ```

    **Major Updates (X.0.0)**

    * Breaking API changes
    * Architecture redesign
    * Technology migrations
    * Removed deprecated features

    ```json
    // Example: 1.3.0 → 2.0.0
    {
      "version": "2.0.0",
      "breaking": [
        "Changed 'onPress' prop to 'onPress'",
        "Removed deprecated 'isLarge' prop",
        "New required prop 'accessibilityLabel'",
        "Migrated from class to function component"
      ]
    }
    ```
  </Tab>

  <Tab>
    **Version Management Strategy**

    **Semantic Versioning Rules**

    Follow strict semantic versioning (SemVer):

    ```typescript
    // Version format: MAJOR.MINOR.PATCH

    // PATCH: Backward compatible bug fixes
    "1.2.3" → "1.2.4"

    // MINOR: Backward compatible new features
    "1.2.4" → "1.3.0"

    // MAJOR: Breaking changes
    "1.3.0" → "2.0.0"
    ```

    **Pre-release Versions**

    Use pre-release versions for testing:

    ```json
    {
      "version": "2.0.0-beta.1",
      "version": "2.0.0-rc.1",
      "version": "2.0.0"
    }
    ```

    **Version Tags**

    ```bash
    # Tag stable releases
    git tag -a v1.2.3 -m "Release version 1.2.3"

    # Tag pre-releases
    git tag -a v2.0.0-beta.1 -m "Beta release for v2.0.0"

    # Push tags
    git push origin --tags
    ```

    **Branch Strategy**

    ```
    main
    ├── develop
    │   ├── feature/new-component-prop
    │   └── feature/performance-improvement
    ├── release/v1.3.0
    └── hotfix/critical-bug-fix
    ```
  </Tab>

  <Tab>
    **Change Communication**

    **Changelog Format**

    ```markdown
    # Changelog

    ## [2.0.0] - 2024-01-15

    ### 💥 Breaking Changes
    - Changed `onClick` prop to `onPress` for React Native consistency
    - Removed deprecated `isLarge` prop - use `size="large"` instead
    - Made `accessibilityLabel` a required prop

    ### ✨ New Features
    - Added `loading` prop with built-in spinner
    - Added `icon` prop for leading/trailing icons
    - Added haptic feedback support on iOS

    ### 🐛 Bug Fixes
    - Fixed memory leak in animation cleanup
    - Fixed touch target size on small devices
    - Fixed theme switching visual glitch

    ### 🚀 Performance
    - Improved render performance by 30%
    - Reduced bundle size by 15%

    ### 📝 Documentation
    - Added migration guide from v1.x
    - Added accessibility best practices
    - Updated all code examples
    ```

    **Release Announcement Template**

    ```markdown
    # Component Update: ComponentName v2.0.0 🎉

    We're excited to announce the release of ComponentName v2.0.0!

    ## What's New
    - ✨ Loading state support
    - 🎨 Icon integration
    - 📱 Haptic feedback
    - ⚡ 30% faster rendering

    ## Breaking Changes ⚠️
    Please review the [migration guide](link) for:
    - Prop name changes
    - Required accessibility labels
    - API updates

    ## Resources
    - 📖 [Documentation](link)
    - 🔄 [Migration Guide](link)
    - 💬 [Discussion Thread](link)
    - 🐛 [Report Issues](link)

    ## Support
    - Slack: #ui-components
    - Migration period: 3 months
    ```
  </Tab>
</Tabs>

## Deprecation Process

<Callout type="warning">
  **Thoughtful Deprecation**

  Deprecation should be a careful, well-communicated process that gives teams adequate time to migrate while maintaining application stability.
</Callout>

<Steps>
  <Step>
    #### Phase 1: Planning (Month -3)

    **Identify Deprecation Candidates**

    * Components with better alternatives
    * Outdated patterns or technologies
    * Low usage or high maintenance burden
    * Security or performance concerns

    **Create Migration Strategy**

    ```markdown
    ## Deprecation Plan: OldComponent

    **Reason**: Replaced by NewComponent with better performance
    **Timeline**: 6 months (Jan 2024 - Jun 2024)
    **Migration Path**: OldComponent → NewComponent
    **Breaking Changes**: Minor API differences
    **Team Impact**: ~50 usage instances across 10 features
    ```
  </Step>

  <Step>
    #### Phase 2: Announcement (Month 0)

    **Add Deprecation Warnings**

    ```typescript
    export const OldComponent = (props: OldComponentProps) => {
      useEffect(() => {
        if (process.env.NODE_ENV !== 'production') {
          console.warn(
            'OldComponent is deprecated and will be removed in v3.0.0.\n' +
            'Please migrate to NewComponent.\n' +
            'Migration guide: https://docs.example.com/migration/old-to-new'
          );
        }
      }, []);
      
      // Component implementation
    };

    /**
     * @deprecated Use NewComponent instead. Will be removed in v3.0.0.
     * @see https://docs.example.com/migration/old-to-new
     */
    export interface OldComponentProps {
      // Props definition
    }
    ```

    **Update Documentation**

    ```markdown
    # OldComponent

    > ⚠️ **Deprecated**: This component is deprecated and will be removed in v3.0.0.
    > Please use [NewComponent](/docs/new-component) instead.
    > See the [migration guide](/docs/migration/old-to-new) for details.
    ```
  </Step>

  <Step>
    #### Phase 3: Migration Support (Months 1-3)

    **Provide Migration Tools**

    ```typescript
    // Codemod for automated migration
    // codemods/old-to-new-component.js
    module.exports = function(fileInfo, api) {
      const j = api.jscodeshift;
      
      return j(fileInfo.source)
        .find(j.ImportDeclaration, {
          source: { value: '@/ui/OldComponent' }
        })
        .replaceWith(
          j.importDeclaration(
            [j.importDefaultSpecifier(j.identifier('NewComponent'))],
            j.literal('@/ui/NewComponent')
          )
        )
        .toSource();
    };
    ```

    **Migration Guide**

    ````markdown
    # Migration Guide: OldComponent to NewComponent

    ## API Changes

    | OldComponent | NewComponent | Notes |
    |--------------|--------------|-------|
    | `type` | `variant` | Same values |
    | `onTap` | `onPress` | Same signature |
    | `large` | `size="large"` | Now uses size prop |

    ## Before
    ```tsx
    <OldComponent
      type="primary"
      onTap={handleTap}
      large
    />
    ````

    ## After

    ```tsx
    <NewComponent
      variant="primary"
      onPress={handleTap}
      size="large"
    />
    ```

    ````
    </Step>

    <Step>
    #### Phase 4: Limited Support (Months 4-5)

    **Maintenance Mode**
    - Critical security fixes only
    - No new features
    - No non-critical bug fixes
    - Increased warning visibility

    ```typescript
    // Increase warning prominence
    export const OldComponent = (props: OldComponentProps) => {
      useEffect(() => {
        console.error(
          '🚨 OldComponent is deprecated and will be removed next month!\n' +
          'Please migrate to NewComponent immediately.\n' +
          'Migration guide: https://docs.example.com/migration/old-to-new'
        );
      }, []);
    };
    ````
  </Step>

  <Step>
    #### Phase 5: Removal (Month 6)

    **Final Steps**

    * Remove component code
    * Update all exports
    * Clean up documentation
    * Archive migration guide
    * Final announcement

    ```bash
    # Remove component files
    rm -rf ui/deprecated/OldComponent

    # Update exports
    # Remove from ui/index.ts

    # Update package version
    npm version major

    # Tag removal
    git tag -a v3.0.0 -m "Remove deprecated OldComponent"
    ```
  </Step>
</Steps>

## Troubleshooting Common Issues

### Development Issues

<Tabs items={["Token Issues", "Performance Issues", "Accessibility Issues"]}>
  <Tab>
    **Design Token Issues**

    **Issue: Component Not Using Design Tokens**

    **Symptoms**:

    * Hardcoded colors, spacing, or typography
    * Inconsistent styling across themes
    * Theme switching not working

    **Solution**:

    ```typescript
    // ❌ Problem: Hardcoded values
    const styles = StyleSheet.create({
      container: {
        backgroundColor: '#3b82f6',
        padding: 16,
        borderRadius: 8,
      },
      text: {
        fontSize: 16,
        color: '#ffffff',
      },
    });

    // ✅ Solution: Use design tokens
    import { theme } from '@/core/shared/styles/theme';

    const styles = StyleSheet.create({
      container: {
        backgroundColor: theme.colors.primary[500],
        padding: theme.spacing.md,
        borderRadius: theme.radii.md,
      },
      text: {
        fontSize: theme.typography.size.md,
        color: theme.colors.primary.contrast,
      },
    });
    ```

    **Debugging Steps**:

    1. Search for hex colors: `#[0-9a-fA-F]{3,6}`
    2. Search for pixel values: `\d+px|\d+\s*,`
    3. Run theme compliance linter
    4. Check theme provider setup
  </Tab>

  <Tab>
    **Performance Issues**

    **Issue: Slow Component Rendering**

    **Symptoms**:

    * Janky animations
    * Delayed user interactions
    * High CPU usage
    * Memory leaks

    **Common Causes & Solutions**:

    **1. Unnecessary Re-renders**

    ```typescript
    // ❌ Problem: Component re-renders on every parent update
    export const ExpensiveComponent = ({ data, onPress }) => {
      const processedData = data.map(item => ({
        ...item,
        computed: heavyComputation(item),
      }));
      
      return <List data={processedData} />;
    };

    // ✅ Solution: Memoize expensive operations
    export const ExpensiveComponent = React.memo(({ data, onPress }) => {
      const processedData = useMemo(
        () => data.map(item => ({
          ...item,
          computed: heavyComputation(item),
        })),
        [data]
      );
      
      return <List data={processedData} />;
    });
    ```

    **2. Memory Leaks**

    ```typescript
    // ❌ Problem: Cleanup not performed
    useEffect(() => {
      const timer = setInterval(updateData, 1000);
      // Missing cleanup!
    }, []);

    // ✅ Solution: Proper cleanup
    useEffect(() => {
      const timer = setInterval(updateData, 1000);
      
      return () => {
        clearInterval(timer);
      };
    }, []);
    ```

    **Performance Debugging Tools**:

    ```typescript
    // Add performance markers
    import { PerformanceProfiler } from '@/core/debug';

    export const Component = () => {
      return (
        <PerformanceProfiler
          id="ComponentName"
          onRender={(id, phase, duration) => {
            console.log(`${id} (${phase}) took ${duration}ms`);
          }}
        >
          {/* Component content */}
        </PerformanceProfiler>
      );
    };
    ```
  </Tab>

  <Tab>
    **Accessibility Issues**

    **Issue: Poor Screen Reader Support**

    **Symptoms**:

    * Elements not announced
    * Incorrect role announcements
    * Missing state information
    * Navigation problems

    **Common Problems & Solutions**:

    **1. Missing Labels**

    ```typescript
    // ❌ Problem: No accessible label
    <TouchableOpacity onPress={onPress}>
      <Icon name="close" />
    </TouchableOpacity>

    // ✅ Solution: Add accessibility label
    <TouchableOpacity
      onPress={onPress}
      accessibilityLabel="Close dialog"
      accessibilityRole="button"
      accessibilityHint="Double tap to close the dialog"
    >
      <Icon name="close" />
    </TouchableOpacity>
    ```

    **2. State Not Communicated**

    ```typescript
    // ❌ Problem: State changes not announced
    <View>
      {isExpanded && <Content />}
    </View>

    // ✅ Solution: Announce state changes
    <View
      accessibilityRole="region"
      accessibilityState={{ expanded: isExpanded }}
      accessibilityLabel="Expandable section"
    >
      {isExpanded && <Content />}
    </View>
    ```

    **3. Focus Management**

    ```typescript
    // ❌ Problem: Focus not managed after action
    const handleDelete = () => {
      deleteItem(item.id);
      // Focus is lost!
    };

    // ✅ Solution: Manage focus properly
    const handleDelete = () => {
      deleteItem(item.id);
      
      // Move focus to next logical element
      if (nextItemRef.current) {
        AccessibilityInfo.setAccessibilityFocus(
          findNodeHandle(nextItemRef.current)
        );
      }
    };
    ```

    **Accessibility Testing Checklist**:

    * [ ] Enable screen reader
    * [ ] Navigate using gestures only
    * [ ] Verify all content is announced
    * [ ] Check focus order is logical
    * [ ] Test with large text sizes
    * [ ] Verify color contrast ratios
  </Tab>
</Tabs>

### Testing Issues

<Tabs items={["Test Failures", "Coverage Issues", "Maintenance"]}>
  <Tab>
    **Common Test Failures**

    **Issue: Tests Break After Token Updates**

    ```typescript
    // ❌ Problem: Hardcoded values in tests
    expect(button.props.style.backgroundColor).toBe('#3b82f6');

    // ✅ Solution: Use token references
    import { theme } from '@/core/shared/styles/theme';

    expect(button.props.style.backgroundColor).toBe(
      theme.colors.primary[500]
    );
    ```

    **Issue: Async Test Failures**

    ```typescript
    // ❌ Problem: Not waiting for async operations
    it('loads data', () => {
      const { getByText } = render(<Component />);
      expect(getByText('Data loaded')).toBeTruthy();
    });

    // ✅ Solution: Wait for async operations
    it('loads data', async () => {
      const { findByText } = render(<Component />);
      expect(await findByText('Data loaded')).toBeTruthy();
    });
    ```

    **Issue: Flaky Tests**

    ```typescript
    // ❌ Problem: Timing-dependent tests
    it('shows tooltip', () => {
      const { getByText, getByTestId } = render(<Component />);
      fireEvent.press(getByTestId('trigger'));
      expect(getByText('Tooltip')).toBeTruthy();
    });

    // ✅ Solution: Wait for animations
    it('shows tooltip', async () => {
      const { getByTestId, findByText } = render(<Component />);
      fireEvent.press(getByTestId('trigger'));
      
      await waitFor(() => {
        expect(findByText('Tooltip')).toBeTruthy();
      });
    });
    ```
  </Tab>

  <Tab>
    **Coverage Issues**

    **Improving Test Coverage**

    ```typescript
    // Example: Comprehensive test coverage
    describe('Button Component', () => {
      // Props testing
      describe('Props', () => {
        it.each([
          ['primary', theme.colors.primary[500]],
          ['secondary', theme.colors.secondary[500]],
          ['danger', theme.colors.danger[500]],
        ])('renders %s variant correctly', (variant, color) => {
          const { getByTestId } = render(
            <Button variant={variant} testID="button">
              Test
            </Button>
          );
          
          expect(
            getByTestId('button').props.style.backgroundColor
          ).toBe(color);
        });
      });
      
      // Interaction testing
      describe('Interactions', () => {
        it('calls onPress when pressed', () => {
          const onPress = jest.fn();
          const { getByText } = render(
            <Button onPress={onPress}>Press me</Button>
          );
          
          fireEvent.press(getByText('Press me'));
          expect(onPress).toHaveBeenCalledTimes(1);
        });
        
        it('does not call onPress when disabled', () => {
          const onPress = jest.fn();
          const { getByText } = render(
            <Button onPress={onPress} disabled>
              Press me
            </Button>
          );
          
          fireEvent.press(getByText('Press me'));
          expect(onPress).not.toHaveBeenCalled();
        });
      });
      
      // Edge cases
      describe('Edge Cases', () => {
        it('handles missing children gracefully', () => {
          const { container } = render(<Button />);
          expect(container).toBeTruthy();
        });
        
        it('handles very long text', () => {
          const longText = 'A'.repeat(100);
          const { getByText } = render(<Button>{longText}</Button>);
          expect(getByText(longText)).toBeTruthy();
        });
      });
    });
    ```

    **Coverage Report Analysis**

    ```bash
    # Generate coverage report
    npm test -- --coverage --coverageReporters=html

    # Open coverage report
    open coverage/lcov-report/index.html
    ```

    **Target Coverage Levels**

    * Statements: 80%+
    * Branches: 75%+
    * Functions: 80%+
    * Lines: 80%+
  </Tab>

  <Tab>
    **Test Maintenance**

    **Keeping Tests Maintainable**

    **1. Test Utilities**

    ```typescript
    // test-utils/render.tsx
    export const renderWithProviders = (
      ui: React.ReactElement,
      options?: RenderOptions
    ) => {
      const Wrapper = ({ children }) => (
        <ThemeProvider>
          <NavigationContainer>
            {children}
          </NavigationContainer>
        </ThemeProvider>
      );
      
      return render(ui, { wrapper: Wrapper, ...options });
    };

    // Usage
    const { getByText } = renderWithProviders(<Component />);
    ```

    **2. Test Data Factories**

    ```typescript
    // test-utils/factories.ts
    export const createMockUser = (overrides?: Partial<User>): User => ({
      id: '1',
      name: 'Test User',
      email: 'test@example.com',
      ...overrides,
    });

    export const createMockProduct = (
      overrides?: Partial<Product>
    ): Product => ({
      id: '1',
      name: 'Test Product',
      price: 99.99,
      ...overrides,
    });
    ```

    **3. Custom Matchers**

    ```typescript
    // test-utils/matchers.ts
    expect.extend({
      toHaveAccessibilityLabel(element, label) {
        const hasLabel = element.props.accessibilityLabel === label;
        
        return {
          pass: hasLabel,
          message: () =>
            `Expected element to have accessibility label "${label}", ` +
            `but found "${element.props.accessibilityLabel}"`,
        };
      },
    });

    // Usage
    expect(button).toHaveAccessibilityLabel('Submit form');
    ```
  </Tab>
</Tabs>

## Best Practices Summary

<Callout type="success">
  **Maintenance Excellence**

  Great component maintenance combines proactive monitoring, thoughtful evolution, clear communication, and comprehensive testing to ensure long-term success.
</Callout>

<Tabs items={["Do's", "Don'ts", "Quick Reference"]}>
  <Tab>
    **(Do ✅) Maintenance Best Practices**

    * **Regular Reviews**: Conduct weekly, monthly, and quarterly reviews
    * **Monitor Metrics**: Track performance, quality, and usage metrics
    * **Document Changes**: Maintain comprehensive changelogs
    * **Communicate Early**: Announce deprecations well in advance
    * **Provide Migration Paths**: Always offer clear upgrade paths
    * **Test Thoroughly**: Maintain high test coverage
    * **Listen to Feedback**: Act on user and developer feedback
    * **Plan Ahead**: Consider long-term impact of changes
    * **Automate Checks**: Use CI/CD for quality gates
    * **Version Properly**: Follow semantic versioning strictly
  </Tab>

  <Tab>
    **(Don't ❌) Maintenance Anti-patterns**

    * **Sudden Breaking Changes**: Never break APIs without warning
    * **Poor Communication**: Don't surprise users with changes
    * **Neglect Testing**: Don't let test coverage decline
    * **Ignore Performance**: Don't let performance degrade over time
    * **Skip Documentation**: Don't forget to update docs
    * **Rush Deprecation**: Don't remove features too quickly
    * **Ignore Feedback**: Don't dismiss user concerns
    * **Hardcode Values**: Don't bypass design token system
    * **Mix Concerns**: Don't combine unrelated changes
    * **Break Conventions**: Don't deviate from established patterns
  </Tab>

  <Tab>
    **Quick Reference Guide**

    **Version Bumps**

    * Bug fix: `1.2.3` → `1.2.4` (PATCH)
    * New feature: `1.2.4` → `1.3.0` (MINOR)
    * Breaking change: `1.3.0` → `2.0.0` (MAJOR)

    **Deprecation Timeline**

    * Month -3: Planning
    * Month 0: Announcement
    * Months 1-3: Migration support
    * Months 4-5: Limited support
    * Month 6: Removal

    **Key Commands**

    ```bash
    # Check component health
    npm run component:health ComponentName

    # Run maintenance tasks
    npm run component:audit
    npm run component:update-deps
    npm run component:perf-check

    # Generate reports
    npm run component:coverage
    npm run component:bundle-analysis
    ```

    **Support Channels**

    * Slack: #ui-components
    * Email: [ui-team@company.com](mailto:ui-team@company.com)
    * Docs: /docs/components
    * Issues: github.com/org/repo/issues
  </Tab>
</Tabs>

## Next Steps

After establishing maintenance processes:

1. Set up automated monitoring and alerts
2. Create component health dashboards
3. Schedule regular review meetings
4. Document team-specific processes
5. Train team on maintenance procedures

## Related Documents

* [Development Workflow](/docs/ui-development/architecture/development-workflow) - Complete development process
* [Testing Strategies](/docs/ui-development/architecture/development-workflow/testing-strategies) - Testing best practices
* [Deployment & Integration](/docs/ui-development/architecture/development-workflow/deployment-integration) - Release processes
* [Post-Deployment](/docs/ui-development/architecture/development-workflow/post-deployment) - Monitoring and maintenance
* [Component Patterns](/docs/ui-development/development/component-patterns) - Implementation patterns


# UTA UI Development: AI Collaboration Guide
URL: https://dev.updatetheapp.com/docs/ui-development/architecture/development-workflow/ai-collaboration
Documentation: https://dev.updatetheapp.com/docs/ui-development/architecture/development-workflow/ai-collaboration

Effective prompts and best practices for AI-assisted component development at each phase of the workflow.
        
***

title: AI Collaboration Guide
description: Effective prompts and best practices for AI-assisted component development at each phase of the workflow.
----------------------------------------------------------------------------------------------------------------------

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Callout } from 'fumadocs-ui/components/callout';
import { Steps, Step } from 'fumadocs-ui/components/steps';

# AI Collaboration Guide

## Overview

AI tools can significantly accelerate component development while maintaining quality standards. This guide provides structured prompts and best practices for leveraging AI assistance at each phase of the component development workflow.

<Callout type="info">
  **AI as a Development Partner**

  AI works best as a collaborative partner that helps generate boilerplate, suggest patterns, and catch potential issues. However, human expertise remains essential for architectural decisions, code review, and ensuring alignment with project standards.
</Callout>

## Core Principles

<Tabs items={["Effective Collaboration", "Common Pitfalls", "Quality Control"]}>
  <Tab value="Effective Collaboration">
    **(Do ✅) Effective AI Collaboration**

    * **Provide Context**: Include relevant project details, tech stack, and constraints
    * **Be Specific**: Use clear, detailed requirements rather than vague requests
    * **Reference Standards**: Mention your design system, architecture rules, and patterns
    * **Iterate and Refine**: Use follow-up questions to improve AI suggestions
    * **Validate Output**: Always review and test AI-generated code
    * **Learn Patterns**: Use AI to learn new patterns and best practices

    **Example of Good Context**:

    ```markdown
    We're building a React Native app using TypeScript, following a three-layer UI architecture.
    Components must use our design token system from @/core/shared/styles/theme.
    All components need comprehensive accessibility support and 80%+ test coverage.
    ```
  </Tab>

  <Tab value="Common Pitfalls">
    **(Don't ❌) Common AI Collaboration Mistakes**

    * **Vague Requests**: "Create a button component" without specifications
    * **Blind Acceptance**: Using AI code without review or understanding
    * **Missing Context**: Not providing project-specific requirements
    * **Over-reliance**: Expecting AI to make architectural decisions
    * **Ignoring Standards**: Not validating against your coding standards
    * **Copy-paste Coding**: Using AI output without adaptation

    **Example of Poor Request**:

    ```markdown
    Make a form component that looks nice
    ```

    **Why it's problematic**:

    * No technical specifications
    * No design requirements
    * No integration context
    * No accessibility considerations
  </Tab>

  <Tab value="Quality Control">
    **Quality Control Checklist**

    When using AI-generated code, always verify:

    * [ ] **TypeScript Compliance**: No `any` types, proper type safety
    * [ ] **Design Token Usage**: All styling uses theme tokens
    * [ ] **Accessibility**: Proper roles, labels, and keyboard support
    * [ ] **Performance**: Appropriate memoization and optimizations
    * [ ] **Testing**: Comprehensive test coverage included
    * [ ] **Documentation**: Clear comments and prop descriptions
    * [ ] **Standards Alignment**: Follows your project conventions

    **Validation Commands**:

    ```bash
    # Type checking
    npx tsc --noEmit

    # Linting
    npm run lint

    # Test coverage
    npm test -- --coverage

    # Accessibility audit
    npm run a11y:check
    ```
  </Tab>
</Tabs>

## Phase 1: Requirements & Planning

### AI Prompt: Requirements Definition

<Tabs items={["Basic Template", "Advanced Template", "Example Usage"]}>
  <Tab value="Basic Template">
    ```markdown
    # Component Requirements Definition

    ## Component Context
    - **Component Name**: [Name]
    - **Purpose**: [What it does and why]
    - **Category**: [foundation/patterns/business]
    - **Usage**: [Where and how it will be used]

    ## Technical Requirements
    - React Native with TypeScript
    - Must use design tokens from @/core/shared/styles/theme
    - Accessibility compliant (WCAG 2.1 AA)
    - Cross-platform (iOS & Android)

    ## Please Define:
    1. Complete props interface with types
    2. All component states (default, loading, error, etc.)
    3. Accessibility requirements
    4. Performance considerations
    5. Integration points
    ```
  </Tab>

  <Tab value="Advanced Template">
    ```markdown
    # Advanced Component Specification

    ## Project Context
    - **Tech Stack**: React Native, TypeScript, Expo
    - **Architecture**: Three-layer UI (foundation/patterns/business)
    - **Design System**: [Link to design system]
    - **Similar Components**: [List existing similar components]

    ## Component Details
    - **Name**: [ComponentName]
    - **Purpose**: [Detailed purpose and use cases]
    - **User Stories**: 
      - As a [user], I want to [action] so that [benefit]
      - [Add more user stories]

    ## Technical Specifications
    - **Props Schema**: [Describe expected props]
    - **State Management**: [Local state, context, or external]
    - **Data Flow**: [How data moves through component]
    - **Side Effects**: [API calls, subscriptions, etc.]

    ## Design Requirements
    - **Visual States**: [All visual variations]
    - **Responsive Behavior**: [Mobile, tablet adaptations]
    - **Animation**: [Transitions, loading states]
    - **Theme Support**: [Light/dark mode considerations]

    ## Quality Requirements
    - **Performance**: [Render time, memory usage targets]
    - **Accessibility**: [Specific a11y requirements]
    - **Testing**: [Unit, integration, visual tests needed]
    - **Documentation**: [Props table, examples needed]

    ## Constraints & Considerations
    - **Platform Differences**: [iOS vs Android specifics]
    - **Backwards Compatibility**: [Version support]
    - **Migration Path**: [From existing components]
    ```
  </Tab>

  <Tab value="Example Usage">
    **Example: Search Input Component**

    ```markdown
    # Component Requirements Definition

    ## Component Context
    - **Component Name**: SearchInput
    - **Purpose**: Provides search functionality with autocomplete
    - **Category**: patterns (combines Input + suggestions list)
    - **Usage**: Header search, product search, user search

    ## Technical Requirements
    - React Native with TypeScript
    - Must use design tokens from @/core/shared/styles/theme
    - Accessibility compliant (WCAG 2.1 AA)
    - Cross-platform (iOS & Android)
    - Debounced input for performance

    ## Please Define:
    1. Complete props interface including:
       - Search query handling
       - Suggestion data structure
       - Loading states
       - Customization options
    2. States: empty, typing, loading, results, no results, error
    3. Accessibility: search role, live regions for results
    4. Performance: debouncing, virtualized suggestion list
    5. Integration: How it works with our API client
    ```

    **AI Response Would Include**:

    * Complete TypeScript interfaces
    * State management approach
    * Accessibility implementation
    * Performance optimization strategies
    * Integration examples
  </Tab>
</Tabs>

### AI Prompt: Component Categorization

```markdown
# Component Categorization Decision

## Component Information
- **Name**: [ComponentName]
- **Purpose**: [What the component does]
- **Dependencies**: [What it depends on]
- **Complexity**: [Simple/Medium/Complex]

## Questions to Answer
1. Does it contain business logic or domain rules? [Yes/No]
   - If yes, describe: [Details]

2. Does it combine multiple simpler components? [Yes/No]
   - If yes, list components: [Component list]

3. Is it a single, reusable UI element? [Yes/No]
   - If yes, describe core function: [Details]

## Please recommend:
- Appropriate category (foundation/patterns/business)
- Justification for the recommendation
- Similar existing components in that category
- Potential architectural concerns
```

## Phase 2: Implementation

### AI Prompt: Component Structure

<Tabs items={["File Generation", "Boilerplate Creation", "Complex Component"]}>
  <Tab>
    ```markdown
    # Generate Component File Structure

    ## Component Details
    - **Name**: [ComponentName]
    - **Category**: [foundation/patterns/business]
    - **Purpose**: [Brief description]

    ## Generate Files:
    1. `[ComponentName].tsx` - Main component
    2. `types.ts` - TypeScript interfaces
    3. `index.ts` - Exports
    4. `[ComponentName].test.tsx` - Tests
    5. `styles.ts` - Styled components (if needed)
    6. `hooks.ts` - Custom hooks (if needed)

    ## Requirements:
    - TypeScript with strict mode
    - React Native components
    - Design tokens from @/core/shared/styles/theme
    - Accessibility attributes
    - JSDoc documentation
    - Export patterns matching our standards
    ```
  </Tab>

  <Tab>
    ````markdown
    # Component Boilerplate Generation

    Create a [ComponentName] component with:

    ## Structure Requirements
    - Functional component with TypeScript
    - Props interface in separate types.ts
    - ForwardRef implementation (if applicable)
    - Memoization for performance
    - Error boundary support

    ## Include These Patterns:
    ```typescript
    // Example patterns to follow
    export const Component = React.memo(
      React.forwardRef<View, ComponentProps>((props, ref) => {
        // Implementation
      })
    );
    Component.displayName = 'ComponentName';
    ````

    ## Styling Requirements:

    * Use StyleSheet.create
    * Import theme tokens
    * Support theme variants
    * Handle responsive sizing

    ## Standard Props:

    * testID for testing
    * style for custom styling
    * accessibility props
    * className (if web support needed)

    ````
    </Tab>
    <Tab>
    ```markdown
    # Complex Pattern Component

    Generate a [ComponentName] that:

    ## Architecture
    - Uses compound component pattern
    - Provides context for child components
    - Exports sub-components

    ## Example Structure:
    ```typescript
    <DataTable>
      <DataTable.Header>
        <DataTable.Column>Name</DataTable.Column>
      </DataTable.Header>
      <DataTable.Body>
        <DataTable.Row>
          <DataTable.Cell>Value</DataTable.Cell>
        </DataTable.Row>
      </DataTable.Body>
    </DataTable>
    ````

    ## Requirements:

    * Type-safe compound components
    * Context for shared state
    * Flexible composition
    * Child component validation
    * Proper display names

    ## Files Needed:

    * Main component with context
    * Sub-components in separate files
    * Comprehensive types
    * Usage examples

    ````
    </Tab>
    </Tabs>

    ### AI Prompt: Implementation

    ```markdown
    # Implement [ComponentName] Component

    ## Specifications
    [Paste the agreed-upon props interface and requirements]

    ## Implementation Requirements:
    1. **Core Functionality**
    - [List specific features to implement]
    - Handle all props appropriately
    - Implement proper state management

    2. **Styling**
    - Use only design tokens from theme
    - Create responsive styles
    - Handle all visual states

    3. **Accessibility**
    - Add appropriate ARIA attributes
    - Ensure keyboard navigation
    - Include screen reader support

    4. **Performance**
    - Use React.memo if appropriate
    - Implement useMemo/useCallback where needed
    - Optimize re-renders

    5. **Error Handling**
    - Validate props
    - Handle edge cases
    - Provide meaningful error messages

    ## Code Structure:
    - Clear separation of concerns
    - Extracted helper functions
    - Proper TypeScript types
    - Comprehensive JSDoc comments
    ````

    ### AI Prompt: Design Token Application

    ````markdown
    # Apply Design Tokens to [ComponentName]

    ## Component Styling Needs:
    - Visual states: [default, hover, active, disabled]
    - Size variations: [small, medium, large]
    - Theme support: [light, dark]

    ## Available Tokens:
    ```typescript
    // Reference our theme structure
    theme = {
      colors: { primary, secondary, text, background },
      spacing: { xs, sm, md, lg, xl },
      typography: { size, weight, lineHeight },
      radii: { sm, md, lg },
      shadows: { sm, md, lg }
    }
    ````

    ## Create styles.ts that:

    1. Uses only theme tokens (no hardcoded values)
    2. Supports all component variants
    3. Handles responsive sizing
    4. Includes platform-specific styles if needed
    5. Exports typed style functions

    ## Example Pattern:

    ```typescript
    export const getStyles = (props: StyleProps) => {
      return StyleSheet.create({
        container: {
          backgroundColor: theme.colors[props.variant],
          padding: theme.spacing[props.size],
          // etc.
        }
      });
    };
    ```

    ````

    ### AI Prompt: Accessibility Implementation

    ```markdown
    # Add Accessibility to [ComponentName]

    ## Component Type: [Button/Input/List/etc.]

    ## Accessibility Requirements:
    1. **Screen Reader Support**
       - Appropriate role
       - Descriptive labels
       - State announcements
       - Value announcements (if applicable)

    2. **Keyboard Navigation**
       - Focus management
       - Tab order
       - Keyboard shortcuts (if applicable)

    3. **Visual Accessibility**
       - Focus indicators
       - Color contrast compliance
       - Touch target size (min 44x44)

    ## Platform Considerations:
    - iOS: VoiceOver specific attributes
    - Android: TalkBack specific attributes

    ## Implementation Checklist:
    - [ ] accessibilityRole
    - [ ] accessibilityLabel
    - [ ] accessibilityHint
    - [ ] accessibilityState
    - [ ] accessibilityValue
    - [ ] accessibilityActions
    - [ ] Focus management hooks

    Please implement comprehensive accessibility with examples.
    ````

    ## Phase 3: Testing

    ### AI Prompt: Test Generation

    <Tabs items={["Unit Tests", "Integration Tests", "Accessibility Tests"]}>
      <Tab value="Unit Tests">
        ```markdown
        # Generate Unit Tests for [ComponentName]

        ## Component Details:
        [Paste component props interface]

        ## Test Requirements:
        1. **Rendering Tests**
           - Default props rendering
           - All prop variations
           - Conditional rendering

        2. **Interaction Tests**
           - User interactions (press, type, etc.)
           - Event handler calls
           - State changes

        3. **Props Tests**
           - Required vs optional props
           - Prop type validation
           - Default values

        4. **Edge Cases**
           - Empty/null data
           - Very long content
           - Error states
           - Loading states

        ## Test Utilities:
        - @testing-library/react-native
        - Jest
        - Custom test utils from test-utils/

        ## Coverage Target: 80%+
        ```
      </Tab>

      <Tab value="Integration Tests">
        ````markdown
        # Integration Tests for [ComponentName]

        ## Integration Points:
        - [ ] Theme Provider integration
        - [ ] Navigation integration
        - [ ] State management integration
        - [ ] API integration (if applicable)

        ## Test Scenarios:
        1. **With Providers**
           ```typescript
           <ThemeProvider>
             <NavigationContainer>
               <Component />
             </NavigationContainer>
           </ThemeProvider>
        ````

        2. **With Feature Context**
           * Test within actual feature usage
           * Verify data flow
           * Check side effects

        3. **Cross-Component Integration**
           * Test with related components
           * Verify communication
           * Check composed behavior

        ## Mock Requirements:

        * Navigation mocks
        * API mocks
        * Storage mocks
        * Platform mocks

        ````
        </Tab>
        <Tab value="Accessibility Tests">
        ```markdown
        # Accessibility Tests for [ComponentName]

        ## Test Requirements:

        1. **Screen Reader Tests**
           - Verify all content is announced
           - Check role accuracy
           - Test state change announcements
           - Validate reading order

        2. **Keyboard Navigation Tests**
           - Tab order verification
           - Focus trap testing (if modal)
           - Keyboard shortcut functionality
           - Focus visible indicators

        3. **ARIA Compliance**
           - Required ARIA attributes
           - Valid ARIA relationships
           - Live region updates

        4. **Interaction Tests**
           - Touch target size (44x44 minimum)
           - Gesture alternatives
           - Time-based interaction alternatives

        ## Example Test Structure:
        ```typescript
        describe('Accessibility', () => {
          it('announces role correctly', () => {
            // Test implementation
          });
          
          it('provides descriptive labels', () => {
            // Test implementation
          });
          
          it('manages focus appropriately', () => {
            // Test implementation
          });
        });
        ````
      </Tab>
    </Tabs>

    ### AI Prompt: Snapshot Tests

    ````markdown
    # Generate Snapshot Tests for [ComponentName]

    ## Requirements:
    1. Create snapshots for all visual variants
    2. Include different prop combinations
    3. Test responsive sizes
    4. Capture loading/error states

    ## Structure:
    ```typescript
    describe('ComponentName Snapshots', () => {
      describe('Variants', () => {
        it.each(['primary', 'secondary', 'danger'])
          ('renders %s variant', (variant) => {
            // Snapshot test
          });
      });
      
      describe('States', () => {
        // Loading, disabled, error snapshots
      });
      
      describe('Sizes', () => {
        // Small, medium, large snapshots
      });
    });
    ````

    ## Include:

    * Platform-specific snapshots if needed
    * Theme variant snapshots
    * Complex content scenarios

    ````

    ## Phase 4: Documentation

    ### AI Prompt: Component Documentation

    ```markdown
    # Document [ComponentName] Component

    ## Create Comprehensive Documentation:

    ### 1. Overview Section
    - Component purpose and use cases
    - When to use vs when not to use
    - Related components

    ### 2. Props Documentation
    ```typescript
    interface ComponentProps {
      // Include all props with descriptions
    }
    ````

    ### 3. Usage Examples

    * Basic usage
    * Advanced usage
    * Common patterns
    * Integration examples

    ### 4. Styling Guide

    * Available variants
    * Customization options
    * Theme integration

    ### 5. Accessibility Guide

    * Keyboard shortcuts
    * Screen reader behavior
    * Best practices

    ### 6. Performance Considerations

    * Optimization tips
    * Common pitfalls
    * Benchmarks

    ### 7. Migration Guide (if replacing existing)

    * Breaking changes
    * Update steps
    * Codemod availability

    Format as MDX with live code examples.

    ````

    ## Best Practices Summary

    <Callout type="success">
      **Maximizing AI Effectiveness**
      
      The key to successful AI collaboration is providing clear context, validating output against standards, and using AI as a tool to accelerate development rather than replace critical thinking.
    </Callout>

    ### Quick Reference: Effective Prompts

    <Tabs items={["Planning Phase", "Implementation Phase", "Testing Phase"]}>
      <Tab value="Planning Phase">
        **Planning & Design Prompts**
        
        ```markdown
        # Requirements Definition
        "Define props and states for a [Component] that [purpose]"
        
        # API Design
        "Design a TypeScript interface for [Component] following React Native patterns"
        
        # Architecture Decision
        "Should [Component] be foundation/pattern/business? It [description]"
        
        # Accessibility Planning
        "What accessibility features does a [Component type] need?"
    ````
  </Tab>

  <Tab value="Implementation Phase">
    **Implementation Prompts**

    ```markdown
    # Component Creation
    "Create a React Native [Component] with TypeScript and design tokens"

    # Style Implementation
    "Apply theme tokens to style [Component] with [variants]"

    # State Management
    "Implement [feature] using React hooks and proper memoization"

    # Error Handling
    "Add comprehensive error handling to [Component]"
    ```
  </Tab>

  <Tab value="Testing Phase">
    **Testing & Documentation Prompts**

    ```markdown
    # Test Generation
    "Write unit tests for [Component] with 80%+ coverage"

    # Accessibility Testing
    "Create accessibility tests for [Component] screen reader support"

    # Documentation
    "Document [Component] with props table and usage examples"

    # Performance Testing
    "Write performance tests for [Component] render optimization"
    ```
  </Tab>
</Tabs>

### Integration with CI/CD

Consider using AI tools in your CI/CD pipeline:

```yaml
# Example: AI-assisted code review
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  ai-review:
    steps:
      - name: AI Code Review
        run: |
          # Check for design token usage
          # Verify accessibility attributes
          # Validate TypeScript types
          # Suggest improvements
```

## Next Steps

1. **Practice with Simple Components**: Start with foundation components
2. **Build Prompt Library**: Save effective prompts for reuse
3. **Share Team Learnings**: Document what works well
4. **Iterate and Improve**: Refine prompts based on results
5. **Maintain Standards**: Always validate against project guidelines

## Related Documents

* [Development Workflow](/docs/ui-development/architecture/development-workflow) - Complete development process
* [Component Patterns](/docs/ui-development/development/component-patterns) - Implementation patterns
* [Testing Strategies](/docs/ui-development/architecture/development-workflow/testing-strategies) - Testing approaches
* [Code Review Guidelines](/docs/development-workflow/code-review) - Review standards


# UTA UI Development: Component Patterns
URL: https://dev.updatetheapp.com/docs/ui-development/development/component-patterns
Documentation: https://dev.updatetheapp.com/docs/ui-development/development/component-patterns

Best practices and patterns for building reusable, maintainable React Native components
        
***

title: Component Patterns
description: Best practices and patterns for building reusable, maintainable React Native components
----------------------------------------------------------------------------------------------------

import { File, Folder, Files } from 'fumadocs-ui/components/files';
import { Callout } from 'fumadocs-ui/components/callout';

# Component Patterns

## Executive Summary

This document outlines standardized patterns for building React Native components in our application. It covers component organization, TypeScript integration, performance optimization, and testing strategies. Following these patterns ensures consistency, maintainability, and optimal performance across the codebase.

<Callout type="info">
  **Component Development Philosophy**

  Our component architecture emphasizes:

  * **Reusability**: Build once, use everywhere
  * **Type Safety**: Full TypeScript coverage
  * **Performance**: Optimized for 60fps
  * **Testability**: Easy to test in isolation
  * **Accessibility**: Inclusive by default
</Callout>

## Purpose & Scope

* **Target Audience**: React Native developers building UI components for the application
* **Problems Addressed**: Component reusability, type safety, performance optimization, and testing complexity
* **Scope Boundaries**: Covers component architecture, patterns, and best practices but not state management or business logic implementation

## Guide Sections

This comprehensive guide is organized into focused sections:

### 📋 [Component Architecture](/docs/ui-development/development/component-patterns/component-architecture)

Fundamental patterns and organization strategies:

* Directory structure and file organization
* Component types (Pure, Container/Presenter, Compound, HOC, Render Props)
* Data flow patterns
* Architecture diagrams

### 📘 [TypeScript Patterns](/docs/ui-development/development/component-patterns/typescript-patterns)

Type-safe component development:

* Props interface patterns
* Generic components
* Discriminated unions
* Advanced TypeScript techniques

### ⚡ [Performance Optimization](/docs/ui-development/development/component-patterns/performance-optimization)

Building high-performance components:

* Memoization strategies
* Lazy loading patterns
* Virtualization techniques
* Bundle size optimization

### 🧪 [Testing Strategies](/docs/ui-development/development/component-patterns/testing-strategies)

Comprehensive testing approaches:

* Component testing patterns
* Hook testing
* Visual regression testing
* Testing best practices

## Component Organization

### Standard Directory Structure

<Files>
  <Folder name="ComponentName" defaultOpen>
    <File name="ComponentName.tsx" />

    <File name="styles.ts" />

    <File name="types.ts" />

    <File name="index.ts" />

    <Folder name="__tests__">
      <File name="ComponentName.test.tsx" />
    </Folder>

    <Folder name="hooks">
      <File name="useComponentLogic.ts" />
    </Folder>
  </Folder>
</Files>

### File Responsibilities

```typescript
// ComponentName.tsx - Main component implementation
export const ComponentName: React.FC<ComponentNameProps> = ({ prop1, prop2 }) => {
  // Component logic
  return <View>...</View>;
};

// styles.ts - Component styles
import { StyleSheet } from 'react-native';
export const styles = StyleSheet.create({
  container: { flex: 1 },
});

// types.ts - Component types and interfaces
export interface ComponentNameProps {
  prop1: string;
  prop2?: number;
  onPress?: () => void;
}

// index.ts - Barrel export
export { ComponentName } from './ComponentName';
export type { ComponentNameProps } from './types';
```

## Quick Examples

### Pure Functional Component

For a complete example of a pure functional component with all features, see the [Button Reference Implementation](/docs/reference-implementations/ui/foundation/Button).

Key patterns demonstrated:

* ✅ Pure functional component with TypeScript
* ✅ Props interface with proper defaults
* ✅ Design token integration
* ✅ Accessibility implementation
* ✅ Loading and disabled states

### Container/Presenter Pattern

```typescript
// Container handles data and logic
export const ProductListContainer: React.FC = () => {
  const { data: products, isLoading, error } = useProducts();

  if (isLoading) return <LoadingView />;
  if (error) return <ErrorView error={error} />;

  return <ProductList products={products} />;
};

// Presenter handles UI rendering
export const ProductList: React.FC<ProductListProps> = ({ products }) => {
  return (
    <FlatList
      data={products}
      renderItem={({ item }) => <ProductCard product={item} />}
    />
  );
};
```

## Design Principles

### Core Principles

1. **Single Responsibility**: Each component should do one thing well
2. **Composition over Inheritance**: Build complex UIs from simple components
3. **Props over State**: Prefer controlled components
4. **Type Safety**: Full TypeScript coverage
5. **Performance First**: Optimize for 60fps

### Component Decision Matrix

| Pattern             | Benefits            | Drawbacks      | Use When               |
| ------------------- | ------------------- | -------------- | ---------------------- |
| Container/Presenter | Clear separation    | More files     | Complex state logic    |
| Compound Components | Flexible API        | More complex   | Multi-part components  |
| Render Props        | Maximum flexibility | Verbose syntax | Dynamic rendering      |
| HOCs                | Reusable logic      | Wrapper hell   | Cross-cutting concerns |

## Best Practices Summary

<Callout type="success">
  **Component Development Checklist**

  * ✅ Use TypeScript for all components
  * ✅ Include accessibility props
  * ✅ Export types alongside components
  * ✅ Optimize for performance
  * ✅ Write comprehensive tests
  * ✅ Document complex patterns
  * ✅ Follow naming conventions
</Callout>

### Quick Do's and Don'ts

* **(Do ✅)** Keep components focused on a single responsibility
* **(Do ✅)** Provide sensible default props
* **(Do ✅)** Use design tokens for styling
* **(Don't ❌)** Put business logic in presentational components
* **(Don't ❌)** Use inline styles for complex styling
* **(Don't ❌)** Create deeply nested component structures
* **(Consider 🤔)** Breaking large components into smaller ones
* **(Be Aware ❗)** Of performance implications for list items

## Summary

Effective component patterns ensure:

1. **Consistent structure** across the codebase
2. **Reusable and testable** components
3. **Type-safe** implementations
4. **Performance** optimizations
5. **Clear separation** of concerns

Following these patterns creates a maintainable, scalable UI architecture.

## Related Documents

* [Project Structure](/docs/architecture/project-structure) - Overall project organization
* [Three-Layer Architecture](/docs/ui-development/architecture#three-layer-architecture) - Component categorization
* [Component Examples](/docs/reference-implementations/ui) - Real-world implementations
* [TypeScript Guidelines](/docs/coding-standards/typescript-guidelines) - TypeScript best practices
* [Testing Standards](/docs/testing/testing-standards) - Component testing strategies


# UTA UI Development: Component Architecture
URL: https://dev.updatetheapp.com/docs/ui-development/development/component-patterns/component-architecture
Documentation: https://dev.updatetheapp.com/docs/ui-development/development/component-patterns/component-architecture

Fundamental patterns and organization strategies for React Native components
        
***

title: Component Architecture
description: Fundamental patterns and organization strategies for React Native components
-----------------------------------------------------------------------------------------

import { Callout } from 'fumadocs-ui/components/callout';

# Component Architecture

## Overview

This section covers the fundamental architectural patterns for building React Native components. Understanding these patterns helps create consistent, maintainable, and scalable component architectures.

<Callout type="info">
  **Architectural Goals**

  Our component architecture aims to:

  * **Separate concerns** between logic and presentation
  * **Maximize reusability** across different contexts
  * **Ensure testability** in isolation
  * **Optimize performance** by default
</Callout>

## Core Components/Architecture

<Mermaid
  chart={`
flowchart TD
subgraph ComponentArchitecture[Component Architecture]
  UI[UI Components]
  Hooks[Custom Hooks]
  Props[Props/Types]
  Styles[StyleSheet]
end

subgraph DataFlow[Data Flow]
  State[State Management]
  Props[Component Props]
  Events[Event Handlers]
end

UI --> Hooks
UI --> Props
UI --> Styles

Props --> State
Events --> State
State --> UI

style UI fill:#bbf,stroke:#333
style Hooks fill:#f9f,stroke:#333
style Props fill:#bfb,stroke:#333
style Styles fill:#fbb,stroke:#333
style State fill:#ffe,stroke:#333
style Events fill:#ddf,stroke:#333
`}
/>

## Component Types and Patterns

### 1. Pure Functional Components

The default pattern for all components. Pure components are predictable and easy to test.

```typescript
// ui/foundation/Button/Button.tsx
import React from 'react';
import { TouchableOpacity, Text, ActivityIndicator } from 'react-native';
import { styles } from './styles';
import type { ButtonProps } from './types';

export const Button: React.FC<ButtonProps> = ({
  title,
  onPress,
  variant = 'primary',
  size = 'medium',
  disabled = false,
  loading = false,
  testID,
  ...rest
}) => {
  const isDisabled = disabled || loading;

  return (
    <TouchableOpacity
      style={[
        styles.button,
        styles[variant],
        styles[size],
        isDisabled && styles.disabled,
      ]}
      onPress={onPress}
      disabled={isDisabled}
      testID={testID}
      {...rest}
    >
      {loading ? (
        <ActivityIndicator color={styles[variant].color} />
      ) : (
        <Text style={[styles.text, styles[`${variant}Text`]]}>{title}</Text>
      )}
    </TouchableOpacity>
  );
};
```

### 2. Container/Presentational Pattern

<Mermaid
  chart={`flowchart TD
  Container[Container Component] --> |Props| Presenter[Presentational Component]
  Container --> |Data| Store[State/API]
  Store --> |Updates| Container
  
  style Container fill:#f9f,stroke:#333,stroke-width:2px
  style Presenter fill:#bbf,stroke:#333,stroke-width:2px
  style Store fill:#bfb,stroke:#333,stroke-width:2px
`}
/>

#### Container Component (Smart)

Handles data fetching, state management, and business logic:

```typescript
// features/products/components/ProductList/ProductListContainer.tsx
import React from 'react';
import { useProducts } from '@/core/domains/products/hooks';
import { ProductList } from './ProductList';
import { LoadingView, ErrorView } from '@/ui';

export const ProductListContainer: React.FC = () => {
  const { data: products, isLoading, error, refetch } = useProducts();

  if (isLoading) return <LoadingView />;
  if (error) return <ErrorView error={error} onRetry={refetch} />;

  return (
    <ProductList 
      products={products} 
      onRefresh={refetch}
    />
  );
};
```

#### Presentational Component (Dumb)

Focuses purely on UI rendering:

```typescript
// features/products/components/ProductList/ProductList.tsx
import React from 'react';
import { FlatList, RefreshControl } from 'react-native';
import { ProductCard } from '../ProductCard';
import { EmptyState } from '@/ui';
import type { Product } from '@/core/domains/products/types';
import { styles } from './styles';

interface ProductListProps {
  products: Product[];
  onRefresh?: () => void;
  refreshing?: boolean;
}

export const ProductList: React.FC<ProductListProps> = ({ 
  products, 
  onRefresh,
  refreshing = false 
}) => {
  return (
    <FlatList
      data={products}
      keyExtractor={(item) => item.id}
      renderItem={({ item }) => <ProductCard product={item} />}
      contentContainerStyle={styles.container}
      ItemSeparatorComponent={() => <View style={styles.separator} />}
      ListEmptyComponent={<EmptyState message="No products found" />}
      refreshControl={
        onRefresh ? (
          <RefreshControl refreshing={refreshing} onRefresh={onRefresh} />
        ) : undefined
      }
    />
  );
};
```

### 3. Compound Component Pattern

For complex components with multiple related parts:

```typescript
// ui/Card/Card.tsx
import React, { createContext, useContext } from 'react';
import { View, Text } from 'react-native';
import { styles } from './styles';
import type { CardProps, CardContextValue } from './types';

// Context for sharing state between compound components
const CardContext = createContext<CardContextValue | undefined>(undefined);

// Main component with sub-components
export const Card: React.FC<CardProps> & {
  Header: typeof CardHeader;
  Body: typeof CardBody;
  Footer: typeof CardFooter;
} = ({ children, variant = 'default', elevated = false }) => {
  const contextValue: CardContextValue = { variant, elevated };

  return (
    <CardContext.Provider value={contextValue}>
      <View style={[
        styles.container, 
        styles[variant],
        elevated && styles.elevated
      ]}>
        {children}
      </View>
    </CardContext.Provider>
  );
};

// Sub-components
const CardHeader: React.FC<CardHeaderProps> = ({ title, subtitle, action }) => {
  const context = useContext(CardContext);
  
  return (
    <View style={styles.header}>
      <View style={styles.headerText}>
        <Text style={[styles.title, styles[`${context?.variant}Title`]]}>
          {title}
        </Text>
        {subtitle && (
          <Text style={styles.subtitle}>{subtitle}</Text>
        )}
      </View>
      {action && <View style={styles.headerAction}>{action}</View>}
    </View>
  );
};

const CardBody: React.FC<CardBodyProps> = ({ children, padded = true }) => (
  <View style={[styles.body, padded && styles.bodyPadded]}>
    {children}
  </View>
);

const CardFooter: React.FC<CardFooterProps> = ({ children, divider = true }) => (
  <View style={[styles.footer, divider && styles.footerDivider]}>
    {children}
  </View>
);

// Attach sub-components
Card.Header = CardHeader;
Card.Body = CardBody;
Card.Footer = CardFooter;

// Usage example:
<Card variant="elevated" elevated>
  <Card.Header 
    title="Product Details" 
    subtitle="Premium Collection"
    action={<IconButton icon="more-vert" onPress={handleMore} />}
  />
  <Card.Body>
    <ProductDetails product={product} />
  </Card.Body>
  <Card.Footer>
    <Button title="Add to Cart" onPress={handleAddToCart} />
  </Card.Footer>
</Card>
```

### 4. Higher-Order Component Pattern

For adding cross-cutting functionality:

```typescript
// ui/hoc/withLoading.tsx
import React from 'react';
import { View, ActivityIndicator } from 'react-native';
import { styles } from './styles';

interface WithLoadingProps {
  isLoading: boolean;
  loadingComponent?: React.ReactElement;
}

export function withLoading<P extends object>(
  Component: React.ComponentType<P>
): React.FC<P & WithLoadingProps> {
  return ({ isLoading, loadingComponent, ...props }) => {
    if (isLoading) {
      return loadingComponent || (
        <View style={styles.loadingContainer}>
          <ActivityIndicator size="large" />
        </View>
      );
    }
    
    return <Component {...(props as P)} />;
  };
}

// Usage
const ProductListWithLoading = withLoading(ProductList);

// In component
<ProductListWithLoading 
  isLoading={loading} 
  products={products} 
/>
```

### 5. Render Props Pattern

For maximum flexibility in rendering:

```typescript
// ui/DataProvider/DataProvider.tsx
interface DataProviderProps<T> {
  url: string;
  params?: Record<string, any>;
  children: (props: {
    data: T | null;
    loading: boolean;
    error: Error | null;
    refetch: () => void;
  }) => React.ReactElement;
}

export function DataProvider<T>({ url, params, children }: DataProviderProps<T>) {
  const [state, setState] = useState<{
    data: T | null;
    loading: boolean;
    error: Error | null;
  }>({
    data: null,
    loading: true,
    error: null,
  });

  const fetchData = useCallback(async () => {
    setState(prev => ({ ...prev, loading: true, error: null }));
    
    try {
      const response = await api.get<T>(url, { params });
      setState({ data: response.data, loading: false, error: null });
    } catch (error) {
      setState({ data: null, loading: false, error: error as Error });
    }
  }, [url, params]);

  useEffect(() => {
    fetchData();
  }, [fetchData]);

  return children({
    ...state,
    refetch: fetchData,
  });
}

// Usage
<DataProvider<Product[]> url="/api/products" params={{ category: 'electronics' }}>
  {({ data, loading, error, refetch }) => {
    if (loading) return <LoadingView />;
    if (error) return <ErrorView error={error} onRetry={refetch} />;
    return <ProductList products={data!} onRefresh={refetch} />;
  }}
</DataProvider>
```

## Component Data Flow

<Mermaid
  chart={`
flowchart TD
subgraph ComponentDataFlow[Component Data Flow]
  Props[Props]
  State[State]
  Events[Events]
  UI[UI Components]
end

Props --> UI
State --> UI
Events --> State

style Props fill:#bbf,stroke:#333
style State fill:#f9f,stroke:#333
style Events fill:#bfb,stroke:#333
style UI fill:#fbb,stroke:#333
`}
/>

### Data Flow Best Practices

1. **Unidirectional Data Flow**: Data flows down through props, events flow up through callbacks
2. **Single Source of Truth**: Each piece of state should have one authoritative source
3. **Immutable Updates**: Never mutate state directly
4. **Minimal State**: Only store what you can't derive

```typescript
// Example of proper data flow
const ParentComponent: React.FC = () => {
  const [selectedId, setSelectedId] = useState<string | null>(null);
  
  const handleSelect = (id: string) => {
    setSelectedId(id);
  };
  
  return (
    <View>
      <ChildComponent 
        selectedId={selectedId}
        onSelect={handleSelect}
      />
      <DetailView itemId={selectedId} />
    </View>
  );
};
```

## Design Decisions and Trade-offs

### Pattern Selection Guide

| Pattern                 | Use When                                                                                    | Avoid When                                                           |
| ----------------------- | ------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
| **Pure Components**     | - Simple UI with no side effects<br />- Props determine output<br />- Need high reusability | - Complex state management<br />- Side effects needed                |
| **Container/Presenter** | - Clear separation needed<br />- Complex business logic<br />- Different data sources       | - Simple components<br />- Overhead not justified                    |
| **Compound Components** | - Related UI elements<br />- Flexible composition<br />- Shared state needed                | - Simple, standalone components<br />- No relationship between parts |
| **HOCs**                | - Cross-cutting concerns<br />- Reusable enhancements<br />- Legacy codebases               | - Hooks can solve it<br />- Deep composition needed                  |
| **Render Props**        | - Maximum flexibility<br />- Dynamic rendering<br />- Inversion of control                  | - Simple cases<br />- Performance critical                           |

### Architecture Principles

1. **Composition Over Configuration**
   ```typescript
   // ✅ Good - Composable
   <Card>
     <Card.Header title="Title" />
     <Card.Body>{content}</Card.Body>
   </Card>

   // ❌ Avoid - Configuration heavy
   <Card 
     headerTitle="Title"
     bodyContent={content}
     showHeader={true}
     showBody={true}
   />
   ```

2. **Explicit Over Implicit**
   ```typescript
   // ✅ Good - Explicit props
   <Button 
     variant="primary"
     size="large"
     disabled={!isValid}
   />

   // ❌ Avoid - Implicit behavior
   <Button primary large />
   ```

3. **Isolated Over Coupled**
   ```typescript
   // ✅ Good - Isolated component
   <ProductCard 
     product={product}
     onPress={() => navigate('ProductDetail', { id: product.id })}
   />

   // ❌ Avoid - Coupled to navigation
   <ProductCard 
     product={product}
     navigation={navigation}
   />
   ```

## Summary

Component architecture patterns provide:

* **Structure** for organizing component code
* **Separation** of concerns between logic and UI
* **Flexibility** in composition and reuse
* **Consistency** across the codebase
* **Testability** through isolation

Choose patterns based on your specific needs, keeping simplicity and maintainability as primary goals.

## Next Steps

* Explore [TypeScript Patterns](/docs/ui-development/development/component-patterns/typescript-patterns) for type-safe components
* Learn about [Performance Optimization](/docs/ui-development/development/component-patterns/performance-optimization) techniques
* Review [Testing Strategies](/docs/ui-development/development/component-patterns/testing-strategies) for components

## Related Documents

* [Three-Layer Architecture](/docs/ui-development/architecture#three-layer-architecture)
* [Component Examples](/docs/ui-development/development/examples)
* [Project Structure](/docs/architecture/project-structure)


# UTA UI Development: TypeScript Patterns
URL: https://dev.updatetheapp.com/docs/ui-development/development/component-patterns/typescript-patterns
Documentation: https://dev.updatetheapp.com/docs/ui-development/development/component-patterns/typescript-patterns

Type-safe component development patterns and advanced TypeScript techniques
        
***

title: TypeScript Patterns
description: Type-safe component development patterns and advanced TypeScript techniques
----------------------------------------------------------------------------------------

import { Callout } from 'fumadocs-ui/components/callout';

# TypeScript Patterns

## Overview

TypeScript provides powerful type safety for React Native components. This guide covers essential patterns for building type-safe, maintainable components with comprehensive TypeScript support.

<Callout type="info">
  **TypeScript Benefits**

  Using TypeScript for components provides:

  * **Compile-time safety** catching errors before runtime
  * **Better IDE support** with autocomplete and refactoring
  * **Self-documenting code** through type definitions
  * **Easier refactoring** with confidence
</Callout>

## Props Interface Patterns

### Basic Props Pattern

Start with well-defined interfaces for all component props:

```typescript
// types.ts
import type { ViewStyle, TextStyle, StyleProp } from 'react-native';

// Base props for common attributes
interface BaseComponentProps {
  testID?: string;
  accessible?: boolean;
  accessibilityLabel?: string;
  accessibilityHint?: string;
  accessibilityRole?: string;
}

// Specific component props extending base
export interface ButtonProps extends BaseComponentProps {
  // Required props
  title: string;
  onPress: () => void;
  
  // Optional props with defaults
  variant?: 'primary' | 'secondary' | 'outline' | 'ghost';
  size?: 'small' | 'medium' | 'large';
  disabled?: boolean;
  loading?: boolean;
  
  // Style overrides
  style?: StyleProp<ViewStyle>;
  textStyle?: StyleProp<TextStyle>;
  
  // Additional content
  icon?: React.ReactNode;
  iconPosition?: 'left' | 'right';
}
```

### Props with Children

Handle different children patterns:

```typescript
// Single child required
interface SingleChildProps {
  children: React.ReactElement;
}

// Multiple children
interface MultipleChildrenProps {
  children: React.ReactNode;
}

// Typed children
interface TypedChildrenProps {
  children: React.ReactElement<ChildComponentProps> | React.ReactElement<ChildComponentProps>[];
}

// Function as children (render prop)
interface RenderChildrenProps<T> {
  children: (data: T) => React.ReactNode;
}
```

### Event Handler Props

Type event handlers properly:

```typescript
interface InteractiveComponentProps {
  // Simple event
  onPress?: () => void;
  
  // Event with parameters
  onChange?: (value: string) => void;
  
  // Event with event object
  onLayout?: (event: LayoutChangeEvent) => void;
  
  // Async event handler
  onSubmit?: (data: FormData) => Promise<void>;
  
  // Event that can prevent default
  onClose?: () => boolean | void;
}
```

## Generic Component Patterns

### Basic Generic Component

Create reusable components that work with any data type:

```typescript
// ui/List/List.tsx
interface ListProps<T> {
  data: T[];
  renderItem: (item: T, index: number) => React.ReactElement;
  keyExtractor: (item: T, index: number) => string;
  ItemSeparatorComponent?: React.ComponentType;
  ListEmptyComponent?: React.ComponentType;
  onItemPress?: (item: T) => void;
}

export function List<T>({
  data,
  renderItem,
  keyExtractor,
  ItemSeparatorComponent,
  ListEmptyComponent,
  onItemPress,
}: ListProps<T>) {
  if (data.length === 0 && ListEmptyComponent) {
    return <ListEmptyComponent />;
  }

  return (
    <FlatList
      data={data}
      renderItem={({ item, index }) => (
        <TouchableOpacity 
          onPress={() => onItemPress?.(item)}
          disabled={!onItemPress}
        >
          {renderItem(item, index)}
        </TouchableOpacity>
      )}
      keyExtractor={keyExtractor}
      ItemSeparatorComponent={ItemSeparatorComponent}
    />
  );
}

// Usage with type inference
<List<Product>
  data={products}
  renderItem={(product) => <ProductCard product={product} />}
  keyExtractor={(product) => product.id}
  onItemPress={(product) => navigateToProduct(product.id)}
/>
```

### Constrained Generics

Add constraints to generic types:

```typescript
// Ensure items have an id property
interface Identifiable {
  id: string;
}

interface SelectableListProps<T extends Identifiable> {
  items: T[];
  selectedIds: string[];
  onSelectionChange: (ids: string[]) => void;
  renderItem: (item: T, isSelected: boolean) => React.ReactElement;
}

export function SelectableList<T extends Identifiable>({
  items,
  selectedIds,
  onSelectionChange,
  renderItem,
}: SelectableListProps<T>) {
  const toggleSelection = (id: string) => {
    const newSelection = selectedIds.includes(id)
      ? selectedIds.filter(selectedId => selectedId !== id)
      : [...selectedIds, id];
    
    onSelectionChange(newSelection);
  };

  return (
    <FlatList
      data={items}
      renderItem={({ item }) => (
        <TouchableOpacity onPress={() => toggleSelection(item.id)}>
          {renderItem(item, selectedIds.includes(item.id))}
        </TouchableOpacity>
      )}
      keyExtractor={(item) => item.id}
    />
  );
}
```

## Discriminated Union Props

Use discriminated unions for components with multiple modes:

```typescript
// ui/Message/types.ts
type BaseMessageProps = {
  title: string;
  description?: string;
};

type MessageProps = BaseMessageProps & (
  | { type: 'success'; onDismiss?: () => void }
  | { type: 'error'; onRetry?: () => void; retryLabel?: string }
  | { type: 'warning'; action?: { label: string; onPress: () => void } }
  | { type: 'info' }
);

// ui/Message/Message.tsx
export const Message: React.FC<MessageProps> = (props) => {
  const renderAction = () => {
    switch (props.type) {
      case 'success':
        return props.onDismiss ? (
          <IconButton icon="close" onPress={props.onDismiss} />
        ) : null;
      
      case 'error':
        return props.onRetry ? (
          <Button 
            title={props.retryLabel || 'Retry'} 
            onPress={props.onRetry}
            size="small"
          />
        ) : null;
      
      case 'warning':
        return props.action ? (
          <Button 
            title={props.action.label} 
            onPress={props.action.onPress}
            size="small"
            variant="outline"
          />
        ) : null;
      
      case 'info':
        return null;
    }
  };

  return (
    <View style={[styles.container, styles[props.type]]}>
      <View style={styles.content}>
        <Text style={styles.title}>{props.title}</Text>
        {props.description && (
          <Text style={styles.description}>{props.description}</Text>
        )}
      </View>
      {renderAction()}
    </View>
  );
};
```

## Advanced Type Patterns

### Conditional Types

Use conditional types for flexible APIs:

```typescript
// Props that change based on a condition
type ConditionalProps<T extends boolean> = {
  multiSelect: T;
  value: T extends true ? string[] : string;
  onChange: (value: T extends true ? string[] : string) => void;
};

interface SelectProps<T extends boolean = false> extends ConditionalProps<T> {
  options: Array<{ label: string; value: string }>;
  placeholder?: string;
}

// Usage
<Select
  multiSelect={false}
  value="option1"
  onChange={(value) => console.log(value)} // value is string
  options={options}
/>

<Select
  multiSelect={true}
  value={["option1", "option2"]}
  onChange={(values) => console.log(values)} // values is string[]
  options={options}
/>
```

### Mapped Types

Create variations of existing types:

```typescript
// Make all properties optional except specific ones
type PartialExcept<T, K extends keyof T> = Partial<T> & Pick<T, K>;

interface FormFieldProps {
  name: string;
  label: string;
  value: string;
  error?: string;
  required?: boolean;
  disabled?: boolean;
}

// Label and name are required, others optional
type MinimalFormFieldProps = PartialExcept<FormFieldProps, 'name' | 'label'>;

// Create readonly version
type ReadonlyFormFieldProps = Readonly<FormFieldProps>;

// Deep partial for nested objects
type DeepPartial<T> = {
  [P in keyof T]?: T[P] extends object ? DeepPartial<T[P]> : T[P];
};
```

### Template Literal Types

Use template literals for dynamic prop names:

```typescript
type Spacing = 'small' | 'medium' | 'large';
type Side = 'top' | 'right' | 'bottom' | 'left';

// Generate margin/padding props
type SpacingProps = {
  [K in `margin${Capitalize<Side>}`]?: Spacing;
} & {
  [K in `padding${Capitalize<Side>}`]?: Spacing;
};

interface BoxProps extends SpacingProps {
  children: React.ReactNode;
}

// Usage provides autocomplete for all spacing props
<Box
  marginTop="small"
  paddingLeft="medium"
  paddingRight="medium"
>
  {content}
</Box>
```

## Type Guards and Assertions

### Custom Type Guards

Create type guards for runtime type checking:

```typescript
// Type guard functions
function isErrorResponse(response: ApiResponse): response is ErrorResponse {
  return 'error' in response && response.error !== undefined;
}

function isLoadingState<T>(state: AsyncState<T>): state is LoadingState {
  return state.status === 'loading';
}

// Using type guards
const handleResponse = (response: ApiResponse) => {
  if (isErrorResponse(response)) {
    // TypeScript knows response.error exists
    showError(response.error.message);
  } else {
    // TypeScript knows response.data exists
    processData(response.data);
  }
};
```

### Assertion Functions

Create assertion functions for type narrowing:

```typescript
function assertDefined<T>(value: T | null | undefined, message?: string): asserts value is T {
  if (value === null || value === undefined) {
    throw new Error(message || 'Value is not defined');
  }
}

function assertType<T>(value: unknown, check: (value: unknown) => value is T): asserts value is T {
  if (!check(value)) {
    throw new Error('Type assertion failed');
  }
}

// Usage
const processUser = (user: User | null) => {
  assertDefined(user, 'User must be logged in');
  // TypeScript now knows user is User, not null
  console.log(user.name);
};
```

## Utility Types

### Component Props Utilities

Extract and manipulate component props:

```typescript
// Extract props from a component
type ButtonComponentProps = React.ComponentProps<typeof Button>;

// Get ref type for a component
type ButtonRef = React.ElementRef<typeof Button>;

// Omit specific props
type ButtonWithoutOnPress = Omit<ButtonProps, 'onPress'>;

// Make specific props required
type RequiredFields<T, K extends keyof T> = T & Required<Pick<T, K>>;
type ButtonWithRequiredTestID = RequiredFields<ButtonProps, 'testID'>;

// Props with default values
interface PropsWithDefaults<T> {
  props: T;
  defaults: Partial<T>;
}
```

### HOC Type Patterns

Type higher-order components correctly:

```typescript
// HOC that adds props
interface WithThemeProps {
  theme: Theme;
}

function withTheme<P extends object>(
  Component: React.ComponentType<P & WithThemeProps>
): React.ComponentType<Omit<P, keyof WithThemeProps>> {
  return (props: Omit<P, keyof WithThemeProps>) => {
    const theme = useTheme();
    return <Component {...(props as P)} theme={theme} />;
  };
}

// HOC that modifies props
interface WithLoadingProps {
  loading?: boolean;
}

function withLoading<P extends object>(
  Component: React.ComponentType<P>
): React.ComponentType<P & WithLoadingProps> {
  return ({ loading, ...props }: P & WithLoadingProps) => {
    if (loading) {
      return <LoadingSpinner />;
    }
    return <Component {...(props as P)} />;
  };
}
```

## Best Practices

<Callout type="success">
  **TypeScript Best Practices**

  1. **Prefer interfaces over types** for object shapes
  2. **Use const assertions** for literal types
  3. **Export types alongside components**
  4. **Avoid `any`** - use `unknown` if type is truly unknown
  5. **Enable strict mode** in tsconfig.json
  6. **Document complex types** with JSDoc comments
</Callout>

### Type Organization

```typescript
// ❌ Avoid - Types mixed with implementation
const Button = ({ title, onPress }: { title: string; onPress: () => void }) => {
  // ...
};

// ✅ Good - Separate type definitions
interface ButtonProps {
  title: string;
  onPress: () => void;
}

const Button: React.FC<ButtonProps> = ({ title, onPress }) => {
  // ...
};

// ✅ Better - Types in separate file
// types.ts
export interface ButtonProps {
  title: string;
  onPress: () => void;
}

// Button.tsx
import type { ButtonProps } from './types';

export const Button: React.FC<ButtonProps> = ({ title, onPress }) => {
  // ...
};
```

### Const Assertions

Use const assertions for literal types:

```typescript
// Without const assertion
const SIZES = {
  small: 8,
  medium: 16,
  large: 24,
}; // Type: { small: number; medium: number; large: number; }

// With const assertion
const SIZES = {
  small: 8,
  medium: 16,
  large: 24,
} as const; // Type: { readonly small: 8; readonly medium: 16; readonly large: 24; }

type Size = keyof typeof SIZES; // 'small' | 'medium' | 'large'
type SizeValue = typeof SIZES[Size]; // 8 | 16 | 24
```

## Summary

TypeScript patterns for components ensure:

* **Type safety** throughout the component tree
* **Better developer experience** with autocomplete
* **Fewer runtime errors** through compile-time checks
* **Self-documenting code** through type definitions
* **Easier refactoring** with confidence

Use these patterns to build robust, maintainable React Native components.

## Next Steps

* Learn about [Performance Optimization](/docs/ui-development/development/component-patterns/performance-optimization) with TypeScript
* Review [Testing Strategies](/docs/ui-development/development/component-patterns/testing-strategies) for typed components
* Explore [Component Architecture](/docs/ui-development/development/component-patterns/component-architecture) patterns

## Related Documents

* [TypeScript Guidelines](/docs/coding-standards/typescript-guidelines)
* [Component Examples](/docs/ui-development/development/examples)
* [API Types](/docs/api/types)


# UTA UI Development: Performance Optimization
URL: https://dev.updatetheapp.com/docs/ui-development/development/component-patterns/performance-optimization
Documentation: https://dev.updatetheapp.com/docs/ui-development/development/component-patterns/performance-optimization

Building high-performance React Native components with optimization techniques
        
***

title: Performance Optimization
description: Building high-performance React Native components with optimization techniques
-------------------------------------------------------------------------------------------

import { Callout } from 'fumadocs-ui/components/callout';
import { Steps, Step } from 'fumadocs-ui/components/steps';

# Performance Optimization

## Overview

Performance is critical for React Native applications. This guide covers essential techniques for optimizing component performance, reducing re-renders, and ensuring smooth 60fps interactions.

<Callout type="warning">
  **Performance First Mindset**

  Poor performance in React Native manifests as:

  * Janky animations and scrolling
  * Slow screen transitions
  * Unresponsive touch interactions
  * High battery consumption

  Always profile before optimizing!
</Callout>

## Performance Implications

Understanding how React Native renders components is crucial:

* **JavaScript Thread**: Runs your React code and business logic
* **UI Thread**: Handles native UI rendering and user interactions
* **Bridge**: Communication layer between JS and native
* **60fps Target**: \~16ms per frame for smooth interactions

## Memoization Patterns

### React.memo for Pure Components

Prevent unnecessary re-renders with `React.memo`:

```typescript
// ❌ Without memo - re-renders on every parent update
const ExpensiveComponent: React.FC<Props> = ({ data, onPress }) => {
  console.log('Rendering ExpensiveComponent');
  return (
    <View>
      {data.map(item => (
        <Text key={item.id}>{item.name}</Text>
      ))}
    </View>
  );
};

// ✅ With memo - only re-renders when props change
export const ExpensiveComponent = React.memo<Props>(({ data, onPress }) => {
  console.log('Rendering ExpensiveComponent');
  return (
    <View>
      {data.map(item => (
        <Text key={item.id}>{item.name}</Text>
      ))}
    </View>
  );
});

// ✅ With custom comparison
export const ExpensiveComponent = React.memo<Props>(
  ({ data, onPress }) => {
    // Component implementation
  },
  (prevProps, nextProps) => {
    // Return true if props are equal (skip re-render)
    return (
      prevProps.data.length === nextProps.data.length &&
      prevProps.data.every((item, index) => item.id === nextProps.data[index].id)
    );
  }
);
```

### useMemo for Expensive Computations

Cache computed values between renders:

```typescript
const ProductList: React.FC<ProductListProps> = ({ products, filters }) => {
  // ❌ Recalculates on every render
  const filteredProducts = products.filter(product => {
    return filters.every(filter => filter.matches(product));
  });

  // ✅ Only recalculates when dependencies change
  const filteredProducts = useMemo(() => {
    console.log('Filtering products');
    return products.filter(product => {
      return filters.every(filter => filter.matches(product));
    });
  }, [products, filters]);

  // ✅ Complex calculations
  const statistics = useMemo(() => {
    return {
      total: filteredProducts.length,
      avgPrice: filteredProducts.reduce((sum, p) => sum + p.price, 0) / filteredProducts.length,
      categories: [...new Set(filteredProducts.map(p => p.category))],
    };
  }, [filteredProducts]);

  return (
    <View>
      <Statistics {...statistics} />
      <FlatList
        data={filteredProducts}
        renderItem={({ item }) => <ProductCard product={item} />}
      />
    </View>
  );
};
```

### useCallback for Stable References

Prevent child re-renders by maintaining stable function references:

```typescript
const ParentComponent: React.FC = () => {
  const [selectedId, setSelectedId] = useState<string | null>(null);

  // ❌ Creates new function on every render
  const handleSelect = (id: string) => {
    setSelectedId(id);
  };

  // ✅ Stable function reference
  const handleSelect = useCallback((id: string) => {
    setSelectedId(id);
  }, []); // Empty deps because setState is stable

  // ✅ With dependencies
  const handleSelectWithLogging = useCallback((id: string) => {
    console.log(`Previous: ${selectedId}, New: ${id}`);
    setSelectedId(id);
  }, [selectedId]);

  return (
    <FlatList
      data={items}
      renderItem={({ item }) => (
        <MemoizedItem
          item={item}
          isSelected={item.id === selectedId}
          onSelect={handleSelect}
        />
      )}
    />
  );
};
```

## Lazy Loading Patterns

### Component Code Splitting

Split large components to reduce initial bundle size:

```typescript
// ❌ Loading everything upfront
import { HeavyComponent } from './HeavyComponent';
import { AnalyticsView } from './AnalyticsView';
import { AdminPanel } from './AdminPanel';

// ✅ Load on demand
const HeavyComponent = lazy(() => import('./HeavyComponent'));
const AnalyticsView = lazy(() => import('./AnalyticsView'));
const AdminPanel = lazy(() => import('./AdminPanel'));

const App: React.FC = () => {
  const [showAnalytics, setShowAnalytics] = useState(false);

  return (
    <View>
      <Suspense fallback={<LoadingSpinner />}>
        {showAnalytics && <AnalyticsView />}
      </Suspense>
    </View>
  );
};
```

### Progressive Loading

Load content progressively for better perceived performance:

```typescript
const ProgressiveScreen: React.FC = () => {
  const [phase, setPhase] = useState<'critical' | 'important' | 'nice-to-have'>('critical');

  useEffect(() => {
    // Load critical content immediately
    const timer1 = setTimeout(() => setPhase('important'), 100);
    const timer2 = setTimeout(() => setPhase('nice-to-have'), 500);

    return () => {
      clearTimeout(timer1);
      clearTimeout(timer2);
    };
  }, []);

  return (
    <ScrollView>
      {/* Critical content - render immediately */}
      <Header />
      <MainContent />

      {/* Important but not critical */}
      {phase !== 'critical' && (
        <Suspense fallback={<Skeleton height={200} />}>
          <RelatedContent />
        </Suspense>
      )}

      {/* Nice to have - load last */}
      {phase === 'nice-to-have' && (
        <Suspense fallback={<Skeleton height={100} />}>
          <Recommendations />
        </Suspense>
      )}
    </ScrollView>
  );
};
```

## Virtualization Patterns

### Optimized FlatList

Configure FlatList for optimal performance:

```typescript
const OptimizedList: React.FC<Props> = ({ data }) => {
  // Stable references for props
  const keyExtractor = useCallback((item: Item) => item.id, []);
  
  const getItemLayout = useCallback(
    (data: ArrayLike<Item> | null | undefined, index: number) => ({
      length: ITEM_HEIGHT,
      offset: ITEM_HEIGHT * index,
      index,
    }),
    []
  );

  const renderItem = useCallback(({ item }: { item: Item }) => (
    <MemoizedItemComponent item={item} />
  ), []);

  return (
    <FlatList
      data={data}
      renderItem={renderItem}
      keyExtractor={keyExtractor}
      getItemLayout={getItemLayout}
      
      // Performance optimizations
      removeClippedSubviews={true}
      maxToRenderPerBatch={10}
      updateCellsBatchingPeriod={50}
      windowSize={10}
      initialNumToRender={10}
      
      // Avoid inline functions
      ItemSeparatorComponent={ItemSeparator}
      ListEmptyComponent={EmptyComponent}
      ListFooterComponent={FooterComponent}
    />
  );
};

// Memoized item component
const ItemComponent = memo<{ item: Item }>(({ item }) => {
  return (
    <View style={styles.item}>
      <Text>{item.title}</Text>
      <Text>{item.description}</Text>
    </View>
  );
});

// Pre-defined components
const ItemSeparator = () => <View style={styles.separator} />;
const EmptyComponent = () => <EmptyState message="No items" />;
const FooterComponent = () => <LoadingIndicator />;
```

### Custom Virtualization

For complex layouts, implement custom virtualization:

```typescript
const VirtualizedGrid: React.FC<Props> = ({ items, columns = 2 }) => {
  const [visibleRange, setVisibleRange] = useState({ start: 0, end: 10 });
  
  const handleScroll = useCallback((event: NativeSyntheticEvent<NativeScrollEvent>) => {
    const { contentOffset, layoutMeasurement } = event.nativeEvent;
    const itemHeight = ITEM_HEIGHT + ITEM_MARGIN;
    const rowsPerScreen = Math.ceil(layoutMeasurement.height / itemHeight);
    
    const startRow = Math.floor(contentOffset.y / itemHeight);
    const endRow = startRow + rowsPerScreen + 1; // Buffer
    
    setVisibleRange({
      start: startRow * columns,
      end: Math.min(endRow * columns, items.length)
    });
  }, [columns, items.length]);

  const visibleItems = useMemo(() => 
    items.slice(visibleRange.start, visibleRange.end),
    [items, visibleRange]
  );

  return (
    <ScrollView onScroll={handleScroll} scrollEventThrottle={16}>
      <View style={{ height: Math.ceil(items.length / columns) * (ITEM_HEIGHT + ITEM_MARGIN) }}>
        {visibleItems.map((item, index) => {
          const actualIndex = visibleRange.start + index;
          const row = Math.floor(actualIndex / columns);
          const col = actualIndex % columns;
          
          return (
            <View
              key={item.id}
              style={[
                styles.gridItem,
                {
                  position: 'absolute',
                  top: row * (ITEM_HEIGHT + ITEM_MARGIN),
                  left: col * (ITEM_WIDTH + ITEM_MARGIN),
                }
              ]}
            >
              <GridItem item={item} />
            </View>
          );
        })}
      </View>
    </ScrollView>
  );
};
```

## Optimization Techniques

### Image Optimization

<Steps>
  <Step>
    #### Use Appropriate Formats

    ```typescript
    // ✅ Use FastImage for better caching
    import FastImage from 'react-native-fast-image';

    <FastImage
      style={styles.image}
      source={{
        uri: imageUrl,
        priority: FastImage.priority.normal,
      }}
      resizeMode={FastImage.resizeMode.cover}
    />
    ```
  </Step>

  <Step>
    #### Implement Progressive Loading

    ```typescript
    const ProgressiveImage: React.FC<Props> = ({ source, thumbnail }) => {
      const [loaded, setLoaded] = useState(false);
      const opacity = useRef(new Animated.Value(0)).current;
      
      const onLoad = () => {
        Animated.timing(opacity, {
          toValue: 1,
          duration: 300,
          useNativeDriver: true,
        }).start();
        setLoaded(true);
      };
      
      return (
        <View>
          <FastImage
            source={{ uri: thumbnail }}
            style={styles.image}
            blurRadius={loaded ? 0 : 2}
          />
          <Animated.View style={[styles.imageOverlay, { opacity }]}>
            <FastImage
              source={{ uri: source }}
              style={styles.image}
              onLoad={onLoad}
            />
          </Animated.View>
        </View>
      );
    };
    ```
  </Step>

  <Step>
    #### Optimize Image Sizes

    ```typescript
    const getOptimizedImageUrl = (url: string, width: number) => {
      // Use image service that supports resizing
      return `${url}?w=${width}&q=75&fm=webp`;
    };

    const ResponsiveImage: React.FC<Props> = ({ source }) => {
      const { width } = useWindowDimensions();
      const imageUrl = useMemo(() => 
        getOptimizedImageUrl(source, width * PixelRatio.get()),
        [source, width]
      );
      
      return <FastImage source={{ uri: imageUrl }} />;
    };
    ```
  </Step>
</Steps>

### Animation Optimization

Use native driver and optimize animations:

```typescript
// ❌ JS-driven animation (runs on JS thread)
Animated.timing(animatedValue, {
  toValue: 1,
  duration: 300,
  useNativeDriver: false, // Can't use native driver with layout props
}).start();

// ✅ Native-driven animation (runs on UI thread)
const AnimatedComponent: React.FC = () => {
  const translateY = useRef(new Animated.Value(0)).current;
  const opacity = useRef(new Animated.Value(0)).current;

  useEffect(() => {
    Animated.parallel([
      Animated.timing(translateY, {
        toValue: -20,
        duration: 300,
        useNativeDriver: true, // ✅ Runs on UI thread
      }),
      Animated.timing(opacity, {
        toValue: 1,
        duration: 300,
        useNativeDriver: true, // ✅ Runs on UI thread
      }),
    ]).start();
  }, []);

  return (
    <Animated.View
      style={{
        transform: [{ translateY }],
        opacity,
      }}
    >
      {/* Content */}
    </Animated.View>
  );
};
```

### Reanimated for Complex Animations

Use Reanimated 2 for high-performance animations:

```typescript
import Animated, {
  useSharedValue,
  useAnimatedStyle,
  withSpring,
  withTiming,
  runOnJS,
} from 'react-native-reanimated';

const InteractiveComponent: React.FC = () => {
  const scale = useSharedValue(1);
  const rotation = useSharedValue(0);

  const animatedStyle = useAnimatedStyle(() => ({
    transform: [
      { scale: scale.value },
      { rotateZ: `${rotation.value}deg` },
    ],
  }));

  const handlePress = () => {
    scale.value = withSpring(1.2, {}, () => {
      scale.value = withSpring(1);
    });
    rotation.value = withTiming(360, { duration: 500 }, () => {
      rotation.value = 0;
    });
  };

  return (
    <Animated.View style={[styles.box, animatedStyle]}>
      <TouchableOpacity onPress={handlePress}>
        <Text>Tap me!</Text>
      </TouchableOpacity>
    </Animated.View>
  );
};
```

## Common Pitfalls and Solutions

<Mermaid
  chart={`flowchart TD
  Issue1[Re-rendering Issues] --> Solution1[Use memo/useCallback]
  Issue2[Slow Lists] --> Solution2[Optimize FlatList]
  Issue3[Large Bundle] --> Solution3[Code Splitting]
  Issue4[Memory Leaks] --> Solution4[Cleanup Effects]
  Issue5[Janky Animations] --> Solution5[Use Native Driver]
  
  style Issue1 fill:#fbb,stroke:#333,stroke-width:2px
  style Issue2 fill:#fbb,stroke:#333,stroke-width:2px
  style Issue3 fill:#fbb,stroke:#333,stroke-width:2px
  style Issue4 fill:#fbb,stroke:#333,stroke-width:2px
  style Issue5 fill:#fbb,stroke:#333,stroke-width:2px
  
  style Solution1 fill:#bfb,stroke:#333,stroke-width:2px
  style Solution2 fill:#bfb,stroke:#333,stroke-width:2px
  style Solution3 fill:#bfb,stroke:#333,stroke-width:2px
  style Solution4 fill:#bfb,stroke:#333,stroke-width:2px
  style Solution5 fill:#bfb,stroke:#333,stroke-width:2px
`}
/>

### Common Issues and Solutions

1. **Anonymous Functions in Render**
   ```typescript
   // ❌ Creates new function every render
   <Button onPress={() => handlePress(item.id)} />

   // ✅ Stable reference
   const handleItemPress = useCallback((id: string) => {
     handlePress(id);
   }, [handlePress]);
   ```

2. **Inline Styles**
   ```typescript
   // ❌ Creates new object every render
   <View style={{ flex: 1, padding: 20 }} />

   // ✅ Use StyleSheet
   <View style={styles.container} />
   ```

3. **Array Index as Key**
   ```typescript
   // ❌ Causes re-render issues
   items.map((item, index) => <Item key={index} />)

   // ✅ Use stable unique key
   items.map((item) => <Item key={item.id} />)
   ```

## Performance Monitoring

### Performance Observer

Monitor component performance in development:

```typescript
const usePerformanceMonitor = (componentName: string) => {
  const renderCount = useRef(0);
  const renderTime = useRef(performance.now());
  
  useEffect(() => {
    renderCount.current += 1;
    const now = performance.now();
    const timeSinceLastRender = now - renderTime.current;
    renderTime.current = now;
    
    if (__DEV__) {
      console.log(`[Performance] ${componentName}:`, {
        renderCount: renderCount.current,
        timeSinceLastRender: `${timeSinceLastRender.toFixed(2)}ms`,
      });
    }
  });
};

// Usage
const MyComponent: React.FC = () => {
  usePerformanceMonitor('MyComponent');
  // Component logic
};
```

## Best Practices

<Callout type="success">
  **Performance Best Practices**

  1. **Profile before optimizing** - Use React DevTools Profiler
  2. **Optimize the critical path** - Focus on initial render
  3. **Avoid premature optimization** - Measure first
  4. **Use production builds** for performance testing
  5. **Test on low-end devices** - They reveal issues
  6. **Monitor bundle size** - Use Metro bundle analyzer
</Callout>

### Performance Guidelines

* **(Do ✅) Use FlatList** for long lists
* **(Do ✅) Implement getItemLayout** when possible
* **(Do ✅) Use InteractionManager** for post-interaction work
* **(Do ✅) Profile on real devices**
* **(Don't ❌) Nest FlatLists** or ScrollViews
* **(Don't ❌) Use array index** as key in lists
* **(Consider 🤔) React.memo** for expensive components
* **(Be Aware ❗) Of re-render cascades** in large trees

## Summary

Performance optimization in React Native requires:

* **Understanding the render cycle** and bridge communication
* **Strategic memoization** to prevent unnecessary work
* **Efficient list rendering** with proper virtualization
* **Native-driven animations** for smooth interactions
* **Continuous monitoring** and profiling

Always measure performance impact before and after optimizations.

## Next Steps

* Review [Testing Strategies](/docs/ui-development/development/component-patterns/testing-strategies) for performance testing
* Explore [Component Architecture](/docs/ui-development/development/component-patterns/component-architecture) for efficient patterns
* Learn about [TypeScript Patterns](/docs/ui-development/development/component-patterns/typescript-patterns) for type-safe optimizations

## Related Documents

* [React Native Performance](https://reactnative.dev/docs/performance)
* [Flipper Integration](/docs/debugging/flipper)
* [Bundle Optimization](/docs/deployment/bundle-optimization)


# UTA UI Development: Testing Strategies
URL: https://dev.updatetheapp.com/docs/ui-development/development/component-patterns/testing-strategies
Documentation: https://dev.updatetheapp.com/docs/ui-development/development/component-patterns/testing-strategies

Comprehensive testing approaches for React Native components
        
***

title: Testing Strategies
description: Comprehensive testing approaches for React Native components
-------------------------------------------------------------------------

import { Callout } from 'fumadocs-ui/components/callout';
import { Steps, Step } from 'fumadocs-ui/components/steps';

# Testing Strategies

## Overview

Testing React Native components ensures reliability, maintainability, and confidence in your code. This guide covers unit testing, integration testing, and visual regression testing strategies.

<Callout type="info">
  **Testing Philosophy**

  Good tests should be:

  * **Fast** - Run quickly for rapid feedback
  * **Reliable** - Consistent results across runs
  * **Isolated** - Test one thing at a time
  * **Readable** - Clear intent and failure messages
  * **Maintainable** - Easy to update with code changes
</Callout>

## Component Testing Patterns

### Basic Component Tests

Start with testing component rendering and basic interactions:

```typescript
// ui/foundation/Button/__tests__/Button.test.tsx
import React from 'react';
import { render, fireEvent, screen } from '@testing-library/react-native';
import { Button } from '../Button';

describe('Button Component', () => {
  it('renders correctly with required props', () => {
    render(<Button title="Click me" onPress={() => {}} />);
    
    expect(screen.getByText('Click me')).toBeTruthy();
  });

  it('calls onPress when pressed', () => {
    const onPress = jest.fn();
    render(<Button title="Click me" onPress={onPress} />);
    
    fireEvent.press(screen.getByText('Click me'));
    
    expect(onPress).toHaveBeenCalledTimes(1);
  });

  it('shows loading state', () => {
    render(
      <Button 
        title="Click me" 
        onPress={() => {}} 
        loading 
        testID="button" 
      />
    );
    
    expect(screen.getByTestId('button-loading')).toBeTruthy();
    expect(screen.queryByText('Click me')).toBeNull();
  });

  it('disables interaction when disabled', () => {
    const onPress = jest.fn();
    render(
      <Button 
        title="Click me" 
        onPress={onPress} 
        disabled 
        testID="button"
      />
    );
    
    const button = screen.getByTestId('button');
    fireEvent.press(button);
    
    expect(onPress).not.toHaveBeenCalled();
    expect(button.props.accessibilityState.disabled).toBe(true);
  });
});
```

### Testing Props and State

Test component behavior with different prop combinations:

```typescript
// features/products/components/__tests__/ProductCard.test.tsx
import React from 'react';
import { render, fireEvent, screen, waitFor } from '@testing-library/react-native';
import { ProductCard } from '../ProductCard';
import { mockProduct } from '@/test/mocks';

describe('ProductCard Component', () => {
  const defaultProps = {
    product: mockProduct,
    onPress: jest.fn(),
    onAddToCart: jest.fn(),
  };

  beforeEach(() => {
    jest.clearAllMocks();
  });

  it('displays product information correctly', () => {
    render(<ProductCard {...defaultProps} />);
    
    expect(screen.getByText(mockProduct.name)).toBeTruthy();
    expect(screen.getByText(`$${mockProduct.price}`)).toBeTruthy();
    expect(screen.getByTestId('product-image')).toHaveProp('source', {
      uri: mockProduct.imageUrl,
    });
  });

  it('shows discount badge when product is on sale', () => {
    const productOnSale = {
      ...mockProduct,
      originalPrice: 100,
      price: 80,
    };
    
    render(<ProductCard {...defaultProps} product={productOnSale} />);
    
    expect(screen.getByText('20% OFF')).toBeTruthy();
    expect(screen.getByText('$100')).toHaveStyle({
      textDecorationLine: 'line-through',
    });
  });

  it('handles favorite toggle', async () => {
    const { rerender } = render(
      <ProductCard {...defaultProps} isFavorite={false} />
    );
    
    const favoriteButton = screen.getByTestId('favorite-button');
    fireEvent.press(favoriteButton);
    
    // Simulate prop update from parent
    rerender(<ProductCard {...defaultProps} isFavorite={true} />);
    
    await waitFor(() => {
      expect(screen.getByTestId('favorite-icon-filled')).toBeTruthy();
    });
  });
});
```

### Testing Async Behavior

Handle asynchronous operations in tests:

```typescript
// features/search/components/__tests__/SearchBar.test.tsx
import React from 'react';
import { render, fireEvent, screen, waitFor } from '@testing-library/react-native';
import { SearchBar } from '../SearchBar';

describe('SearchBar Component', () => {
  jest.useFakeTimers();

  it('debounces search input', async () => {
    const onSearch = jest.fn();
    render(<SearchBar onSearch={onSearch} debounceMs={300} />);
    
    const input = screen.getByPlaceholderText('Search...');
    
    // Type multiple characters quickly
    fireEvent.changeText(input, 'a');
    fireEvent.changeText(input, 'ab');
    fireEvent.changeText(input, 'abc');
    
    // onSearch should not be called immediately
    expect(onSearch).not.toHaveBeenCalled();
    
    // Fast-forward timers
    jest.advanceTimersByTime(300);
    
    // Should be called once with final value
    expect(onSearch).toHaveBeenCalledTimes(1);
    expect(onSearch).toHaveBeenCalledWith('abc');
  });

  it('shows loading state during search', async () => {
    const onSearch = jest.fn().mockImplementation(() => 
      new Promise(resolve => setTimeout(resolve, 1000))
    );
    
    render(<SearchBar onSearch={onSearch} />);
    
    const input = screen.getByPlaceholderText('Search...');
    fireEvent.changeText(input, 'test');
    fireEvent(input, 'submitEditing');
    
    // Should show loading
    await waitFor(() => {
      expect(screen.getByTestId('search-loading')).toBeTruthy();
    });
    
    // Complete the search
    jest.advanceTimersByTime(1000);
    
    // Loading should disappear
    await waitFor(() => {
      expect(screen.queryByTestId('search-loading')).toBeNull();
    });
  });
});
```

## Hook Testing

### Custom Hook Tests

Test custom hooks in isolation:

```typescript
// features/cart/hooks/__tests__/useCart.test.ts
import { renderHook, act } from '@testing-library/react-hooks';
import { useCart } from '../useCart';
import { mockProduct } from '@/test/mocks';

describe('useCart Hook', () => {
  it('adds items to cart', () => {
    const { result } = renderHook(() => useCart());
    
    expect(result.current.items).toHaveLength(0);
    expect(result.current.total).toBe(0);
    
    act(() => {
      result.current.addItem(mockProduct);
    });
    
    expect(result.current.items).toHaveLength(1);
    expect(result.current.items[0]).toEqual({
      ...mockProduct,
      quantity: 1,
    });
    expect(result.current.total).toBe(mockProduct.price);
  });

  it('updates quantity for existing items', () => {
    const { result } = renderHook(() => useCart());
    
    act(() => {
      result.current.addItem(mockProduct);
      result.current.addItem(mockProduct);
    });
    
    expect(result.current.items).toHaveLength(1);
    expect(result.current.items[0].quantity).toBe(2);
    expect(result.current.total).toBe(mockProduct.price * 2);
  });

  it('removes items from cart', () => {
    const { result } = renderHook(() => useCart());
    
    act(() => {
      result.current.addItem(mockProduct);
    });
    
    expect(result.current.items).toHaveLength(1);
    
    act(() => {
      result.current.removeItem(mockProduct.id);
    });
    
    expect(result.current.items).toHaveLength(0);
    expect(result.current.total).toBe(0);
  });

  it('clears cart', () => {
    const { result } = renderHook(() => useCart());
    
    act(() => {
      result.current.addItem(mockProduct);
      result.current.addItem({ ...mockProduct, id: '2' });
    });
    
    expect(result.current.items).toHaveLength(2);
    
    act(() => {
      result.current.clearCart();
    });
    
    expect(result.current.items).toHaveLength(0);
    expect(result.current.total).toBe(0);
  });
});
```

### Testing Hooks with Context

Test hooks that depend on context:

```typescript
// core/auth/hooks/__tests__/useAuth.test.tsx
import React from 'react';
import { renderHook, act } from '@testing-library/react-hooks';
import { AuthProvider } from '../../context/AuthContext';
import { useAuth } from '../useAuth';
import { authService } from '../../services/authService';

// Mock the auth service
jest.mock('../../services/authService');

describe('useAuth Hook', () => {
  const wrapper = ({ children }: { children: React.ReactNode }) => (
    <AuthProvider>{children}</AuthProvider>
  );

  beforeEach(() => {
    jest.clearAllMocks();
  });

  it('starts with unauthenticated state', () => {
    const { result } = renderHook(() => useAuth(), { wrapper });
    
    expect(result.current.isAuthenticated).toBe(false);
    expect(result.current.user).toBeNull();
    expect(result.current.isLoading).toBe(false);
  });

  it('handles login successfully', async () => {
    const mockUser = { id: '1', email: 'test@example.com' };
    (authService.login as jest.Mock).mockResolvedValue({
      user: mockUser,
      token: 'mock-token',
    });
    
    const { result } = renderHook(() => useAuth(), { wrapper });
    
    await act(async () => {
      await result.current.login('test@example.com', 'password');
    });
    
    expect(result.current.isAuthenticated).toBe(true);
    expect(result.current.user).toEqual(mockUser);
    expect(authService.login).toHaveBeenCalledWith(
      'test@example.com',
      'password'
    );
  });

  it('handles login failure', async () => {
    const error = new Error('Invalid credentials');
    (authService.login as jest.Mock).mockRejectedValue(error);
    
    const { result } = renderHook(() => useAuth(), { wrapper });
    
    await expect(
      act(async () => {
        await result.current.login('test@example.com', 'wrong-password');
      })
    ).rejects.toThrow('Invalid credentials');
    
    expect(result.current.isAuthenticated).toBe(false);
    expect(result.current.user).toBeNull();
  });
});
```

## Integration Testing

### Screen Integration Tests

Test complete user flows:

```typescript
// features/checkout/__tests__/CheckoutFlow.test.tsx
import React from 'react';
import { render, fireEvent, screen, waitFor } from '@testing-library/react-native';
import { NavigationContainer } from '@react-navigation/native';
import { CheckoutNavigator } from '../navigation/CheckoutNavigator';
import { CartProvider } from '@/features/cart/context/CartContext';
import { mockProduct } from '@/test/mocks';
import * as api from '@/core/api';

// Mock API calls
jest.mock('@/core/api');

describe('Checkout Flow Integration', () => {
  const renderCheckout = () => {
    return render(
      <NavigationContainer>
        <CartProvider>
          <CheckoutNavigator />
        </CartProvider>
      </NavigationContainer>
    );
  };

  it('completes full checkout flow', async () => {
    (api.processPayment as jest.Mock).mockResolvedValue({
      success: true,
      orderId: '12345',
    });

    renderCheckout();
    
    // Add item to cart
    fireEvent.press(screen.getByText('Add to Cart'));
    
    // Navigate to checkout
    fireEvent.press(screen.getByText('Checkout'));
    
    // Fill shipping info
    await waitFor(() => {
      expect(screen.getByText('Shipping Information')).toBeTruthy();
    });
    
    fireEvent.changeText(
      screen.getByPlaceholderText('Full Name'),
      'John Doe'
    );
    fireEvent.changeText(
      screen.getByPlaceholderText('Address'),
      '123 Main St'
    );
    
    fireEvent.press(screen.getByText('Continue to Payment'));
    
    // Fill payment info
    await waitFor(() => {
      expect(screen.getByText('Payment Information')).toBeTruthy();
    });
    
    fireEvent.changeText(
      screen.getByPlaceholderText('Card Number'),
      '4242424242424242'
    );
    
    // Complete order
    fireEvent.press(screen.getByText('Place Order'));
    
    // Verify success screen
    await waitFor(() => {
      expect(screen.getByText('Order Confirmed!')).toBeTruthy();
      expect(screen.getByText('Order #12345')).toBeTruthy();
    });
  });
});
```

## Testing Best Practices

<Steps>
  <Step>
    #### Arrange, Act, Assert

    ```typescript
    it('follows AAA pattern', () => {
      // Arrange - Set up test data and conditions
      const onPress = jest.fn();
      const { getByText } = render(
        <Button title="Click" onPress={onPress} />
      );
      
      // Act - Perform the action
      fireEvent.press(getByText('Click'));
      
      // Assert - Verify the outcome
      expect(onPress).toHaveBeenCalledTimes(1);
    });
    ```
  </Step>

  <Step>
    #### Use Testing IDs

    ```typescript
    // Component
    <TouchableOpacity
      testID="submit-button"
      accessibilityLabel="Submit form"
      onPress={handleSubmit}
    >
      <Text>Submit</Text>
    </TouchableOpacity>

    // Test
    const submitButton = screen.getByTestId('submit-button');
    fireEvent.press(submitButton);
    ```
  </Step>

  <Step>
    #### Mock External Dependencies

    ```typescript
    // Mock navigation
    const mockNavigate = jest.fn();
    jest.mock('@react-navigation/native', () => ({
      useNavigation: () => ({
        navigate: mockNavigate,
      }),
    }));

    // Mock async storage
    jest.mock('@react-native-async-storage/async-storage', () => ({
      getItem: jest.fn(),
      setItem: jest.fn(),
      removeItem: jest.fn(),
    }));
    ```
  </Step>
</Steps>

## Snapshot Testing

Use snapshots for stable UI components:

```typescript
// ui/Card/__tests__/Card.test.tsx
import React from 'react';
import renderer from 'react-test-renderer';
import { Card } from '../Card';

describe('Card Component Snapshots', () => {
  it('renders default card correctly', () => {
    const tree = renderer.create(
      <Card>
        <Card.Header title="Title" subtitle="Subtitle" />
        <Card.Body>
          <Text>Content</Text>
        </Card.Body>
      </Card>
    ).toJSON();
    
    expect(tree).toMatchSnapshot();
  });

  it('renders elevated card correctly', () => {
    const tree = renderer.create(
      <Card variant="elevated" elevated>
        <Card.Header title="Elevated Card" />
      </Card>
    ).toJSON();
    
    expect(tree).toMatchSnapshot();
  });
});
```

## Performance Testing

Test component performance characteristics:

```typescript
// ui/LargeList/__tests__/LargeList.performance.test.tsx
import React from 'react';
import { render, measure } from '@testing-library/react-native';
import { LargeList } from '../LargeList';

describe('LargeList Performance', () => {
  it('renders large dataset efficiently', async () => {
    const items = Array.from({ length: 1000 }, (_, i) => ({
      id: `item-${i}`,
      title: `Item ${i}`,
    }));
    
    const renderTime = await measure(() => {
      render(<LargeList data={items} />);
    });
    
    // Should render in under 100ms
    expect(renderTime).toBeLessThan(100);
  });

  it('handles rapid scrolling without dropping frames', () => {
    const { getByTestId } = render(
      <LargeList data={generateLargeDataset()} />
    );
    
    const list = getByTestId('large-list');
    const frameDrops = measureFrameDrops(() => {
      // Simulate rapid scrolling
      for (let i = 0; i < 10; i++) {
        fireEvent.scroll(list, {
          nativeEvent: {
            contentOffset: { y: i * 1000 },
          },
        });
      }
    });
    
    // Should maintain 60fps (no frame drops)
    expect(frameDrops).toBe(0);
  });
});
```

## Test Utilities

Create reusable test utilities:

```typescript
// test/utils/render.tsx
import React from 'react';
import { render as rtlRender } from '@testing-library/react-native';
import { ThemeProvider } from '@/ui/theme';
import { NavigationContainer } from '@react-navigation/native';

// Custom render with providers
export function render(
  ui: React.ReactElement,
  options?: {
    initialState?: any;
    theme?: 'light' | 'dark';
  }
) {
  const Wrapper: React.FC<{ children: React.ReactNode }> = ({ children }) => (
    <NavigationContainer>
      <ThemeProvider theme={options?.theme || 'light'}>
        {children}
      </ThemeProvider>
    </NavigationContainer>
  );

  return rtlRender(ui, { wrapper: Wrapper, ...options });
}

// Re-export everything
export * from '@testing-library/react-native';
```

## Best Practices Summary

<Callout type="success">
  **Testing Best Practices**

  1. **Test behavior, not implementation** - Focus on user interactions
  2. **Keep tests isolated** - Each test should be independent
  3. **Use descriptive test names** - Clear what's being tested
  4. **Avoid testing internals** - Test public APIs only
  5. **Mock external dependencies** - Keep tests fast and reliable
  6. **Test edge cases** - Empty states, errors, loading
  7. **Maintain test coverage** - Aim for 80%+ coverage
</Callout>

### Testing Guidelines

* **(Do ✅) Write tests first** (TDD) when possible
* **(Do ✅) Test user interactions** over implementation
* **(Do ✅) Use semantic queries** (by role, label, text)
* **(Do ✅) Test accessibility** features
* **(Don't ❌) Test framework code** or third-party libraries
* **(Don't ❌) Mock everything** - some integration is good
* **(Consider 🤔) Visual regression tests** for UI consistency
* **(Be Aware ❗) Of async behavior** - use waitFor appropriately

## Summary

Comprehensive testing ensures:

* **Confidence** in code changes
* **Documentation** through test cases
* **Regression prevention** for future changes
* **Better design** through testability
* **Faster debugging** with clear test failures

Invest in good tests - they pay dividends in maintainability.

## Related Documents

* [Component Patterns](/docs/ui-development/development/component-patterns)
* [Testing Standards](/docs/testing/testing-standards)
* [CI/CD Pipeline](/docs/deployment/ci-cd)
* [Mock Data](/docs/testing/mock-data)


# UTA UI Development: Testing Patterns for UI Components
URL: https://dev.updatetheapp.com/docs/ui-development/development/testing-patterns
Documentation: https://dev.updatetheapp.com/docs/ui-development/development/testing-patterns

Comprehensive guide to testing UI components across all architectural layers with practical examples and best practices.
        
***

title: Testing Patterns for UI Components\
description: Comprehensive guide to testing UI components across all architectural layers with practical examples and best practices.
-------------------------------------------------------------------------------------------------------------------------------------

import { Callout } from 'fumadocs-ui/components/callout';
import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Steps, Step } from 'fumadocs-ui/components/steps';
import { Card, Cards } from 'fumadocs-ui/components/card';

# UI Testing Patterns

## Overview

## Testing Strategy by Layer

### Foundation Components Testing

Foundation components are atomic UI elements with no business logic. Testing focuses on:

* (Do ✅) Test prop variations and visual states
* (Do ✅) Verify accessibility attributes
* (Do ✅) Test responsive behavior
* (Don't ❌) Test implementation details
* (Don't ❌) Mock child components

#### Example: Testing a Button Component

<Tabs items={["Component", "Test File", "Test Utils"]}>
  <Tab>
    ```typescript
    // src/ui/foundation/Button/Button.tsx
    import React from 'react';
    import { TouchableOpacity, Text, ActivityIndicator } from 'react-native';
    import { useTheme } from '@/core/shared/styles';

    interface ButtonProps {
      variant?: 'primary' | 'secondary' | 'danger';
      size?: 'small' | 'medium' | 'large';
      disabled?: boolean;
      loading?: boolean;
      onPress: () => void;
      children: React.ReactNode;
      testID?: string;
    }

    export const Button: React.FC<ButtonProps> = ({
      variant = 'primary',
      size = 'medium',
      disabled = false,
      loading = false,
      onPress,
      children,
      testID = 'button',
    }) => {
      const theme = useTheme();
      const styles = getStyles(theme, variant, size, disabled);

      return (
        <TouchableOpacity
          style={styles.container}
          onPress={onPress}
          disabled={disabled || loading}
          testID={testID}
          accessibilityRole="button"
          accessibilityState={{ disabled: disabled || loading }}
        >
          {loading ? (
            <ActivityIndicator color={styles.text.color} testID={`${testID}-loader`} />
          ) : (
            <Text style={styles.text}>{children}</Text>
          )}
        </TouchableOpacity>
      );
    };
    ```
  </Tab>

  <Tab>
    ```typescript
    // src/ui/foundation/Button/Button.test.tsx
    import React from 'react';
    import { render, fireEvent } from '@testing-library/react-native';
    import { Button } from './Button';
    import { ThemeProvider } from '@/core/shared/styles';

    const renderWithTheme = (component: React.ReactElement) => {
      return render(<ThemeProvider>{component}</ThemeProvider>);
    };

    describe('Button', () => {
      describe('Rendering', () => {
        it('renders with default props', () => {
          const { getByText, getByTestId } = renderWithTheme(
            <Button onPress={jest.fn()}>Click me</Button>
          );
          
          expect(getByText('Click me')).toBeTruthy();
          expect(getByTestId('button')).toBeTruthy();
        });

        it('renders all variants correctly', () => {
          const variants = ['primary', 'secondary', 'danger'] as const;
          
          variants.forEach(variant => {
            const { getByTestId } = renderWithTheme(
              <Button variant={variant} onPress={jest.fn()}>
                Test
              </Button>
            );
            
            const button = getByTestId('button');
            expect(button).toHaveStyle(expect.objectContaining({
              backgroundColor: expect.any(String)
            }));
          });
        });

        it('shows loading indicator when loading', () => {
          const { getByTestId, queryByText } = renderWithTheme(
            <Button loading onPress={jest.fn()}>
              Click me
            </Button>
          );
          
          expect(getByTestId('button-loader')).toBeTruthy();
          expect(queryByText('Click me')).toBeFalsy();
        });
      });

      describe('Interactions', () => {
        it('calls onPress when pressed', () => {
          const onPress = jest.fn();
          const { getByTestId } = renderWithTheme(
            <Button onPress={onPress}>Click me</Button>
          );
          
          fireEvent.press(getByTestId('button'));
          expect(onPress).toHaveBeenCalledTimes(1);
        });

        it('does not call onPress when disabled', () => {
          const onPress = jest.fn();
          const { getByTestId } = renderWithTheme(
            <Button disabled onPress={onPress}>
              Click me
            </Button>
          );
          
          fireEvent.press(getByTestId('button'));
          expect(onPress).not.toHaveBeenCalled();
        });
      });

      describe('Accessibility', () => {
        it('has correct accessibility props', () => {
          const { getByTestId } = renderWithTheme(
            <Button onPress={jest.fn()}>Click me</Button>
          );
          
          const button = getByTestId('button');
          expect(button).toHaveAccessibilityRole('button');
          expect(button).toHaveAccessibilityState({ disabled: false });
        });

        it('updates accessibility state when disabled', () => {
          const { getByTestId } = renderWithTheme(
            <Button disabled onPress={jest.fn()}>
              Click me
            </Button>
          );
          
          expect(getByTestId('button')).toHaveAccessibilityState({ 
            disabled: true 
          });
        });
      });
    });
    ```
  </Tab>

  <Tab>
    ```typescript
    // src/ui/test-utils/index.tsx
    import React from 'react';
    import { render, RenderOptions } from '@testing-library/react-native';
    import { ThemeProvider } from '@/core/shared/styles';
    import { SafeAreaProvider } from 'react-native-safe-area-context';

    interface AllTheProvidersProps {
      children: React.ReactNode;
    }

    const AllTheProviders: React.FC<AllTheProvidersProps> = ({ children }) => {
      return (
        <SafeAreaProvider>
          <ThemeProvider>
            {children}
          </ThemeProvider>
        </SafeAreaProvider>
      );
    };

    const customRender = (
      ui: React.ReactElement,
      options?: Omit<RenderOptions, 'wrapper'>
    ) => render(ui, { wrapper: AllTheProviders, ...options });

    // Re-export everything
    export * from '@testing-library/react-native';
    export { customRender as render };
    ```
  </Tab>
</Tabs>

### Pattern Components Testing

Pattern components compose foundation components and may have internal state. Testing focuses on:

* (Do ✅) Test component composition behavior
* (Do ✅) Verify state management works correctly
* (Do ✅) Test interaction between child components
* (Consider 🤔) Integration tests for complex patterns
* (Don't ❌) Test foundation component internals

#### Example: Testing a Form Pattern

```typescript
// src/ui/patterns/Form/Form.test.tsx
import React from 'react';
import { render, fireEvent, waitFor } from '@/ui/test-utils';
import { Form, FormField } from './Form';

describe('Form Pattern', () => {
  const mockSubmit = jest.fn();
  
  const TestForm = () => (
    <Form onSubmit={mockSubmit}>
      <FormField
        name="email"
        label="Email"
        rules={{ required: 'Email is required' }}
      />
      <FormField
        name="password"
        label="Password"
        type="password"
        rules={{ required: 'Password is required' }}
      />
    </Form>
  );

  beforeEach(() => {
    mockSubmit.mockClear();
  });

  it('validates required fields on submit', async () => {
    const { getByText } = render(<TestForm />);
    
    fireEvent.press(getByText('Submit'));
    
    await waitFor(() => {
      expect(getByText('Email is required')).toBeTruthy();
      expect(getByText('Password is required')).toBeTruthy();
    });
    
    expect(mockSubmit).not.toHaveBeenCalled();
  });

  it('submits valid form data', async () => {
    const { getByLabelText, getByText } = render(<TestForm />);
    
    fireEvent.changeText(getByLabelText('Email'), 'test@example.com');
    fireEvent.changeText(getByLabelText('Password'), 'password123');
    fireEvent.press(getByText('Submit'));
    
    await waitFor(() => {
      expect(mockSubmit).toHaveBeenCalledWith({
        email: 'test@example.com',
        password: 'password123'
      });
    });
  });
});
```

### Business Components Testing

Business components integrate with domain logic and external services. Testing strategy:

* (Do ✅) Mock external dependencies (API calls, navigation)
* (Do ✅) Test loading, error, and success states
* (Do ✅) Verify business logic execution
* (Do ✅) Test edge cases and error scenarios
* (Consider 🤔) Integration tests with real API in CI

#### Example: Testing a Product Card

<Tabs items={["Component", "Test", "Mocks"]}>
  <Tab>
    ```typescript
    // src/ui/business/ProductCard/ProductCard.tsx
    import React from 'react';
    import { View, Text } from 'react-native';
    import { Button } from '@/ui/foundation/Button';
    import { Card } from '@/ui/patterns/Card';
    import { useCart } from '@/features/cart/hooks';
    import { useProductDetails } from '@/features/products/hooks';
    import { formatPrice } from '@shared/utils';

    interface ProductCardProps {
      productId: string;
      onPress?: () => void;
    }

    export const ProductCard: React.FC<ProductCardProps> = ({ 
      productId, 
      onPress 
    }) => {
      const { data: product, isLoading, error } = useProductDetails(productId);
      const { addToCart, isAddingToCart } = useCart();

      if (isLoading) return <Card.Skeleton />;
      if (error) return <Card.Error message="Failed to load product" />;
      if (!product) return null;

      const handleAddToCart = async () => {
        try {
          await addToCart(product);
        } catch (error) {
          // Error handling is done in the hook
        }
      };

      return (
        <Card onPress={onPress} testID="product-card">
          <Card.Image source={{ uri: product.imageUrl }} />
          <Card.Content>
            <Text testID="product-name">{product.name}</Text>
            <Text testID="product-price">{formatPrice(product.price)}</Text>
            <Button
              onPress={handleAddToCart}
              loading={isAddingToCart}
              testID="add-to-cart"
            >
              Add to Cart
            </Button>
          </Card.Content>
        </Card>
      );
    };
    ```
  </Tab>

  <Tab>
    ```typescript
    // src/ui/business/ProductCard/ProductCard.test.tsx
    import React from 'react';
    import { render, fireEvent, waitFor } from '@/ui/test-utils';
    import { ProductCard } from './ProductCard';
    import { useCart } from '@/features/cart/hooks';
    import { useProductDetails } from '@/features/products/hooks';

    // Mock the hooks
    jest.mock('@/features/cart/hooks');
    jest.mock('@/features/products/hooks');

    describe('ProductCard', () => {
      const mockProduct = {
        id: '1',
        name: 'Test Product',
        price: 99.99,
        imageUrl: 'https://example.com/product.jpg'
      };

      const mockAddToCart = jest.fn();
      const mockOnPress = jest.fn();

      beforeEach(() => {
        jest.clearAllMocks();
        
        (useCart as jest.Mock).mockReturnValue({
          addToCart: mockAddToCart,
          isAddingToCart: false
        });
        
        (useProductDetails as jest.Mock).mockReturnValue({
          data: mockProduct,
          isLoading: false,
          error: null
        });
      });

      describe('Loading State', () => {
        it('shows skeleton while loading', () => {
          (useProductDetails as jest.Mock).mockReturnValue({
            data: null,
            isLoading: true,
            error: null
          });

          const { getByTestId } = render(
            <ProductCard productId="1" />
          );

          expect(() => getByTestId('card-skeleton')).not.toThrow();
        });
      });

      describe('Error State', () => {
        it('shows error message on failure', () => {
          (useProductDetails as jest.Mock).mockReturnValue({
            data: null,
            isLoading: false,
            error: new Error('Network error')
          });

          const { getByText } = render(
            <ProductCard productId="1" />
          );

          expect(getByText('Failed to load product')).toBeTruthy();
        });
      });

      describe('Success State', () => {
        it('displays product information', () => {
          const { getByTestId } = render(
            <ProductCard productId="1" />
          );

          expect(getByTestId('product-name')).toHaveTextContent('Test Product');
          expect(getByTestId('product-price')).toHaveTextContent('$99.99');
        });

        it('calls onPress when card is pressed', () => {
          const { getByTestId } = render(
            <ProductCard productId="1" onPress={mockOnPress} />
          );

          fireEvent.press(getByTestId('product-card'));
          expect(mockOnPress).toHaveBeenCalledTimes(1);
        });

        it('adds product to cart', async () => {
          const { getByTestId } = render(
            <ProductCard productId="1" />
          );

          fireEvent.press(getByTestId('add-to-cart'));

          await waitFor(() => {
            expect(mockAddToCart).toHaveBeenCalledWith(mockProduct);
          });
        });

        it('shows loading state while adding to cart', () => {
          (useCart as jest.Mock).mockReturnValue({
            addToCart: mockAddToCart,
            isAddingToCart: true
          });

          const { getByTestId } = render(
            <ProductCard productId="1" />
          );

          expect(getByTestId('add-to-cart-loader')).toBeTruthy();
        });
      });
    });
    ```
  </Tab>

  <Tab>
    ```typescript
    // src/test/mocks/handlers.ts
    import { rest } from 'msw';
    import { API_BASE_URL } from '@config/api';

    export const handlers = [
      rest.get(`${API_BASE_URL}/products/:id`, (req, res, ctx) => {
        const { id } = req.params;
        
        return res(
          ctx.json({
            id,
            name: 'Mocked Product',
            price: 99.99,
            imageUrl: 'https://example.com/product.jpg'
          })
        );
      }),

      rest.post(`${API_BASE_URL}/cart/items`, (req, res, ctx) => {
        return res(
          ctx.json({
            success: true,
            cartId: 'cart-123',
            itemCount: 1
          })
        );
      })
    ];

    // src/test/mocks/server.ts
    import { setupServer } from 'msw/node';
    import { handlers } from './handlers';

    export const server = setupServer(...handlers);
    ```
  </Tab>
</Tabs>

## Testing Best Practices

### 1. Test Organization

<Steps>
  <Step>
    #### Group by Feature

    Organize tests to mirror component structure:

    ```
    __tests__/
    ├── foundation/
    │   ├── Button.test.tsx
    │   └── Input.test.tsx
    ├── patterns/
    │   ├── Form.test.tsx
    │   └── Modal.test.tsx
    └── business/
        ├── ProductCard.test.tsx
        └── UserProfile.test.tsx
    ```
  </Step>

  <Step>
    #### Use Descriptive Names

    * Test files: `ComponentName.test.tsx`
    * Test suites: `describe('ComponentName', ...)`
    * Test cases: `it('should verb when condition', ...)`
  </Step>

  <Step>
    #### Follow AAA Pattern

    ```typescript
    it('should update count when increment button is pressed', () => {
      // Arrange
      const { getByTestId } = render(<Counter initialCount={0} />);
      
      // Act
      fireEvent.press(getByTestId('increment-button'));
      
      // Assert
      expect(getByTestId('count-display')).toHaveTextContent('1');
    });
    ```
  </Step>
</Steps>

### 2. Testing Utilities

Create reusable testing utilities for common scenarios:

```typescript
// src/test/utils/gesture.ts
export const swipeLeft = (element: ReactTestInstance) => {
  fireEvent(element, 'swipeableHandlerStateChange', {
    nativeEvent: { state: State.ACTIVE }
  });
};

// src/test/utils/async.ts
export const waitForLoadingToFinish = async () => {
  await waitFor(() => {
    expect(screen.queryByTestId('loading')).toBeNull();
  });
};
```

### 3. Snapshot Testing

Use snapshots judiciously:

* (Do ✅) Snapshot small, stable components
* (Do ✅) Review snapshot changes carefully
* (Don't ❌) Snapshot entire screens
* (Don't ❌) Ignore snapshot updates

```typescript
describe('Button Snapshots', () => {
  it('matches snapshot for primary variant', () => {
    const tree = render(
      <Button variant="primary" onPress={jest.fn()}>
        Click me
      </Button>
    ).toJSON();
    
    expect(tree).toMatchSnapshot();
  });
});
```

## Performance Testing

### Measuring Component Performance

```typescript
// src/ui/foundation/List/List.perf.test.tsx
import React from 'react';
import { measurePerformance } from '@test/utils/performance';
import { List } from './List';

describe('List Performance', () => {
  it('renders 1000 items within performance budget', async () => {
    const items = Array.from({ length: 1000 }, (_, i) => ({
      id: `item-${i}`,
      title: `Item ${i}`
    }));

    const { renderTime, rerenderTime } = await measurePerformance(
      <List data={items} renderItem={({ item }) => <Text>{item.title}</Text>} />
    );

    expect(renderTime).toBeLessThan(100); // Initial render < 100ms
    expect(rerenderTime).toBeLessThan(50); // Re-render < 50ms
  });
});
```

## Common Testing Patterns

### Testing Hooks

```typescript
// src/features/auth/hooks/useAuth.test.ts
import { renderHook, act } from '@testing-library/react-hooks';
import { useAuth } from './useAuth';
import { AuthProvider } from '../providers/AuthProvider';

describe('useAuth', () => {
  const wrapper = ({ children }: { children: React.ReactNode }) => (
    <AuthProvider>{children}</AuthProvider>
  );

  it('logs in user successfully', async () => {
    const { result } = renderHook(() => useAuth(), { wrapper });

    await act(async () => {
      await result.current.login('user@example.com', 'password');
    });

    expect(result.current.isAuthenticated).toBe(true);
    expect(result.current.user).toEqual(
      expect.objectContaining({
        email: 'user@example.com'
      })
    );
  });
});
```

### Testing Navigation

```typescript
// src/features/navigation/Navigation.test.tsx
import React from 'react';
import { NavigationContainer } from '@react-navigation/native';
import { render, fireEvent } from '@testing-library/react-native';
import { AppNavigator } from './AppNavigator';

const TestNavigator = () => (
  <NavigationContainer>
    <AppNavigator />
  </NavigationContainer>
);

describe('Navigation', () => {
  it('navigates to product details on card press', () => {
    const { getByTestId } = render(<TestNavigator />);
    
    fireEvent.press(getByTestId('product-card-1'));
    
    expect(getByTestId('product-details-screen')).toBeTruthy();
  });
});
```

## Testing Checklist

Before considering your component tests complete:

* [ ] All props are tested
* [ ] User interactions work correctly
* [ ] Loading states are handled
* [ ] Error states show appropriate UI
* [ ] Accessibility props are verified
* [ ] Edge cases are covered
* [ ] Performance is within budget
* [ ] Mocks are properly cleaned up

## Common Pitfalls

1. **Over-mocking**: Don't mock everything - keep integration points when valuable
2. **Testing Implementation**: Focus on behavior, not how it's achieved
3. **Ignoring Async**: Always handle async operations with proper waitFor
4. **Missing Cleanup**: Clean up timers, mocks, and subscriptions

## Related Documents

* [Component Patterns](/docs/ui-development/development/component-patterns) - Learn about component design
* [Performance Guide](/docs/ui-development/development/performance-guide) - Optimize component performance
* [TypeScript Patterns](/docs/guides/typescript-react-patterns) - Type-safe testing approaches
* [Error Handling](/docs/guides/error-handling) - Testing error scenarios


# UTA UI Development: Brand Assets Overview
URL: https://dev.updatetheapp.com/docs/ui-development/assets/assets-management
Documentation: https://dev.updatetheapp.com/docs/ui-development/assets/assets-management

Comprehensive guide for handling brand assets, fonts, and animations in React Native applications with clear decision frameworks and best practices
        
***

title: "Brand Assets Overview"
description: "Comprehensive guide for handling brand assets, fonts, and animations in React Native applications with clear decision frameworks and best practices"
------------------------------------------------------------------------------------------------------------------------------------------------------------------

import { Card, Cards } from 'fumadocs-ui/components/card';
import { Callout } from 'fumadocs-ui/components/callout';

# Brand Assets Overview

## What This Guide Covers

This comprehensive guide provides best practices for managing **brand assets**, **fonts**, **animations**, and other static assets in React Native applications. Our approach emphasizes performance optimization, proper organization, and maintainable workflows.

**Important Scope Distinction**: This guide covers brand assets, illustrations, fonts, and animations. For **UI icons** (navigation, actions, status), see the [Icon Management Guide](/docs/ui-development/assets/icon-management).

## Asset Categories

### Brand Assets (This Guide)

* **Logos**: Company, product, partner logos
* **Illustrations**: Onboarding graphics, empty states, hero images
* **Complex Graphics**: Marketing materials, detailed graphics
* **Backgrounds**: Splash screens, hero banners, decorative images
* **Screenshots**: App previews, feature showcases

### UI Icons (Icon Management Guide)

* **Navigation Icons**: Arrows, menu, close, back
* **Action Icons**: Edit, delete, save, search, share
* **Status Icons**: Check, error, warning, info, loading
* **Social Icons**: Platform icons used systematically

## Purpose & Scope

* **Target Audience**: React Native developers working with brand assets, fonts, animations, and complex graphics
* **Problems Addressed**: Asset optimization, bundle size management, multi-resolution handling, performance issues
* **Scope Boundaries**: Covers static brand asset management but excludes UI icons and dynamic content from APIs

## Asset Management Guides

<Cards>
  <Card title="Image Optimization Guide" description="SVG vs PNG/JPG decisions, multi-resolution handling, format optimization, and automated processing workflows" href="/docs/ui-development/assets/assets-management/image-optimization-guide" />

  <Card title="Font Management Guide" description="Custom font loading, fallback strategies, performance optimization, and platform-specific considerations" href="/docs/ui-development/assets/assets-management/font-management-guide" />

  <Card title="Animation Assets Guide" description="Lottie animations, video assets, performance optimization, and memory management best practices" href="/docs/ui-development/assets/assets-management/animation-assets-guide" />

  <Card title="Performance Optimization" description="Bundle size analysis, caching strategies, lazy loading, and production optimization techniques" href="/docs/ui-development/assets/assets-management/performance-optimization" />
</Cards>

## Quick Decision Framework

### When to Use This Guide vs Icon Management

| Asset Type              | Use This Guide | Use Icon Management | Rationale                        |
| ----------------------- | -------------- | ------------------- | -------------------------------- |
| Company Logo            | ✅              | ❌                   | Brand asset, not UI element      |
| Navigation Arrow        | ❌              | ✅                   | UI icon, systematic usage        |
| Onboarding Illustration | ✅              | ❌                   | Complex graphic, brand-specific  |
| Status Check Icon       | ❌              | ✅                   | UI icon, repeated usage          |
| Hero Banner Photo       | ✅              | ❌                   | Brand asset, marketing content   |
| Social Media Icon       | ❌              | ✅                   | UI icon, systematic in interface |

### Asset Format Decision Matrix

| Asset Type           | SVG | PNG | JPG | Recommendation                 |
| -------------------- | --- | --- | --- | ------------------------------ |
| Company Logo         | ✅   | 🤔  | ❌   | **SVG** - Perfect scalability  |
| Product Logo         | ✅   | 🤔  | ❌   | **SVG** - Brand consistency    |
| Simple Illustration  | ✅   | 🤔  | ❌   | **SVG** - Small size, scalable |
| Complex Illustration | 🤔  | ✅   | ✅   | **PNG/JPG** - Better rendering |
| Photo Background     | ❌   | 🤔  | ✅   | **JPG** - Optimized for photos |
| App Screenshots      | ❌   | ✅   | 🤔  | **PNG** - Lossless UI elements |

## Asset Organization Structure

```
assets/                        # Project root level
├── brand/                     # Brand assets (this guide)
│   ├── logos/                 # Company/product logos
│   ├── illustrations/         # Marketing/onboarding graphics
│   └── backgrounds/           # Hero banners, splash screens
├── fonts/                     # Custom font files (this guide)
├── animations/                # Lottie and other animations (this guide)
└── sounds/                    # Audio assets (this guide)
```

<Callout type="info">
  **Why Project Root?** Placing assets at project root (same level as `src/`) provides cleaner import paths, Metro bundler compatibility, and follows React Native community conventions.
</Callout>

## Brand Asset Implementation Scenarios

### "I need to add a company or product logo"

→ Follow [Image Optimization Guide](/docs/ui-development/assets/assets-management/image-optimization-guide) to choose between SVG (scalable) vs PNG (multi-resolution) based on logo complexity

### "I want to add custom fonts for branding"

→ Use [Font Management Guide](/docs/ui-development/assets/assets-management/font-management-guide) for font loading strategies, fallbacks, and performance optimization

### "I need to add hero images or marketing graphics"

→ Review [Image Optimization Guide](/docs/ui-development/assets/assets-management/image-optimization-guide) for JPG vs PNG decisions and multi-resolution handling

### "I have large image assets affecting app performance"

→ Check [Performance Optimization](/docs/ui-development/assets/assets-management/performance-optimization) for bundle size analysis and optimization techniques

## Key Principles

1. **Performance First**: Always optimize assets before adding to project
2. **Format Selection**: Choose the right format (SVG for logos, PNG for complex graphics, JPG for photos)
3. **Resolution Independence**: Provide multiple resolutions (@1x, @2x, @3x) for PNG/JPG assets
4. **Bundle Size Awareness**: Monitor impact on app bundle size
5. **Platform Compatibility**: Ensure assets work across iOS and Android

## Getting Started

1. **Start Here**: Review the [Image Optimization Guide](/docs/ui-development/assets/assets-management/image-optimization-guide) to understand format decisions
2. **Set Up Fonts**: Follow [Font Management Guide](/docs/ui-development/assets/assets-management/font-management-guide) for custom typography
3. **Add Animations**: Use [Animation Assets Guide](/docs/ui-development/assets/assets-management/animation-assets-guide) for motion graphics
4. **Optimize Performance**: Apply [Performance Optimization](/docs/ui-development/assets/assets-management/performance-optimization) techniques

## Related Documentation

* [Icon Management Guide](/docs/ui-development/assets/icon-management) - For UI icons and systematic iconography
* [Project Structure Guide](/docs/architecture/project-structure) - For overall project organization
* [Performance Guide](/docs/performance) - For general performance optimization
* [Build Configuration](/docs/deployment/build-configuration) - For bundling and deployment

***

**Remember**: Proper asset management directly impacts app performance, user experience, and development efficiency. Take time to understand format decisions and optimization strategies before implementing.


# UTA UI Development: Image Optimization Guide
URL: https://dev.updatetheapp.com/docs/ui-development/assets/assets-management/image-optimization-guide
Documentation: https://dev.updatetheapp.com/docs/ui-development/assets/assets-management/image-optimization-guide

Comprehensive guide for optimizing images in React Native applications including format decisions, multi-resolution handling, and automated workflows
        
***

title: "Image Optimization Guide"
description: "Comprehensive guide for optimizing images in React Native applications including format decisions, multi-resolution handling, and automated workflows"
--------------------------------------------------------------------------------------------------------------------------------------------------------------------

import { Callout } from 'fumadocs-ui/components/callout';
import { Step, Steps } from 'fumadocs-ui/components/steps';
import { Tabs, Tab } from 'fumadocs-ui/components/tabs';

# Image Optimization Guide

## Overview

This guide provides comprehensive strategies for optimizing brand assets, illustrations, and complex graphics in React Native applications. We focus on format selection, multi-resolution handling, and automated optimization workflows.

## SVG vs Image Format Decision Framework

### When to Use SVG for Brand Assets

**(Do ✅) Use SVG for:**

* **Logos**: Perfect scalability, crisp at any size, small file size
* **Simple Illustrations**: Vector-based graphics with solid colors
* **Icons in Brand Assets**: Brand-specific iconography
* **Geometric Graphics**: Shapes, patterns, simple designs

**Benefits:**

* Resolution independent (perfect on all screen densities)
* Smaller file sizes for simple graphics
* Easy to programmatically modify colors/styling
* Crisp rendering at any scale

### When to Use PNG/JPG for Brand Assets

**(Do ✅) Use PNG/JPG for:**

* **Photographic Content**: Real photos, complex textures
* **Complex Illustrations**: Detailed artwork with gradients, shadows, effects
* **Screenshots**: App screenshots, UI mockups
* **Backgrounds**: Complex gradients, photographic backgrounds

**Benefits:**

* Better for photographic/complex content
* Faster rendering for complex graphics
* No dependency on react-native-svg
* Better browser/platform compatibility

### Decision Matrix

| Asset Type            | SVG | PNG | JPG | Recommendation                 |
| --------------------- | --- | --- | --- | ------------------------------ |
| Company Logo          | ✅   | 🤔  | ❌   | **SVG** - Perfect scalability  |
| Product Logo          | ✅   | 🤔  | ❌   | **SVG** - Brand consistency    |
| Simple Illustration   | ✅   | 🤔  | ❌   | **SVG** - Small size, scalable |
| Complex Illustration  | 🤔  | ✅   | ✅   | **PNG/JPG** - Better rendering |
| Photo Background      | ❌   | 🤔  | ✅   | **JPG** - Optimized for photos |
| App Screenshots       | ❌   | ✅   | 🤔  | **PNG** - Lossless UI elements |
| Hero Banner (photo)   | ❌   | 🤔  | ✅   | **JPG** - Photographic content |
| Hero Banner (graphic) | ✅   | 🤔  | ❌   | **SVG** - Vector graphics      |

## Multi-Resolution Image Management

### Understanding Screen Densities

<Callout type="info">
  **Screen Density Basics**: React Native automatically selects the appropriate image resolution based on device pixel density. Provide multiple resolutions to ensure crisp rendering across all devices.
</Callout>

| Density     | Scale Factor | Typical Devices     | File Suffix    |
| ----------- | ------------ | ------------------- | -------------- |
| MDPI        | 1x           | Lower-end Android   | `image.png`    |
| HDPI/Retina | 2x           | Most modern devices | `image@2x.png` |
| XHDPI       | 3x           | High-end devices    | `image@3x.png` |

### Multi-Resolution Implementation

<Tabs items={["PNG/JPG Assets", "SVG Assets", "Code Examples"]}>
  <Tab>
    #### PNG/JPG Multi-Resolution Setup

    ```
    assets/brand/logos/
    ├── partner-logo.png        # 1x resolution (base)
    ├── partner-logo@2x.png     # 2x resolution
    └── partner-logo@3x.png     # 3x resolution
    ```

    **Best Practices:**

    * **(Do ✅)** Start with highest resolution and scale down
    * **(Do ✅)** Maintain aspect ratio across all resolutions
    * **(Do ✅)** Use consistent naming with @2x, @3x suffixes
    * **(Don't ❌)** Use only single resolution images
  </Tab>

  <Tab>
    #### SVG Assets (Resolution Independent)

    ```
    assets/brand/logos/
    ├── company-logo.svg        # Single file, all resolutions
    └── product-logo.svg        # Scales automatically
    ```

    **Advantages:**

    * Single file serves all screen densities
    * Perfect scaling at any size
    * Smaller bundle size for simple graphics
    * Easy to modify colors programmatically
  </Tab>

  <Tab>
    #### Usage in Code

    ```typescript
    // Multi-resolution PNG/JPG (React Native auto-selects)
    <Image 
      source={require('@/assets/brand/logos/partner-logo.png')}
      style={{ width: 100, height: 40 }}
      resizeMode="contain"
    />

    // SVG Component (resolution independent)
    import CompanyLogo from '@/assets/brand/logos/CompanyLogo';
    <CompanyLogo width={120} height={40} />

    // Assets constant approach
    import { Images } from '@/core/constants/images';
    <Image 
      source={Images.brand.logos.partner}
      style={{ width: 100, height: 40 }}
    />
    ```
  </Tab>
</Tabs>

## Image Optimization Workflows

### Manual Optimization Tools

<Tabs items={["Online Tools", "Desktop Applications", "Command Line"]}>
  <Tab>
    #### Online Optimization Tools

    * **TinyPNG**: [https://tinypng.com](https://tinypng.com) - PNG/JPG compression
    * **SVGO**: [https://jakearchibald.github.io/svgomg/](https://jakearchibald.github.io/svgomg/) - SVG optimization
    * **Squoosh**: [https://squoosh.app](https://squoosh.app) - Advanced image compression

    <Callout type="warn">
      **Privacy Consideration**: Be aware of privacy implications when using online tools with sensitive brand assets. Consider on-premise solutions for confidential materials.
    </Callout>
  </Tab>

  <Tab>
    #### Desktop Applications

    * **ImageOptim** (macOS): [https://imageoptim.com](https://imageoptim.com)
    * **FileOptimizer** (Windows): Free lossless file compressor
    * **GIMP**: Free alternative to Photoshop with export optimization

    **Benefits:**

    * No internet required
    * Batch processing capabilities
    * Privacy protection for sensitive assets
  </Tab>

  <Tab>
    #### Command Line Tools

    ```bash
    # ImageMagick - Resize and optimize
    convert input.png -quality 85 -resize 200x200 output.png

    # WebP conversion
    cwebp -q 80 input.png -o output.webp

    # SVGO - SVG optimization
    npx svgo input.svg -o output.svg

    # Batch processing with ImageMagick
    mogrify -quality 85 -resize 300x300 *.png
    ```
  </Tab>
</Tabs>

### Automated Optimization Pipeline

<Steps>
  <Step>
    #### Set Up Package Scripts

    Add optimization scripts to your package.json

    ```json
    {
      "scripts": {
        "optimize:images": "imagemin assets/brand/**/*.{jpg,png} --out-dir=assets/brand/optimized",
        "optimize:svg": "svgo assets/brand/**/*.svg",
        "generate:webp": "node scripts/generate-webp.js",
        "optimize:all": "npm run optimize:images && npm run optimize:svg"
      }
    }
    ```
  </Step>

  <Step>
    #### Install Optimization Dependencies

    Add necessary packages for automated optimization

    ```bash
    npm install --save-dev imagemin imagemin-pngquant imagemin-mozjpeg svgo
    ```
  </Step>

  <Step>
    #### Create Optimization Script

    Set up automated processing for new assets

    ```javascript
    // scripts/optimize-assets.js
    const imagemin = require('imagemin');
    const imageminPngquant = require('imagemin-pngquant');
    const imageminMozjpeg = require('imagemin-mozjpeg');

    async function optimizeImages() {
      await imagemin(['assets/brand/**/*.{jpg,png}'], {
        destination: 'assets/brand/optimized',
        plugins: [
          imageminMozjpeg({ quality: 85 }),
          imageminPngquant({ quality: [0.6, 0.8] })
        ]
      });
      console.log('Images optimized!');
    }

    optimizeImages();
    ```
  </Step>

  <Step>
    #### Set Up Pre-commit Hook

    Automatically optimize assets before committing

    ```json
    // package.json
    {
      "husky": {
        "hooks": {
          "pre-commit": "lint-staged"
        }
      },
      "lint-staged": {
        "assets/**/*.{png,jpg,jpeg}": [
          "npm run optimize:images",
          "git add"
        ],
        "assets/**/*.svg": [
          "npm run optimize:svg",
          "git add"
        ]
      }
    }
    ```
  </Step>
</Steps>

## Asset Constants Pattern

### Centralized Asset Management

```typescript
// core/constants/images.ts
export const Images = {
  brand: {
    logos: {
      // SVG logos (recommended for scalability)
      company: require('@/assets/brand/logos/company-logo.svg'),
      product: require('@/assets/brand/logos/product-logo.svg'),
      // PNG logos (when SVG not available)
      partner: require('@/assets/brand/logos/partner-logo.png'),
    },
    illustrations: {
      onboarding: {
        // SVG for simple illustrations
        welcomeSimple: require('@/assets/brand/illustrations/onboarding/welcome-simple.svg'),
        // PNG for complex illustrations
        featuresComplex: require('@/assets/brand/illustrations/onboarding/features-complex.png'),
      },
      emptyStates: {
        // SVG for simple graphics
        noData: require('@/assets/brand/illustrations/empty-states/no-data.svg'),
        noNetwork: require('@/assets/brand/illustrations/empty-states/no-network.svg'),
      },
    },
    backgrounds: {
      // JPG for photographic backgrounds
      splashPhoto: require('@/assets/brand/backgrounds/splash-photo.jpg'),
      heroBanner: require('@/assets/brand/backgrounds/hero-banner.jpg'),
      // SVG for geometric/gradient backgrounds
      gradientBg: require('@/assets/brand/backgrounds/gradient-bg.svg'),
    },
  },
};
```

### Usage Examples

<Tabs items={["SVG Components", "Image Components", "TypeScript Typing"]}>
  <Tab>
    #### SVG Component Usage

    ```typescript
    // SVG Components (for logos and simple graphics)
    import CompanyLogo from '@/assets/brand/logos/CompanyLogo';

    export const Header = () => (
      <View style={styles.header}>
        <CompanyLogo width={120} height={40} />
      </View>
    );
    ```
  </Tab>

  <Tab>
    #### Image Component Usage

    ```typescript
    import { Images } from '@/core/constants/images';

    export const HeroBanner = () => (
      <Image 
        source={Images.brand.backgrounds.heroBanner}
        style={{ width: 300, height: 200 }}
        resizeMode="cover"
      />
    );
    ```
  </Tab>

  <Tab>
    #### TypeScript Type Definitions

    ```typescript
    // types/assets.ts
    export interface ImageAssets {
      brand: {
        logos: {
          company: any;
          product: any;
          partner: any;
        };
        illustrations: {
          onboarding: {
            welcomeSimple: any;
            featuresComplex: any;
          };
          emptyStates: {
            noData: any;
            noNetwork: any;
          };
        };
        backgrounds: {
          splashPhoto: any;
          heroBanner: any;
          gradientBg: any;
        };
      };
    }
    ```
  </Tab>
</Tabs>

## Common Optimization Issues

### Issue 1: Oversized Images

**Problem**: Using large images for small display areas
**Impact**: Increased bundle size, slower loading, memory issues

```typescript
// ❌ BAD: Using unoptimized images
<Image source={require('./hero.png')} />
// 5MB image displayed at 200x200

// ✅ GOOD: Using optimized assets
<Image
  source={require('./hero-optimized.jpg')}
  style={{ width: 200, height: 200 }}
  resizeMode="cover"
/>
// 150KB image sized appropriately
```

### Issue 2: Missing Multi-Resolution Assets

**Problem**: Only providing single resolution images
**Impact**: Blurry images on high-density screens

```typescript
// ❌ BAD: Single resolution only
assets/brand/logos/logo.png

// ✅ GOOD: Multiple resolutions
assets/brand/logos/logo.png      # 1x
assets/brand/logos/logo@2x.png   # 2x  
assets/brand/logos/logo@3x.png   # 3x
```

### Issue 3: Wrong Format Selection

**Problem**: Using PNG for photographic content or JPG for logos
**Impact**: Larger file sizes, quality issues

```typescript
// ❌ BAD: Wrong format choices
company-logo.jpg        // Should be SVG or PNG
photo-background.png    // Should be JPG
complex-illustration.svg // Should be PNG for complex artwork

// ✅ GOOD: Correct format choices
company-logo.svg        // Vector logo
photo-background.jpg    // Photographic content
complex-illustration.png // Complex raster artwork
```

## Performance Best Practices

### Bundle Size Management

* **(Do ✅)** Monitor bundle size impact when adding new assets
* **(Do ✅)** Use bundle analyzer to identify large assets
* **(Do ✅)** Implement lazy loading for large assets
* **(Consider 🤔)** Using remote assets for very large images

### Memory Management

* **(Do ✅)** Specify image dimensions to prevent layout shifts
* **(Do ✅)** Use appropriate `resizeMode` for your use case
* **(Do ✅)** Implement image caching with libraries like FastImage
* **(Don't ❌)** Load large images unnecessarily

### Loading Strategies

```typescript
// ✅ GOOD: Lazy loading with FastImage
import FastImage from 'react-native-fast-image';

export const OptimizedImage = ({ source, style }) => (
  <FastImage
    source={source}
    style={style}
    resizeMode={FastImage.resizeMode.cover}
    priority={FastImage.priority.normal}
  />
);
```

## Asset Naming Conventions

### Recommended Naming Pattern

```
✅ GOOD:
- logo-company-primary.svg
- logo-product-secondary.svg
- bg-onboarding-welcome.jpg
- bg-onboarding-welcome@2x.jpg
- bg-onboarding-welcome@3x.jpg
- illustration-empty-state-no-data.svg

❌ BAD:
- company_logo.png
- CompanyLogo.png
- logo-2x.png (missing descriptive name)
- onboarding_bg_1.jpg (unclear purpose)
```

### Naming Conventions

* Use **kebab-case** for all filenames
* Include **asset type prefix** (logo-, bg-, illustration-)
* Add **descriptive context** (company, product, onboarding)
* Use **semantic suffixes** (@2x, @3x for multi-resolution)

## Testing Asset Optimization

```typescript
// __tests__/assets.test.ts
describe('Asset Optimization', () => {
  it('should load all required brand assets', () => {
    Object.values(Images.brand.logos).forEach(image => {
      expect(image).toBeDefined();
    });
  });

  it('should have optimized file sizes', async () => {
    // Test that images are under reasonable size limits
    const logoSize = await getAssetSize(Images.brand.logos.company);
    expect(logoSize).toBeLessThan(50000); // 50KB limit for logos
  });

  it('should provide multi-resolution assets', () => {
    // Verify that @2x and @3x variants exist for PNG/JPG
    const partnerLogo = Images.brand.logos.partner;
    expect(partnerLogo).toBeDefined();
    // Additional checks for resolution variants
  });
});
```

## Related Documentation

* [Font Management Guide](/docs/ui-development/assets/assets-management/font-management-guide) - Custom typography integration
* [Animation Assets Guide](/docs/ui-development/assets/assets-management/animation-assets-guide) - Motion graphics optimization
* [Performance Optimization](/docs/ui-development/assets/assets-management/performance-optimization) - Bundle size and caching
* [Icon Management Guide](/docs/ui-development/assets/icon-management) - UI icon system implementation


# UTA UI Development: Font Management Guide
URL: https://dev.updatetheapp.com/docs/ui-development/assets/assets-management/font-management-guide
Documentation: https://dev.updatetheapp.com/docs/ui-development/assets/assets-management/font-management-guide

Comprehensive guide for managing custom fonts in React Native applications including loading strategies, fallbacks, and performance optimization
        
***

title: "Font Management Guide"
description: "Comprehensive guide for managing custom fonts in React Native applications including loading strategies, fallbacks, and performance optimization"
---------------------------------------------------------------------------------------------------------------------------------------------------------------

import { Callout } from 'fumadocs-ui/components/callout';
import { Step, Steps } from 'fumadocs-ui/components/steps';
import { Tabs, Tab } from 'fumadocs-ui/components/tabs';

# Font Management Guide

## Overview

This guide provides best practices for **loading and configuring custom fonts** in React Native applications, including loading strategies, fallback mechanisms, performance optimization, and platform-specific considerations.

<Callout type="info">
  **Scope**: This guide focuses on font **asset loading and technical setup**. For typography scales, font sizes, and design system integration, see [Theme Management](/docs/ui-development/theme-management).
</Callout>

## Font Loading Strategies

### Expo Font Loading

<Tabs items={["Basic Setup", "Advanced Loading", "Error Handling"]}>
  <Tab>
    #### Basic Font Loading with Expo

    ```typescript
    // App.tsx
    import * as Font from 'expo-font';
    import { useState, useEffect } from 'react';

    const loadFonts = async () => {
      await Font.loadAsync({
        'Roboto-Regular': require('@/assets/fonts/Roboto-Regular.ttf'),
        'Roboto-Bold': require('@/assets/fonts/Roboto-Bold.ttf'),
        'Roboto-Light': require('@/assets/fonts/Roboto-Light.ttf'),
        'CustomIcons': require('@/assets/fonts/CustomIcons.ttf'),
      });
    };

    export default function App() {
      const [fontsLoaded, setFontsLoaded] = useState(false);

      useEffect(() => {
        loadFonts().then(() => setFontsLoaded(true));
      }, []);

      if (!fontsLoaded) {
        return <SplashScreen />;
      }

      return <MainApp />;
    }
    ```
  </Tab>

  <Tab>
    #### Advanced Font Loading with Caching

    ```typescript
    // core/services/fontService.ts
    import * as Font from 'expo-font';
    import AsyncStorage from '@react-native-async-storage/async-storage';

    const FONT_CACHE_KEY = 'fonts_loaded_v1';

    export const FontService = {
      async loadFonts(): Promise<void> {
        try {
          // Check if fonts were previously loaded
          const cached = await AsyncStorage.getItem(FONT_CACHE_KEY);
          
          if (!cached) {
            await Font.loadAsync({
              'Inter-Regular': require('@/assets/fonts/Inter-Regular.ttf'),
              'Inter-Medium': require('@/assets/fonts/Inter-Medium.ttf'),
              'Inter-SemiBold': require('@/assets/fonts/Inter-SemiBold.ttf'),
              'Inter-Bold': require('@/assets/fonts/Inter-Bold.ttf'),
            });
            
            // Cache successful load
            await AsyncStorage.setItem(FONT_CACHE_KEY, 'true');
          }
        } catch (error) {
          console.warn('Font loading failed:', error);
          // Continue with system fonts
        }
      },
      
      isLoaded(fontFamily: string): boolean {
        return Font.isLoaded(fontFamily);
      }
    };
    ```
  </Tab>

  <Tab>
    #### Error Handling and Fallbacks

    ```typescript
    // hooks/useFonts.ts
    import { useState, useEffect } from 'react';
    import { FontService } from '@/core/services/fontService';

    export const useFonts = () => {
      const [fontsLoaded, setFontsLoaded] = useState(false);
      const [fontError, setFontError] = useState<string | null>(null);

      useEffect(() => {
        const loadFonts = async () => {
          try {
            await FontService.loadFonts();
            setFontsLoaded(true);
          } catch (error) {
            setFontError(error.message);
            setFontsLoaded(true); // Continue with fallback fonts
          }
        };

        loadFonts();
      }, []);

      return { fontsLoaded, fontError };
    };
    ```
  </Tab>
</Tabs>

### React Native CLI Font Setup

<Steps>
  <Step>
    #### Place Font Files

    Copy font files to the appropriate platform directories

    ```
    # iOS
    ios/YourApp/fonts/
    ├── Inter-Regular.ttf
    ├── Inter-Bold.ttf
    └── Inter-SemiBold.ttf

    # Android
    android/app/src/main/assets/fonts/
    ├── Inter-Regular.ttf
    ├── Inter-Bold.ttf
    └── Inter-SemiBold.ttf
    ```
  </Step>

  <Step>
    #### Configure iOS Info.plist

    Add font declarations to iOS configuration

    ```xml
    <!-- ios/YourApp/Info.plist -->
    <key>UIAppFonts</key>
    <array>
      <string>Inter-Regular.ttf</string>
      <string>Inter-Bold.ttf</string>
      <string>Inter-SemiBold.ttf</string>
    </array>
    ```
  </Step>

  <Step>
    #### Link Fonts (if using React Native CLI)

    Run linking command for automatic setup

    ```bash
    # React Native 0.60+ (auto-linking)
    npx react-native run-ios
    npx react-native run-android

    # Older versions
    npx react-native link
    ```
  </Step>

  <Step>
    #### Test Font Loading

    Verify fonts are available in your app

    ```typescript
    // Test component
    const FontTest = () => (
      <View>
        <Text style={{ fontFamily: 'Inter-Regular' }}>Regular Text</Text>
        <Text style={{ fontFamily: 'Inter-Bold' }}>Bold Text</Text>
        <Text style={{ fontFamily: 'Inter-SemiBold' }}>SemiBold Text</Text>
      </View>
    );
    ```
  </Step>
</Steps>

## Font Organization and Constants

### Font Constants Pattern

<Callout type="info">
  **Typography Scale Integration**: For font sizes, weights, and design system typography, use the centralized theme management system. See [Theme Management Implementation](/docs/ui-development/theme-management/implementation) for the canonical typography definitions.
</Callout>

```typescript
// core/constants/fonts.ts
export const Fonts = {
  // Primary font family
  primary: {
    regular: 'Inter-Regular',
    medium: 'Inter-Medium',
    semiBold: 'Inter-SemiBold',
    bold: 'Inter-Bold',
  },
  
  // Secondary font family (if needed)
  secondary: {
    regular: 'Roboto-Regular',
    medium: 'Roboto-Medium',
    bold: 'Roboto-Bold',
  },
  
  // Icon fonts
  icons: {
    custom: 'CustomIcons',
    material: 'MaterialIcons',
  },
  
  // System font fallbacks
  system: {
    ios: 'San Francisco',
    android: 'Roboto',
    default: 'System',
  }
};
```

<Callout type="warn">
  **Design System Integration**: Instead of defining font sizes and weights here, import them from the theme management system to maintain consistency across your application.
</Callout>

```typescript
// Use theme management for typography scale
import { useTheme } from '@core/shared/styles';

// Example: Integrating with theme management
const ProductCard = () => {
  const theme = useTheme();
  
  return (
    <Text style={theme.textStyles.body}>
      Typography using design system
    </Text>
  );
};
```

### Typography Component Integration

<Callout type="info">
  **Recommended Approach**: Use the centralized Typography component from the theme management system instead of creating custom typography components. This ensures consistency with your design system.
</Callout>

<Callout type="warn">
  **Naming Standards**: Follow our [File Naming Conventions](/docs/coding-standards/file-naming-conventions) and [Project Structure](/docs/architecture/project-structure) when creating components. Use concise, descriptive names that align with React community practices.
</Callout>

```typescript
// Recommended: Use theme management Typography
import { useTheme } from '@core/shared/styles';

const ProductDetail = () => {
  const theme = useTheme();
  
  return (
    <View>
      <Text style={theme.textStyles.h1}>Product Name</Text>
      <Text style={theme.textStyles.body}>Product description</Text>
      <Text style={theme.textStyles.caption}>Price details</Text>
    </View>
  );
};
```

If you need custom typography components that integrate with font loading, combine font management with theme system:

```typescript
// ui/foundation/Text/Text.tsx
import React from 'react';
import { Text as RNText, TextProps, Platform } from 'react-native';
import { useTheme } from '@core/shared/styles';
import { useFonts } from '@/hooks/useFonts';
import { Fonts } from '@/core/constants/fonts';

interface CustomTextProps extends TextProps {
  variant?: 'h1' | 'h2' | 'h3' | 'body' | 'bodySmall' | 'button' | 'caption';
}

export const Text: React.FC<CustomTextProps> = ({
  variant = 'body',
  style,
  children,
  ...props
}) => {
  const theme = useTheme();
  const { fontsLoaded } = useFonts();
  
  // Get theme text styles
  const baseStyle = theme.textStyles[variant] || theme.textStyles.body;
  
  // Apply fallback font if custom fonts aren't loaded
  const textStyle = fontsLoaded 
    ? baseStyle
    : {
        ...baseStyle,
        fontFamily: Platform.select({
          ios: Fonts.system.ios,
          android: Fonts.system.android,
          default: Fonts.system.default,
        }),
      };

  return (
    <RNText style={[textStyle, style]} {...props}>
      {children}
    </RNText>
  );
};
```

## Platform-Specific Considerations

### iOS Font Configuration

<Tabs items={["Info.plist Setup", "Font Display Names", "Weight Mapping"]}>
  <Tab>
    #### Configuring iOS Info.plist

    ```xml
    <!-- ios/YourApp/Info.plist -->
    <dict>
      <!-- Other keys -->
      <key>UIAppFonts</key>
      <array>
        <string>Inter-Regular.ttf</string>
        <string>Inter-Medium.ttf</string>
        <string>Inter-SemiBold.ttf</string>
        <string>Inter-Bold.ttf</string>
        <string>CustomIcons.ttf</string>
      </array>
    </dict>
    ```

    <Callout type="info">
      **Font File Names**: Use the exact filename (including extension) as it appears in your bundle, not the PostScript name.
    </Callout>
  </Tab>

  <Tab>
    #### Finding Font Display Names

    ```typescript
    // Development helper to find font names
    const FontDebugger = () => {
      useEffect(() => {
        if (__DEV__) {
          // iOS: List all available fonts
          const fontFamilies = require('react-native').Platform.select({
            ios: () => {
              const { NativeModules } = require('react-native');
              return NativeModules.RNFontList?.getFontList() || [];
            },
            default: () => []
          })();
          
          console.log('Available fonts:', fontFamilies);
        }
      }, []);
      
      return null;
    };
    ```
  </Tab>

  <Tab>
    #### iOS Font Weight Mapping

    ```typescript
    // Platform-specific font weight handling
    const getIOSFontFamily = (family: string, weight: string) => {
      const weightMap = {
        '300': `${family}-Light`,
        '400': `${family}-Regular`,
        '500': `${family}-Medium`,
        '600': `${family}-SemiBold`,
        '700': `${family}-Bold`,
        '800': `${family}-ExtraBold`,
      };
      
      return weightMap[weight] || `${family}-Regular`;
    };
    ```
  </Tab>
</Tabs>

### Android Font Configuration

```typescript
// Platform-specific font handling for Android
const getAndroidFontFamily = (family: string, weight: string) => {
  // Android can use fontWeight property with single family
  return {
    fontFamily: family,
    fontWeight: weight,
  };
};

// Platform-agnostic font style helper
export const getFontStyle = (family: string, weight: string) => {
  return Platform.select({
    ios: {
      fontFamily: getIOSFontFamily(family, weight),
    },
    android: getAndroidFontFamily(family, weight),
    default: {
      fontFamily: family,
      fontWeight: weight,
    },
  });
};
```

## Font Fallback Strategies

### Graceful Degradation

```typescript
// core/utils/fontFallback.ts
import { Platform } from 'react-native';
import { Fonts } from '@/core/constants/fonts';

export const FontFallback = {
  getFont(
    preferredFont: string,
    fallbackFont?: string
  ): string {
    // Check if font is loaded (Expo only)
    if (typeof Font !== 'undefined' && Font.isLoaded?.(preferredFont)) {
      return preferredFont;
    }
    
    // Use provided fallback
    if (fallbackFont) {
      return fallbackFont;
    }
    
    // Use system font as last resort
    return Platform.select({
      ios: Fonts.system.ios,
      android: Fonts.system.android,
      default: Fonts.system.default,
    });
  },
  
  createFontStack(fonts: string[]): string {
    // Create font family stack for CSS-like fallback
    return fonts.join(', ');
  }
};

// Usage in styles
const styles = StyleSheet.create({
  title: {
    fontFamily: FontFallback.getFont('Inter-Bold', 'System'),
    fontSize: 24,
  },
  
  body: {
    fontFamily: FontFallback.createFontStack([
      'Inter-Regular',
      'San Francisco',
      'Roboto',
      'System'
    ]),
    fontSize: 16,
  },
});
```

### Loading State Management

```typescript
// components/FontAwareText.tsx
import React from 'react';
import { Text, TextProps } from 'react-native';
import { useFonts } from '@/hooks/useFonts';
import { FontFallback } from '@/core/utils/fontFallback';

interface FontAwareTextProps extends TextProps {
  fontFamily?: string;
  fallbackFont?: string;
}

export const FontAwareText: React.FC<FontAwareTextProps> = ({
  fontFamily = 'Inter-Regular',
  fallbackFont,
  style,
  children,
  ...props
}) => {
  const { fontsLoaded } = useFonts();
  
  const resolvedFontFamily = fontsLoaded
    ? fontFamily
    : FontFallback.getFont(fontFamily, fallbackFont);
  
  return (
    <Text
      style={[{ fontFamily: resolvedFontFamily }, style]}
      {...props}
    >
      {children}
    </Text>
  );
};
```

## Performance Optimization

### Font Loading Performance

<Callout type="warn">
  **Performance Impact**: Loading many custom fonts can significantly impact app startup time. Follow these strategies to minimize the impact.
</Callout>

#### Essential vs Optional Fonts

```typescript
// Prioritize critical fonts for immediate loading
const FontLoader = {
  async loadEssentialFonts() {
    // Load only fonts needed for initial screen
    await Font.loadAsync({
      'Inter-Regular': require('@/assets/fonts/Inter-Regular.ttf'),
      'Inter-Bold': require('@/assets/fonts/Inter-Bold.ttf'),
    });
  },
  
  async loadOptionalFonts() {
    // Load additional fonts in background
    await Font.loadAsync({
      'Inter-Light': require('@/assets/fonts/Inter-Light.ttf'),
      'Inter-SemiBold': require('@/assets/fonts/Inter-SemiBold.ttf'),
      'CustomIcons': require('@/assets/fonts/CustomIcons.ttf'),
    });
  }
};

// In your app
export default function App() {
  const [essentialFontsLoaded, setEssentialFontsLoaded] = useState(false);
  
  useEffect(() => {
    FontLoader.loadEssentialFonts()
      .then(() => setEssentialFontsLoaded(true));
    
    // Load optional fonts in background
    FontLoader.loadOptionalFonts();
  }, []);
  
  if (!essentialFontsLoaded) {
    return <SplashScreen />;
  }
  
  return <MainApp />;
}
```

### Bundle Size Optimization

#### Font Subsetting

```typescript
// Only include characters you need
const FontOptimization = {
  // Analyze text usage to determine required character set
  analyzeCharacterUsage(texts: string[]): Set<string> {
    const chars = new Set<string>();
    texts.forEach(text => {
      for (const char of text) {
        chars.add(char);
      }
    });
    return chars;
  },
  
  // Generate subset specification for font optimization tools
  generateSubsetSpec(chars: Set<string>): string {
    return Array.from(chars).join('');
  }
};
```

#### Font Format Optimization

```bash
# Use tools like fonttools to create optimized font files
pip install fonttools

# Subset font to specific characters
pyftsubset Inter-Regular.ttf \
  --text="ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789" \
  --output-file=Inter-Regular-subset.ttf

# Convert to WOFF2 for web (if using web components)
fonttools ttLib.woff2 compress Inter-Regular.ttf
```

## Custom Icon Fonts

### Creating Icon Fonts

<Steps>
  <Step>
    #### Design Icons

    Create SVG icons following these guidelines:

    * Use consistent artboard size (24x24px recommended)
    * Maintain uniform stroke width (2px)
    * Use simple paths without complex effects
    * Name files descriptively (arrow-left.svg, user-profile.svg)
  </Step>

  <Step>
    #### Generate Icon Font

    Use tools like IcoMoon or Fontello to create icon fonts

    ```bash
    # Using fontello-cli
    npm install -g fontello-cli

    # Upload SVGs and download font
    fontello-cli install --config fontello-config.json
    ```
  </Step>

  <Step>
    #### Integrate Icon Font

    Add the generated font to your React Native app

    ```typescript
    // core/constants/icons.ts
    export const IconFont = {
      family: 'CustomIcons',
      glyphs: {
        home: '\ue900',
        profile: '\ue901',
        settings: '\ue902',
        search: '\ue903',
      }
    };

    // components/IconText.tsx
    export const IconText = ({ icon, size = 24, color = '#000' }) => (
      <Text style={{
        fontFamily: IconFont.family,
        fontSize: size,
        color,
      }}>
        {IconFont.glyphs[icon]}
      </Text>
    );
    ```
  </Step>
</Steps>

## Testing Font Implementation

### Font Loading Tests

```typescript
// __tests__/fonts.test.ts
import { FontService } from '@/core/services/fontService';
import { Fonts } from '@/core/constants/fonts';

describe('Font Management', () => {
  it('should load all essential fonts', async () => {
    await FontService.loadFonts();
    
    // Test that fonts are available
    expect(FontService.isLoaded('Inter-Regular')).toBe(true);
    expect(FontService.isLoaded('Inter-Bold')).toBe(true);
  });
  
  it('should handle font loading failures gracefully', async () => {
    // Mock font loading failure
    jest.spyOn(Font, 'loadAsync').mockRejectedValue(new Error('Font load failed'));
    
    // Should not throw error
    await expect(FontService.loadFonts()).resolves.not.toThrow();
  });
  
  it('should provide correct font family constants', () => {
    expect(Fonts.primary.regular).toBeDefined();
    expect(Fonts.primary.bold).toBeDefined();
    expect(typeof Fonts.primary.regular).toBe('string');
  });
});
```

### Typography Component Tests

```typescript
// __tests__/Typography.test.tsx
import React from 'react';
import { render } from '@testing-library/react-native';
import { Typography } from '@/ui/foundation/Typography/Typography';

describe('Typography Component', () => {
  it('should render with correct font family', () => {
    const { getByTestId } = render(
      <Typography testID="typography" variant="heading1">
        Test Text
      </Typography>
    );
    
    const element = getByTestId('typography');
    expect(element.props.style).toMatchObject({
      fontFamily: expect.stringContaining('Inter'),
    });
  });
  
  it('should handle font fallbacks', () => {
    const { getByTestId } = render(
      <Typography testID="typography" family="system">
        Test Text
      </Typography>
    );
    
    const element = getByTestId('typography');
    // Should fall back to system font
    expect(element.props.style.fontFamily).toBeDefined();
  });
});
```

## Common Font Issues

### Issue 1: Fonts Not Loading on iOS

**Problem**: Custom fonts appear as system fonts on iOS
**Solutions**:

```typescript
// ❌ Common mistakes
// Using PostScript name instead of filename
'InterRegular' // Wrong

// ✅ Correct approach
// Use exact filename in Info.plist and code
'Inter-Regular' // Correct filename
```

### Issue 2: Font Weight Not Working

**Problem**: Different font weights appear identical
**Solutions**:

```typescript
// ❌ BAD: Relying on fontWeight property only
{
  fontFamily: 'Inter',
  fontWeight: 'bold', // May not work on iOS
}

// ✅ GOOD: Use specific font family names
{
  fontFamily: Platform.select({
    ios: 'Inter-Bold',
    android: 'Inter',
  }),
  fontWeight: Platform.select({
    ios: undefined,
    android: 'bold',
  }),
}
```

### Issue 3: Missing Character Glyphs

**Problem**: Some characters display as squares or missing glyphs
**Solutions**:

```typescript
// Check character support in font
const hasCharacterSupport = (font: string, character: string): boolean => {
  // Implementation to check if font supports character
  // Use fallback font for unsupported characters
  return true; // Simplified
};

// Provide fallback for unsupported characters
const TextWithFallback = ({ text, primaryFont, fallbackFont }) => {
  const hasSupport = hasCharacterSupport(primaryFont, text);
  return (
    <Text style={{ fontFamily: hasSupport ? primaryFont : fallbackFont }}>
      {text}
    </Text>
  );
};
```

## Related Documentation

* [Theme Management Implementation](/docs/ui-development/theme-management/implementation) - **Typography scales, font sizes, and design system integration**
* [Theme Management Overview](/docs/ui-development/theme-management) - Complete design system and theming guide
* [Image Optimization Guide](/docs/ui-development/assets/assets-management/image-optimization-guide) - Asset format decisions and optimization
* [Animation Assets Guide](/docs/ui-development/assets/assets-management/animation-assets-guide) - Motion graphics and animations
* [Performance Optimization](/docs/ui-development/assets/assets-management/performance-optimization) - Bundle size and loading optimization
* [Icon Management Guide](/docs/ui-development/assets/icon-management) - UI icon systems and vector icons


# UTA UI Development: Animation Assets Guide
URL: https://dev.updatetheapp.com/docs/ui-development/assets/assets-management/animation-assets-guide
Documentation: https://dev.updatetheapp.com/docs/ui-development/assets/assets-management/animation-assets-guide

Comprehensive guide for implementing and optimizing animations in React Native applications including Lottie animations, video assets, performance optimization, and memory management
        
***

title: "Animation Assets Guide"
description: "Comprehensive guide for implementing and optimizing animations in React Native applications including Lottie animations, video assets, performance optimization, and memory management"
-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

import { Tabs, Tab } from 'fumadocs-ui/components/tabs';
import { Callout } from 'fumadocs-ui/components/callout';
import { Step, Steps } from 'fumadocs-ui/components/steps';

# Animation Assets Guide

## Overview

Animations enhance user experience but can significantly impact app performance if not implemented properly. This guide covers Lottie animations, video assets, performance optimization, and memory management strategies for React Native applications.

<Callout type="info">
  **Scope**: This guide focuses on animation assets (Lottie, videos, GIFs) for brand experiences. For UI micro-interactions and transitions, see the UI Development guides.
</Callout>

## Lottie Animations

### Getting Started with Lottie

<Steps>
  <Step>
    #### Install Dependencies

    Add the required packages for Lottie support

    ```bash
    # For Expo projects
    npx expo install lottie-react-native

    # For React Native CLI projects
    npm install lottie-react-native
    npx react-native link lottie-react-native
    ```
  </Step>

  <Step>
    #### Basic Implementation

    ```typescript
    // components/LottieAnimation.tsx
    import React from 'react';
    import LottieView from 'lottie-react-native';

    interface LottieAnimationProps {
      source: any;
      autoPlay?: boolean;
      loop?: boolean;
      style?: any;
    }

    export const LottieAnimation: React.FC<LottieAnimationProps> = ({
      source,
      autoPlay = true,
      loop = false,
      style,
    }) => {
      return (
        <LottieView
          source={source}
          autoPlay={autoPlay}
          loop={loop}
          style={style}
        />
      );
    };
    ```
  </Step>

  <Step>
    #### Asset Organization

    Organize Lottie files in a structured manner

    ```
    assets/animations/
    ├── onboarding/
    │   ├── welcome.json
    │   ├── features.json
    │   └── complete.json
    ├── loaders/
    │   ├── spinner.json
    │   └── progress.json
    └── feedback/
        ├── success.json
        ├── error.json
        └── celebration.json
    ```
  </Step>
</Steps>

### Advanced Lottie Implementation

<Tabs items={["Controlled Animation", "Dynamic Properties", "Performance Optimization"]}>
  <Tab>
    #### Controlled Animation with Refs

    ```typescript
    // components/ControlledLottieView.tsx
    import React, { useRef, useImperativeHandle, forwardRef } from 'react';
    import LottieView from 'lottie-react-native';

    export interface LottieAnimationHandle {
      play: () => void;
      pause: () => void;
      reset: () => void;
    }

    export const ControlledLottieView = forwardRef<
      LottieAnimationHandle, 
      any
    >(({ source, style, onAnimationFinish }, ref) => {
      const animationRef = useRef<LottieView>(null);
      
      useImperativeHandle(ref, () => ({
        play: () => animationRef.current?.play(),
        pause: () => animationRef.current?.pause(),
        reset: () => animationRef.current?.reset(),
      }));
      
      return (
        <LottieView
          ref={animationRef}
          source={source}
          style={style}
          onAnimationFinish={onAnimationFinish}
          autoPlay={false}
        />
      );
    });
    ```
  </Tab>

  <Tab>
    #### Dynamic Color Properties

    ```typescript
    // components/DynamicLottieView.tsx
    import React from 'react';
    import LottieView from 'lottie-react-native';

    interface DynamicLottieViewProps {
      source: any;
      colorFilters?: Array<{
        keypath: string;
        color: string;
      }>;
    }

    export const DynamicLottieView: React.FC<DynamicLottieViewProps> = ({
      source,
      colorFilters,
      ...props
    }) => {
      return (
        <LottieView
          source={source}
          colorFilters={colorFilters}
          {...props}
        />
      );
    };
    ```
  </Tab>

  <Tab>
    #### Performance-Optimized Animation

    ```typescript
    // components/OptimizedLottieView.tsx
    import React, { useEffect, useRef, useState } from 'react';
    import { AppState, Platform } from 'react-native';
    import LottieView from 'lottie-react-native';

    export const OptimizedLottieView: React.FC<any> = ({
      source,
      pauseOnBackground = true,
      ...props
    }) => {
      const animationRef = useRef<LottieView>(null);
      const [appState, setAppState] = useState(AppState.currentState);
      
      useEffect(() => {
        if (!pauseOnBackground) return;
        
        const subscription = AppState.addEventListener('change', (nextAppState) => {
          if (appState.match(/inactive|background/) && nextAppState === 'active') {
            animationRef.current?.play();
          } else if (nextAppState.match(/inactive|background/)) {
            animationRef.current?.pause();
          }
          setAppState(nextAppState);
        });
        
        return () => subscription?.remove();
      }, [appState, pauseOnBackground]);
      
      return (
        <LottieView
          ref={animationRef}
          source={source}
          renderMode={Platform.select({
            android: 'SOFTWARE',
            ios: 'AUTOMATIC',
          })}
          {...props}
        />
      );
    };
    ```
  </Tab>
</Tabs>

## Video Assets

### Video Implementation

```typescript
// components/VideoPlayer.tsx
import React, { useRef, useState } from 'react';
import { View, StyleSheet } from 'react-native';
import Video from 'react-native-video';

interface VideoPlayerProps {
  source: any;
  autoPlay?: boolean;
  loop?: boolean;
  muted?: boolean;
  onLoadStart?: () => void;
  onLoad?: () => void;
  onError?: (error: any) => void;
}

export const VideoPlayer: React.FC<VideoPlayerProps> = ({
  source,
  autoPlay = false,
  loop = false,
  muted = true,
  onLoadStart,
  onLoad,
  onError,
}) => {
  const videoRef = useRef<Video>(null);
  const [paused, setPaused] = useState(!autoPlay);

  return (
    <View style={styles.container}>
      <Video
        ref={videoRef}
        source={source}
        style={styles.video}
        paused={paused}
        repeat={loop}
        muted={muted}
        resizeMode="cover"
        onLoadStart={onLoadStart}
        onLoad={onLoad}
        onError={onError}
        playInBackground={false}
        playWhenInactive={false}
      />
    </View>
  );
};

const styles = StyleSheet.create({
  container: {
    flex: 1,
  },
  video: {
    position: 'absolute',
    top: 0,
    left: 0,
    bottom: 0,
    right: 0,
  },
});
```

### Video Optimization

<Tabs items={["Format Optimization", "Progressive Loading", "Memory Management"]}>
  <Tab>
    #### Video Format and Quality

    ```bash
    # Optimize video for mobile
    ffmpeg -i input.mp4 \
      -c:v libx264 \
      -preset slow \
      -crf 23 \
      -c:a aac \
      -b:a 128k \
      -movflags +faststart \
      output.mp4

    # Create multiple quality versions
    # Low quality (for slow connections)
    ffmpeg -i input.mp4 -s 480x270 -b:v 500k output_low.mp4

    # Medium quality
    ffmpeg -i input.mp4 -s 720x405 -b:v 1000k output_medium.mp4

    # High quality
    ffmpeg -i input.mp4 -s 1080x607 -b:v 2000k output_high.mp4
    ```
  </Tab>

  <Tab>
    #### Progressive Video Loading

    ```typescript
    // hooks/useProgressiveVideo.ts
    import { useState, useEffect } from 'react';
    import NetInfo from '@react-native-netinfo/netinfo';

    interface VideoQuality {
      uri: string;
      quality: 'low' | 'medium' | 'high';
      size: number;
    }

    export const useProgressiveVideo = (videoQualities: VideoQuality[]) => {
      const [selectedVideo, setSelectedVideo] = useState<VideoQuality | null>(null);
      const [isLoading, setIsLoading] = useState(true);
      
      useEffect(() => {
        const selectOptimalQuality = async () => {
          const netInfo = await NetInfo.fetch();
          
          let quality: 'low' | 'medium' | 'high' = 'medium';
          
          if (netInfo.type === 'cellular') {
            quality = 'low';
          } else if (netInfo.type === 'wifi') {
            quality = netInfo.isConnectionExpensive ? 'medium' : 'high';
          }
          
          const video = videoQualities.find(v => v.quality === quality) 
            || videoQualities[0];
          
          setSelectedVideo(video);
          setIsLoading(false);
        };
        
        selectOptimalQuality();
      }, [videoQualities]);
      
      return { selectedVideo, isLoading };
    };
    ```
  </Tab>

  <Tab>
    #### Memory Management for Videos

    ```typescript
    // components/ManagedVideoPlayer.tsx
    import React, { useEffect, useRef } from 'react';
    import { AppState } from 'react-native';
    import Video from 'react-native-video';

    export const ManagedVideoPlayer: React.FC<any> = ({ source, ...props }) => {
      const videoRef = useRef<Video>(null);
      
      useEffect(() => {
        const subscription = AppState.addEventListener('change', (nextAppState) => {
          if (nextAppState === 'background') {
            // Pause and potentially unload video to save memory
            videoRef.current?.seek(0);
          }
        });
        
        return () => {
          subscription?.remove();
          // Cleanup video resources
          videoRef.current = null;
        };
      }, []);
      
      return (
        <Video
          ref={videoRef}
          source={source}
          playInBackground={false}
          playWhenInactive={false}
          {...props}
        />
      );
    };
    ```
  </Tab>
</Tabs>

## Animation Performance Optimization

### Animation Asset Optimization

<Steps>
  <Step>
    #### Lottie File Optimization

    ```bash
    # Install optimization tools
    npm install -g @lottiefiles/lottie-compress

    # Optimize Lottie files
    lottie-compress input.json --output output.json --quality 0.8
    ```
  </Step>

  <Step>
    #### Asset Size Analysis

    ```typescript
    // scripts/analyze-animations.ts
    import fs from 'fs';
    import path from 'path';

    interface AnimationAnalysis {
      path: string;
      size: number;
      type: 'lottie' | 'video' | 'gif';
      recommendations: string[];
    }

    export class AnimationAssetAnalyzer {
      analyze(): AnimationAnalysis[] {
        const animationsDir = 'assets/animations';
        const files = this.getAllAnimationFiles(animationsDir);
        
        return files.map(file => this.analyzeFile(file));
      }
      
      private analyzeFile(filePath: string): AnimationAnalysis {
        const stats = fs.statSync(filePath);
        const ext = path.extname(filePath).toLowerCase();
        const size = stats.size;
        
        const type = this.getAnimationType(ext);
        const recommendations = this.generateRecommendations(type, size);
        
        return {
          path: filePath,
          size,
          type,
          recommendations,
        };
      }
      
      private generateRecommendations(type: string, size: number): string[] {
        const recommendations = [];
        
        if (type === 'lottie' && size > 100 * 1024) {
          recommendations.push('Large Lottie file - consider optimization');
        }
        
        if (type === 'video' && size > 5 * 1024 * 1024) {
          recommendations.push('Large video file - consider compression');
        }
        
        return recommendations;
      }
    }
    ```
  </Step>

  <Step>
    #### Runtime Optimization

    ```typescript
    // core/performance/AnimationManager.ts
    export class AnimationManager {
      private static activeAnimations = new Set<string>();
      private static maxConcurrentAnimations = 3;
      
      static canPlayAnimation(id: string): boolean {
        return this.activeAnimations.size < this.maxConcurrentAnimations;
      }
      
      static registerAnimation(id: string): void {
        if (this.canPlayAnimation(id)) {
          this.activeAnimations.add(id);
        }
      }
      
      static unregisterAnimation(id: string): void {
        this.activeAnimations.delete(id);
      }
    }
    ```
  </Step>
</Steps>

## Memory Management

### Animation Memory Optimization

```typescript
// hooks/useAnimationMemoryManager.ts
import { useEffect, useRef } from 'react';
import { AppState } from 'react-native';

export const useAnimationMemoryManager = (animationId: string) => {
  const animationRef = useRef<any>(null);
  
  useEffect(() => {
    const subscription = AppState.addEventListener('change', (nextAppState) => {
      if (nextAppState === 'background') {
        animationRef.current?.pause();
      } else if (nextAppState === 'active') {
        animationRef.current?.play();
      }
    });
    
    return () => {
      subscription?.remove();
      animationRef.current = null;
    };
  }, []);
  
  return animationRef;
};
```

### Performance Monitoring

```typescript
// utils/AnimationPerformanceMonitor.ts
export class AnimationPerformanceMonitor {
  private static metrics = {
    lottieAnimations: [] as Array<{name: string; loadTime: number; fps: number}>,
    videoPlays: [] as Array<{name: string; loadTime: number; resolution: string}>,
  };
  
  static recordLottiePerformance(name: string, loadTime: number, fps: number): void {
    this.metrics.lottieAnimations.push({ name, loadTime, fps });
    
    if (fps < 30) {
      console.warn(`Low FPS Lottie animation: ${name} at ${fps} FPS`);
    }
  }
  
  static recordVideoPerformance(name: string, loadTime: number, resolution: string): void {
    this.metrics.videoPlays.push({ name, loadTime, resolution });
    
    if (loadTime > 3000) {
      console.warn(`Slow video load: ${name} took ${loadTime}ms`);
    }
  }
  
  static getPerformanceReport() {
    const { lottieAnimations, videoPlays } = this.metrics;
    
    return {
      lottie: {
        total: lottieAnimations.length,
        averageFPS: lottieAnimations.reduce((a, b) => a + b.fps, 0) / lottieAnimations.length,
        lowPerformanceAnimations: lottieAnimations.filter(a => a.fps < 30),
      },
      video: {
        total: videoPlays.length,
        averageLoadTime: videoPlays.reduce((a, b) => a + b.loadTime, 0) / videoPlays.length,
        slowLoads: videoPlays.filter(v => v.loadTime > 3000),
      },
    };
  }
}
```

## Best Practices

### Animation Implementation

**(Do ✅):**

* Optimize Lottie JSON files before use
* Use appropriate render modes for different platforms
* Pause animations when app is backgrounded
* Limit concurrent complex animations
* Implement proper memory management

**(Don't ❌):**

* Use unoptimized animation files from design tools
* Run multiple heavy animations simultaneously
* Keep animations playing when not visible
* Ignore memory management for video assets

### Video Asset Management

**(Do ✅):**

* Provide multiple quality options for different network conditions
* Use poster images for video thumbnails
* Properly manage video memory and lifecycle
* Optimize video compression for mobile

**(Don't ❌):**

* Auto-play videos on cellular connections
* Keep video components mounted when not needed
* Use high-resolution videos for background animations
* Ignore platform-specific video optimizations

## Common Use Cases

### Onboarding Animations

```typescript
// components/OnboardingAnimation.tsx
import React, { useRef, useEffect } from 'react';
import { ControlledLottieView, LottieAnimationHandle } from './ControlledLottieView';

interface OnboardingAnimationProps {
  step: number;
  onComplete: () => void;
}

export const OnboardingAnimation: React.FC<OnboardingAnimationProps> = ({
  step,
  onComplete,
}) => {
  const animationRef = useRef<LottieAnimationHandle>(null);
  
  const animations = [
    require('@/assets/animations/onboarding/welcome.json'),
    require('@/assets/animations/onboarding/features.json'),
    require('@/assets/animations/onboarding/complete.json'),
  ];
  
  useEffect(() => {
    animationRef.current?.reset();
    animationRef.current?.play();
  }, [step]);
  
  return (
    <ControlledLottieView
      ref={animationRef}
      source={animations[step]}
      onAnimationFinish={onComplete}
      style={{ width: 300, height: 300 }}
    />
  );
};
```

### Loading States

```typescript
// components/LoadingAnimation.tsx
import React from 'react';
import { OptimizedLottieView } from './OptimizedLottieView';

interface LoadingAnimationProps {
  size?: 'small' | 'medium' | 'large';
}

export const LoadingAnimation: React.FC<LoadingAnimationProps> = ({
  size = 'medium',
}) => {
  const sizeMap = {
    small: { width: 40, height: 40 },
    medium: { width: 80, height: 80 },
    large: { width: 120, height: 120 },
  };
  
  return (
    <OptimizedLottieView
      source={require('@/assets/animations/loading-spinner.json')}
      autoPlay
      loop
      style={sizeMap[size]}
    />
  );
};
```

## Related Documentation

* [Performance Optimization](/docs/ui-development/assets/assets-management/performance-optimization) - General brand asset performance
* [Image Optimization Guide](/docs/ui-development/assets/assets-management/image-optimization-guide) - Static visual assets
* [Font Management Guide](/docs/ui-development/assets/assets-management/font-management-guide) - Typography and font loading

***

**Remember**: Animations should enhance user experience, not hinder performance. Always test on lower-end devices.


# UTA UI Development: Performance Optimization
URL: https://dev.updatetheapp.com/docs/ui-development/assets/assets-management/performance-optimization
Documentation: https://dev.updatetheapp.com/docs/ui-development/assets/assets-management/performance-optimization

Comprehensive performance optimization strategies for brand assets including image compression, font loading, animation memory management, and build-time optimization techniques
        
***

title: "Performance Optimization"
description: "Comprehensive performance optimization strategies for brand assets including image compression, font loading, animation memory management, and build-time optimization techniques"
------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

import { Tabs, Tab } from 'fumadocs-ui/components/tabs';
import { Callout } from 'fumadocs-ui/components/callout';
import { Step, Steps } from 'fumadocs-ui/components/steps';

# Brand Assets Performance Optimization

## Overview

Brand asset performance directly impacts app startup time, memory usage, and user experience. This guide covers optimization strategies specifically for images, fonts, animations, and other brand assets—distinct from UI icon optimization.

<Callout type="info">
  **Scope**: This guide focuses on brand assets (logos, illustrations, fonts, animations). For UI icon performance optimization, see [Icon Performance Guide](/docs/ui-development/assets/icon-management/performance-optimization).
</Callout>

## Image Performance Optimization

### Bundle Size Analysis for Images

<Tabs items={["Metro Analysis", "Manual Analysis", "Automated Scripts"]}>
  <Tab>
    #### Metro Bundle Analyzer Setup

    ```javascript
    // metro.config.js
    const { getDefaultConfig } = require('expo/metro-config');

    const config = getDefaultConfig(__dirname);

    // Enable bundle analysis for images
    if (process.env.ANALYZE_BUNDLE === 'true') {
      config.transformer = {
        ...config.transformer,
        assetExts: [...config.transformer.assetExts, 'png', 'jpg', 'jpeg', 'svg'],
      };
    }

    module.exports = config;
    ```
  </Tab>

  <Tab>
    #### Manual Bundle Analysis

    ```typescript
    // scripts/analyze-image-assets.ts
    import fs from 'fs';
    import path from 'path';

    export class ImageAssetAnalyzer {
      private assetsPath = 'assets/brand';
      
      analyze() {
        const images = this.scanImageAssets();
        return images.map(img => this.analyzeImage(img));
      }
      
      private analyzeImage(imagePath: string) {
        const stats = fs.statSync(imagePath);
        const size = stats.size;
        const recommendations = [];
        
        if (size > 100 * 1024) { // 100KB
          recommendations.push('Consider compression - file over 100KB');
        }
        
        return {
          path: imagePath,
          size,
          recommendations,
        };
      }
    }
    ```
  </Tab>

  <Tab>
    #### Automated Analysis Scripts

    ```json
    {
      "scripts": {
        "analyze:images": "node scripts/analyze-image-assets.js",
        "optimize:images": "node scripts/optimize-brand-images.js"
      }
    }
    ```
  </Tab>
</Tabs>

### Image Compression Strategies

<Steps>
  <Step>
    #### Lossless Optimization

    Start with lossless optimization to reduce file size without quality loss

    ```bash
    # PNG optimization
    pngquant --quality=80-95 assets/brand/**/*.png

    # JPEG optimization  
    jpegoptim --max=85 assets/brand/**/*.jpg
    ```
  </Step>

  <Step>
    #### Format Selection

    Choose the most efficient format for each image type

    ```typescript
    const getOptimalFormat = (imageType: string, hasTransparency: boolean) => {
      if (hasTransparency) return 'PNG';
      if (imageType === 'photo') return 'JPEG';
      if (imageType === 'logo') return 'SVG';
      return 'WebP'; // Best compression for supported devices
    };
    ```
  </Step>

  <Step>
    #### Multi-Resolution Optimization

    Optimize each resolution variant appropriately

    ```bash
    # Different quality for different resolutions
    imagemin assets/brand/logos/logo.png --quality=80-90    # 1x
    imagemin assets/brand/logos/logo@2x.png --quality=85-95 # 2x
    imagemin assets/brand/logos/logo@3x.png --quality=90-98 # 3x
    ```
  </Step>
</Steps>

## Font Performance Optimization

### Font Loading Optimization

```typescript
// core/performance/FontLoader.ts
import * as Font from 'expo-font';
import AsyncStorage from '@react-native-async-storage/async-storage';

export class OptimizedFontLoader {
  private static fonts = {
    'Inter-Regular': require('@/assets/fonts/Inter-Regular.ttf'),
    'Inter-Medium': require('@/assets/fonts/Inter-Medium.ttf'),
    'Inter-Bold': require('@/assets/fonts/Inter-Bold.ttf'),
  };
  
  static async loadEssentialFonts(): Promise<boolean> {
    try {
      // Check cache first
      const cached = await AsyncStorage.getItem('fonts_loaded_v2');
      if (cached) return true;
      
      // Load with timeout
      await Promise.race([
        Font.loadAsync(this.fonts),
        new Promise((_, reject) => 
          setTimeout(() => reject(new Error('Font load timeout')), 5000)
        )
      ]);
      
      await AsyncStorage.setItem('fonts_loaded_v2', 'true');
      return true;
      
    } catch (error) {
      console.warn('Font loading failed, using system fonts:', error);
      return false;
    }
  }
}
```

### Font Bundle Optimization

```javascript
// scripts/optimize-fonts.js
class FontBundleOptimizer {
  analyze() {
    const fonts = this.scanFonts();
    return {
      fonts,
      totalSize: fonts.reduce((sum, font) => sum + font.size, 0),
      recommendations: this.generateRecommendations(fonts),
    };
  }
  
  generateRecommendations(fonts) {
    const recommendations = [];
    const oversized = fonts.filter(f => f.size > 200 * 1024);
    
    if (oversized.length > 0) {
      recommendations.push(`${oversized.length} fonts exceed 200KB - consider subsetting`);
    }
    
    return recommendations;
  }
}
```

## Animation Performance

### Lottie Animation Optimization

```typescript
// components/OptimizedLottieView.tsx
import React, { useEffect, useRef, useState } from 'react';
import LottieView from 'lottie-react-native';
import { AppState } from 'react-native';

export const OptimizedLottieView: React.FC<any> = ({
  source,
  autoPlay = false,
  loop = false,
  ...props
}) => {
  const animationRef = useRef<LottieView>(null);
  const [isAppActive, setIsAppActive] = useState(true);
  
  useEffect(() => {
    const subscription = AppState.addEventListener('change', (nextAppState) => {
      const isActive = nextAppState === 'active';
      setIsAppActive(isActive);
      
      if (animationRef.current) {
        if (isActive && autoPlay) {
          animationRef.current.play();
        } else {
          animationRef.current.pause();
        }
      }
    });
    
    return () => subscription?.remove();
  }, [autoPlay]);
  
  return (
    <LottieView
      ref={animationRef}
      source={source}
      autoPlay={autoPlay && isAppActive}
      loop={loop}
      renderMode="SOFTWARE" // Better performance for complex animations
      {...props}
    />
  );
};
```

## Performance Monitoring

### Asset Performance Metrics

```typescript
// utils/AssetPerformanceMonitor.ts
export class AssetPerformanceMonitor {
  private static metrics = {
    imageLoads: [] as Array<{name: string; time: number; size: number}>,
    fontLoads: [] as Array<{family: string; time: number; success: boolean}>,
  };
  
  static recordImageLoad(name: string, loadTime: number, sizeBytes: number): void {
    this.metrics.imageLoads.push({ name, time: loadTime, size: sizeBytes });
    
    if (loadTime > 100) {
      console.warn(`Slow image load: ${name} took ${loadTime}ms`);
    }
  }
  
  static getPerformanceReport() {
    const { imageLoads, fontLoads } = this.metrics;
    
    return {
      images: {
        total: imageLoads.length,
        averageLoadTime: imageLoads.reduce((a, b) => a + b.time, 0) / imageLoads.length,
        totalSize: imageLoads.reduce((a, b) => a + b.size, 0),
      },
      fonts: {
        total: fontLoads.length,
        successRate: (fontLoads.filter(f => f.success).length / fontLoads.length) * 100,
      },
    };
  }
}
```

## Production Best Practices

### Image Optimization

**(Do ✅):**

* Compress images before adding to project
* Use appropriate formats (SVG for logos, JPEG for photos, PNG for transparency)
* Provide multi-resolution variants (@1x, @2x, @3x)
* Preload critical brand images during app initialization

**(Don't ❌):**

* Use uncompressed images directly from design tools
* Include oversized images (>500KB without good reason)
* Mix up image formats inappropriately

### Font Performance

**(Do ✅):**

* Load essential font weights first, additional weights on demand
* Implement font loading timeouts and fallbacks
* Cache font loading status to avoid re-loading

**(Don't ❌):**

* Load all font weights simultaneously at startup
* Use fonts without fallback strategies
* Block app startup for font loading

### Animation Performance

**(Do ✅):**

* Optimize Lottie JSON files before use
* Pause animations when app is backgrounded
* Limit concurrent complex animations

**(Don't ❌):**

* Run multiple complex animations simultaneously
* Keep animations playing when not visible
* Skip animation performance testing on low-end devices

## Related Documentation

* [Image Optimization Guide](/docs/ui-development/assets/assets-management/image-optimization-guide) - Detailed image format strategies
* [Font Management Guide](/docs/ui-development/assets/assets-management/font-management-guide) - Font loading and platform considerations
* [Icon Performance Optimization](/docs/ui-development/assets/icon-management/performance-optimization) - UI icon-specific performance

***

**Remember**: Brand asset performance optimization is an ongoing process. Regular monitoring ensures optimal user experience.


# UTA UI Development: Icon Management
URL: https://dev.updatetheapp.com/docs/ui-development/assets/icon-management
Documentation: https://dev.updatetheapp.com/docs/ui-development/assets/icon-management

Comprehensive guide for managing UI icons in React Native applications with unified component system and type safety
        
***

title: Icon Management
description: Comprehensive guide for managing UI icons in React Native applications with unified component system and type safety
---------------------------------------------------------------------------------------------------------------------------------

import { Callout } from 'fumadocs-ui/components/callout';

# Icon Management Guide

## Overview

This guide provides a comprehensive system for managing **UI icons** (navigation, actions, status) in React Native applications. It covers vector icon libraries, custom designer SVGs, and provides a unified component system with complete type safety.

**Important Scope**: This system handles UI icons only. For brand assets (logos, illustrations), see the [Assets Management Guide](/docs/ui-development/assets/assets-management).

## Quick Decision Framework

### When to Use Each Icon Type

| Icon Type        | Use Case              | Examples                          | Benefits                       |
| ---------------- | --------------------- | --------------------------------- | ------------------------------ |
| **Vector Icons** | Standard UI patterns  | Home, Search, Menu, Settings      | Small bundle, consistent style |
| **Custom SVGs**  | Brand-specific UI     | Custom navigation, unique actions | Perfect brand alignment        |
| **Icon Fonts**   | Legacy or specialized | Symbol fonts, custom icon sets    | Single file, efficient         |

### Recommended Approach by Project Type

| Project Type    | Primary Choice            | Secondary             | Bundle Priority       |
| --------------- | ------------------------- | --------------------- | --------------------- |
| **MVP**         | @expo/vector-icons        | Custom SVGs for brand | Speed                 |
| **Corporate**   | react-native-vector-icons | Custom SVGs           | Consistency           |
| **Consumer**    | Custom SVGs + Vector      | Icon fonts            | Brand differentiation |
| **White Label** | Configurable registry     | All types             | Flexibility           |

## Architecture Overview

### Core Components

```typescript
// Unified Icon System Architecture
<Icon name="search" size={24} color="primary" />     // Vector icons
<Icon name="custom-action" size={20} />              // Custom SVGs  
<Icon name="brand-symbol" size={16} />               // Icon fonts
```

### Directory Structure

```
ui/foundation/Icon/
├── Icon.tsx              # Unified Icon component
├── registry.ts           # Co-located icon registry
├── types.ts              # TypeScript definitions
└── index.ts              # Clean exports

ui/foundation/icons/custom/    # Flat structure for custom SVGs
├── ArrowLeftIcon.tsx
├── MenuIcon.tsx
├── SearchIcon.tsx
└── index.ts

assets/icons/              # Processing workspace
├── custom-exports/        # Designer SVG exports
└── optimized/             # Processed SVGs
```

## Implementation Guides

### 📚 Detailed Documentation

Choose the guide that matches your implementation needs:

#### [Vector Icons Guide](/docs/ui-development/assets/icon-management/vector-icons-guide)

* **@expo/vector-icons** setup and usage
* **react-native-vector-icons** configuration
* Popular icon libraries (FontAwesome, Ionicons, MaterialIcons)
* Platform-specific considerations

#### [Custom Icons Guide](/docs/ui-development/assets/icon-management/custom-icons-guide)

* Designer SVG workflow (Figma → React Native)
* Flat folder structure implementation
* SVGR automation and optimization
* Icon font creation

#### [Implementation Patterns](/docs/ui-development/assets/icon-management/implementation-patterns)

* Co-located icon registry pattern
* Unified Icon component
* Type safety and validation
* Testing strategies

#### [Performance Optimization](/docs/ui-development/assets/icon-management/performance-optimization)

* Bundle size optimization
* Runtime performance
* Memory management
* Cross-platform considerations

## Quick Start

### 1. Choose Your Primary Icon Source

```typescript
// Option A: Start with @expo/vector-icons (Recommended for Expo)
import Ionicons from '@expo/vector-icons/Ionicons';
<Ionicons name="home" size={24} color="black" />

// Option B: Start with react-native-vector-icons
import Icon from 'react-native-vector-icons/MaterialIcons';
<Icon name="home" size={24} color="black" />

// Option C: Start with custom SVGs
<Icon name="custom-home" size={24} color="primary" />
```

### 2. Set Up Unified Component (Recommended)

```typescript
// ui/foundation/Icon/Icon.tsx
interface IconProps {
  name: string;
  size?: number;
  color?: string;
}

export const Icon: React.FC<IconProps> = ({ name, size = 24, color = "black" }) => {
  // Implementation in detailed guides
};
```

### 3. Configure Your Registry

```typescript
// ui/foundation/Icon/registry.ts
export const IconRegistry = {
  vector: {
    // Vector icon mappings
  },
  custom: {
    // Custom SVG mappings
  },
  fonts: {
    // Icon font mappings
  },
};
```

<Callout type="info">
  **Why Use a Registry?** The registry pattern provides type safety, consistency, and maintainability that significantly outweighs the initial setup cost. See [Implementation Patterns - Why Registry Pattern?](/docs/ui-development/assets/icon-management/implementation-patterns#why-use-an-icon-registry-pattern) for detailed pros/cons analysis.
</Callout>

## Best Practices

### Design Principles

* **(Do ✅)** Use vector icons for standard UI patterns
* **(Do ✅)** Keep icon registry co-located with Icon component
* **(Do ✅)** Implement flat folder structure for custom icons
* **(Do ✅)** Ensure complete type safety
* **(Don't ❌)** Mix UI icons with brand assets
* **(Don't ❌)** Create deep nested icon directories

### Performance Guidelines

* **(Do ✅)** Tree shake vector icon libraries
* **(Do ✅)** Optimize custom SVGs before conversion
* **(Do ✅)** Use appropriate icon sizes (16, 20, 24, 32px)
* **(Consider 🤔)** Icon font generation for large custom sets

## Migration Strategy

### From Mixed Icon Approach

1. **Audit Current Icons**: Categorize UI icons vs brand assets
2. **Choose Primary Vector Library**: @expo/vector-icons or react-native-vector-icons
3. **Implement Unified Component**: Gradual migration with backwards compatibility
4. **Move Custom Icons**: Flat structure with SVGR automation
5. **Update Registry**: Co-located with complete type definitions

### From No Icon System

1. **Start with Vector Icons**: Quick wins with standard patterns
2. **Add Custom SVGs**: For brand-specific UI needs
3. **Implement Registry**: Centralized management
4. **Add Type Safety**: Complete TypeScript integration

## Next Steps

1. **Review Project Type**: Choose recommended approach from decision framework
2. **Select Guide**: Pick the most relevant implementation guide
3. **Set Up Infrastructure**: Follow step-by-step setup instructions
4. **Implement Gradually**: Start with most common icons

## Related Documents

* [Assets Management Guide](/docs/ui-development/assets/assets-management) - For brand assets (logos, illustrations)
* [UI Development Guidelines](/docs/ui-development) - For general UI patterns
* [Performance Guide](/docs/performance) - For optimization strategies


# UTA UI Development: Vector Icons Guide
URL: https://dev.updatetheapp.com/docs/ui-development/assets/icon-management/vector-icons-guide
Documentation: https://dev.updatetheapp.com/docs/ui-development/assets/icon-management/vector-icons-guide

Complete guide for implementing vector icon libraries including @expo/vector-icons and react-native-vector-icons
        
***

title: Vector Icons Guide\
description: Complete guide for implementing vector icon libraries including @expo/vector-icons and react-native-vector-icons
-----------------------------------------------------------------------------------------------------------------------------

import { Step, Steps } from 'fumadocs-ui/components/steps';
import { Tabs, Tab } from 'fumadocs-ui/components/tabs';

# Vector Icons Implementation Guide

## Overview

Vector icons provide the foundation of most React Native icon systems. This guide covers the two primary vector icon solutions: **@expo/vector-icons** (recommended for Expo projects) and **react-native-vector-icons** (for bare React Native).

## Primary Vector Icon Libraries

### @expo/vector-icons (Recommended for Expo)

**✅ Advantages:**

* Pre-installed in Expo projects
* Zero configuration required
* Tree shaking support
* Built-in TypeScript definitions
* Popular icon sets included

**📦 Included Icon Sets:**

* **Ionicons** - Clean, modern iOS-style icons
* **MaterialIcons** - Google Material Design icons
* **FontAwesome** - Comprehensive icon library
* **AntDesign** - Ant Design icon set
* **Entypo** - General purpose icons

### react-native-vector-icons

**✅ Advantages:**

* Works in bare React Native projects
* Larger selection of icon sets
* Custom font support
* Platform-specific configurations
* Mature ecosystem

## Installation and Setup

<Tabs items={["@expo/vector-icons", "react-native-vector-icons"]}>
  <Tab>
    ### @expo/vector-icons Setup

    **Already installed** if using `create-expo-app`:

    ```bash
    # Check if installed
    npm list @expo/vector-icons

    # If not installed (rare)
    npm install @expo/vector-icons
    ```

    **Basic Usage:**

    ```typescript
    import Ionicons from '@expo/vector-icons/Ionicons';
    import MaterialIcons from '@expo/vector-icons/MaterialIcons';
    import FontAwesome from '@expo/vector-icons/FontAwesome';

    // Basic icon usage
    <Ionicons name="home" size={24} color="black" />
    <MaterialIcons name="search" size={32} color="blue" />
    <FontAwesome name="heart" size={20} color="red" />
    ```
  </Tab>

  <Tab>
    ### react-native-vector-icons Setup

    <Steps>
      <Step>
        #### Install Package

        ```bash
        npm install react-native-vector-icons
        ```
      </Step>

      <Step>
        #### iOS Configuration

        Add to `ios/YourProject/Info.plist`:

        ```xml
        <key>UIAppFonts</key>
        <array>
          <string>AntDesign.ttf</string>
          <string>Entypo.ttf</string>
          <string>EvilIcons.ttf</string>
          <string>Feather.ttf</string>
          <string>FontAwesome.ttf</string>
          <string>Foundation.ttf</string>
          <string>Ionicons.ttf</string>
          <string>MaterialIcons.ttf</string>
          <string>MaterialCommunityIcons.ttf</string>
          <string>SimpleLineIcons.ttf</string>
          <string>Octicons.ttf</string>
          <string>Zocial.ttf</string>
        </array>
        ```
      </Step>

      <Step>
        #### Android Configuration

        Add to `android/app/build.gradle`:

        ```
        apply from: "../../node_modules/react-native-vector-icons/fonts.gradle"
        ```
      </Step>

      <Step>
        #### Usage

        ```typescript
        import Icon from 'react-native-vector-icons/MaterialIcons';
        import FontAwesome from 'react-native-vector-icons/FontAwesome';
        import Ionicons from 'react-native-vector-icons/Ionicons';

        <Icon name="home" size={24} color="black" />
        <FontAwesome name="heart" size={20} color="red" />
        <Ionicons name="settings" size={32} color="blue" />
        ```
      </Step>
    </Steps>
  </Tab>
</Tabs>

## Icon Registry Pattern

### Basic Registry Implementation

```typescript
// ui/foundation/Icon/registry.ts
export const VectorIconRegistry = {
  // Ionicons mapping
  ionicons: {
    home: 'home',
    search: 'search',
    settings: 'settings',
    profile: 'person',
    menu: 'menu',
    close: 'close',
    back: 'arrow-back',
    forward: 'arrow-forward',
    heart: 'heart',
    star: 'star',
  },
  
  // Material Icons mapping
  material: {
    home: 'home',
    search: 'search', 
    settings: 'settings',
    profile: 'person',
    menu: 'menu',
    close: 'close',
    back: 'arrow_back',
    forward: 'arrow_forward',
    heart: 'favorite',
    star: 'star',
  },
  
  // FontAwesome mapping
  fontAwesome: {
    home: 'home',
    search: 'search',
    settings: 'cog',
    profile: 'user',
    menu: 'bars',
    close: 'times',
    back: 'arrow-left',
    forward: 'arrow-right',
    heart: 'heart',
    star: 'star',
  },
} as const;

// Type definitions
export type IoniconsName = keyof typeof VectorIconRegistry.ionicons;
export type MaterialIconName = keyof typeof VectorIconRegistry.material;
export type FontAwesomeName = keyof typeof VectorIconRegistry.fontAwesome;
```

### Platform-Specific Icons

```typescript
// Platform-specific icon registry
import { Platform } from 'react-native';

export const PlatformIconRegistry = {
  back: Platform.select({
    ios: 'ios-arrow-back',
    android: 'md-arrow-back',
  }),
  forward: Platform.select({
    ios: 'ios-arrow-forward', 
    android: 'md-arrow-forward',
  }),
  menu: Platform.select({
    ios: 'ios-menu',
    android: 'md-menu',
  }),
  settings: Platform.select({
    ios: 'ios-settings',
    android: 'md-settings',
  }),
} as const;
```

## Unified Icon Component Implementation

### Basic Implementation

<Tabs items={["@expo/vector-icons", "react-native-vector-icons"]}>
  <Tab>
    ```typescript
    // ui/foundation/Icon/Icon.tsx
    import React from 'react';
    import Ionicons from '@expo/vector-icons/Ionicons';
    import MaterialIcons from '@expo/vector-icons/MaterialIcons';
    import FontAwesome from '@expo/vector-icons/FontAwesome';
    import { VectorIconRegistry, IoniconsName, MaterialIconName, FontAwesomeName } from './registry';

    type IconLibrary = 'ionicons' | 'material' | 'fontAwesome';

    interface IconProps {
      name: IoniconsName | MaterialIconName | FontAwesomeName;
      size?: number;
      color?: string;
      library?: IconLibrary;
    }

    export const Icon: React.FC<IconProps> = ({ 
      name, 
      size = 24, 
      color = 'black',
      library = 'ionicons' // Default library
    }) => {
      switch (library) {
        case 'ionicons':
          return (
            <Ionicons 
              name={VectorIconRegistry.ionicons[name as IoniconsName]} 
              size={size} 
              color={color} 
            />
          );
        case 'material':
          return (
            <MaterialIcons 
              name={VectorIconRegistry.material[name as MaterialIconName]}
              size={size} 
              color={color} 
            />
          );
        case 'fontAwesome':
          return (
            <FontAwesome 
              name={VectorIconRegistry.fontAwesome[name as FontAwesomeName]}
              size={size} 
              color={color} 
            />
          );
        default:
          return (
            <Ionicons 
              name={VectorIconRegistry.ionicons[name as IoniconsName]} 
              size={size} 
              color={color} 
            />
          );
      }
    };
    ```
  </Tab>

  <Tab>
    ```typescript
    // ui/foundation/Icon/Icon.tsx
    import React from 'react';
    import MaterialIcon from 'react-native-vector-icons/MaterialIcons';
    import FontAwesome from 'react-native-vector-icons/FontAwesome';
    import Ionicons from 'react-native-vector-icons/Ionicons';
    import { VectorIconRegistry, IoniconsName, MaterialIconName, FontAwesomeName } from './registry';

    type IconLibrary = 'ionicons' | 'material' | 'fontAwesome';

    interface IconProps {
      name: IoniconsName | MaterialIconName | FontAwesomeName;
      size?: number;
      color?: string;
      library?: IconLibrary;
    }

    export const Icon: React.FC<IconProps> = ({ 
      name, 
      size = 24, 
      color = 'black',
      library = 'material' // Default library
    }) => {
      switch (library) {
        case 'ionicons':
          return (
            <Ionicons 
              name={VectorIconRegistry.ionicons[name as IoniconsName]} 
              size={size} 
              color={color} 
            />
          );
        case 'material':
          return (
            <MaterialIcon 
              name={VectorIconRegistry.material[name as MaterialIconName]}
              size={size} 
              color={color} 
            />
          );
        case 'fontAwesome':
          return (
            <FontAwesome 
              name={VectorIconRegistry.fontAwesome[name as FontAwesomeName]}
              size={size} 
              color={color} 
            />
          );
        default:
          return (
            <MaterialIcon 
              name={VectorIconRegistry.material[name as MaterialIconName]} 
              size={size} 
              color={color} 
            />
          );
      }
    };
    ```
  </Tab>
</Tabs>

### Advanced Implementation with Theme Integration

```typescript
// ui/foundation/Icon/Icon.tsx
import React from 'react';
import { useTheme } from '@/core/shared/hooks/useTheme';
import { IconRegistry } from './registry';

interface IconProps {
  name: keyof typeof IconRegistry.vector;
  size?: 'sm' | 'md' | 'lg' | 'xl' | number;
  color?: 'primary' | 'secondary' | 'accent' | 'muted' | string;
  library?: 'ionicons' | 'material' | 'fontAwesome';
}

export const Icon: React.FC<IconProps> = ({ 
  name, 
  size = 'md', 
  color = 'primary',
  library = 'ionicons'
}) => {
  const theme = useTheme();
  
  // Size mapping
  const sizeMap = {
    sm: 16,
    md: 24,
    lg: 32,
    xl: 48,
  };
  
  const iconSize = typeof size === 'number' ? size : sizeMap[size];
  
  // Color mapping
  const colorMap = {
    primary: theme.colors.primary,
    secondary: theme.colors.secondary,
    accent: theme.colors.accent,
    muted: theme.colors.muted,
  };
  
  const iconColor = colorMap[color as keyof typeof colorMap] || color;
  
  // Icon implementation based on library...
  // (Same switch logic as above)
};
```

## Usage Examples

### Basic Usage

```typescript
// Basic icon usage
<Icon name="home" size={24} color="black" />
<Icon name="search" size="md" color="primary" />
<Icon name="settings" library="material" />

// Different libraries
<Icon name="heart" library="fontAwesome" size="lg" color="red" />
<Icon name="menu" library="ionicons" size={32} />
```

### In Navigation

```typescript
// Bottom tab navigation
import { createBottomTabNavigator } from '@react-navigation/bottom-tabs';
import { Icon } from '@/ui/foundation/Icon';

const Tab = createBottomTabNavigator();

export function AppTabs() {
  return (
    <Tab.Navigator>
      <Tab.Screen 
        name="Home" 
        component={HomeScreen}
        options={{
          tabBarIcon: ({ color, size }) => (
            <Icon name="home" size={size} color={color} />
          ),
        }}
      />
      <Tab.Screen 
        name="Search" 
        component={SearchScreen}
        options={{
          tabBarIcon: ({ color, size }) => (
            <Icon name="search" size={size} color={color} />
          ),
        }}
      />
    </Tab.Navigator>
  );
}
```

### In Components

```typescript
// Button with icon
export const IconButton: React.FC<IconButtonProps> = ({ 
  iconName, 
  onPress, 
  children 
}) => {
  return (
    <TouchableOpacity onPress={onPress} style={styles.button}>
      <Icon name={iconName} size="md" color="white" />
      {children && <Text style={styles.text}>{children}</Text>}
    </TouchableOpacity>
  );
};

// List item with icon
export const ListItem: React.FC<ListItemProps> = ({ 
  iconName, 
  title, 
  subtitle 
}) => {
  return (
    <View style={styles.container}>
      <Icon name={iconName} size="lg" color="primary" />
      <View style={styles.content}>
        <Text style={styles.title}>{title}</Text>
        {subtitle && <Text style={styles.subtitle}>{subtitle}</Text>}
      </View>
    </View>
  );
};
```

## Performance Optimization

### Tree Shaking

```typescript
// ✅ GOOD: Import specific icon sets
import Ionicons from '@expo/vector-icons/Ionicons';
import MaterialIcons from '@expo/vector-icons/MaterialIcons';

// ❌ BAD: Import entire library
import * as VectorIcons from '@expo/vector-icons';
```

### Icon Registry Optimization

```typescript
// ✅ GOOD: Only include icons you actually use
export const OptimizedIconRegistry = {
  ionicons: {
    // Only include the 10-15 icons you actually use
    home: 'home',
    search: 'search',
    settings: 'settings',
    // Don't include hundreds of unused icons
  },
} as const;
```

### Bundle Size Analysis

```bash
# Analyze your bundle to see icon library impact
npx react-native bundle \
  --platform android \
  --dev false \
  --entry-file index.js \
  --bundle-output bundle.js \
  --sourcemap-output bundle.map

# Use source-map-explorer to visualize
npx source-map-explorer bundle.js bundle.map
```

## Common Patterns

### Icon Button Component

```typescript
// Reusable icon button pattern
interface IconButtonProps {
  iconName: keyof typeof IconRegistry.vector;
  onPress: () => void;
  size?: 'sm' | 'md' | 'lg';
  variant?: 'primary' | 'secondary' | 'ghost';
  disabled?: boolean;
}

export const IconButton: React.FC<IconButtonProps> = ({
  iconName,
  onPress,
  size = 'md',
  variant = 'primary',
  disabled = false,
}) => {
  const theme = useTheme();
  
  const buttonStyle = [
    styles.base,
    styles[variant],
    disabled && styles.disabled,
  ];
  
  return (
    <TouchableOpacity 
      style={buttonStyle} 
      onPress={onPress}
      disabled={disabled}
    >
      <Icon 
        name={iconName} 
        size={size} 
        color={disabled ? 'muted' : 'white'} 
      />
    </TouchableOpacity>
  );
};
```

### Icon with Badge

```typescript
// Icon with notification badge
interface BadgedIconProps {
  iconName: keyof typeof IconRegistry.vector;
  badgeCount?: number;
  showBadge?: boolean;
}

export const BadgedIcon: React.FC<BadgedIconProps> = ({
  iconName,
  badgeCount,
  showBadge = false,
}) => {
  return (
    <View style={styles.container}>
      <Icon name={iconName} size="lg" color="primary" />
      {showBadge && (
        <View style={styles.badge}>
          <Text style={styles.badgeText}>
            {badgeCount && badgeCount > 99 ? '99+' : badgeCount}
          </Text>
        </View>
      )}
    </View>
  );
};
```

## Testing Vector Icons

### Component Tests

```typescript
// __tests__/Icon.test.tsx
import React from 'react';
import { render } from '@testing-library/react-native';
import { Icon } from '../Icon';

describe('Icon Component', () => {
  it('renders ionicons correctly', () => {
    const { getByTestId } = render(
      <Icon name="home" library="ionicons" testID="home-icon" />
    );
    
    expect(getByTestId('home-icon')).toBeTruthy();
  });
  
  it('applies correct size', () => {
    const { getByTestId } = render(
      <Icon name="search" size={32} testID="search-icon" />
    );
    
    const icon = getByTestId('search-icon');
    expect(icon.props.size).toBe(32);
  });
  
  it('applies correct color', () => {
    const { getByTestId } = render(
      <Icon name="heart" color="red" testID="heart-icon" />
    );
    
    const icon = getByTestId('heart-icon');
    expect(icon.props.color).toBe('red');
  });
});
```

## Troubleshooting

### Common Issues

**Icons not showing on Android:**

* Ensure fonts are properly linked in `android/app/build.gradle`
* Check that font files are in `android/app/src/main/assets/fonts/`

**TypeScript errors:**

* Ensure icon names match registry definitions
* Update TypeScript definitions when adding new icons

**Bundle size too large:**

* Use tree shaking imports
* Only include used icon sets
* Consider icon font generation for large custom sets

### Platform-Specific Issues

**iOS:**

* Ensure font files are listed in `Info.plist`
* Check that fonts are included in build target

**Android:**

* Verify Gradle font configuration
* Ensure proper font file names (case-sensitive)

## Related Documents

* [Custom Icons Guide](/docs/ui-development/assets/icon-management/custom-icons-guide)
* [Implementation Patterns](/docs/ui-development/assets/icon-management/implementation-patterns)
* [Performance Optimization](/docs/ui-development/assets/icon-management/performance-optimization)


# UTA UI Development: Custom Icons Guide
URL: https://dev.updatetheapp.com/docs/ui-development/assets/icon-management/custom-icons-guide
Documentation: https://dev.updatetheapp.com/docs/ui-development/assets/icon-management/custom-icons-guide

Complete workflow for implementing custom designer SVGs with flat folder structure, SVGR automation, and icon font creation
        
***

title: Custom Icons Guide
description: Complete workflow for implementing custom designer SVGs with flat folder structure, SVGR automation, and icon font creation
----------------------------------------------------------------------------------------------------------------------------------------

import { Step, Steps } from 'fumadocs-ui/components/steps';
import { Tabs, Tab } from 'fumadocs-ui/components/tabs';
import { Callout } from 'fumadocs-ui/components/callout';

# Custom Icons Implementation Guide

## Overview

Custom icons enable perfect brand alignment while maintaining systematic UI iconography. This guide covers the complete workflow from designer export to React Native implementation using a flat folder structure with SVGR automation.

**Scope**: This covers UI icons only. For brand assets (logos, complex illustrations), see the [Assets Management Guide](/docs/ui-development/assets/assets-management).

## When to Use Custom Icons

### ✅ **Use Custom Icons For:**

* **Brand-specific UI patterns** - Navigation styles unique to your brand
* **Custom action icons** - Actions not available in standard libraries
* **Consistent design language** - Icons that match your exact design system
* **Specialized functionality** - Domain-specific actions or states

### 🤔 **Consider Vector Icons Instead:**

* **Standard UI patterns** - Home, search, menu, settings
* **MVP development** - Speed over perfect brand alignment
* **Small teams** - Limited design resources

## Flat Folder Structure Architecture

### Core Principle: Simplicity

```
ui/foundation/icons/custom/     # Flat structure - no subfolders
├── ArrowLeftIcon.tsx          # Navigation icons
├── ArrowRightIcon.tsx
├── MenuIcon.tsx
├── CloseIcon.tsx
├── SearchIcon.tsx             # Action icons  
├── EditIcon.tsx
├── DeleteIcon.tsx
├── SaveIcon.tsx
├── HeartIcon.tsx              # Status/social icons
├── StarIcon.tsx
├── NotificationIcon.tsx
├── types.ts                   # TypeScript definitions
└── index.ts                   # Barrel exports
```

**Why Flat Structure?**

* **(Do ✅)** Easy discovery and navigation
* **(Do ✅)** Simplified imports and maintenance
* **(Do ✅)** No deep nesting complexity
* **(Do ✅)** Consistent with foundation component patterns

## Designer-Developer Workflow

### Phase 1: Designer Guidelines

<Callout type="info">
  **Designer Handoff Standards**

  To ensure smooth implementation, establish these guidelines with your design team:
</Callout>

#### Export Requirements

| Requirement       | Specification                         | Why Important                              |
| ----------------- | ------------------------------------- | ------------------------------------------ |
| **Artboard Size** | 24x24px (consistent viewBox)          | Scalable baseline for all screen densities |
| **Stroke Width**  | 2px (consistent across all icons)     | Visual consistency and clarity             |
| **Colors**        | Single color or currentColor          | Enables theme-based color changes          |
| **Format**        | SVG (optimized export)                | Vector format for perfect scaling          |
| **Naming**        | kebab-case (arrow-left, user-profile) | Consistent with component naming           |

#### Design Checklist

* **(Do ✅)** Use consistent 24x24px artboard for all icons
* **(Do ✅)** Apply 2px stroke width throughout
* **(Do ✅)** Remove background fills and unnecessary elements
* **(Do ✅)** Use single color (#000000 or currentColor)
* **(Do ✅)** Optimize paths and reduce complexity
* **(Don't ❌)** Include multiple colors in UI icons
* **(Don't ❌)** Use different stroke widths within icon set
* **(Don't ❌)** Export with embedded text or complex effects

### Phase 2: Export Process

<Steps>
  <Step>
    #### Designer Export Setup

    **From Figma:**

    ```bash
    # Export settings
    Format: SVG
    Export options: 
      - Remove "Include id attribute" 
      - Enable "Optimize SVG"
      - Use outline stroke
    ```

    **Naming Convention:**

    ```
    arrow-left.svg        # ✅ kebab-case
    user-profile.svg      # ✅ descriptive
    shopping-cart.svg     # ✅ clear purpose

    # Avoid:
    ArrowLeft.svg         # ❌ PascalCase  
    arrow_left.svg        # ❌ snake_case
    icon1.svg             # ❌ non-descriptive
    ```
  </Step>

  <Step>
    #### Export Location

    ```bash
    # Designer places exports here
    mkdir -p assets/icons/custom-exports/

    # Directory structure
    assets/icons/
    ├── custom-exports/           # Designer SVG files
    │   ├── arrow-left.svg
    │   ├── menu.svg
    │   ├── search.svg
    │   └── heart.svg
    └── optimized/               # Processed SVGs
        ├── arrow-left.svg
        ├── menu.svg  
        ├── search.svg
        └── heart.svg
    ```
  </Step>
</Steps>

## Technical Implementation

### Dependencies Setup

<Tabs items={["npm", "yarn"]}>
  <Tab>
    ```bash
    # Core dependencies
    npm install react-native-svg

    # Development dependencies  
    npm install --save-dev @svgr/cli svgo

    # Optional: For icon fonts
    npm install --save-dev fanticon
    ```
  </Tab>

  <Tab>
    ```bash
    # Core dependencies
    yarn add react-native-svg

    # Development dependencies
    yarn add --dev @svgr/cli svgo

    # Optional: For icon fonts  
    yarn add --dev fanticon
    ```
  </Tab>
</Tabs>

### Configuration Files

#### SVGO Configuration

```javascript
// svgo.config.js
module.exports = {
  plugins: [
    {
      name: 'preset-default',
      params: {
        overrides: {
          removeViewBox: false, // Keep viewBox for proper scaling
          removeTitle: false,   // Keep title for accessibility
        },
      },
    },
    {
      name: 'addAttributesToSVGElement',
      params: {
        attributes: [
          { xmlns: 'http://www.w3.org/2000/svg' }
        ],
      },
    },
    {
      name: 'removeDimensions', // Remove width/height, keep viewBox
    },
  ],
};
```

#### SVGR Configuration

```javascript
// svgr.config.js
module.exports = {
  native: true,
  typescript: true,
  icon: true,
  replaceAttrValues: {
    '#000': 'currentColor',
    '#000000': 'currentColor',
    'black': 'currentColor',
  },
  svgProps: {
    width: '{size}',
    height: '{size}',
    fill: '{color}',
  },
  template: (variables, { tpl }) => {
    return tpl`
${variables.imports};

interface ${variables.componentName}Props {
  size?: number;
  color?: string;
}

const ${variables.componentName}: React.FC<${variables.componentName}Props> = ({ 
  size = 24, 
  color = 'currentColor',
  ...props 
}) => (
  ${variables.jsx}
);

${variables.exports};
`;
  },
};
```

### Automation Scripts

#### Processing Pipeline

```bash
#!/bin/bash
# scripts/process-custom-icons.sh

set -e

echo "🎨 Processing custom icons..."

# Step 1: Optimize SVGs
echo "📦 Optimizing SVGs with SVGO..."
npx svgo \
  --config svgo.config.js \
  --input assets/icons/custom-exports \
  --output assets/icons/optimized \
  --recursive

# Step 2: Generate React Native components
echo "⚛️ Generating React Native components..."
npx @svgr/cli \
  --config-file svgr.config.js \
  --out-dir ui/foundation/icons/custom \
  --typescript \
  assets/icons/optimized

# Step 3: Generate barrel exports
echo "📋 Generating barrel exports..."
node scripts/generate-icon-exports.js

echo "✅ Custom icons processed successfully!"
echo "📁 Components available in: ui/foundation/icons/custom/"
```

#### Export Generation

```javascript
// scripts/generate-icon-exports.js
const fs = require('fs');
const path = require('path');

const iconsDir = path.join(__dirname, '../ui/foundation/icons/custom');
const outputFile = path.join(iconsDir, 'index.ts');

// Read all .tsx files
const iconFiles = fs.readdirSync(iconsDir)
  .filter(file => file.endsWith('.tsx') && file !== 'index.tsx')
  .map(file => file.replace('.tsx', ''));

// Generate exports
const exports = iconFiles
  .map(name => `export { default as ${name} } from './${name}';`)
  .join('\n');

// Generate type union
const iconNames = iconFiles
  .map(name => name.replace('Icon', '').toLowerCase())
  .map(name => `'${name}'`)
  .join(' | ');

const content = `// Auto-generated file - do not edit manually
${exports}

// Type definition for custom icon names
export type CustomIconName = ${iconNames};

// Icon component mapping
export const customIcons = {
${iconFiles.map(name => {
  const iconName = name.replace('Icon', '').toLowerCase();
  return `  '${iconName}': ${name},`;
}).join('\n')}
} as const;
`;

fs.writeFileSync(outputFile, content);
console.log(`✅ Generated exports for ${iconFiles.length} icons`);
```

### Package.json Scripts

```json
{
  "scripts": {
    "icons:process": "bash scripts/process-custom-icons.sh",
    "icons:optimize": "npx svgo --config svgo.config.js --input assets/icons/custom-exports --output assets/icons/optimized --recursive",
    "icons:generate": "npx @svgr/cli --config-file svgr.config.js --out-dir ui/foundation/icons/custom --typescript assets/icons/optimized",
    "icons:exports": "node scripts/generate-icon-exports.js"
  }
}
```

## Registry Integration

### Custom Icon Registry

```typescript
// ui/foundation/Icon/registry.ts
import { customIcons, CustomIconName } from '../icons/custom';

export const IconRegistry = {
  // Vector icons (from previous guide)
  vector: {
    ionicons: { /* ... */ },
    material: { /* ... */ },
    fontAwesome: { /* ... */ },
  },
  
  // Custom icons (flat structure)
  custom: customIcons,
  
  // Icon fonts (if needed)
  fonts: {
    // Custom icon font mappings
  },
} as const;

// Type definitions
export type VectorIconName = keyof typeof IconRegistry.vector.ionicons;
export type { CustomIconName };
export type IconName = VectorIconName | CustomIconName;
```

### Unified Icon Component Update

```typescript
// ui/foundation/Icon/Icon.tsx
import React from 'react';
import Ionicons from '@expo/vector-icons/Ionicons';
import { IconRegistry, VectorIconName, CustomIconName } from './registry';

interface IconProps {
  name: VectorIconName | CustomIconName;
  size?: number;
  color?: string;
  library?: 'vector' | 'custom';
}

export const Icon: React.FC<IconProps> = ({ 
  name, 
  size = 24, 
  color = 'currentColor',
  library = 'vector'
}) => {
  // Auto-detect library if not specified
  const detectedLibrary = library === 'vector' 
    ? (name in IconRegistry.vector.ionicons ? 'vector' : 'custom')
    : library;

  switch (detectedLibrary) {
    case 'vector':
      return (
        <Ionicons 
          name={IconRegistry.vector.ionicons[name as VectorIconName]} 
          size={size} 
          color={color} 
        />
      );
    
    case 'custom':
      const CustomIconComponent = IconRegistry.custom[name as CustomIconName];
      if (!CustomIconComponent) {
        console.warn(`Custom icon "${name}" not found`);
        return null;
      }
      return <CustomIconComponent size={size} color={color} />;
    
    default:
      console.warn(`Unknown icon library: ${detectedLibrary}`);
      return null;
  }
};
```

## Usage Examples

### Basic Implementation

```typescript
// Basic custom icon usage
<Icon name="arrow-left" library="custom" size={24} color="primary" />
<Icon name="menu" library="custom" size={32} />
<Icon name="heart" library="custom" size={20} color="red" />

// Auto-detection (falls back to custom if not found in vector)
<Icon name="brand-specific-action" size={24} />
```

### In Navigation Components

```typescript
// Custom navigation with brand-specific icons
export const CustomHeader: React.FC = () => {
  return (
    <View style={styles.header}>
      <TouchableOpacity onPress={handleBack}>
        <Icon name="arrow-left" library="custom" size={24} color="white" />
      </TouchableOpacity>
      
      <Text style={styles.title}>Settings</Text>
      
      <TouchableOpacity onPress={handleMenu}>
        <Icon name="menu" library="custom" size={24} color="white" />
      </TouchableOpacity>
    </View>
  );
};
```

### Theme Integration

```typescript
// Theme-aware custom icons
export const ThemedIcon: React.FC<ThemedIconProps> = ({ 
  name, 
  size = 'md',
  variant = 'primary' 
}) => {
  const theme = useTheme();
  
  const sizeMap = {
    sm: 16,
    md: 24, 
    lg: 32,
    xl: 48,
  };
  
  const colorMap = {
    primary: theme.colors.primary,
    secondary: theme.colors.secondary,
    accent: theme.colors.accent,
    muted: theme.colors.textMuted,
  };
  
  return (
    <Icon 
      name={name}
      library="custom"
      size={typeof size === 'number' ? size : sizeMap[size]}
      color={colorMap[variant]}
    />
  );
};
```

## Icon Font Generation (Advanced)

### When to Consider Icon Fonts

* **Large custom icon sets** (50+ icons)
* **Performance optimization** needed
* **Legacy platform support** required
* **Consistent baseline alignment** important

### Setup and Generation

<Steps>
  <Step>
    #### Install Fanticon

    ```bash
    npm install --save-dev fanticon
    ```
  </Step>

  <Step>
    #### Configuration

    ```javascript
    // scripts/generate-icon-font.js
    const fanticon = require('fanticon');

    fanticon({
      inputDir: './assets/icons/optimized',
      outputDir: './assets/fonts',
      fontTypes: ['ttf', 'woff', 'woff2'],
      assetTypes: ['ts', 'json'],
      name: 'CustomIcons',
      prefix: 'icon',
      selector: '.icon',
      formatOptions: {
        json: {
          indent: 2
        }
      },
      pathOptions: {
        ts: './ui/foundation/icons/custom/font-mapping.ts'
      }
    });
    ```
  </Step>

  <Step>
    #### Usage with Icon Fonts

    ```typescript
    // ui/foundation/icons/custom/IconFont.tsx
    import { createIconSetFromFontello } from '@expo/vector-icons';
    import fontMapping from './font-mapping';

    const CustomIconFont = createIconSetFromFontello(
      fontMapping,
      'CustomIcons',
      'CustomIcons.ttf'
    );

    export default CustomIconFont;
    ```
  </Step>
</Steps>

## Performance Optimization

### Bundle Size Management

```typescript
// ✅ GOOD: Import specific icons only
import { ArrowLeftIcon, MenuIcon } from '@/ui/foundation/icons/custom';

// ❌ BAD: Import all custom icons
import * as CustomIcons from '@/ui/foundation/icons/custom';
```

### Lazy Loading Pattern

```typescript
// Lazy load custom icons for better performance
const LazyCustomIcon: React.FC<LazyIconProps> = ({ name, ...props }) => {
  const [IconComponent, setIconComponent] = useState<React.ComponentType | null>(null);
  
  useEffect(() => {
    const loadIcon = async () => {
      try {
        const { [name]: Component } = await import('@/ui/foundation/icons/custom');
        setIconComponent(() => Component);
      } catch (error) {
        console.warn(`Failed to load custom icon: ${name}`);
      }
    };
    
    loadIcon();
  }, [name]);
  
  if (!IconComponent) {
    return <View style={{ width: props.size, height: props.size }} />;
  }
  
  return <IconComponent {...props} />;
};
```

## Testing Custom Icons

### Component Tests

```typescript
// __tests__/CustomIcon.test.tsx
import React from 'react';
import { render } from '@testing-library/react-native';
import { Icon } from '../Icon';

describe('Custom Icon Component', () => {
  it('renders custom icons correctly', () => {
    const { getByTestId } = render(
      <Icon name="arrow-left" library="custom" testID="custom-icon" />
    );
    
    expect(getByTestId('custom-icon')).toBeTruthy();
  });
  
  it('applies custom size and color', () => {
    const { getByTestId } = render(
      <Icon 
        name="menu" 
        library="custom" 
        size={32} 
        color="red" 
        testID="menu-icon" 
      />
    );
    
    const icon = getByTestId('menu-icon');
    expect(icon.props.size).toBe(32);
    expect(icon.props.color).toBe('red');
  });
  
  it('handles missing custom icons gracefully', () => {
    const { container } = render(
      <Icon name="non-existent" library="custom" />
    );
    
    // Should not crash and render nothing
    expect(container.children).toHaveLength(0);
  });
});
```

### Icon Processing Tests

```typescript
// __tests__/icon-processing.test.js
const fs = require('fs');
const path = require('path');

describe('Icon Processing Pipeline', () => {
  const customIconsDir = path.join(__dirname, '../ui/foundation/icons/custom');
  
  it('generates proper TypeScript components', () => {
    const files = fs.readdirSync(customIconsDir)
      .filter(file => file.endsWith('.tsx'));
    
    expect(files.length).toBeGreaterThan(0);
    
    files.forEach(file => {
      const content = fs.readFileSync(path.join(customIconsDir, file), 'utf8');
      expect(content).toContain('interface');
      expect(content).toContain('size?:');
      expect(content).toContain('color?:');
    });
  });
  
  it('generates proper barrel exports', () => {
    const indexFile = path.join(customIconsDir, 'index.ts');
    const content = fs.readFileSync(indexFile, 'utf8');
    
    expect(content).toContain('export { default as');
    expect(content).toContain('CustomIconName');
    expect(content).toContain('customIcons');
  });
});
```

## Troubleshooting

### Common Issues

**SVGR not generating proper components:**

* Check SVGR configuration in `svgr.config.js`
* Ensure SVG files are properly optimized
* Verify template syntax is correct

**Icons not displaying:**

* Check if `react-native-svg` is properly installed
* Verify component imports are correct
* Ensure SVG viewBox is preserved

**Type errors:**

* Regenerate barrel exports after adding new icons
* Check TypeScript definitions in registry
* Verify icon names match file names

### Platform-Specific Issues

**Metro bundler errors:**

* Add SVG extension to Metro configuration
* Clear Metro cache: `npx react-native start --reset-cache`

**Build failures:**

* Ensure all SVG files are valid
* Check for unsupported SVG features
* Verify SVGR output is valid TypeScript

## Related Documents

* [Vector Icons Guide](/docs/ui-development/assets/icon-management/vector-icons-guide)
* [Implementation Patterns](/docs/ui-development/assets/icon-management/implementation-patterns)
* [Performance Optimization](/docs/ui-development/assets/icon-management/performance-optimization)
* [Assets Management Guide](/docs/ui-development/assets/assets-management)


# UTA UI Development: Implementation Patterns
URL: https://dev.updatetheapp.com/docs/ui-development/assets/icon-management/implementation-patterns
Documentation: https://dev.updatetheapp.com/docs/ui-development/assets/icon-management/implementation-patterns

Advanced patterns for icon registry architecture, unified component design, automation workflows, and scalable icon system integration
        
***

title: Implementation Patterns
description: Advanced patterns for icon registry architecture, unified component design, automation workflows, and scalable icon system integration
---------------------------------------------------------------------------------------------------------------------------------------------------

import { Step, Steps } from 'fumadocs-ui/components/steps';
import { Tabs, Tab } from 'fumadocs-ui/components/tabs';
import { Callout } from 'fumadocs-ui/components/callout';

# Icon Implementation Patterns

## Overview

This guide covers advanced implementation patterns for building a robust, scalable, and maintainable icon system. It focuses on architectural patterns, automation workflows, and integration strategies that scale from small teams to enterprise-level applications.

## Prerequisites

To get the most out of this document, we recommend you first understand these key areas and review the related guides:

* [Vector Icons Guide](/docs/ui-development/assets/icon-management/vector-icons-guide) - Foundation for vector icon libraries
* [Custom Icons Guide](/docs/ui-development/assets/icon-management/custom-icons-guide) - Custom SVG workflow and flat structure
* Basic TypeScript and React Native component patterns

## Registry Architecture Patterns

### Why Use an Icon Registry Pattern?

The Icon Registry Pattern is a centralized approach to managing icon definitions, mappings, and configurations. Before diving into implementation, it's important to understand why this pattern is recommended over alternatives.

#### Problem Statement

Without a registry pattern, teams typically face these challenges:

```typescript
// ❌ PROBLEM: Scattered icon usage throughout codebase
import MaterialIcons from 'react-native-vector-icons/MaterialIcons';
import Ionicons from 'react-native-vector-icons/Ionicons';

// Inconsistent icon names across the app
<MaterialIcons name="home" size={24} />           // One screen
<Ionicons name="home-outline" size={24} />        // Another screen  
<MaterialIcons name="house" size={24} />          // Yet another screen

// Magic strings everywhere
<MaterialIcons name="settings" size={24} />       // No type safety
<MaterialIcons name="account_circle" size={24} /> // Typo goes unnoticed
```

#### Registry Pattern Benefits

| Benefit                | Description                                 | Impact                             |
| ---------------------- | ------------------------------------------- | ---------------------------------- |
| **Type Safety**        | Compile-time validation of icon names       | Prevents runtime errors from typos |
| **Consistency**        | Single source of truth for icon mappings    | Ensures visual consistency         |
| **Maintainability**    | Centralized changes affect entire app       | Easy to swap icon libraries        |
| **Semantic Naming**    | Business-friendly names vs library-specific | Better code readability            |
| **Auto-completion**    | IDE support for available icons             | Improved developer experience      |
| **Refactoring Safety** | Changes propagate automatically             | Reduces update overhead            |

#### Comparison: Registry vs Direct Usage

<Tabs items={["Without Registry", "With Registry"]}>
  <Tab>
    ```typescript
    // ❌ Direct library usage - Problems:

    // 1. Scattered imports across many files
    import MaterialIcons from 'react-native-vector-icons/MaterialIcons';
    import Ionicons from 'react-native-vector-icons/Ionicons';

    // 2. Magic strings with no type safety
    <MaterialIcons name="home" size={24} />
    <MaterialIcons name="seting" size={24} /> // Typo!

    // 3. Inconsistent icon choices
    <MaterialIcons name="home" />          // Some screens
    <Ionicons name="home-outline" />       // Other screens
    <MaterialIcons name="house" />         // More screens

    // 4. Platform differences ignored
    <MaterialIcons name="arrow-back" />    // Wrong on iOS

    // 5. Library changes require global find/replace
    // Need to change ALL MaterialIcons to Ionicons? 
    // Find/replace across 100+ files!
    ```
  </Tab>

  <Tab>
    ```typescript
    // ✅ Registry pattern - Solutions:

    // 1. Single import everywhere
    import { Icon } from '@/ui/foundation/Icon';

    // 2. Type-safe icon names
    <Icon name="home" />                   // ✅ Autocomplete
    <Icon name="seting" />                 // ❌ Compile error

    // 3. Consistent icon choices
    <Icon name="home" />                   // Same everywhere

    // 4. Platform differences handled automatically
    <Icon name="back" />                   // Auto iOS/Android

    // 5. Library changes in one file
    // Change library in registry.ts - done!
    // All icons automatically updated
    ```
  </Tab>
</Tabs>

#### Registry Pattern Trade-offs

**✅ Advantages:**

* **(Do ✅)** Complete type safety and autocomplete support
* **(Do ✅)** Centralized icon management and consistency
* **(Do ✅)** Easy library swapping and updates
* **(Do ✅)** Semantic naming improves code readability
* **(Do ✅)** Platform-specific logic handled once
* **(Do ✅)** Testing and validation simplified

**⚠️ Disadvantages:**

* **(Consider 🤔)** Additional abstraction layer adds complexity
* **(Consider 🤔)** Initial setup overhead for registry configuration
* **(Consider 🤔)** All icon names must be pre-defined (less flexibility)
* **(Be Aware ❗)** Registry can become large with many icon types
* **(Be Aware ❗)** Team must learn registry API instead of direct library usage

#### When to Use Registry Pattern

**✅ Use Registry When:**

* Team size > 3 developers (consistency becomes critical)
* App has > 50 icons (management overhead pays off)
* Multiple icon sources (vector libs + custom + images)
* Long-term maintenance expected (>1 year project)
* Type safety is priority
* Platform-specific icons needed

**🤔 Consider Alternatives When:**

* Small prototype or MVP (\< 20 icons)
* Single developer project
* One-time use application
* Performance is absolutely critical (minimal abstraction needed)

#### Alternative Approaches Comparison

| Approach                   | Type Safety | Consistency | Maintainability | Setup Cost | Performance |
| -------------------------- | ----------- | ----------- | --------------- | ---------- | ----------- |
| **Direct Library Usage**   | ❌ None      | ❌ Manual    | ❌ Scattered     | ✅ Zero     | ✅ Optimal   |
| **Constants File**         | ⚠️ Partial  | ✅ Good      | ⚠️ Moderate     | ✅ Low      | ✅ Good      |
| **Registry Pattern**       | ✅ Complete  | ✅ Excellent | ✅ Excellent     | ⚠️ Medium  | ✅ Good      |
| **Icon Component Library** | ✅ Complete  | ✅ Excellent | ✅ Good          | ❌ High     | ⚠️ Depends  |

### Co-located Registry Pattern

The co-located registry pattern keeps icon definitions close to the Icon component for better maintainability and type safety.

```typescript
// ui/foundation/Icon/registry.ts
import { IconSet } from '@expo/vector-icons';
import { customIcons, CustomIconName } from '../icons/custom';

// Vector icon configurations
const vectorIconConfigs = {
  ionicons: {
    component: IconSet.Ionicons,
    prefix: '',
    map: {
      // Semantic name -> actual icon name mapping
      'home': 'home-outline',
      'search': 'search-outline', 
      'profile': 'person-outline',
      'settings': 'settings-outline',
      'menu': 'menu-outline',
      'close': 'close-outline',
      'back': 'arrow-back-outline',
      'forward': 'arrow-forward-outline',
      'edit': 'create-outline',
      'delete': 'trash-outline',
      'save': 'checkmark-outline',
    }
  },
  material: {
    component: IconSet.MaterialIcons,
    prefix: '',
    map: {
      'home': 'home',
      'search': 'search',
      'profile': 'person',
      'settings': 'settings',
      'notification': 'notifications',
      'favorite': 'favorite_border',
    }
  }
} as const;

// Centralized icon registry
export const IconRegistry = {
  vector: vectorIconConfigs,
  custom: customIcons,
  
  // Icon fonts (if using custom fonts)
  fonts: {
    // Custom icon font mappings would go here
  },
  
  // Image-based icons (for complex graphics)
  images: {
    // PNG/JPG icon mappings would go here  
  },
} as const;

// Type definitions for all icon sources
export type VectorLibrary = keyof typeof IconRegistry.vector;
export type VectorIconName = keyof typeof IconRegistry.vector.ionicons.map;
export type { CustomIconName };
export type ImageIconName = keyof typeof IconRegistry.images;
export type IconName = VectorIconName | CustomIconName | ImageIconName;

// Registry utilities
export const getVectorIcon = (library: VectorLibrary, name: VectorIconName) => {
  const config = IconRegistry.vector[library];
  return {
    component: config.component,
    name: config.map[name],
  };
};

export const getCustomIcon = (name: CustomIconName) => {
  return IconRegistry.custom[name];
};
```

### Semantic Naming Strategy

Map semantic names to actual icon implementations for flexibility:

```typescript
// ui/foundation/Icon/semanticRegistry.ts
export const SemanticIconMap = {
  // Navigation
  navigation: {
    'home': { library: 'vector', name: 'home' },
    'back': { library: 'vector', name: 'back' },
    'menu': { library: 'vector', name: 'menu' },
    'close': { library: 'vector', name: 'close' },
  },
  
  // Actions
  actions: {
    'edit': { library: 'vector', name: 'edit' },
    'delete': { library: 'vector', name: 'delete' },
    'save': { library: 'vector', name: 'save' },
    'share': { library: 'custom', name: 'share' }, // Brand-specific share icon
  },
  
  // Status & Social
  social: {
    'like': { library: 'custom', name: 'heart' }, // Custom heart animation
    'star': { library: 'vector', name: 'star' },
    'notification': { library: 'vector', name: 'notification' },
  },
  
  // Brand-specific
  brand: {
    'logo': { library: 'custom', name: 'logo' },
    'brand-action': { library: 'custom', name: 'brand-action' },
  }
} as const;

export type SemanticCategory = keyof typeof SemanticIconMap;
export type SemanticIconName<T extends SemanticCategory> = keyof typeof SemanticIconMap[T];
```

## Unified Icon Component Patterns

### Basic Unified Component

The foundation Icon component that handles all icon types:

```typescript
// ui/foundation/Icon/Icon.tsx
import React from 'react';
import { View, Image, StyleSheet } from 'react-native';
import { IconRegistry, VectorLibrary, VectorIconName, CustomIconName, ImageIconName } from './registry';

export interface IconProps {
  name: VectorIconName | CustomIconName | ImageIconName;
  size?: number;
  color?: string;
  library?: 'vector' | 'custom' | 'images' | 'auto';
  vectorLibrary?: VectorLibrary;
  style?: any;
  testID?: string;
}

export const Icon: React.FC<IconProps> = ({
  name,
  size = 24,
  color = 'currentColor',
  library = 'auto',
  vectorLibrary = 'ionicons',
  style,
  testID,
  ...props
}) => {
  // Auto-detection logic
  const detectedLibrary = library === 'auto' 
    ? detectIconLibrary(name)
    : library;

  const renderIcon = () => {
    switch (detectedLibrary) {
      case 'vector':
        return renderVectorIcon(name as VectorIconName, vectorLibrary, size, color);
      
      case 'custom':
        return renderCustomIcon(name as CustomIconName, size, color);
      
      case 'images':
        return renderImageIcon(name as ImageIconName, size);
      
      default:
        console.warn(`Unknown icon library: ${detectedLibrary} for icon: ${name}`);
        return null;
    }
  };

  return (
    <View style={[{ width: size, height: size }, style]} testID={testID}>
      {renderIcon()}
    </View>
  );
};

// Helper functions
const detectIconLibrary = (name: string): 'vector' | 'custom' | 'images' => {
  if (name in IconRegistry.custom) return 'custom';
  if (name in IconRegistry.images) return 'images';
  return 'vector'; // Default fallback
};

const renderVectorIcon = (name: VectorIconName, library: VectorLibrary, size: number, color: string) => {
  const config = IconRegistry.vector[library];
  const IconComponent = config.component;
  const iconName = config.map[name];
  
  if (!iconName) {
    console.warn(`Icon "${name}" not found in ${library} library`);
    return null;
  }
  
  return <IconComponent name={iconName} size={size} color={color} />;
};

const renderCustomIcon = (name: CustomIconName, size: number, color: string) => {
  const IconComponent = IconRegistry.custom[name];
  
  if (!IconComponent) {
    console.warn(`Custom icon "${name}" not found`);
    return null;
  }
  
  return <IconComponent size={size} color={color} />;
};

const renderImageIcon = (name: ImageIconName, size: number) => {
  const imageSource = IconRegistry.images[name];
  
  if (!imageSource) {
    console.warn(`Image icon "${name}" not found`);
    return null;
  }
  
  return (
    <Image 
      source={imageSource} 
      style={{ width: size, height: size }}
      resizeMode="contain"
    />
  );
};
```

### Enhanced Icon Component with Design Tokens

Integration with design system tokens for consistent theming:

```typescript
// ui/foundation/Icon/ThemedIcon.tsx
import React from 'react';
import { useTheme } from '@/core/theme';
import { Icon, IconProps } from './Icon';

interface ThemedIconProps extends Omit<IconProps, 'size' | 'color'> {
  size?: 'xs' | 'sm' | 'md' | 'lg' | 'xl' | number;
  variant?: 'primary' | 'secondary' | 'accent' | 'muted' | 'danger' | 'success';
  disabled?: boolean;
}

export const ThemedIcon: React.FC<ThemedIconProps> = ({
  size = 'md',
  variant = 'primary',
  disabled = false,
  ...props
}) => {
  const theme = useTheme();
  
  // Size mapping from design tokens
  const sizeMap = {
    xs: theme.iconSizes.xs,    // 12
    sm: theme.iconSizes.sm,    // 16  
    md: theme.iconSizes.md,    // 24
    lg: theme.iconSizes.lg,    // 32
    xl: theme.iconSizes.xl,    // 48
  };
  
  // Color mapping from design tokens
  const colorMap = {
    primary: theme.colors.icon.primary,
    secondary: theme.colors.icon.secondary,
    accent: theme.colors.icon.accent,
    muted: theme.colors.icon.muted,
    danger: theme.colors.icon.danger,
    success: theme.colors.icon.success,
  };
  
  const resolvedSize = typeof size === 'number' ? size : sizeMap[size];
  const resolvedColor = disabled 
    ? theme.colors.icon.disabled 
    : colorMap[variant];
  
  return (
    <Icon
      {...props}
      size={resolvedSize}
      color={resolvedColor}
    />
  );
};
```

### Semantic Icon Component

Component that uses semantic naming for better maintainability:

```typescript
// ui/foundation/Icon/SemanticIcon.tsx
import React from 'react';
import { SemanticIconMap, SemanticCategory, SemanticIconName } from './semanticRegistry';
import { ThemedIcon, ThemedIconProps } from './ThemedIcon';

interface SemanticIconProps<T extends SemanticCategory> extends Omit<ThemedIconProps, 'name'> {
  category: T;
  name: SemanticIconName<T>;
}

export const SemanticIcon = <T extends SemanticCategory>({
  category,
  name,
  ...props
}: SemanticIconProps<T>) => {
  const iconConfig = SemanticIconMap[category][name];
  
  if (!iconConfig) {
    console.warn(`Semantic icon "${String(name)}" not found in category "${category}"`);
    return null;
  }
  
  return (
    <ThemedIcon
      {...props}
      name={iconConfig.name}
      library={iconConfig.library}
    />
  );
};

// Usage examples with full type safety
// <SemanticIcon category="navigation" name="home" size="md" variant="primary" />
// <SemanticIcon category="actions" name="edit" size="lg" variant="accent" />
// <SemanticIcon category="brand" name="logo" size="xl" />
```

## Automation Workflow Patterns

### Continuous Icon Processing

Automated workflow for processing designer exports:

```javascript
// scripts/icon-automation.js
const fs = require('fs');
const path = require('path');
const { execSync } = require('child_process');
const chokidar = require('chokidar');

class IconAutomation {
  constructor(config = {}) {
    this.config = {
      inputDir: 'assets/icons/custom-exports',
      optimizedDir: 'assets/icons/optimized', 
      outputDir: 'ui/foundation/icons/custom',
      registryPath: 'ui/foundation/Icon/registry.ts',
      watchMode: false,
      ...config
    };
  }

  async processIcons() {
    console.log('🎨 Starting icon processing pipeline...');
    
    try {
      await this.optimizeSVGs();
      await this.generateComponents();
      await this.updateRegistry();
      await this.runTests();
      
      console.log('✅ Icon processing completed successfully!');
    } catch (error) {
      console.error('❌ Icon processing failed:', error.message);
      process.exit(1);
    }
  }

  async optimizeSVGs() {
    console.log('📦 Optimizing SVGs...');
    
    const command = `npx svgo \
      --config svgo.config.js \
      --input ${this.config.inputDir} \
      --output ${this.config.optimizedDir} \
      --recursive`;
    
    execSync(command, { stdio: 'inherit' });
  }

  async generateComponents() {
    console.log('⚛️ Generating React components...');
    
    const command = `npx @svgr/cli \
      --config-file svgr.config.js \
      --out-dir ${this.config.outputDir} \
      --typescript \
      ${this.config.optimizedDir}`;
    
    execSync(command, { stdio: 'inherit' });
  }

  async updateRegistry() {
    console.log('📋 Updating icon registry...');
    
    const iconFiles = this.getIconFiles();
    const registryContent = this.generateRegistryContent(iconFiles);
    
    const indexPath = path.join(this.config.outputDir, 'index.ts');
    fs.writeFileSync(indexPath, registryContent);
    
    console.log(`📊 Updated registry with ${iconFiles.length} icons`);
  }

  getIconFiles() {
    const files = fs.readdirSync(this.config.outputDir)
      .filter(file => file.endsWith('.tsx') && file !== 'index.tsx')
      .map(file => file.replace('.tsx', ''));
    
    return files;
  }

  generateRegistryContent(iconFiles) {
    const exports = iconFiles
      .map(name => `export { default as ${name} } from './${name}';`)
      .join('\n');

    const iconNames = iconFiles
      .map(name => name.replace('Icon', '').toLowerCase())
      .map(name => `'${name}'`)
      .join(' | ');

    const iconMapping = iconFiles.map(name => {
      const iconName = name.replace('Icon', '').toLowerCase();
      return `  '${iconName}': ${name},`;
    }).join('\n');

    return `// Auto-generated file - do not edit manually
// Generated at: ${new Date().toISOString()}
// Total icons: ${iconFiles.length}

${exports}

// Type definition for custom icon names
export type CustomIconName = ${iconNames};

// Icon component mapping for registry
export const customIcons = {
${iconMapping}
} as const;

// Icon metadata
export const iconMetadata = {
  count: ${iconFiles.length},
  lastUpdated: '${new Date().toISOString()}',
  icons: [${iconFiles.map(name => `'${name}'`).join(', ')}],
} as const;
`;
  }

  async runTests() {
    console.log('🧪 Running icon tests...');
    
    try {
      execSync('npm run test -- --testPathPattern=icon', { stdio: 'inherit' });
    } catch (error) {
      console.warn('⚠️ Some tests failed, but continuing...');
    }
  }

  startWatcher() {
    console.log(`👁️ Watching ${this.config.inputDir} for changes...`);
    
    const watcher = chokidar.watch(`${this.config.inputDir}/**/*.svg`);
    
    let timeout;
    const processWithDebounce = () => {
      clearTimeout(timeout);
      timeout = setTimeout(() => {
        this.processIcons();
      }, 1000); // 1 second debounce
    };
    
    watcher
      .on('add', processWithDebounce)
      .on('change', processWithDebounce)
      .on('unlink', processWithDebounce);
  }
}

// CLI usage
if (require.main === module) {
  const automation = new IconAutomation();
  
  const args = process.argv.slice(2);
  const watchMode = args.includes('--watch');
  
  if (watchMode) {
    automation.startWatcher();
  } else {
    automation.processIcons();
  }
}

module.exports = IconAutomation;
```

### Pre-commit Hook Integration

Ensure icon consistency with Git hooks:

```bash
#!/bin/sh
# .husky/pre-commit

echo "🔍 Checking for icon changes..."

# Check if any SVG files changed
if git diff --cached --name-only | grep -E "\.(svg)$" > /dev/null; then
  echo "📦 SVG files changed, processing icons..."
  
  # Process icons
  npm run icons:process
  
  # Stage the generated files
  git add ui/foundation/icons/custom/
  git add assets/icons/optimized/
  
  echo "✅ Icons processed and staged"
fi

# Run standard linting and tests
npm run lint:staged
npm run test:icons
```

### Package.json Scripts Integration

Complete script integration for icon workflows:

```json
{
  "scripts": {
    "icons:process": "node scripts/icon-automation.js",
    "icons:watch": "node scripts/icon-automation.js --watch",
    "icons:optimize": "npx svgo --config svgo.config.js --input assets/icons/custom-exports --output assets/icons/optimized --recursive",
    "icons:generate": "npx @svgr/cli --config-file svgr.config.js --out-dir ui/foundation/icons/custom --typescript assets/icons/optimized",
    "icons:registry": "node scripts/generate-icon-registry.js",
    "icons:clean": "rm -rf ui/foundation/icons/custom/*.tsx && rm -rf assets/icons/optimized/*",
    "icons:validate": "node scripts/validate-icons.js",
    "test:icons": "jest --testPathPattern=icon",
    "lint:icons": "eslint ui/foundation/icons/custom/ --ext .tsx"
  }
}
```

## Advanced Integration Patterns

### Theme Integration Pattern

Deep integration with design system theming:

```typescript
// ui/foundation/Icon/ThemeIntegration.tsx
import React, { createContext, useContext } from 'react';
import { IconProps } from './Icon';

interface IconTheme {
  sizes: Record<string, number>;
  colors: Record<string, string>;
  variants: Record<string, Partial<IconProps>>;
}

const IconThemeContext = createContext<IconTheme | null>(null);

export const IconThemeProvider: React.FC<{ theme: IconTheme; children: React.ReactNode }> = ({
  theme,
  children
}) => (
  <IconThemeContext.Provider value={theme}>
    {children}
  </IconThemeContext.Provider>
);

export const useIconTheme = () => {
  const theme = useContext(IconThemeContext);
  if (!theme) {
    throw new Error('useIconTheme must be used within IconThemeProvider');
  }
  return theme;
};

// Enhanced themed icon with context
export const ContextThemedIcon: React.FC<IconProps & {
  themeSize?: string;
  themeColor?: string;
  themeVariant?: string;
}> = ({
  themeSize,
  themeColor,
  themeVariant,
  size,
  color,
  ...props
}) => {
  const theme = useIconTheme();
  
  const resolvedSize = size ?? (themeSize ? theme.sizes[themeSize] : undefined);
  const resolvedColor = color ?? (themeColor ? theme.colors[themeColor] : undefined);
  
  const variantProps = themeVariant ? theme.variants[themeVariant] : {};
  
  return (
    <Icon
      {...variantProps}
      {...props}
      size={resolvedSize}
      color={resolvedColor}
    />
  );
};
```

### Performance Optimization Pattern

Lazy loading and caching strategies:

```typescript
// ui/foundation/Icon/LazyIcon.tsx
import React, { useState, useEffect, useMemo } from 'react';
import { IconProps } from './Icon';

interface LazyIconProps extends IconProps {
  fallback?: React.ReactNode;
  timeout?: number;
}

// Icon cache for performance
const iconCache = new Map<string, React.ComponentType>();

export const LazyIcon: React.FC<LazyIconProps> = ({
  name,
  library = 'auto',
  fallback = null,
  timeout = 5000,
  ...props
}) => {
  const [IconComponent, setIconComponent] = useState<React.ComponentType | null>(null);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState<string | null>(null);
  
  const cacheKey = `${library}-${name}`;
  
  useEffect(() => {
    let isMounted = true;
    
    // Check cache first
    if (iconCache.has(cacheKey)) {
      setIconComponent(() => iconCache.get(cacheKey)!);
      setLoading(false);
      return;
    }
    
    const loadIcon = async () => {
      try {
        setLoading(true);
        setError(null);
        
        let Component: React.ComponentType;
        
        if (library === 'custom') {
          const iconModule = await import(`../icons/custom/${name}Icon`);
          Component = iconModule.default;
        } else {
          // Handle vector icons or other types
          const { Icon } = await import('./Icon');
          Component = (componentProps: any) => <Icon {...componentProps} name={name} library={library} />;
        }
        
        if (isMounted) {
          iconCache.set(cacheKey, Component);
          setIconComponent(() => Component);
          setLoading(false);
        }
      } catch (err) {
        if (isMounted) {
          setError(`Failed to load icon: ${name}`);
          setLoading(false);
          console.warn(`LazyIcon: ${err}`);
        }
      }
    };
    
    // Add timeout
    const timeoutId = setTimeout(() => {
      if (isMounted && loading) {
        setError(`Timeout loading icon: ${name}`);
        setLoading(false);
      }
    }, timeout);
    
    loadIcon();
    
    return () => {
      isMounted = false;
      clearTimeout(timeoutId);
    };
  }, [cacheKey, name, library, timeout, loading]);
  
  if (loading) {
    return fallback;
  }
  
  if (error || !IconComponent) {
    console.warn(`LazyIcon error: ${error}`);
    return fallback;
  }
  
  return <IconComponent {...props} />;
};

// Preload utility for critical icons
export const preloadIcons = async (icons: Array<{name: string, library?: string}>) => {
  const promises = icons.map(async ({ name, library = 'custom' }) => {
    const cacheKey = `${library}-${name}`;
    
    if (iconCache.has(cacheKey)) {
      return; // Already cached
    }
    
    try {
      if (library === 'custom') {
        const iconModule = await import(`../icons/custom/${name}Icon`);
        iconCache.set(cacheKey, iconModule.default);
      }
    } catch (error) {
      console.warn(`Failed to preload icon ${name}:`, error);
    }
  });
  
  await Promise.allSettled(promises);
};
```

### Analytics Integration Pattern

Track icon usage for optimization insights:

```typescript
// ui/foundation/Icon/Analytics.tsx
import React from 'react';
import { Icon, IconProps } from './Icon';

interface AnalyticsIconProps extends IconProps {
  trackUsage?: boolean;
  category?: string;
}

class IconAnalytics {
  private static instance: IconAnalytics;
  private usageMap = new Map<string, number>();
  private lastReported = Date.now();
  
  static getInstance(): IconAnalytics {
    if (!IconAnalytics.instance) {
      IconAnalytics.instance = new IconAnalytics();
    }
    return IconAnalytics.instance;
  }
  
  trackIconUsage(name: string, library: string, category?: string) {
    const key = `${library}:${name}`;
    const currentCount = this.usageMap.get(key) || 0;
    this.usageMap.set(key, currentCount + 1);
    
    // Report every 10 minutes
    if (Date.now() - this.lastReported > 10 * 60 * 1000) {
      this.reportUsage();
      this.lastReported = Date.now();
    }
  }
  
  private reportUsage() {
    const usageData = Array.from(this.usageMap.entries())
      .map(([key, count]) => ({ icon: key, usage: count }))
      .sort((a, b) => b.usage - a.usage);
    
    // Send to analytics service
    console.log('Icon Usage Analytics:', usageData);
    
    // You could send this to your analytics service:
    // analyticsService.track('icon_usage', { icons: usageData });
  }
  
  getUsageReport() {
    return new Map(this.usageMap);
  }
  
  resetUsage() {
    this.usageMap.clear();
  }
}

export const AnalyticsIcon: React.FC<AnalyticsIconProps> = ({
  trackUsage = true,
  category,
  name,
  library = 'auto',
  ...props
}) => {
  React.useEffect(() => {
    if (trackUsage) {
      const analytics = IconAnalytics.getInstance();
      analytics.trackIconUsage(name, library || 'auto', category);
    }
  }, [name, library, trackUsage, category]);
  
  return <Icon {...props} name={name} library={library} />;
};

// Usage analytics hook
export const useIconAnalytics = () => {
  const analytics = IconAnalytics.getInstance();
  
  return {
    getUsageReport: () => analytics.getUsageReport(),
    resetUsage: () => analytics.resetUsage(),
  };
};
```

## Testing Patterns

### Component Testing Strategy

Comprehensive testing for icon components:

```typescript
// __tests__/Icon.patterns.test.ts
import React from 'react';
import { render, waitFor } from '@testing-library/react-native';
import { Icon } from '../Icon';
import { LazyIcon } from '../LazyIcon';
import { ThemedIcon } from '../ThemedIcon';
import { SemanticIcon } from '../SemanticIcon';

// Mock the icon registry
jest.mock('../registry', () => ({
  IconRegistry: {
    vector: {
      ionicons: {
        component: jest.fn(() => 'MockedVectorIcon'),
        map: { home: 'home-outline', search: 'search-outline' }
      }
    },
    custom: {
      'custom-icon': jest.fn(() => 'MockedCustomIcon')
    }
  }
}));

describe('Icon Implementation Patterns', () => {
  describe('Basic Icon Component', () => {
    it('renders vector icons correctly', () => {
      const { getByTestId } = render(
        <Icon name="home" library="vector" testID="vector-icon" />
      );
      
      expect(getByTestId('vector-icon')).toBeTruthy();
    });
    
    it('renders custom icons correctly', () => {
      const { getByTestId } = render(
        <Icon name="custom-icon" library="custom" testID="custom-icon" />
      );
      
      expect(getByTestId('custom-icon')).toBeTruthy();
    });
    
    it('auto-detects icon library', () => {
      const { getByTestId } = render(
        <Icon name="custom-icon" library="auto" testID="auto-icon" />
      );
      
      expect(getByTestId('auto-icon')).toBeTruthy();
    });
  });
  
  describe('Lazy Icon Component', () => {
    it('shows fallback while loading', async () => {
      const fallback = <div testID="fallback">Loading...</div>;
      
      const { getByTestId, queryByTestId } = render(
        <LazyIcon name="custom-icon" fallback={fallback} testID="lazy-icon" />
      );
      
      expect(getByTestId('fallback')).toBeTruthy();
      
      await waitFor(() => {
        expect(queryByTestId('fallback')).toBeNull();
      });
    });
    
    it('handles loading errors gracefully', async () => {
      const fallback = <div testID="error-fallback">Error</div>;
      
      const { getByTestId } = render(
        <LazyIcon name="non-existent" fallback={fallback} timeout={100} />
      );
      
      await waitFor(() => {
        expect(getByTestId('error-fallback')).toBeTruthy();
      }, { timeout: 200 });
    });
  });
  
  describe('Themed Icon Component', () => {
    const mockTheme = {
      iconSizes: { sm: 16, md: 24, lg: 32 },
      colors: {
        icon: {
          primary: '#007AFF',
          secondary: '#666666',
          disabled: '#CCCCCC'
        }
      }
    };
    
    it('applies theme sizes correctly', () => {
      const { getByTestId } = render(
        <ThemedIcon name="home" size="lg" testID="themed-icon" />
      );
      
      const icon = getByTestId('themed-icon');
      expect(icon.props.style).toEqual(
        expect.arrayContaining([
          expect.objectContaining({ width: 32, height: 32 })
        ])
      );
    });
    
    it('applies disabled state correctly', () => {
      const { getByTestId } = render(
        <ThemedIcon name="home" disabled testID="disabled-icon" />
      );
      
      expect(getByTestId('disabled-icon')).toBeTruthy();
    });
  });
});
```

### Registry Testing

Validate icon registry integrity:

```typescript
// __tests__/registry.test.ts
import { IconRegistry } from '../registry';
import * as customIcons from '../icons/custom';

describe('Icon Registry', () => {
  it('has valid vector icon mappings', () => {
    Object.entries(IconRegistry.vector).forEach(([library, config]) => {
      expect(config.component).toBeDefined();
      expect(config.map).toBeDefined();
      expect(Object.keys(config.map).length).toBeGreaterThan(0);
    });
  });
  
  it('has matching custom icon exports', () => {
    const registryIcons = Object.keys(IconRegistry.custom);
    const exportedIcons = Object.keys(customIcons);
    
    expect(registryIcons.sort()).toEqual(exportedIcons.sort());
  });
  
  it('validates semantic mappings', () => {
    // Test that all semantic mappings point to valid icons
    // This would depend on your semantic registry implementation
  });
});
```

## Deployment and Monitoring Patterns

### Bundle Analysis

Monitor icon bundle impact:

```javascript
// scripts/analyze-icon-bundle.js
const fs = require('fs');
const path = require('path');

class IconBundleAnalyzer {
  analyzeBundle() {
    const customIconsDir = 'ui/foundation/icons/custom';
    const stats = this.getIconStats(customIconsDir);
    
    console.log('📊 Icon Bundle Analysis');
    console.log('========================');
    console.log(`Total custom icons: ${stats.totalIcons}`);
    console.log(`Total size: ${this.formatBytes(stats.totalSize)}`);
    console.log(`Average size: ${this.formatBytes(stats.averageSize)}`);
    console.log(`Largest icon: ${stats.largestIcon.name} (${this.formatBytes(stats.largestIcon.size)})`);
    console.log(`Smallest icon: ${stats.smallestIcon.name} (${this.formatBytes(stats.smallestIcon.size)})`);
    
    if (stats.recommendationsCount > 0) {
      console.log(`\n💡 ${stats.recommendationsCount} optimization recommendations available`);
    }
  }
  
  getIconStats(dir) {
    const files = fs.readdirSync(dir)
      .filter(file => file.endsWith('.tsx'))
      .map(file => {
        const filePath = path.join(dir, file);
        const size = fs.statSync(filePath).size;
        return { name: file, size };
      });
    
    const totalSize = files.reduce((sum, file) => sum + file.size, 0);
    const largestIcon = files.reduce((max, file) => file.size > max.size ? file : max);
    const smallestIcon = files.reduce((min, file) => file.size < min.size ? file : min);
    
    return {
      totalIcons: files.length,
      totalSize,
      averageSize: totalSize / files.length,
      largestIcon,
      smallestIcon,
      recommendationsCount: files.filter(f => f.size > 10000).length // Files > 10KB
    };
  }
  
  formatBytes(bytes) {
    if (bytes === 0) return '0 Bytes';
    const k = 1024;
    const sizes = ['Bytes', 'KB', 'MB'];
    const i = Math.floor(Math.log(bytes) / Math.log(k));
    return parseFloat((bytes / Math.pow(k, i)).toFixed(2)) + ' ' + sizes[i];
  }
}

if (require.main === module) {
  const analyzer = new IconBundleAnalyzer();
  analyzer.analyzeBundle();
}
```

## Related Documents

* [Vector Icons Guide](/docs/ui-development/assets/icon-management/vector-icons-guide) - Foundation patterns for vector libraries
* [Custom Icons Guide](/docs/ui-development/assets/icon-management/custom-icons-guide) - SVG workflow and flat structure
* [Performance Optimization](/docs/ui-development/assets/icon-management/performance-optimization) - Advanced optimization techniques
* [Assets Management Guide](/docs/ui-development/assets/assets-management) - Brand assets and overall asset strategy


# UTA UI Development: Performance Optimization
URL: https://dev.updatetheapp.com/docs/ui-development/assets/icon-management/performance-optimization
Documentation: https://dev.updatetheapp.com/docs/ui-development/assets/icon-management/performance-optimization

Advanced performance optimization techniques for icon systems including bundle analysis, lazy loading, caching, and performance monitoring
        
***

title: Performance Optimization
description: Advanced performance optimization techniques for icon systems including bundle analysis, lazy loading, caching, and performance monitoring
-------------------------------------------------------------------------------------------------------------------------------------------------------

import { Tabs, Tab } from 'fumadocs-ui/components/tabs';
import { Callout } from 'fumadocs-ui/components/callout';

# Icon Performance Optimization

## Overview

Icon performance significantly impacts app startup time and memory usage. This guide covers optimization strategies from bundle analysis to runtime performance monitoring, ensuring your icon system scales efficiently.

## Bundle Size Optimization

### Import Analysis and Tree Shaking

<Callout type="info">
  **Bundle Impact**: Improper icon imports can increase bundle size by 50-200KB per icon library.
</Callout>

```typescript
// ❌ BAD: Imports entire icon library
import * as Icons from '@expo/vector-icons/Ionicons';
import * as CustomIcons from '@/ui/foundation/icons/custom';

// ✅ GOOD: Import specific icons only
import { Home, Search, Profile } from '@expo/vector-icons/Ionicons';
import { ArrowLeftIcon, MenuIcon } from '@/ui/foundation/icons/custom';

// ✅ GOOD: Dynamic imports for better code splitting
const LazyIcon = React.lazy(() => import('@/ui/foundation/icons/custom/ComplexIcon'));
```

### Metro Bundle Analyzer Integration

```javascript
// metro.config.js
const { getDefaultConfig } = require('expo/metro-config');

const config = getDefaultConfig(__dirname);

// Enable bundle analysis in development
if (process.env.NODE_ENV === 'development') {
  config.transformer = {
    ...config.transformer,
    unstable_allowRequireContext: true,
  };
  
  // Add bundle size analysis
  config.serializer = {
    ...config.serializer,
    customSerializer: require('./scripts/bundle-analyzer'),
  };
}

module.exports = config;
```

### Custom Icon Bundle Analysis

```typescript
// scripts/icon-bundle-analyzer.ts
import { execSync } from 'child_process';
import fs from 'fs';
import path from 'path';

interface IconBundleStats {
  totalIcons: number;
  totalSize: number;
  averageSize: number;
  largestIcons: Array<{name: string; size: number}>;
  recommendations: string[];
}

export class IconBundleAnalyzer {
  private customIconsPath = 'ui/foundation/icons/custom';
  
  analyze(): IconBundleStats {
    const icons = this.scanCustomIcons();
    const stats = this.calculateStats(icons);
    const recommendations = this.generateRecommendations(icons, stats);
    
    return {
      ...stats,
      recommendations,
    };
  }
  
  private scanCustomIcons() {
    const iconFiles = fs.readdirSync(this.customIconsPath)
      .filter(file => file.endsWith('.tsx'))
      .map(file => {
        const filePath = path.join(this.customIconsPath, file);
        const content = fs.readFileSync(filePath, 'utf8');
        const size = Buffer.byteLength(content, 'utf8');
        
        return {
          name: file.replace('.tsx', ''),
          size,
          complexity: this.analyzeComplexity(content),
        };
      });
    
    return iconFiles;
  }
  
  private analyzeComplexity(content: string): 'low' | 'medium' | 'high' {
    const pathCount = (content.match(/<path/g) || []).length;
    const transformCount = (content.match(/transform/g) || []).length;
    
    if (pathCount > 10 || transformCount > 3) return 'high';
    if (pathCount > 5 || transformCount > 1) return 'medium';
    return 'low';
  }
  
  private generateRecommendations(icons: any[], stats: IconBundleStats): string[] {
    const recommendations = [];
    
    const largeIcons = icons.filter(icon => icon.size > 5000);
    if (largeIcons.length > 0) {
      recommendations.push(`Consider optimizing ${largeIcons.length} large icons (>5KB)`);
    }
    
    const complexIcons = icons.filter(icon => icon.complexity === 'high');
    if (complexIcons.length > 0) {
      recommendations.push(`Simplify ${complexIcons.length} complex icons for better performance`);
    }
    
    if (stats.totalIcons > 50) {
      recommendations.push('Consider implementing lazy loading for icons');
    }
    
    return recommendations;
  }
}
```

## Runtime Performance Optimization

### Icon Caching Strategy

```typescript
// ui/foundation/Icon/IconCache.ts
class IconCache {
  private static instance: IconCache;
  private cache = new Map<string, React.ComponentType>();
  private preloadQueue = new Set<string>();
  
  static getInstance(): IconCache {
    if (!IconCache.instance) {
      IconCache.instance = new IconCache();
    }
    return IconCache.instance;
  }
  
  get(key: string): React.ComponentType | null {
    return this.cache.get(key) || null;
  }
  
  set(key: string, component: React.ComponentType): void {
    this.cache.set(key, component);
    this.preloadQueue.delete(key);
  }
  
  async preload(iconNames: string[]): Promise<void> {
    const promises = iconNames
      .filter(name => !this.cache.has(name))
      .map(name => this.loadIcon(name));
    
    await Promise.allSettled(promises);
  }
  
  private async loadIcon(name: string): Promise<void> {
    try {
      const iconModule = await import(`../icons/custom/${name}Icon`);
      this.cache.set(name, iconModule.default);
    } catch (error) {
      console.warn(`Failed to preload icon: ${name}`);
    }
  }
  
  getCacheStats() {
    return {
      size: this.cache.size,
      memoryUsage: this.cache.size * 1024, // Rough estimate
      hitRate: this.calculateHitRate(),
    };
  }
  
  private calculateHitRate(): number {
    // Implementation depends on usage tracking
    return 0.85; // Placeholder
  }
}
```

### Lazy Loading Implementation

```typescript
// ui/foundation/Icon/LazyIcon.tsx
import React, { Suspense, useState, useEffect } from 'react';
import { View, ActivityIndicator } from 'react-native';
import { IconCache } from './IconCache';

interface LazyIconProps {
  name: string;
  size?: number;
  color?: string;
  fallback?: React.ReactNode;
  preload?: boolean;
}

export const LazyIcon: React.FC<LazyIconProps> = ({
  name,
  size = 24,
  color = 'currentColor',
  fallback,
  preload = false,
  ...props
}) => {
  const [Component, setComponent] = useState<React.ComponentType | null>(null);
  const cache = IconCache.getInstance();
  
  useEffect(() => {
    const cached = cache.get(name);
    if (cached) {
      setComponent(() => cached);
      return;
    }
    
    if (preload) {
      cache.preload([name]);
    }
    
    const loadComponent = async () => {
      try {
        const iconModule = await import(`../icons/custom/${name}Icon`);
        const LoadedComponent = iconModule.default;
        
        cache.set(name, LoadedComponent);
        setComponent(() => LoadedComponent);
      } catch (error) {
        console.warn(`Failed to load icon: ${name}`);
      }
    };
    
    loadComponent();
  }, [name, preload, cache]);
  
  const defaultFallback = (
    <View style={{ width: size, height: size, justifyContent: 'center', alignItems: 'center' }}>
      <ActivityIndicator size="small" color={color} />
    </View>
  );
  
  if (!Component) {
    return fallback || defaultFallback;
  }
  
  return <Component size={size} color={color} {...props} />;
};
```

### Memory Management

```typescript
// ui/foundation/Icon/MemoryManager.ts
export class IconMemoryManager {
  private static maxCacheSize = 100; // Maximum cached icons
  private static memoryThreshold = 50 * 1024 * 1024; // 50MB threshold
  
  static cleanup(): void {
    const cache = IconCache.getInstance();
    const stats = cache.getCacheStats();
    
    if (stats.memoryUsage > this.memoryThreshold) {
      this.performCleanup(cache);
    }
  }
  
  private static performCleanup(cache: IconCache): void {
    // Implement LRU cleanup strategy
    const usage = this.getUsageStats();
    const leastUsed = usage
      .sort((a, b) => a.lastUsed - b.lastUsed)
      .slice(0, Math.floor(cache.getCacheStats().size * 0.3));
    
    leastUsed.forEach(item => {
      cache.delete(item.name);
    });
    
    console.log(`Cleaned up ${leastUsed.length} cached icons`);
  }
  
  private static getUsageStats(): Array<{name: string; lastUsed: number}> {
    // Implementation depends on usage tracking
    return [];
  }
}
```

## Critical Icon Preloading

### App Startup Optimization

```typescript
// core/performance/IconPreloader.ts
export class IconPreloader {
  private static criticalIcons = [
    'home', 'search', 'profile', 'menu', 'back', 'close'
  ];
  
  static async preloadCriticalIcons(): Promise<void> {
    const startTime = performance.now();
    
    try {
      const cache = IconCache.getInstance();
      await cache.preload(this.criticalIcons);
      
      const duration = performance.now() - startTime;
      console.log(`Preloaded ${this.criticalIcons.length} icons in ${duration.toFixed(2)}ms`);
      
    } catch (error) {
      console.warn('Icon preloading failed:', error);
    }
  }
  
  static preloadForRoute(routeName: string): Promise<void> {
    const routeIcons = this.getRouteIcons(routeName);
    const cache = IconCache.getInstance();
    return cache.preload(routeIcons);
  }
  
  private static getRouteIcons(routeName: string): string[] {
    const routeIconMap: Record<string, string[]> = {
      'Home': ['home', 'notification', 'search'],
      'Profile': ['profile', 'edit', 'settings'],
      'Settings': ['settings', 'help', 'logout'],
      // Add more route mappings
    };
    
    return routeIconMap[routeName] || [];
  }
}

// App.tsx - Preload during app initialization
export default function App() {
  useEffect(() => {
    IconPreloader.preloadCriticalIcons();
  }, []);
  
  // ... rest of app
}
```

### Route-based Preloading

```typescript
// navigation/IconPreloadingNavigator.tsx
import { useEffect } from 'react';
import { useNavigation } from '@react-navigation/native';
import { IconPreloader } from '@/core/performance/IconPreloader';

export const useRouteIconPreloading = () => {
  const navigation = useNavigation();
  
  useEffect(() => {
    const unsubscribe = navigation.addListener('focus', (e) => {
      const routeName = e.target?.split('-')[0];
      if (routeName) {
        IconPreloader.preloadForRoute(routeName);
      }
    });
    
    return unsubscribe;
  }, [navigation]);
};
```

## Performance Monitoring

### Icon Performance Metrics

```typescript
// utils/IconPerformanceMonitor.ts
interface IconMetrics {
  loadTime: number;
  renderTime: number;
  cacheHit: boolean;
  iconName: string;
  size: number;
}

export class IconPerformanceMonitor {
  private static metrics: IconMetrics[] = [];
  private static maxMetrics = 1000;
  
  static measureIconLoad<T>(
    iconName: string,
    loadFn: () => Promise<T>
  ): Promise<T> {
    const startTime = performance.now();
    
    return loadFn().then(result => {
      const loadTime = performance.now() - startTime;
      
      this.recordMetric({
        iconName,
        loadTime,
        renderTime: 0,
        cacheHit: false,
        size: 0,
      });
      
      return result;
    });
  }
  
  static measureIconRender(iconName: string, renderFn: () => void): void {
    const startTime = performance.now();
    renderFn();
    const renderTime = performance.now() - startTime;
    
    this.recordMetric({
      iconName,
      loadTime: 0,
      renderTime,
      cacheHit: true,
      size: 0,
    });
  }
  
  private static recordMetric(metric: IconMetrics): void {
    this.metrics.push(metric);
    
    if (this.metrics.length > this.maxMetrics) {
      this.metrics = this.metrics.slice(-this.maxMetrics);
    }
  }
  
  static getPerformanceReport(): {
    averageLoadTime: number;
    averageRenderTime: number;
    cacheHitRate: number;
    slowestIcons: Array<{name: string; time: number}>;
  } {
    const loadTimes = this.metrics.map(m => m.loadTime);
    const renderTimes = this.metrics.map(m => m.renderTime);
    const cacheHits = this.metrics.filter(m => m.cacheHit).length;
    
    const slowestIcons = this.metrics
      .sort((a, b) => (b.loadTime + b.renderTime) - (a.loadTime + a.renderTime))
      .slice(0, 10)
      .map(m => ({ name: m.iconName, time: m.loadTime + m.renderTime }));
    
    return {
      averageLoadTime: loadTimes.reduce((a, b) => a + b, 0) / loadTimes.length,
      averageRenderTime: renderTimes.reduce((a, b) => a + b, 0) / renderTimes.length,
      cacheHitRate: cacheHits / this.metrics.length,
      slowestIcons,
    };
  }
}
```

### Development Performance Tools

```typescript
// tools/IconDebugger.tsx
import React, { useState, useEffect } from 'react';
import { View, Text, Button, ScrollView } from 'react-native';
import { IconPerformanceMonitor } from '@/utils/IconPerformanceMonitor';
import { IconCache } from '@/ui/foundation/Icon/IconCache';

export const IconDebugger: React.FC = () => {
  const [report, setReport] = useState<any>(null);
  const [cacheStats, setCacheStats] = useState<any>(null);
  
  useEffect(() => {
    updateStats();
    const interval = setInterval(updateStats, 5000);
    return () => clearInterval(interval);
  }, []);
  
  const updateStats = () => {
    setReport(IconPerformanceMonitor.getPerformanceReport());
    setCacheStats(IconCache.getInstance().getCacheStats());
  };
  
  const clearCache = () => {
    IconCache.getInstance().clear();
    updateStats();
  };
  
  if (!__DEV__) return null;
  
  return (
    <View style={{ padding: 20, backgroundColor: '#f0f0f0' }}>
      <Text style={{ fontSize: 18, fontWeight: 'bold' }}>Icon Performance</Text>
      
      {report && (
        <View style={{ marginTop: 10 }}>
          <Text>Avg Load Time: {report.averageLoadTime?.toFixed(2)}ms</Text>
          <Text>Avg Render Time: {report.averageRenderTime?.toFixed(2)}ms</Text>
          <Text>Cache Hit Rate: {(report.cacheHitRate * 100)?.toFixed(1)}%</Text>
        </View>
      )}
      
      {cacheStats && (
        <View style={{ marginTop: 10 }}>
          <Text>Cached Icons: {cacheStats.size}</Text>
          <Text>Memory Usage: ~{(cacheStats.memoryUsage / 1024).toFixed(1)}KB</Text>
        </View>
      )}
      
      <Button title="Clear Cache" onPress={clearCache} />
      
      {report?.slowestIcons && (
        <ScrollView style={{ maxHeight: 200, marginTop: 10 }}>
          <Text style={{ fontWeight: 'bold' }}>Slowest Icons:</Text>
          {report.slowestIcons.map((icon: any, index: number) => (
            <Text key={index}>{icon.name}: {icon.time.toFixed(2)}ms</Text>
          ))}
        </ScrollView>
      )}
    </View>
  );
};
```

## Production Optimization Strategies

### Build-time Optimization

```javascript
// scripts/optimize-icons-build.js
const fs = require('fs');
const path = require('path');
const svgo = require('svgo');

class BuildTimeIconOptimizer {
  constructor() {
    this.svgoConfig = {
      plugins: [
        'preset-default',
        'removeDoctype',
        'removeComments',
        'removeMetadata',
        'removeViewBox',
        'removeDimensions',
      ],
    };
  }
  
  async optimizeForProduction() {
    const iconsDir = 'ui/foundation/icons/custom';
    const files = fs.readdirSync(iconsDir)
      .filter(file => file.endsWith('.tsx'));
    
    console.log(`Optimizing ${files.length} icons for production...`);
    
    for (const file of files) {
      await this.optimizeIconFile(path.join(iconsDir, file));
    }
    
    console.log('Icon optimization complete!');
  }
  
  async optimizeIconFile(filePath) {
    const content = fs.readFileSync(filePath, 'utf8');
    
    // Extract SVG content
    const svgMatch = content.match(/<svg[^>]*>.*?<\/svg>/s);
    if (!svgMatch) return;
    
    const optimizedSvg = await svgo.optimize(svgMatch[0], this.svgoConfig);
    const optimizedContent = content.replace(svgMatch[0], optimizedSvg.data);
    
    fs.writeFileSync(filePath, optimizedContent);
  }
}

if (require.main === module) {
  const optimizer = new BuildTimeIconOptimizer();
  optimizer.optimizeForProduction();
}
```

### Runtime Performance Best Practices

<Tabs items={["Do's", "Don'ts"]}>
  <Tab>
    ```typescript
    // ✅ GOOD: Efficient icon usage patterns

    // 1. Use memoization for expensive icons
    const MemoizedIcon = React.memo(Icon);

    // 2. Preload critical icons at app start
    useEffect(() => {
      IconPreloader.preloadCriticalIcons();
    }, []);

    // 3. Use appropriate sizes
    <Icon name="home" size={24} /> // Standard size
    <Icon name="hero" size={48} />  // Larger for hero sections

    // 4. Implement proper caching
    const iconCache = IconCache.getInstance();

    // 5. Monitor performance in development
    if (__DEV__) {
      IconPerformanceMonitor.measureIconRender('home', renderIcon);
    }
    ```
  </Tab>

  <Tab>
    ```typescript
    // ❌ BAD: Performance anti-patterns

    // 1. Don't import entire icon libraries
    import * as Icons from '@expo/vector-icons/Ionicons';

    // 2. Don't create icons in render loops
    icons.map(name => <Icon key={name} name={name} />); // Use keys properly

    // 3. Don't use oversized icons
    <Icon name="small-indicator" size={200} /> // Wasteful

    // 4. Don't ignore memory management
    // Always implement cache cleanup for long-running apps

    // 5. Don't block the main thread
    // Use lazy loading for non-critical icons
    ```
  </Tab>
</Tabs>

## Testing Performance

### Performance Test Suite

```typescript
// __tests__/icon-performance.test.ts
import { IconPerformanceMonitor } from '@/utils/IconPerformanceMonitor';
import { IconCache } from '@/ui/foundation/Icon/IconCache';
import { render } from '@testing-library/react-native';
import { Icon } from '@/ui/foundation/Icon/Icon';

describe('Icon Performance', () => {
  beforeEach(() => {
    IconCache.getInstance().clear();
  });
  
  it('should load icons within performance thresholds', async () => {
    const startTime = performance.now();
    
    const { findByTestId } = render(
      <Icon name="home" testID="performance-icon" />
    );
    
    await findByTestId('performance-icon');
    const loadTime = performance.now() - startTime;
    
    expect(loadTime).toBeLessThan(100); // Should load within 100ms
  });
  
  it('should cache icons effectively', async () => {
    const cache = IconCache.getInstance();
    
    // First load
    await cache.preload(['home']);
    const firstStats = cache.getCacheStats();
    
    // Second access should be from cache
    const cachedIcon = cache.get('home');
    
    expect(cachedIcon).toBeTruthy();
    expect(firstStats.size).toBe(1);
  });
  
  it('should handle memory cleanup', () => {
    const cache = IconCache.getInstance();
    
    // Fill cache
    for (let i = 0; i < 150; i++) {
      cache.set(`icon-${i}`, jest.fn());
    }
    
    // Trigger cleanup
    IconMemoryManager.cleanup();
    
    const stats = cache.getCacheStats();
    expect(stats.size).toBeLessThan(150); // Should have cleaned up
  });
});
```

## Related Documents

* [Vector Icons Guide](/docs/ui-development/assets/icon-management/vector-icons-guide) - Foundation for vector libraries
* [Custom Icons Guide](/docs/ui-development/assets/icon-management/custom-icons-guide) - SVG workflow and optimization
* [Implementation Patterns](/docs/ui-development/assets/icon-management/implementation-patterns) - Advanced architectural patterns


# UTA UI Development: Splash Screen Guide
URL: https://dev.updatetheapp.com/docs/ui-development/splash-screens
Documentation: https://dev.updatetheapp.com/docs/ui-development/splash-screens

A comprehensive guide for implementing and managing splash screens in React Native applications
        
***

title: Splash Screen Guide
description: A comprehensive guide for implementing and managing splash screens in React Native applications
------------------------------------------------------------------------------------------------------------

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Callout } from 'fumadocs-ui/components/callout';

# Splash Screen Guide

## Introduction

A splash screen is a temporary UI element displayed immediately when an app is launched, providing immediate visual feedback to users while the app initializes. Beyond being a mere loading screen, a well-designed splash screen serves several important purposes:

* **Improves perceived performance** by giving immediate visual feedback
* **Strengthens brand identity** by prominently displaying logos and brand colors
* **Bridges the gap** between the user tapping your app icon and the app becoming interactive
* **Masks initialization complexity** with a simple, elegant screen

In our initialization architecture, the splash screen plays a crucial role during the Pre-UI stage when critical initializations occur before any React components are rendered.

<Callout type="info">
  **Key Integration Point**

  The splash screen is managed by our initialization system and should remain visible until the Pre-UI stage completes. This ensures users see a smooth transition from splash screen to your app content.
</Callout>

## Choosing a Library

Several libraries are available for implementing splash screens in React Native. We recommend using **react-native-bootsplash** for its reliability, features, and performance.

<Tabs items={["react-native-bootsplash", "expo-splash-screen", "Other Options"]}>
  <Tab>
    [react-native-bootsplash](https://github.com/zoontek/react-native-bootsplash) is our recommended solution because it offers:

    * **Native implementation** for both iOS and Android
    * **Asset generation CLI** to automate resource creation
    * **Customizable transitions** with fade durations
    * **Progress reporting API** for initialization feedback
    * **Storyboard support** for iOS
    * **Android 12+ compatibility** with the new SplashScreen API
    * **Excellent TypeScript support**

    The library provides a clean API that aligns perfectly with our initialization architecture.
  </Tab>

  <Tab>
    [expo-splash-screen](https://docs.expo.dev/versions/latest/sdk/splash-screen/) is the standard solution for Expo-based applications, offering:

    * **Seamless integration** with Expo projects
    * **Config-based setup** via app.json
    * **Auto-hiding prevention** to control hiding programmatically
    * **Simple API** with preventAutoHideAsync() and hideAsync()
    * **Support for managed and bare workflows**

    While it works well in Expo environments, it has fewer customization options compared to react-native-bootsplash.
  </Tab>

  <Tab>
    Other options include:

    * **React Native's built-in LaunchScreen** (iOS) / **SplashScreen** (Android): Basic functionality but requires manual setup and lacks unified API
    * **react-native-splash-screen**: An older but stable library, with less frequent updates
    * **Custom implementation**: Creating splash screens directly in native code for maximum customization

    These alternatives may be suitable for specific requirements but generally offer fewer features and convenience compared to our recommended options.
  </Tab>
</Tabs>

## Guide Sections

This comprehensive guide is organized into focused sections:

### 📱 [Platform Implementation](/docs/ui-development/splash-screens/platform-implementation)

Native setup and configuration for iOS and Android platforms, including:

* iOS Storyboard configuration
* Android drawable and theme setup
* Platform-specific best practices
* Handling different Android versions

### 🎨 [Design & Assets](/docs/ui-development/splash-screens/design-assets)

Creating and optimizing splash screen assets:

* Asset generation with CLI tools
* Supporting light/dark modes
* Image optimization techniques
* Resolution and sizing guidelines

### 🔄 [Integration with App Initialization](/docs/ui-development/splash-screens/initialization-integration)

Seamlessly integrating splash screens with the app initialization flow:

* Pre-UI stage coordination
* Progress reporting during initialization
* Custom loading screens
* Error handling strategies

### 🏢 [White-Label Support](/docs/ui-development/splash-screens/white-label-support)

Implementing splash screens for multi-brand applications:

* Build-time vs runtime configuration
* Brand asset management
* Dynamic brand selection
* Hybrid approaches

### 🛠️ [Advanced Topics](/docs/ui-development/splash-screens/advanced-topics)

Advanced implementations and customizations:

* Custom animations
* Progress indicators
* Abstracting functionality
* Performance optimization

## Quick Start

For a basic implementation:

1. **Install the library**:
   ```bash
   npm install react-native-bootsplash
   cd ios && pod install
   ```

2. **Generate assets**:
   ```bash
   npx react-native-bootsplash generate \
     --assets-path=assets/splash \
     --background-color="#FFFFFF" \
     --logo-width=100 \
     path/to/your/logo.png
   ```

3. **Configure platforms**: See [Platform Implementation](/docs/ui-development/splash-screens/platform-implementation)

4. **Integrate with initialization**: See [Integration Guide](/docs/ui-development/splash-screens/initialization-integration)

## Summary

A well-implemented splash screen enhances user experience by providing immediate visual feedback during app initialization. By following the patterns in this guide, you can create professional, performant splash screens that integrate seamlessly with our initialization architecture.

Key principles to remember:

* Keep splash screens simple and brand-focused
* Use our SplashScreen abstraction for library flexibility
* Hide the splash screen after Pre-UI initialization completes
* Support both light and dark modes
* Optimize assets for performance
* Test across multiple devices and platforms

## Related Documents

* [App Initialization Architecture](/docs/architecture/app-initialization) - Overview of the app initialization process
* [Pre-UI Initialization Guide](/docs/guides/app-initialization/pre-ui-initialization-guide) - Details on the critical initialization stage
* [Theme Management](/docs/ui-development/theme-management) - Guide for implementing theming with white-label support
* [iOS Launch Sequence](https://developer.apple.com/documentation/uikit/about-the-app-launch-sequence) - Apple's official documentation
* [Android Splash Screen](https://developer.android.com/develop/ui/views/launch/splash-screen) - Android's official documentation


# UTA UI Development: Platform Implementation
URL: https://dev.updatetheapp.com/docs/ui-development/splash-screens/platform-implementation
Documentation: https://dev.updatetheapp.com/docs/ui-development/splash-screens/platform-implementation

Native setup and configuration for iOS and Android splash screens
        
***

title: Platform Implementation
description: Native setup and configuration for iOS and Android splash screens
------------------------------------------------------------------------------

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Callout } from 'fumadocs-ui/components/callout';
import { Steps, Step } from 'fumadocs-ui/components/steps';

# Platform Implementation

## Overview

Setting up splash screens requires platform-specific configuration for both iOS and Android. This guide provides detailed instructions for each platform, ensuring your splash screen displays correctly across all devices and OS versions.

<Callout type="warning">
  **Platform Differences**

  iOS and Android handle splash screens differently:

  * **iOS**: Uses Storyboard files for launch screens
  * **Android**: Uses drawable resources and themes (with special handling for Android 12+)
</Callout>

## iOS Configuration

iOS uses Storyboard files for splash screens, which offers flexibility in layout and automatic handling of different device sizes.

<Steps>
  <Step>
    #### Install Dependencies

    After installing react-native-bootsplash, install iOS pods:

    ```bash
    cd ios && pod install
    ```
  </Step>

  <Step>
    #### Generate Assets

    Use the CLI tool to generate iOS-specific assets:

    ```bash
    npx react-native-bootsplash generate \
      --assets-path=assets/splash \
      --background-color="#FFFFFF" \
      --logo-width=100 \
      --flavor=main \
      path/to/your/logo.png
    ```

    This creates the necessary image assets and Storyboard files.
  </Step>

  <Step>
    #### Configure Xcode Project

    1. **Open iOS project in Xcode** (`ios/YourProject.xcworkspace`)
    2. **Set Launch Screen File** in project settings:
       * Select your project in the Project Navigator
       * Go to "General" tab > "App Icons and Launch Screen"
       * Set "Launch Screen File" to "BootSplash" (created by the generator)
  </Step>

  <Step>
    #### Update Info.plist

    Add or update these entries in `ios/YourProject/Info.plist`:

    ```xml
    <key>UILaunchStoryboardName</key>
    <string>BootSplash</string>

    <!-- For dark mode support -->
    <key>UIUserInterfaceStyle</key>
    <string>Automatic</string>
    ```
  </Step>

  <Step>
    #### Configure AppDelegate

    Update `ios/YourProject/AppDelegate.mm` to show the splash screen:

    ```objc
    #import "RNBootSplash.h"

    - (BOOL)application:(UIApplication *)application 
        didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
    {
      // ... existing code ...
      
      // Initialize and show splash screen
      [RNBootSplash initWithStoryboard:@"BootSplash" rootView:self.window.rootViewController.view];
      
      return YES;
    }
    ```
  </Step>
</Steps>

### iOS Customization Options

#### Custom Storyboard Layout

You can customize the generated Storyboard for more complex layouts:

1. Open `BootSplash.storyboard` in Xcode
2. Add additional UI elements (labels, secondary images, etc.)
3. Use Auto Layout constraints for proper positioning
4. Test on different device sizes using the preview

#### Dark Mode Support

To support dark mode with different assets:

1. Create separate image sets for light and dark appearances
2. In Xcode, select your image asset
3. In the Attributes Inspector, change "Appearances" to "Any, Dark"
4. Add appropriate images for each appearance

### iOS Troubleshooting

<Tabs items={["Black Screen", "Wrong Size", "Not Showing"]}>
  <Tab>
    **Issue**: Black screen appears instead of splash screen

    **Solutions**:

    * Ensure `UILaunchStoryboardName` is correctly set in Info.plist
    * Verify the Storyboard file is included in the build target
    * Check that image assets are properly linked
    * Clean build folder and rebuild: `Product > Clean Build Folder`
  </Tab>

  <Tab>
    **Issue**: Splash screen appears stretched or wrong size

    **Solutions**:

    * Check Auto Layout constraints in the Storyboard
    * Ensure image content mode is set to "Aspect Fit" or "Aspect Fill"
    * Verify you're using the correct image resolutions (@1x, @2x, @3x)
    * Test on different device simulators
  </Tab>

  <Tab>
    **Issue**: Splash screen not showing at all

    **Solutions**:

    * Verify AppDelegate initialization code is present
    * Check that RNBootSplash pod is properly installed
    * Ensure you're not calling `hide()` too early
    * Look for any native crash logs in Xcode console
  </Tab>
</Tabs>

## Android Configuration

Android splash screen implementation varies based on the Android version, with Android 12+ introducing a new SplashScreen API.

<Steps>
  <Step>
    #### Generate Assets

    Run the asset generator for Android:

    ```bash
    npx react-native-bootsplash generate \
      --assets-path=assets/splash \
      --background-color="#FFFFFF" \
      --logo-width=100 \
      --flavor=main \
      path/to/your/logo.png
    ```
  </Step>

  <Step>
    #### Update MainActivity

    Modify `android/app/src/main/java/.../MainActivity.java`:

    <Tabs items={["Java", "Kotlin"]}>
      <Tab>
        ```java
        import com.zoontek.rnbootsplash.RNBootSplash;
        import android.os.Bundle;

        public class MainActivity extends ReactActivity {
          @Override
          protected void onCreate(Bundle savedInstanceState) {
            RNBootSplash.init(this); // Initialize splash screen
            super.onCreate(null); // Pass null to fix white flash
          }
        }
        ```
      </Tab>

      <Tab>
        ```kotlin
        import com.zoontek.rnbootsplash.RNBootSplash
        import android.os.Bundle

        class MainActivity : ReactActivity() {
          override fun onCreate(savedInstanceState: Bundle?) {
            RNBootSplash.init(this) // Initialize splash screen
            super.onCreate(null) // Pass null to fix white flash
          }
        }
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step>
    #### Configure styles.xml

    Update `android/app/src/main/res/values/styles.xml`:

    ```xml
    <resources>
      <!-- Base application theme -->
      <style name="AppTheme" parent="Theme.AppCompat.DayNight.NoActionBar">
        <!-- Your app theme customizations -->
      </style>
      
      <!-- BootSplash theme -->
      <style name="BootTheme" parent="Theme.BootSplash">
        <item name="bootSplashBackground">@color/bootsplash_background</item>
        <item name="bootSplashLogo">@drawable/bootsplash_logo</item>
        <item name="postBootSplashTheme">@style/AppTheme</item>
      </style>
    </resources>
    ```
  </Step>

  <Step>
    #### Update AndroidManifest.xml

    Apply the BootTheme to MainActivity:

    ```xml
    <activity
      android:name=".MainActivity"
      android:label="@string/app_name"
      android:configChanges="keyboard|keyboardHidden|orientation|screenLayout|screenSize|smallestScreenSize|uiMode"
      android:launchMode="singleTask"
      android:windowSoftInputMode="adjustResize"
      android:exported="true"
      android:theme="@style/BootTheme">
      <!-- ... intent filters ... -->
    </activity>
    ```
  </Step>
</Steps>

### Android 12+ Specific Configuration

Android 12 introduced a new SplashScreen API with specific requirements:

<Callout type="info">
  **Android 12 Requirements**

  * Splash screens are mandatory on Android 12+
  * The system enforces specific design constraints
  * Custom animations are limited compared to earlier versions
</Callout>

#### Additional Configuration for Android 12+

1. **Update `styles.xml` for Android 12+** (create `values-v31/styles.xml`):
   ```xml
   <resources>
     <style name="BootTheme" parent="Theme.BootSplash">
       <item name="android:windowSplashScreenBackground">@color/bootsplash_background</item>
       <item name="android:windowSplashScreenAnimatedIcon">@drawable/bootsplash_logo</item>
       <item name="android:windowSplashScreenAnimationDuration">200</item>
       <item name="postBootSplashTheme">@style/AppTheme</item>
     </style>
   </resources>
   ```

2. **Handle the splash screen duration**:
   ```java
   // In MainActivity.java
   @Override
   protected void onCreate(Bundle savedInstanceState) {
     // Keep splash screen visible while app loads
     if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) {
       getSplashScreen().setKeepOnScreenCondition(() -> true);
     }
     
     RNBootSplash.init(this);
     super.onCreate(null);
   }
   ```

### Dark Mode Support for Android

To support dark mode on Android:

1. **Create dark mode colors** (`values-night/colors.xml`):
   ```xml
   <resources>
     <color name="bootsplash_background">#121212</color>
   </resources>
   ```

2. **Provide dark mode drawable** if needed:
   * Place dark mode logo in `drawable-night-*dpi` folders
   * Or use vector drawables with theme colors

### Android Troubleshooting

<Tabs items={["White Flash", "Not Centered", "Crashes"]}>
  <Tab>
    **Issue**: White flash appears before splash screen

    **Solutions**:

    * Ensure `super.onCreate(null)` passes null parameter
    * Set `android:windowDisablePreview` to true in theme
    * Check that theme is properly applied in AndroidManifest.xml
    * Verify background color matches your splash screen
  </Tab>

  <Tab>
    **Issue**: Logo not centered or wrong size

    **Solutions**:

    * Regenerate assets with correct `--logo-width` parameter
    * Check drawable resources are in correct density folders
    * For Android 12+, verify windowSplashScreenAnimatedIcon size
    * Use vector drawables for better scaling
  </Tab>

  <Tab>
    **Issue**: App crashes on launch

    **Solutions**:

    * Check logcat for specific error messages
    * Verify RNBootSplash is properly linked
    * Ensure MainActivity imports are correct
    * Clean and rebuild: `cd android && ./gradlew clean`
  </Tab>
</Tabs>

## Platform-Specific Best Practices

### iOS Best Practices

* **(Do ✅) Use vector images (PDF) when possible** for better scaling
* **(Do ✅) Test on all device sizes** including iPad if supported
* **(Do ✅) Keep Storyboard simple** to avoid loading delays
* **(Don't ❌) Include text in images** - use Storyboard labels for localization
* **(Consider 🤔) Using SF Symbols** for system-consistent icons

### Android Best Practices

* **(Do ✅) Use vector drawables** for logos when possible
* **(Do ✅) Test on Android 12+ devices** for new API compliance
* **(Do ✅) Provide all density resources** (mdpi, hdpi, xhdpi, xxhdpi, xxxhdpi)
* **(Don't ❌) Use large bitmap images** that could cause OOM errors
* **(Be Aware ❗) Of status bar handling** - it may overlay your content

## Testing Your Implementation

### iOS Testing Checklist

* [ ] Test on iPhone SE (smallest screen)
* [ ] Test on iPhone Pro Max (largest screen)
* [ ] Test on iPad (if supported)
* [ ] Verify landscape orientation (if supported)
* [ ] Check dark mode appearance
* [ ] Verify no layout shifts during transition

### Android Testing Checklist

* [ ] Test on Android 8 (API 26)
* [ ] Test on Android 12+ (API 31+)
* [ ] Test on small screen devices
* [ ] Test on tablets (if supported)
* [ ] Verify dark mode appearance
* [ ] Check different aspect ratios (16:9, 18:9, 19:9)

## Summary

Platform-specific implementation requires attention to detail and thorough testing. Key takeaways:

* **iOS**: Focus on Storyboard configuration and Auto Layout
* **Android**: Handle version differences, especially Android 12+
* **Both**: Support dark mode and test on various devices
* **Assets**: Use appropriate formats and resolutions
* **Testing**: Verify on real devices when possible

## Next Steps

* Configure [Design & Assets](/docs/ui-development/splash-screens/design-assets) for optimal visual quality
* Set up [Integration with App Initialization](/docs/ui-development/splash-screens/initialization-integration)
* Explore [White-Label Support](/docs/ui-development/splash-screens/white-label-support) for multi-brand apps

## Related Documents

* [react-native-bootsplash Documentation](https://github.com/zoontek/react-native-bootsplash)
* [iOS Human Interface Guidelines - Launch Screen](https://developer.apple.com/design/human-interface-guidelines/ios/visual-design/launch-screen/)
* [Android Splash Screen Guidelines](https://developer.android.com/develop/ui/views/launch/splash-screen)


# UTA UI Development: Design & Assets
URL: https://dev.updatetheapp.com/docs/ui-development/splash-screens/design-assets
Documentation: https://dev.updatetheapp.com/docs/ui-development/splash-screens/design-assets

Creating and optimizing splash screen assets for professional appearance across all devices
        
***

title: Design & Assets
description: Creating and optimizing splash screen assets for professional appearance across all devices
--------------------------------------------------------------------------------------------------------

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Callout } from 'fumadocs-ui/components/callout';
import { Steps, Step } from 'fumadocs-ui/components/steps';

# Design & Assets

## Overview

Creating effective splash screen assets requires careful consideration of design principles, technical constraints, and platform differences. This guide covers everything you need to create professional splash screens that look great on all devices.

<Callout type="info">
  **Asset Quality Matters**

  Your splash screen is often the first visual element users see. High-quality, properly optimized assets ensure:

  * Professional first impression
  * Fast loading times
  * Crisp appearance on all screen densities
  * Proper scaling across device sizes
</Callout>

## Design Principles

### Simplicity

* **(Do ✅) Keep the design minimal and brand-focused**
  * Display only essential elements (logo, brand name, etc.)
  * Avoid complex animations that extend display time
  * Focus on visual identity rather than functionality

* **(Don't ❌) Add interactive elements or complex layouts**
  * The splash screen is temporary by design
  * Avoid overwhelming users with information
  * Remember it's a loading indicator, not a feature screen

### Visual Hierarchy

<Steps>
  <Step>
    #### Primary Element

    Your logo or brand icon should be the focal point:

    * Center it on the screen
    * Size it appropriately (typically 100-150dp)
    * Ensure adequate padding from screen edges
  </Step>

  <Step>
    #### Secondary Elements (Optional)

    If including additional elements:

    * Brand name or tagline below the logo
    * Keep text minimal and readable
    * Maintain visual balance
  </Step>

  <Step>
    #### Background

    Choose a background that complements your brand:

    * Solid colors work best
    * Avoid complex patterns or gradients
    * Consider both light and dark modes
  </Step>
</Steps>

## Asset Requirements

### Image Formats

<Tabs items={["Recommended Formats", "Platform Specifics", "Vector vs Raster"]}>
  <Tab>
    **PNG** (Recommended for most cases)

    * Supports transparency
    * Lossless compression
    * Wide compatibility
    * Good for logos with solid colors

    **SVG** (For vector graphics)

    * Scalable without quality loss
    * Smaller file sizes
    * Not directly supported on all platforms
    * Convert to PNG for final assets

    **PDF** (iOS vector format)

    * Native vector support on iOS
    * Automatically scales for different devices
    * Requires conversion for Android
  </Tab>

  <Tab>
    **iOS Requirements**

    * Formats: PNG or PDF (vector)
    * Resolutions: @1x, @2x, @3x
    * Transparency: Supported
    * Recommended: Use PDF for logos

    **Android Requirements**

    * Formats: PNG or WebP
    * Densities: mdpi, hdpi, xhdpi, xxhdpi, xxxhdpi
    * Vector: Use SVG converted to Vector Drawable
    * 9-patch: Supported for stretchable areas
  </Tab>

  <Tab>
    **When to Use Vector**

    * Simple logos with solid colors
    * Geometric shapes
    * Text-based logos
    * When file size is critical

    **When to Use Raster (PNG)**

    * Complex illustrations
    * Photographic elements
    * Gradients or effects
    * When vector conversion is problematic
  </Tab>
</Tabs>

### Size Guidelines

The react-native-bootsplash CLI uses a base logo width that scales appropriately:

```bash
npx react-native-bootsplash generate \
  --assets-path=assets/splash \
  --background-color="#FFFFFF" \
  --logo-width=100 \  # Base width in dp/pt
  path/to/your/logo.png
```

#### Recommended Logo Sizes

| Screen Size      | Logo Width | Use Case              |
| ---------------- | ---------- | --------------------- |
| Small (phones)   | 80-100dp   | Default for most apps |
| Medium (tablets) | 120-150dp  | Larger screens        |
| Large (branding) | 150-200dp  | Brand-focused apps    |

### Resolution Requirements

#### iOS Asset Resolutions

```
logo.png     (1x)  - 100 x 100 px
logo@2x.png  (2x)  - 200 x 200 px
logo@3x.png  (3x)  - 300 x 300 px
```

#### Android Density Buckets

```
drawable-mdpi/logo.png    (1x)   - 100 x 100 px
drawable-hdpi/logo.png    (1.5x) - 150 x 150 px
drawable-xhdpi/logo.png   (2x)   - 200 x 200 px
drawable-xxhdpi/logo.png  (3x)   - 300 x 300 px
drawable-xxxhdpi/logo.png (4x)   - 400 x 400 px
```

## Asset Generation

### Using the CLI Tool

The react-native-bootsplash CLI automates asset generation:

<Steps>
  <Step>
    #### Prepare Your Source Image

    * Use the highest resolution version available
    * PNG format with transparency (if needed)
    * Square aspect ratio works best
    * Minimum 1024x1024px recommended
  </Step>

  <Step>
    #### Run the Generator

    ```bash
    npx react-native-bootsplash generate \
      --assets-path=assets/splash \
      --background-color="#FFFFFF" \
      --logo-width=100 \
      --flavor=main \
      path/to/your/logo.png
    ```
  </Step>

  <Step>
    #### Verify Generated Assets

    Check the output directory for:

    * iOS: Multiple resolution variants
    * Android: Density-specific folders
    * Config files for both platforms
  </Step>
</Steps>

### CLI Options Explained

```bash
--assets-path      # Output directory for generated assets
--background-color # Hex color for splash background
--logo-width       # Base width in dp (iOS) / dp (Android)
--flavor           # Build flavor for white-label apps
--platforms        # Target platforms (ios, android, or both)
--dark-mode        # Generate dark mode variants
```

## Dark Mode Support

<Callout type="info">
  **Dark Mode Considerations**

  Many users prefer dark mode. Supporting it in your splash screen:

  * Provides consistency with system preferences
  * Reduces eye strain in low-light conditions
  * Shows attention to detail
</Callout>

### Implementation Strategies

<Tabs items={["Adaptive Logos", "Separate Assets", "Background Only"]}>
  <Tab>
    **Adaptive Logo Design**

    Create logos that work on both light and dark backgrounds:

    ```bash
    # Generate with transparent background
    npx react-native-bootsplash generate \
      --assets-path=assets/splash \
      --logo-width=100 \
      path/to/adaptive-logo.png
    ```

    Design tips:

    * Use colors that contrast well on both backgrounds
    * Add subtle outlines or shadows
    * Test visibility on various backgrounds
  </Tab>

  <Tab>
    **Separate Light/Dark Assets**

    Create distinct assets for each mode:

    ```bash
    # Light mode
    npx react-native-bootsplash generate \
      --assets-path=assets/splash/light \
      --background-color="#FFFFFF" \
      --logo-width=100 \
      path/to/logo-light.png

    # Dark mode
    npx react-native-bootsplash generate \
      --assets-path=assets/splash/dark \
      --background-color="#000000" \
      --logo-width=100 \
      path/to/logo-dark.png
    ```
  </Tab>

  <Tab>
    **Background Adaptation Only**

    Keep the same logo but change backgrounds:

    * Define light/dark background colors
    * Use a logo that works on both
    * Simpler implementation
    * May not be suitable for all brands
  </Tab>
</Tabs>

### Platform Implementation

#### iOS Dark Mode

```xml
<!-- In BootSplash.storyboard -->
<!-- Use system background color that adapts -->
<color key="backgroundColor" systemColor="systemBackgroundColor"/>
```

#### Android Dark Mode

```xml
<!-- values/colors.xml -->
<color name="bootsplash_background">#FFFFFF</color>

<!-- values-night/colors.xml -->
<color name="bootsplash_background">#000000</color>
```

## Optimization Techniques

### Image Optimization

<Steps>
  <Step>
    #### Compress PNG Files

    Use tools to reduce file size without quality loss:

    ```bash
    # Using imagemin
    npm install -g imagemin-cli imagemin-pngquant
    imagemin assets/splash/*.png --out-dir=assets/splash/optimized
    ```
  </Step>

  <Step>
    #### Convert to WebP (Android)

    For Android, WebP provides better compression:

    ```bash
    # Using cwebp
    cwebp -q 90 logo.png -o logo.webp
    ```
  </Step>

  <Step>
    #### Validate File Sizes

    Ensure optimized assets are reasonable:

    * Individual images: \< 100KB
    * Total splash assets: \< 500KB
    * Test loading performance
  </Step>
</Steps>

### Vector Optimization

For vector assets (SVG):

```bash
# Using SVGO
npm install -g svgo
svgo input.svg -o output.svg

# Common optimizations
svgo input.svg \
  --enable=removeViewBox \
  --enable=removeTitle \
  --enable=convertColors \
  -o output.svg
```

## Testing Your Assets

### Visual Testing Checklist

* [ ] Logo is clearly visible on all backgrounds
* [ ] No pixelation on high-density screens
* [ ] Proper scaling on different screen sizes
* [ ] Dark mode variants display correctly
* [ ] Loading time is acceptable (\< 0.5s)
* [ ] No visual artifacts or compression issues

### Device Testing Matrix

Test on these key devices:

| Platform | Device Type   | Screen Size | Density |
| -------- | ------------- | ----------- | ------- |
| iOS      | iPhone SE     | 4.7"        | @2x     |
| iOS      | iPhone 14 Pro | 6.1"        | @3x     |
| iOS      | iPad Pro      | 12.9"       | @2x     |
| Android  | Pixel 4a      | 5.8"        | xxhdpi  |
| Android  | Galaxy S23    | 6.1"        | xxxhdpi |
| Android  | Galaxy Tab    | 10.1"       | xhdpi   |

## Common Issues and Solutions

<Tabs items={["Blurry Images", "Wrong Colors", "Loading Issues"]}>
  <Tab>
    **Issue**: Logo appears blurry or pixelated

    **Solutions**:

    * Start with higher resolution source (min 1024x1024)
    * Use vector formats when possible
    * Ensure correct density assets are generated
    * Check image scaling method (use "contain" not "stretch")
    * Verify no compression artifacts
  </Tab>

  <Tab>
    **Issue**: Colors don't match brand guidelines

    **Solutions**:

    * Use exact hex values from brand guide
    * Check color space (sRGB recommended)
    * Test on actual devices (not just simulators)
    * Verify no color profile issues in images
    * Consider screen calibration differences
  </Tab>

  <Tab>
    **Issue**: Splash screen loads slowly

    **Solutions**:

    * Optimize image file sizes
    * Use appropriate formats (WebP for Android)
    * Remove unnecessary image metadata
    * Check total asset bundle size
    * Consider using solid colors instead of images
  </Tab>
</Tabs>

## Best Practices Summary

<Callout type="success">
  **Asset Creation Checklist**

  1. ✅ Design simple, brand-focused splash screens
  2. ✅ Use high-resolution source images (1024x1024+)
  3. ✅ Generate all required density variants
  4. ✅ Support both light and dark modes
  5. ✅ Optimize file sizes without quality loss
  6. ✅ Test on real devices across platforms
  7. ✅ Keep total asset size under 500KB
</Callout>

## Tools and Resources

### Design Tools

* **Figma/Sketch**: Design and export assets
* **Adobe Illustrator**: Vector logo creation
* **Affinity Designer**: Alternative vector tool

### Optimization Tools

* **ImageOptim**: Mac image optimization
* **TinyPNG**: Online PNG compression
* **SVGO**: SVG optimization

### Testing Tools

* **Xcode Simulators**: iOS device testing
* **Android Emulators**: Android device testing
* **Device farms**: Real device testing

## Next Steps

* Implement [Platform-Specific Setup](/docs/ui-development/splash-screens/platform-implementation)
* Configure [App Initialization Integration](/docs/ui-development/splash-screens/initialization-integration)
* Explore [White-Label Asset Management](/docs/ui-development/splash-screens/white-label-support)

## Related Documents

* [Material Design - Launch Screens](https://material.io/design/communication/launch-screen.html)
* [Human Interface Guidelines - Launch Screens](https://developer.apple.com/design/human-interface-guidelines/ios/visual-design/launch-screen/)
* [Image Optimization Guide](https://web.dev/fast/#optimize-your-images)


# UTA UI Development: Integration with App Initialization
URL: https://dev.updatetheapp.com/docs/ui-development/splash-screens/initialization-integration
Documentation: https://dev.updatetheapp.com/docs/ui-development/splash-screens/initialization-integration

Seamlessly integrating splash screens with the app initialization flow, including progress reporting
        
***

title: Integration with App Initialization
description: Seamlessly integrating splash screens with the app initialization flow, including progress reporting
-----------------------------------------------------------------------------------------------------------------

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Callout } from 'fumadocs-ui/components/callout';
import { Steps, Step } from 'fumadocs-ui/components/steps';

# Integration with App Initialization

## Overview

Properly integrating your splash screen with the app initialization process ensures a smooth user experience. The splash screen should remain visible during critical initialization tasks and hide only when your app is ready for interaction.

<Callout type="info">
  **Key Integration Principle**

  The splash screen serves as a visual bridge during the Pre-UI initialization stage. It should:

  * Remain visible until critical services are ready
  * Provide progress feedback for longer operations
  * Hide smoothly when the app is interactive
  * Handle errors gracefully
</Callout>

## Basic Integration

### Setting Up the Abstraction

First, create a splash screen abstraction to decouple your code from specific libraries:

```typescript
// core/shared/splash-screen/SplashScreen.ts
import RNBootSplash from 'react-native-bootsplash';

/**
 * Abstraction for splash screen functionality
 * This allows for easy switching between different splash screen implementations.
 */
export class SplashScreen {
  /**
   * Hide the splash screen with optional fade transition
   * @param options Configuration options for hiding
   */
  static hide(options: { fade?: boolean; duration?: number } = {}) {
    const { fade = true, duration = 500 } = options;
    return RNBootSplash.hide({ fade, duration });
  }

  /**
   * Show the splash screen (usually only needed in development)
   */
  static show() {
    return RNBootSplash.show();
  }

  /**
   * Check if splash screen is visible
   */
  static isVisible(): Promise<boolean> {
    return RNBootSplash.isVisible();
  }
}
```

### Integration Points

<Tabs items={["Expo Router", "React Navigation", "Custom Navigation"]}>
  <Tab>
    ```typescript
    // app/_layout.tsx (Expo Router)
    import { useEffect, useState } from 'react';
    import { initializer, InitStage } from '@/core/shared/app/initialization';
    import { SplashScreen } from '@/core/shared/splash-screen/SplashScreen';

    export default function RootLayout() {
      const [preUIComplete, setPreUIComplete] = useState(false);
      
      useEffect(() => {
        async function initializePreUI() {
          try {
            // Execute Pre-UI stage (critical, blocking)
            await initializer.executeStage(InitStage.PRE_UI);
            
            // Mark Pre-UI complete
            setPreUIComplete(true);
            
            // Hide splash screen with smooth fade
            await SplashScreen.hide({ fade: true, duration: 500 });
            
            // Continue with non-blocking stages
            initializer.executeStage(InitStage.INITIAL_UI).then(() => {
              initializer.executeParallelStage(InitStage.BACKGROUND).then(() => {
                initializer.executeStage(InitStage.FINALIZATION);
              });
            });
          } catch (error) {
            console.error('Pre-UI initialization failed:', error);
            // Still hide splash screen even on error
            SplashScreen.hide({ fade: true });
          }
        }
        
        initializePreUI();
      }, []);
      
      // Keep splash screen visible until Pre-UI is complete
      if (!preUIComplete) {
        return null; // Return nothing, native splash screen still visible
      }
      
      // Main app layout
      return <Stack />;
    }
    ```
  </Tab>

  <Tab>
    ```typescript
    // App.tsx (React Navigation)
    import { useEffect, useState } from 'react';
    import { NavigationContainer } from '@react-navigation/native';
    import { initializer, InitStage } from '@/core/shared/app/initialization';
    import { SplashScreen } from '@/core/shared/splash-screen/SplashScreen';

    export default function App() {
      const [preUIComplete, setPreUIComplete] = useState(false);
      
      useEffect(() => {
        async function initializePreUI() {
          try {
            // Execute Pre-UI stage (critical, blocking)
            await initializer.executeStage(InitStage.PRE_UI);
            
            // Mark Pre-UI complete
            setPreUIComplete(true);
            
            // Hide splash screen with smooth fade
            await SplashScreen.hide({ fade: true, duration: 500 });
            
            // Continue with non-blocking stages
            initializer.executeStage(InitStage.INITIAL_UI).then(() => {
              initializer.executeParallelStage(InitStage.BACKGROUND).then(() => {
                initializer.executeStage(InitStage.FINALIZATION);
              });
            });
          } catch (error) {
            console.error('Pre-UI initialization failed:', error);
            // Still hide splash screen even on error
            SplashScreen.hide({ fade: true });
          }
        }
        
        initializePreUI();
      }, []);
      
      // Keep splash screen visible until Pre-UI is complete
      if (!preUIComplete) {
        return null; // Return nothing, native splash screen still visible
      }
      
      // Main app content
      return (
        <NavigationContainer>
          <AppNavigator />
        </NavigationContainer>
      );
    }
    ```
  </Tab>

  <Tab>
    ```typescript
    // index.js (Custom entry point)
    import { AppRegistry } from 'react-native';
    import { initializer, InitStage } from '@/core/shared/app/initialization';
    import { SplashScreen } from '@/core/shared/splash-screen/SplashScreen';
    import App from './App';

    // Custom initialization wrapper
    const AppWithInitialization = () => {
      const [initialized, setInitialized] = useState(false);
      
      useEffect(() => {
        async function init() {
          try {
            // Run all initialization stages
            await initializer.executeStage(InitStage.PRE_UI);
            await initializer.executeStage(InitStage.INITIAL_UI);
            
            // Mark as initialized
            setInitialized(true);
            
            // Hide splash
            await SplashScreen.hide({ fade: true });
            
            // Background tasks
            initializer.executeParallelStage(InitStage.BACKGROUND);
          } catch (error) {
            console.error('Initialization failed:', error);
            SplashScreen.hide();
          }
        }
        
        init();
      }, []);
      
      if (!initialized) {
        return null;
      }
      
      return <App />;
    };

    AppRegistry.registerComponent('YourApp', () => AppWithInitialization);
    ```
  </Tab>
</Tabs>

## Progress Reporting

For apps with potentially lengthy initialization processes, showing progress enhances user experience:

### Enhanced SplashScreen Class

```typescript
// core/shared/splash-screen/SplashScreen.ts
import RNBootSplash from 'react-native-bootsplash';
import { Platform, DeviceEventEmitter, NativeEventEmitter } from 'react-native';

export class SplashScreen {
  // Track if we're using a custom loading screen that can show progress
  private static usingCustomLoader = false;
  
  // Store the latest progress value (0-1)
  private static currentProgress = 0;
  
  // Event emitter for progress updates
  private static eventEmitter = Platform.OS === 'ios' 
    ? new NativeEventEmitter() 
    : DeviceEventEmitter;
  
  /**
   * Hide the splash screen with optional fade effect
   */
  static async hide(options?: { fade?: boolean; duration?: number }) {
    if (this.usingCustomLoader) {
      // If using custom loader, dispatch an event to hide it
      this.eventEmitter.emit('splash:hide');
      return;
    }
    
    // Default to native splash screen hiding
    return RNBootSplash.hide({
      fade: options?.fade ?? true,
      duration: options?.duration ?? 220
    });
  }

  /**
   * Update the loading progress (0-1)
   * This is only effective when using a custom React-based loading screen
   */
  static setProgress(progress: number) {
    // Ensure progress is between 0-1
    const normalizedProgress = Math.min(Math.max(progress, 0), 1);
    this.currentProgress = normalizedProgress;
    
    // Dispatch progress event
    this.eventEmitter.emit('splash:progress', normalizedProgress);
  }

  /**
   * Enable custom loader mode - transitions from native splash to React-based loader
   */
  static useCustomLoader() {
    this.usingCustomLoader = true;
    // Hide native splash with very quick fade to show custom one
    RNBootSplash.hide({ fade: true, duration: 100 });
  }

  /**
   * Get current progress value (0-1)
   */
  static getProgress() {
    return this.currentProgress;
  }
}
```

### Custom Loading Screen Component

Create a React-based splash screen for progress reporting:

```tsx
// core/shared/splash-screen/CustomSplashScreen.tsx
import React, { useEffect, useState } from 'react';
import { 
  View, 
  Text, 
  StyleSheet, 
  Image, 
  Animated,
  Dimensions,
  StatusBar
} from 'react-native';
import { SplashScreen } from './SplashScreen';

interface Props {
  onInitialized: () => void;
}

export function CustomSplashScreen({ onInitialized }: Props) {
  const [progress, setProgress] = useState(0);
  const [visible, setVisible] = useState(true);
  const progressAnim = React.useRef(new Animated.Value(0)).current;
  const fadeAnim = React.useRef(new Animated.Value(1)).current;
  
  useEffect(() => {
    // Listen for progress updates
    const progressListener = SplashScreen.eventEmitter.addListener(
      'splash:progress',
      (newProgress: number) => {
        setProgress(newProgress);
        
        // Animate progress bar
        Animated.timing(progressAnim, {
          toValue: newProgress,
          duration: 200,
          useNativeDriver: false
        }).start();
      }
    );
    
    // Listen for hide event
    const hideListener = SplashScreen.eventEmitter.addListener(
      'splash:hide',
      () => {
        // Fade out animation
        Animated.timing(fadeAnim, {
          toValue: 0,
          duration: 300,
          useNativeDriver: true,
        }).start(() => {
          setVisible(false);
          onInitialized();
        });
      }
    );
    
    return () => {
      progressListener.remove();
      hideListener.remove();
    };
  }, [onInitialized, progressAnim, fadeAnim]);
  
  if (!visible) return null;
  
  const { width } = Dimensions.get('window');
  const progressWidth = progressAnim.interpolate({
    inputRange: [0, 1],
    outputRange: [0, width * 0.8]
  });
  
  return (
    <Animated.View style={[styles.container, { opacity: fadeAnim }]}>
      <StatusBar hidden />
      <View style={styles.content}>
        <Image 
          source={require('@/assets/splash-logo.png')} 
          style={styles.logo} 
          resizeMode="contain" 
        />
        
        <Text style={styles.title}>Your App Name</Text>
        
        <View style={styles.progressContainer}>
          <Animated.View 
            style={[styles.progressBar, { width: progressWidth }]} 
          />
        </View>
        
        <Text style={styles.progressText}>
          Loading... {Math.round(progress * 100)}%
        </Text>
      </View>
    </Animated.View>
  );
}

const styles = StyleSheet.create({
  container: {
    ...StyleSheet.absoluteFillObject,
    backgroundColor: '#FFFFFF',
    zIndex: 999,
  },
  content: {
    flex: 1,
    justifyContent: 'center',
    alignItems: 'center',
    padding: 24,
  },
  logo: {
    width: 150,
    height: 150,
    marginBottom: 24,
  },
  title: {
    fontSize: 24,
    fontWeight: 'bold',
    marginBottom: 48,
    color: '#333333',
  },
  progressContainer: {
    width: '80%',
    height: 4,
    backgroundColor: '#E0E0E0',
    borderRadius: 2,
    overflow: 'hidden',
    marginBottom: 8,
  },
  progressBar: {
    height: '100%',
    backgroundColor: '#2196F3',
    borderRadius: 2,
  },
  progressText: {
    fontSize: 14,
    color: '#757575',
    marginTop: 8,
  },
});
```

### Integration with Progress Reporting

<Steps>
  <Step>
    #### Enable Custom Loader

    ```typescript
    // In your app entry point
    import { SplashScreen } from '@/core/shared/splash-screen/SplashScreen';

    // Enable custom loader before any initialization
    SplashScreen.useCustomLoader();
    ```
  </Step>

  <Step>
    #### Report Progress During Initialization

    ```typescript
    // In your initialization tasks
    import { SplashScreen } from '@/core/shared/splash-screen/SplashScreen';

    export async function initializeApp() {
      // Pre-UI Stage
      SplashScreen.setProgress(0.1);
      await initializeStorage();
      
      SplashScreen.setProgress(0.2);
      await loadConfiguration();
      
      SplashScreen.setProgress(0.4);
      await authenticateUser();
      
      // Initial UI Stage
      SplashScreen.setProgress(0.6);
      await loadTheme();
      
      SplashScreen.setProgress(0.8);
      await preloadAssets();
      
      // Complete
      SplashScreen.setProgress(1.0);
      await delay(200); // Brief pause at 100%
      
      // Hide splash screen
      SplashScreen.hide();
    }
    ```
  </Step>

  <Step>
    #### Integrate with App Component

    ```typescript
    export default function App() {
      const [initialized, setInitialized] = useState(false);
      
      useEffect(() => {
        // Enable custom splash screen
        SplashScreen.useCustomLoader();
        
        // Run initialization with progress
        initializeApp().catch(error => {
          console.error('Initialization failed:', error);
          SplashScreen.hide();
        });
      }, []);
      
      return (
        <>
          {!initialized && (
            <CustomSplashScreen 
              onInitialized={() => setInitialized(true)}
            />
          )}
          {initialized && (
            <NavigationContainer>
              <AppNavigator />
            </NavigationContainer>
          )}
        </>
      );
    }
    ```
  </Step>
</Steps>

## Advanced Progress Tracking

### Task-Based Progress

For more granular progress tracking based on individual tasks:

```typescript
// core/shared/app/initialization/progress-tracker.ts
export class InitializationProgressTracker {
  private totalTasks = 0;
  private completedTasks = 0;
  private taskWeights: Map<string, number> = new Map();
  
  /**
   * Register a task with optional weight
   */
  registerTask(taskId: string, weight: number = 1) {
    this.taskWeights.set(taskId, weight);
    this.totalTasks += weight;
  }
  
  /**
   * Mark a task as complete
   */
  completeTask(taskId: string) {
    const weight = this.taskWeights.get(taskId) || 1;
    this.completedTasks += weight;
    
    const progress = this.completedTasks / this.totalTasks;
    SplashScreen.setProgress(progress);
  }
  
  /**
   * Reset progress tracking
   */
  reset() {
    this.totalTasks = 0;
    this.completedTasks = 0;
    this.taskWeights.clear();
  }
}

// Usage in initialization
const tracker = new InitializationProgressTracker();

// Register all tasks upfront
tracker.registerTask('storage', 1);
tracker.registerTask('auth', 2); // Auth is weighted more
tracker.registerTask('config', 1);
tracker.registerTask('theme', 1);

// Complete tasks as they finish
await initializeStorage();
tracker.completeTask('storage');

await authenticateUser();
tracker.completeTask('auth');

// ... continue with other tasks
```

### Stage-Based Progress

Map initialization stages to progress ranges:

```typescript
// core/shared/app/initialization/stage-progress.ts
export class StageProgressManager {
  private stageRanges = {
    [InitStage.PRE_UI]: { start: 0, end: 0.4 },
    [InitStage.INITIAL_UI]: { start: 0.4, end: 0.7 },
    [InitStage.BACKGROUND]: { start: 0.7, end: 0.9 },
    [InitStage.FINALIZATION]: { start: 0.9, end: 1.0 },
  };
  
  /**
   * Update progress for a stage
   */
  updateStageProgress(stage: InitStage, stageProgress: number) {
    const range = this.stageRanges[stage];
    const overallProgress = range.start + (range.end - range.start) * stageProgress;
    SplashScreen.setProgress(overallProgress);
  }
}
```

## Error Handling

### Graceful Error Recovery

```typescript
async function initializeWithErrorHandling() {
  try {
    await initializeApp();
  } catch (error) {
    console.error('Initialization error:', error);
    
    // Show error state in custom splash
    SplashScreen.eventEmitter.emit('splash:error', {
      message: 'Failed to initialize app',
      retry: () => initializeWithErrorHandling()
    });
    
    // Or hide splash and show error screen
    setTimeout(() => {
      SplashScreen.hide();
      // Navigate to error screen
    }, 2000);
  }
}
```

### Error State in Custom Splash

```tsx
// Add to CustomSplashScreen component
const [error, setError] = useState<{ message: string; retry?: () => void } | null>(null);

useEffect(() => {
  const errorListener = SplashScreen.eventEmitter.addListener(
    'splash:error',
    (errorInfo) => setError(errorInfo)
  );
  
  return () => errorListener.remove();
}, []);

// In render
{error && (
  <View style={styles.errorContainer}>
    <Text style={styles.errorText}>{error.message}</Text>
    {error.retry && (
      <TouchableOpacity onPress={error.retry} style={styles.retryButton}>
        <Text style={styles.retryText}>Retry</Text>
      </TouchableOpacity>
    )}
  </View>
)}
```

## Performance Considerations

<Callout type="warning">
  **Performance Tips**

  * Don't update progress too frequently (max 10 updates/second)
  * Batch multiple quick tasks before updating progress
  * Use native animations for smooth visual updates
  * Keep custom splash screen lightweight
  * Preload splash screen assets
</Callout>

### Optimized Progress Updates

```typescript
// Debounced progress updates
class DebouncedProgress {
  private pendingProgress: number | null = null;
  private updateTimer: NodeJS.Timeout | null = null;
  
  update(progress: number) {
    this.pendingProgress = progress;
    
    if (!this.updateTimer) {
      this.updateTimer = setTimeout(() => {
        if (this.pendingProgress !== null) {
          SplashScreen.setProgress(this.pendingProgress);
        }
        this.updateTimer = null;
      }, 100); // Update max every 100ms
    }
  }
}
```

## Testing

### Unit Tests

```typescript
// __tests__/splash-screen-integration.test.ts
import { SplashScreen } from '@/core/shared/splash-screen/SplashScreen';

describe('SplashScreen Integration', () => {
  beforeEach(() => {
    jest.clearAllMocks();
  });
  
  it('hides splash after initialization', async () => {
    const hideSpy = jest.spyOn(SplashScreen, 'hide');
    
    await initializeApp();
    
    expect(hideSpy).toHaveBeenCalledWith({ fade: true, duration: 500 });
  });
  
  it('reports progress correctly', async () => {
    const progressSpy = jest.spyOn(SplashScreen, 'setProgress');
    
    await initializeApp();
    
    expect(progressSpy).toHaveBeenCalledWith(expect.any(Number));
    expect(progressSpy).toHaveBeenLastCalledWith(1.0);
  });
  
  it('handles initialization errors', async () => {
    const error = new Error('Init failed');
    jest.spyOn(storage, 'initialize').mockRejectedValue(error);
    
    await expect(initializeApp()).rejects.toThrow(error);
    expect(SplashScreen.hide).toHaveBeenCalled();
  });
});
```

## Summary

Proper integration ensures your splash screen enhances rather than delays the user experience:

* **Hide at the right time**: After critical initialization completes
* **Show progress**: For operations taking more than 2 seconds
* **Handle errors**: Always hide the splash screen, even on failure
* **Test thoroughly**: Verify behavior in all scenarios
* **Optimize performance**: Keep initialization fast and progress smooth

## Next Steps

* Implement [White-Label Support](/docs/ui-development/splash-screens/white-label-support) for multi-brand apps
* Explore [Advanced Topics](/docs/ui-development/splash-screens/advanced-topics) for custom animations
* Review [App Initialization Architecture](/docs/architecture/app-initialization) for optimization

## Related Documents

* [App Initialization Guide](/docs/architecture/app-initialization)
* [Performance Optimization](/docs/guides/performance)
* [Error Handling Patterns](/docs/patterns/error-handling)


# UTA UI Development: White-Label Support
URL: https://dev.updatetheapp.com/docs/ui-development/splash-screens/white-label-support
Documentation: https://dev.updatetheapp.com/docs/ui-development/splash-screens/white-label-support

Implementing splash screens for multi-brand applications with build-time and runtime configurations
        
***

title: White-Label Support
description: Implementing splash screens for multi-brand applications with build-time and runtime configurations
----------------------------------------------------------------------------------------------------------------

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Callout } from 'fumadocs-ui/components/callout';
import { Steps, Step } from 'fumadocs-ui/components/steps';

# White-Label Support

## Overview

White-label applications require different branding assets and configurations based on the brand or client. This guide provides comprehensive strategies for implementing splash screens that support multiple brands with minimal code duplication.

<Callout type="info">
  **White-Label Considerations**

  When building multi-brand apps, splash screens need to:

  * Display brand-specific logos and colors
  * Support different configurations per brand
  * Maintain a single codebase for easier maintenance
  * Allow for both build-time and runtime brand selection
</Callout>

## Configuration Strategies

### Build-Time vs Runtime

<Tabs items={["Build-Time Configuration", "Runtime Configuration", "Hybrid Approach"]}>
  <Tab>
    **Build-Time Configuration**

    Each brand gets its own build with embedded assets:

    **Advantages:**

    * Native splash screens work perfectly
    * Smaller app size per brand
    * Better performance (no runtime decisions)
    * More secure (assets are embedded)

    **Disadvantages:**

    * Multiple builds to maintain
    * Longer deployment process
    * App store submissions per brand

    **When to use:**

    * Distributing through app stores
    * Brands have very different features
    * Security is paramount
  </Tab>

  <Tab>
    **Runtime Configuration**

    Single build determines brand at runtime:

    **Advantages:**

    * Single build for all brands
    * Easy brand switching
    * Simplified deployment
    * Dynamic brand selection

    **Disadvantages:**

    * Larger app size (all assets included)
    * Can't use native splash screens effectively
    * Slight performance overhead

    **When to use:**

    * Enterprise apps with user-selected brands
    * Brand determined by login/API
    * Frequent brand additions
  </Tab>

  <Tab>
    **Hybrid Approach**

    Native splash followed by branded React splash:

    **Advantages:**

    * Immediate native splash response
    * Brand-specific loading screen
    * Good performance
    * Flexible configuration

    **Disadvantages:**

    * More complex implementation
    * Two splash screens to manage
    * Transition must be smooth

    **When to use:**

    * Best of both worlds needed
    * Complex initialization
    * Progress reporting required
  </Tab>
</Tabs>

## Build-Time Implementation

### Asset Organization

```
assets/
├── brands/
│   ├── brand-a/
│   │   ├── splash-logo.png
│   │   ├── splash-logo@2x.png
│   │   ├── splash-logo@3x.png
│   │   └── config.json
│   ├── brand-b/
│   │   ├── splash-logo.png
│   │   ├── splash-logo@2x.png
│   │   ├── splash-logo@3x.png
│   │   └── config.json
│   └── brand-c/
│       └── ...
└── splash/
    └── ... (generated assets)
```

### Generating Brand Assets

Create a script to generate assets for each brand:

```bash
#!/bin/bash
# scripts/generate-splash-screens.sh

BRANDS=("brand-a" "brand-b" "brand-c")

for BRAND in "${BRANDS[@]}"; do
  echo "Generating splash screen for $BRAND..."
  
  # Read brand config
  CONFIG_FILE="assets/brands/$BRAND/config.json"
  BG_COLOR=$(jq -r '.splashBackgroundColor' $CONFIG_FILE)
  LOGO_WIDTH=$(jq -r '.splashLogoWidth' $CONFIG_FILE)
  
  # Generate assets
  npx react-native-bootsplash generate \
    --assets-path="assets/splash/$BRAND" \
    --background-color="$BG_COLOR" \
    --logo-width="$LOGO_WIDTH" \
    --flavor="$BRAND" \
    "assets/brands/$BRAND/splash-logo.png"
done
```

### Android Build Flavors

Configure product flavors in `android/app/build.gradle`:

```groovy
android {
  flavorDimensions "brand"
  
  productFlavors {
    brandA {
      dimension "brand"
      applicationId "com.company.branda"
      resValue "string", "app_name", "Brand A"
      buildConfigField "String", "BRAND_ID", '"brand-a"'
    }
    
    brandB {
      dimension "brand"
      applicationId "com.company.brandb"
      resValue "string", "app_name", "Brand B"
      buildConfigField "String", "BRAND_ID", '"brand-b"'
    }
    
    brandC {
      dimension "brand"
      applicationId "com.company.brandc"
      resValue "string", "app_name", "Brand C"
      buildConfigField "String", "BRAND_ID", '"brand-c"'
    }
  }
}
```

### iOS Build Schemes

<Steps>
  <Step>
    #### Create Build Configurations

    In Xcode:

    1. Select your project
    2. Go to Info tab
    3. Duplicate configurations for each brand
    4. Name them: Debug-BrandA, Release-BrandA, etc.
  </Step>

  <Step>
    #### Create Schemes

    1. Go to Product > Scheme > Manage Schemes
    2. Duplicate the default scheme for each brand
    3. Edit each scheme to use appropriate build configuration
    4. Set environment variables or preprocessor macros
  </Step>

  <Step>
    #### Configure Info.plist

    Use build settings to vary values:

    ```xml
    <key>CFBundleDisplayName</key>
    <string>$(PRODUCT_NAME)</string>
    <key>CFBundleIdentifier</key>
    <string>$(PRODUCT_BUNDLE_IDENTIFIER)</string>
    ```
  </Step>
</Steps>

### JavaScript Configuration

Use react-native-config or similar to load brand config:

```typescript
// config/brand.ts
import Config from 'react-native-config';

export interface BrandConfig {
  id: string;
  name: string;
  colors: {
    primary: string;
    secondary: string;
    background: string;
  };
  api: {
    baseUrl: string;
    apiKey: string;
  };
}

// Load config based on build flavor
export const BRAND_CONFIG: BrandConfig = {
  id: Config.BRAND_ID,
  name: Config.BRAND_NAME,
  colors: {
    primary: Config.PRIMARY_COLOR,
    secondary: Config.SECONDARY_COLOR,
    background: Config.BACKGROUND_COLOR,
  },
  api: {
    baseUrl: Config.API_BASE_URL,
    apiKey: Config.API_KEY,
  },
};
```

## Runtime Implementation

### Brand Manager

Create a centralized brand management system:

```typescript
// core/shared/brands/BrandManager.ts
import AsyncStorage from '@react-native-async-storage/async-storage';

export type BrandId = 'brand-a' | 'brand-b' | 'brand-c';

interface BrandAssets {
  splashLogo: any; // Using require() returns number
  appLogo: any;
  primaryColor: string;
  secondaryColor: string;
}

export class BrandManager {
  private static currentBrand: BrandId | null = null;
  
  private static brands: Record<BrandId, BrandAssets> = {
    'brand-a': {
      splashLogo: require('@/assets/brands/brand-a/splash-logo.png'),
      appLogo: require('@/assets/brands/brand-a/logo.png'),
      primaryColor: '#FF5500',
      secondaryColor: '#FF8800',
    },
    'brand-b': {
      splashLogo: require('@/assets/brands/brand-b/splash-logo.png'),
      appLogo: require('@/assets/brands/brand-b/logo.png'),
      primaryColor: '#0055FF',
      secondaryColor: '#0088FF',
    },
    'brand-c': {
      splashLogo: require('@/assets/brands/brand-c/splash-logo.png'),
      appLogo: require('@/assets/brands/brand-c/logo.png'),
      primaryColor: '#00AA55',
      secondaryColor: '#00DD88',
    },
  };
  
  /**
   * Initialize brand manager
   */
  static async initialize(): Promise<void> {
    // Try to load saved brand
    const savedBrand = await AsyncStorage.getItem('selectedBrand');
    if (savedBrand && this.isValidBrand(savedBrand)) {
      this.currentBrand = savedBrand as BrandId;
    }
  }
  
  /**
   * Set the current brand
   */
  static async setBrand(brandId: BrandId): Promise<void> {
    if (!this.isValidBrand(brandId)) {
      throw new Error(`Invalid brand ID: ${brandId}`);
    }
    
    this.currentBrand = brandId;
    await AsyncStorage.setItem('selectedBrand', brandId);
  }
  
  /**
   * Get current brand assets
   */
  static getAssets(): BrandAssets {
    if (!this.currentBrand) {
      throw new Error('Brand not initialized');
    }
    
    return this.brands[this.currentBrand];
  }
  
  /**
   * Get specific brand assets
   */
  static getBrandAssets(brandId: BrandId): BrandAssets {
    return this.brands[brandId];
  }
  
  /**
   * Check if brand ID is valid
   */
  private static isValidBrand(brandId: string): boolean {
    return Object.keys(this.brands).includes(brandId);
  }
}
```

### Branded Splash Screen Component

```tsx
// core/shared/splash-screen/BrandedSplashScreen.tsx
import React, { useEffect, useState } from 'react';
import { 
  View, 
  Image, 
  StyleSheet, 
  Animated,
  StatusBar,
  ActivityIndicator 
} from 'react-native';
import { BrandManager } from '@/core/shared/brands/BrandManager';
import { SplashScreen } from './SplashScreen';

interface Props {
  onReady: () => void;
}

export function BrandedSplashScreen({ onReady }: Props) {
  const [fadeAnim] = useState(new Animated.Value(1));
  const [assets, setAssets] = useState<any>(null);
  
  useEffect(() => {
    async function loadBrand() {
      try {
        // Initialize brand manager
        await BrandManager.initialize();
        
        // Get brand assets
        const brandAssets = BrandManager.getAssets();
        setAssets(brandAssets);
        
        // Hide native splash quickly
        await SplashScreen.hide({ fade: true, duration: 100 });
      } catch (error) {
        console.error('Failed to load brand:', error);
        // Use default brand or handle error
      }
    }
    
    loadBrand();
  }, []);
  
  useEffect(() => {
    if (assets) {
      // Show branded splash for minimum time
      setTimeout(() => {
        Animated.timing(fadeAnim, {
          toValue: 0,
          duration: 300,
          useNativeDriver: true,
        }).start(() => {
          onReady();
        });
      }, 1500);
    }
  }, [assets, fadeAnim, onReady]);
  
  if (!assets) {
    // Show loading while determining brand
    return (
      <View style={[styles.container, styles.loading]}>
        <ActivityIndicator size="large" color="#999" />
      </View>
    );
  }
  
  return (
    <Animated.View 
      style={[
        styles.container, 
        { 
          opacity: fadeAnim,
          backgroundColor: assets.primaryColor 
        }
      ]}
    >
      <StatusBar hidden />
      <Image 
        source={assets.splashLogo} 
        style={styles.logo} 
        resizeMode="contain" 
      />
    </Animated.View>
  );
}

const styles = StyleSheet.create({
  container: {
    ...StyleSheet.absoluteFillObject,
    justifyContent: 'center',
    alignItems: 'center',
  },
  loading: {
    backgroundColor: '#FFFFFF',
  },
  logo: {
    width: 200,
    height: 200,
  },
});
```

### Brand Selection Screen

For apps where users select their brand:

```tsx
// screens/BrandSelectionScreen.tsx
import React from 'react';
import { View, Text, TouchableOpacity, Image, StyleSheet } from 'react-native';
import { BrandManager, BrandId } from '@/core/shared/brands/BrandManager';

const AVAILABLE_BRANDS: Array<{ id: BrandId; name: string }> = [
  { id: 'brand-a', name: 'Brand A' },
  { id: 'brand-b', name: 'Brand B' },
  { id: 'brand-c', name: 'Brand C' },
];

export function BrandSelectionScreen({ navigation }) {
  const selectBrand = async (brandId: BrandId) => {
    await BrandManager.setBrand(brandId);
    // Restart app or navigate to main screen
    navigation.replace('Main');
  };
  
  return (
    <View style={styles.container}>
      <Text style={styles.title}>Select Your Brand</Text>
      
      {AVAILABLE_BRANDS.map(brand => {
        const assets = BrandManager.getBrandAssets(brand.id);
        
        return (
          <TouchableOpacity
            key={brand.id}
            style={[
              styles.brandCard,
              { borderColor: assets.primaryColor }
            ]}
            onPress={() => selectBrand(brand.id)}
          >
            <Image 
              source={assets.appLogo} 
              style={styles.brandLogo}
              resizeMode="contain"
            />
            <Text style={styles.brandName}>{brand.name}</Text>
          </TouchableOpacity>
        );
      })}
    </View>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    padding: 24,
    justifyContent: 'center',
  },
  title: {
    fontSize: 24,
    fontWeight: 'bold',
    textAlign: 'center',
    marginBottom: 32,
  },
  brandCard: {
    padding: 16,
    marginVertical: 8,
    borderWidth: 2,
    borderRadius: 12,
    alignItems: 'center',
  },
  brandLogo: {
    width: 80,
    height: 80,
    marginBottom: 8,
  },
  brandName: {
    fontSize: 18,
    fontWeight: '600',
  },
});
```

## Hybrid Implementation

Combine native and React splash screens for optimal experience:

```typescript
// App.tsx
import React, { useEffect, useState } from 'react';
import { SplashScreen } from '@/core/shared/splash-screen/SplashScreen';
import { BrandedSplashScreen } from '@/core/shared/splash-screen/BrandedSplashScreen';
import { BrandManager } from '@/core/shared/brands/BrandManager';
import { initializer } from '@/core/shared/app/initialization';

export default function App() {
  const [showBrandedSplash, setShowBrandedSplash] = useState(true);
  const [appReady, setAppReady] = useState(false);
  
  useEffect(() => {
    async function initialize() {
      try {
        // Quick native splash hides automatically when React loads
        
        // Initialize brand
        await BrandManager.initialize();
        
        // Run app initialization
        await initializer.executeStage(InitStage.PRE_UI);
        
        setAppReady(true);
      } catch (error) {
        console.error('Initialization failed:', error);
        setAppReady(true); // Show app anyway
      }
    }
    
    initialize();
  }, []);
  
  if (showBrandedSplash) {
    return (
      <BrandedSplashScreen 
        onReady={() => setShowBrandedSplash(false)}
      />
    );
  }
  
  if (!appReady) {
    return null; // Keep showing nothing while initializing
  }
  
  return <MainApp />;
}
```

## Theming Integration

Integrate splash screen branding with app theming:

```typescript
// core/shared/theme/ThemeProvider.tsx
import React, { createContext, useContext } from 'react';
import { BrandManager } from '@/core/shared/brands/BrandManager';

interface Theme {
  colors: {
    primary: string;
    secondary: string;
    background: string;
    text: string;
  };
  // ... other theme properties
}

const ThemeContext = createContext<Theme | null>(null);

export function ThemeProvider({ children }) {
  const assets = BrandManager.getAssets();
  
  const theme: Theme = {
    colors: {
      primary: assets.primaryColor,
      secondary: assets.secondaryColor,
      background: '#FFFFFF',
      text: '#000000',
    },
    // ... other theme properties
  };
  
  return (
    <ThemeContext.Provider value={theme}>
      {children}
    </ThemeContext.Provider>
  );
}

export const useTheme = () => {
  const theme = useContext(ThemeContext);
  if (!theme) {
    throw new Error('useTheme must be used within ThemeProvider');
  }
  return theme;
};
```

## Testing White-Label Apps

### Automated Testing

```typescript
// __tests__/white-label.test.ts
import { BrandManager } from '@/core/shared/brands/BrandManager';
import { render } from '@testing-library/react-native';
import { BrandedSplashScreen } from '@/core/shared/splash-screen/BrandedSplashScreen';

describe('White-Label Support', () => {
  beforeEach(() => {
    jest.clearAllMocks();
  });
  
  it('loads correct assets for each brand', async () => {
    const brands: BrandId[] = ['brand-a', 'brand-b', 'brand-c'];
    
    for (const brandId of brands) {
      await BrandManager.setBrand(brandId);
      const assets = BrandManager.getAssets();
      
      expect(assets).toBeDefined();
      expect(assets.splashLogo).toBeDefined();
      expect(assets.primaryColor).toMatch(/^#[0-9A-F]{6}$/i);
    }
  });
  
  it('renders branded splash screen', async () => {
    await BrandManager.setBrand('brand-a');
    
    const { getByTestId } = render(
      <BrandedSplashScreen onReady={jest.fn()} />
    );
    
    // Add testID to component for testing
    expect(getByTestId('branded-splash')).toBeTruthy();
  });
});
```

### Manual Testing Checklist

* [ ] Test each brand configuration
* [ ] Verify correct assets display
* [ ] Check app store builds
* [ ] Test brand switching (if applicable)
* [ ] Verify theme consistency
* [ ] Test on various devices
* [ ] Check memory usage with all assets

## Best Practices

<Callout type="success">
  **White-Label Best Practices**

  1. **Consistent Asset Naming**: Use the same filenames across brands
  2. **Validate Assets**: Ensure all brands have required assets
  3. **Automate Generation**: Script asset generation and testing
  4. **Document Brand Configs**: Maintain clear documentation
  5. **Test Thoroughly**: Test each brand configuration
</Callout>

### Asset Guidelines

* **(Do ✅) Standardize dimensions** across all brand assets
* **(Do ✅) Use consistent file formats** (PNG for all)
* **(Do ✅) Optimize file sizes** for each brand
* **(Do ✅) Include all required densities/resolutions**
* **(Don't ❌) Hardcode brand-specific values** in shared code
* **(Consider 🤔) Using SVG** for scalable brand assets

### Code Organization

```
src/
├── core/
│   ├── shared/
│   │   ├── brands/        # Brand management
│   │   └── splash-screen/ # Splash screen components
│   └── brand-specific/    # Brand-specific overrides
│       ├── brand-a/
│       ├── brand-b/
│       └── brand-c/
└── features/              # Shared features
```

## Summary

White-label splash screen support requires careful planning:

* **Choose the right strategy**: Build-time, runtime, or hybrid
* **Organize assets properly**: Consistent structure across brands
* **Automate processes**: Asset generation and testing
* **Test thoroughly**: Each brand on multiple devices
* **Maintain flexibility**: Easy to add new brands

The approach depends on your specific requirements for distribution, brand selection, and maintenance.

## Next Steps

* Explore [Advanced Topics](/docs/ui-development/splash-screens/advanced-topics) for animations
* Review [Platform Implementation](/docs/ui-development/splash-screens/platform-implementation) for setup
* Set up [Asset Generation](/docs/ui-development/splash-screens/design-assets) pipeline

## Related Documents

* [React Native Config](https://github.com/luggit/react-native-config)
* [Build Variants Guide](/docs/deployment/build-variants)
* [Theme Management](/docs/ui-development/styling/theme-management)


# UTA UI Development: Advanced Topics
URL: https://dev.updatetheapp.com/docs/ui-development/splash-screens/advanced-topics
Documentation: https://dev.updatetheapp.com/docs/ui-development/splash-screens/advanced-topics

Advanced splash screen implementations including custom animations, abstractions, and performance optimization
        
***

title: Advanced Topics
description: Advanced splash screen implementations including custom animations, abstractions, and performance optimization
---------------------------------------------------------------------------------------------------------------------------

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Callout } from 'fumadocs-ui/components/callout';
import { Steps, Step } from 'fumadocs-ui/components/steps';

# Advanced Topics

## Overview

This guide covers advanced splash screen implementations for developers who need more control over the splash screen behavior, custom animations, or specific performance optimizations.

<Callout type="info">
  **When to Use Advanced Features**

  Consider these advanced techniques when:

  * You need custom animations beyond simple fades
  * Building a unique brand experience
  * Optimizing for specific performance requirements
  * Creating interactive splash screens
  * Implementing complex loading sequences
</Callout>

## Custom Animations

### Native Hide Animations

react-native-bootsplash provides hooks for custom hide animations:

<Tabs items={["Fade & Scale", "Slide Up", "Circular Reveal"]}>
  <Tab>
    ```typescript
    import { useEffect, useState } from 'react';
    import { Animated, Dimensions } from 'react-native';
    import RNBootSplash from 'react-native-bootsplash';

    export function AnimatedSplashScreen({ onAnimationEnd }) {
      const [opacity] = useState(new Animated.Value(1));
      const [scale] = useState(new Animated.Value(1));
      
      useEffect(() => {
        // Wait for app to be ready, then animate
        Animated.parallel([
          Animated.timing(opacity, {
            toValue: 0,
            duration: 400,
            useNativeDriver: true,
          }),
          Animated.timing(scale, {
            toValue: 0.8,
            duration: 400,
            useNativeDriver: true,
          }),
        ]).start(() => {
          RNBootSplash.hide();
          onAnimationEnd();
        });
      }, []);
      
      return (
        <Animated.View
          style={{
            ...StyleSheet.absoluteFillObject,
            opacity,
            transform: [{ scale }],
            backgroundColor: '#FFFFFF',
            alignItems: 'center',
            justifyContent: 'center',
          }}
        >
          <Image source={require('@/assets/logo.png')} />
        </Animated.View>
      );
    }
    ```
  </Tab>

  <Tab>
    ```typescript
    export function SlideUpSplash({ onAnimationEnd }) {
      const { height } = Dimensions.get('window');
      const [translateY] = useState(new Animated.Value(0));
      
      useEffect(() => {
        Animated.timing(translateY, {
          toValue: -height,
          duration: 500,
          useNativeDriver: true,
          easing: Easing.inOut(Easing.ease),
        }).start(() => {
          RNBootSplash.hide();
          onAnimationEnd();
        });
      }, []);
      
      return (
        <Animated.View
          style={{
            ...StyleSheet.absoluteFillObject,
            transform: [{ translateY }],
            backgroundColor: '#FFFFFF',
            alignItems: 'center',
            justifyContent: 'center',
          }}
        >
          <Image source={require('@/assets/logo.png')} />
        </Animated.View>
      );
    }
    ```
  </Tab>

  <Tab>
    ```typescript
    import MaskedView from '@react-native-masked-view/masked-view';

    export function CircularRevealSplash({ onAnimationEnd }) {
      const [scale] = useState(new Animated.Value(0));
      const { width, height } = Dimensions.get('window');
      const maxRadius = Math.sqrt(width ** 2 + height ** 2);
      
      useEffect(() => {
        Animated.timing(scale, {
          toValue: maxRadius,
          duration: 800,
          useNativeDriver: false, // Can't use native driver with masked view
          easing: Easing.out(Easing.ease),
        }).start(() => {
          RNBootSplash.hide();
          onAnimationEnd();
        });
      }, []);
      
      return (
        <MaskedView
          style={StyleSheet.absoluteFillObject}
          maskElement={
            <View style={StyleSheet.absoluteFillObject}>
              <Animated.View
                style={{
                  width: scale,
                  height: scale,
                  borderRadius: scale,
                  backgroundColor: 'black',
                  position: 'absolute',
                  top: height / 2,
                  left: width / 2,
                  transform: [
                    { translateX: Animated.multiply(scale, -0.5) },
                    { translateY: Animated.multiply(scale, -0.5) },
                  ],
                }}
              />
            </View>
          }
        >
          <View style={styles.container}>
            <Image source={require('@/assets/logo.png')} />
          </View>
        </MaskedView>
      );
    }
    ```
  </Tab>
</Tabs>

### Interactive Splash Screens

Create splash screens that respond to user interaction:

```typescript
import { Gesture, GestureDetector } from 'react-native-gesture-handler';
import Animated, {
  useSharedValue,
  useAnimatedStyle,
  withSpring,
  runOnJS,
} from 'react-native-reanimated';

export function InteractiveSplash({ onComplete }) {
  const translateY = useSharedValue(0);
  const opacity = useSharedValue(1);
  
  const gesture = Gesture.Pan()
    .onUpdate((event) => {
      translateY.value = Math.max(0, event.translationY);
      opacity.value = 1 - Math.abs(translateY.value) / 300;
    })
    .onEnd(() => {
      if (Math.abs(translateY.value) > 100) {
        translateY.value = withSpring(300, {}, () => {
          runOnJS(onComplete)();
        });
        opacity.value = withSpring(0);
      } else {
        translateY.value = withSpring(0);
        opacity.value = withSpring(1);
      }
    });
  
  const animatedStyle = useAnimatedStyle(() => ({
    transform: [{ translateY: translateY.value }],
    opacity: opacity.value,
  }));
  
  return (
    <GestureDetector gesture={gesture}>
      <Animated.View style={[styles.container, animatedStyle]}>
        <Image source={require('@/assets/logo.png')} />
        <Text style={styles.hint}>Swipe up to start</Text>
      </Animated.View>
    </GestureDetector>
  );
}
```

## Abstraction Layer

Create a comprehensive abstraction layer for splash screen functionality:

### Complete Abstraction Implementation

```typescript
// core/shared/splash-screen/SplashScreenManager.ts
import { Platform } from 'react-native';
import RNBootSplash from 'react-native-bootsplash';
// Alternative imports for different libraries
// import SplashScreen from 'react-native-splash-screen';
// import * as ExpoSplashScreen from 'expo-splash-screen';

export interface SplashScreenConfig {
  fade?: boolean;
  duration?: number;
  delay?: number;
}

export interface SplashScreenProvider {
  show(): Promise<void>;
  hide(config?: SplashScreenConfig): Promise<void>;
  isVisible(): Promise<boolean>;
  setProgress?(progress: number): void;
}

// RNBootSplash implementation
class RNBootSplashProvider implements SplashScreenProvider {
  async show(): Promise<void> {
    return RNBootSplash.show();
  }
  
  async hide(config?: SplashScreenConfig): Promise<void> {
    const { fade = true, duration = 500, delay = 0 } = config || {};
    
    if (delay > 0) {
      await new Promise(resolve => setTimeout(resolve, delay));
    }
    
    return RNBootSplash.hide({ fade, duration });
  }
  
  async isVisible(): Promise<boolean> {
    return RNBootSplash.isVisible();
  }
  
  setProgress(progress: number): void {
    // RNBootSplash doesn't support progress natively
    // Could emit events for custom implementation
  }
}

// Factory pattern for provider selection
class SplashScreenFactory {
  static createProvider(type: 'rnbootsplash' | 'expo' | 'legacy'): SplashScreenProvider {
    switch (type) {
      case 'rnbootsplash':
        return new RNBootSplashProvider();
      // Add other providers as needed
      default:
        return new RNBootSplashProvider();
    }
  }
}

// Main abstraction
export class SplashScreenManager {
  private static provider: SplashScreenProvider = SplashScreenFactory.createProvider('rnbootsplash');
  private static config: SplashScreenConfig = {};
  
  /**
   * Configure splash screen behavior
   */
  static configure(config: SplashScreenConfig): void {
    this.config = { ...this.config, ...config };
  }
  
  /**
   * Show splash screen (usually for development)
   */
  static async show(): Promise<void> {
    return this.provider.show();
  }
  
  /**
   * Hide splash screen with configuration
   */
  static async hide(config?: SplashScreenConfig): Promise<void> {
    const mergedConfig = { ...this.config, ...config };
    return this.provider.hide(mergedConfig);
  }
  
  /**
   * Check if splash screen is visible
   */
  static async isVisible(): Promise<boolean> {
    return this.provider.isVisible();
  }
  
  /**
   * Update progress (if supported)
   */
  static setProgress(progress: number): void {
    this.provider.setProgress?.(progress);
  }
  
  /**
   * Platform-specific hide with smart defaults
   */
  static async smartHide(): Promise<void> {
    const config: SplashScreenConfig = Platform.select({
      ios: { fade: true, duration: 400 },
      android: { fade: true, duration: 500 },
      default: { fade: true, duration: 500 },
    });
    
    return this.hide(config);
  }
}
```

### Usage with Abstraction

```typescript
// App initialization
import { SplashScreenManager } from '@/core/shared/splash-screen';

// Configure once
SplashScreenManager.configure({
  fade: true,
  duration: 500,
});

// In your app
async function initializeApp() {
  try {
    // Initialization tasks
    await initializeServices();
    
    // Hide with smart defaults
    await SplashScreenManager.smartHide();
  } catch (error) {
    // Always hide on error
    await SplashScreenManager.hide({ duration: 0 });
  }
}
```

## Performance Optimization

### Preloading Assets

Optimize splash screen transitions by preloading critical assets:

<Steps>
  <Step>
    #### Create Asset Preloader

    ```typescript
    // core/shared/assets/AssetPreloader.ts
    import { Image } from 'react-native';
    import { Asset } from 'expo-asset';

    export class AssetPreloader {
      private static imageAssets = [
        require('@/assets/logo.png'),
        require('@/assets/onboarding/step1.png'),
        require('@/assets/onboarding/step2.png'),
      ];
      
      private static fontAssets = {
        'Inter-Regular': require('@/assets/fonts/Inter-Regular.ttf'),
        'Inter-Bold': require('@/assets/fonts/Inter-Bold.ttf'),
      };
      
      static async preloadImages(): Promise<void> {
        const imagePromises = this.imageAssets.map(image => {
          return Image.prefetch(Image.resolveAssetSource(image).uri);
        });
        
        await Promise.all(imagePromises);
      }
      
      static async preloadFonts(): Promise<void> {
        // For Expo
        await Font.loadAsync(this.fontAssets);
        
        // For bare React Native, fonts are usually linked
      }
      
      static async preloadAll(): Promise<void> {
        await Promise.all([
          this.preloadImages(),
          this.preloadFonts(),
        ]);
      }
    }
    ```
  </Step>

  <Step>
    #### Integrate with Splash Screen

    ```typescript
    export default function App() {
      const [assetsLoaded, setAssetsLoaded] = useState(false);
      
      useEffect(() => {
        async function loadAssets() {
          try {
            // Start preloading while splash is visible
            await AssetPreloader.preloadAll();
            setAssetsLoaded(true);
            
            // Hide splash after assets are ready
            await SplashScreenManager.hide();
          } catch (error) {
            console.error('Asset preload failed:', error);
            // Hide splash anyway
            await SplashScreenManager.hide();
          }
        }
        
        loadAssets();
      }, []);
      
      if (!assetsLoaded) {
        return null; // Keep splash visible
      }
      
      return <MainApp />;
    }
    ```
  </Step>
</Steps>

### Memory Management

Optimize memory usage during splash screen:

```typescript
// Defer heavy imports until after splash
const LazyMainApp = lazy(() => import('./MainApp'));

export default function App() {
  const [splashHidden, setSplashHidden] = useState(false);
  
  useEffect(() => {
    // Minimal initialization
    async function init() {
      // Only critical tasks
      await initializeCriticalServices();
      
      // Hide splash
      await SplashScreenManager.hide();
      setSplashHidden(true);
      
      // Heavy initialization after splash
      setTimeout(() => {
        initializeNonCriticalServices();
      }, 100);
    }
    
    init();
  }, []);
  
  return (
    <Suspense fallback={null}>
      {splashHidden && <LazyMainApp />}
    </Suspense>
  );
}
```

## Debugging & Troubleshooting

### Debug Mode

Create a debug mode for splash screen development:

```typescript
// core/shared/splash-screen/SplashDebug.ts
export class SplashDebug {
  private static enabled = __DEV__;
  private static startTime = Date.now();
  
  static log(message: string, data?: any): void {
    if (!this.enabled) return;
    
    const elapsed = Date.now() - this.startTime;
    console.log(`[Splash ${elapsed}ms] ${message}`, data || '');
  }
  
  static async measureHideTime(hideFunction: () => Promise<void>): Promise<void> {
    const start = Date.now();
    await hideFunction();
    const duration = Date.now() - start;
    
    this.log(`Hide animation completed in ${duration}ms`);
  }
  
  static simulateSlowInit(ms: number = 3000): Promise<void> {
    this.log(`Simulating ${ms}ms initialization`);
    return new Promise(resolve => setTimeout(resolve, ms));
  }
}

// Usage
await SplashDebug.measureHideTime(() => 
  SplashScreenManager.hide({ fade: true })
);
```

### Performance Monitoring

```typescript
// Monitor splash screen performance
export class SplashMetrics {
  private static metrics = {
    showTime: 0,
    hideTime: 0,
    totalDuration: 0,
  };
  
  static recordShow(): void {
    this.metrics.showTime = Date.now();
  }
  
  static recordHide(): void {
    this.metrics.hideTime = Date.now();
    this.metrics.totalDuration = this.metrics.hideTime - this.metrics.showTime;
    
    // Send to analytics
    Analytics.track('splash_screen_duration', {
      duration: this.metrics.totalDuration,
      platform: Platform.OS,
    });
  }
}
```

## Advanced Patterns

### Conditional Splash Screens

Show different splash screens based on conditions:

```typescript
export function ConditionalSplash({ children }) {
  const [splashType, setSplashType] = useState<'loading' | 'update' | 'maintenance' | null>('loading');
  
  useEffect(() => {
    async function checkConditions() {
      // Check for app updates
      if (await UpdateManager.hasRequiredUpdate()) {
        setSplashType('update');
        return;
      }
      
      // Check for maintenance
      if (await API.isUnderMaintenance()) {
        setSplashType('maintenance');
        return;
      }
      
      // Normal initialization
      await initializeApp();
      setSplashType(null);
    }
    
    checkConditions();
  }, []);
  
  switch (splashType) {
    case 'loading':
      return <LoadingSplash />;
    case 'update':
      return <UpdateRequiredSplash />;
    case 'maintenance':
      return <MaintenanceSplash />;
    default:
      return children;
  }
}
```

### Splash Screen A/B Testing

Test different splash screen experiences:

```typescript
export function ABTestSplash({ onComplete }) {
  const [variant] = useState(() => 
    Math.random() > 0.5 ? 'animated' : 'static'
  );
  
  useEffect(() => {
    Analytics.track('splash_screen_viewed', { variant });
  }, [variant]);
  
  if (variant === 'animated') {
    return <AnimatedSplashScreen onComplete={onComplete} />;
  }
  
  return <StaticSplashScreen onComplete={onComplete} />;
}
```

## Best Practices

<Callout type="success">
  **Advanced Implementation Tips**

  1. **Keep animations smooth**: Target 60 FPS
  2. **Test on low-end devices**: Ensure performance
  3. **Handle edge cases**: App backgrounding, crashes
  4. **Monitor metrics**: Track display duration
  5. **Provide fallbacks**: For animation failures
</Callout>

### Performance Guidelines

* **(Do ✅) Use native driver** for animations when possible
* **(Do ✅) Preload critical assets** during splash display
* **(Do ✅) Defer heavy operations** until after splash
* **(Don't ❌) Block the main thread** during initialization
* **(Consider 🤔) Progressive loading** for large apps

## Summary

Advanced splash screen techniques enable unique brand experiences while maintaining performance:

* **Custom animations** create memorable first impressions
* **Abstractions** enable flexibility and maintainability
* **Performance optimization** ensures smooth transitions
* **Debugging tools** help identify issues
* **Advanced patterns** handle complex requirements

Choose techniques that align with your app's needs and user expectations.

## Related Documents

* [Animation Libraries](https://docs.swmansion.com/react-native-reanimated/)
* [Performance Best Practices](/docs/guides/performance)
* [App Initialization Architecture](/docs/architecture/app-initialization)
* [React Native Gesture Handler](https://docs.swmansion.com/react-native-gesture-handler/)


# UTA UI Development: Theme Management
URL: https://dev.updatetheapp.com/docs/ui-development/theme-management
Documentation: https://dev.updatetheapp.com/docs/ui-development/theme-management

Core architecture and concepts for theme implementation in the React Native application.
        
***

title: Theme Management
description: Core architecture and concepts for theme implementation in the React Native application.
-----------------------------------------------------------------------------------------------------

import { Card, Cards } from 'fumadocs-ui/components/card';
import { ChevronRightIcon } from 'lucide-react';
import { Tab, Tabs } from 'fumadocs-ui/components/tabs';

# Theme Management

## Executive Summary

This document outlines the theme management architecture of our application, which provides a flexible foundation for consistent styling, multi-brand support, and runtime theming capabilities. The theme system is deeply integrated with our initialization architecture, particularly the Pre-UI stage, to ensure proper theme application before any visual content is displayed to the user.

## Purpose & Scope

This guide serves as the primary reference for understanding and working with our theme system. Its purpose is to:

* Define the core theme architecture and organization of theme assets
* Explain how themes are loaded during application initialization
* Provide a conceptual overview of multi-brand and white-label support
* Document the core APIs and hooks for consuming theme values

This document is intended for all developers working on UI components, styling, or brand-specific implementations. It covers both the technical architecture of the theme system and the design principles that guide its implementation.

## Theme Structure Organization

Our theme system follows a hierarchical organization with clear separation of concerns:

<Mermaid
  chart={`
flowchart TD
  subgraph ThemeRoot[Theme Root]
      BaseTheme[Base Theme\ncolors, spacing, radius]
      ModeThemes[Mode Themes\nLight/Dark]
      BrandThemes[Brand Themes\nWhite-Label Config]
      DeviceOverrides[Device Overrides\nResponsive/Platform]
  end
  
  BaseTheme --> FinalTheme[Final Theme]
  ModeThemes --> FinalTheme
  BrandThemes --> FinalTheme
  DeviceOverrides --> FinalTheme
  
  FinalTheme --"via ThemeProvider"--> Components[UI Components]
  
  subgraph Components
      direction TB
      UIComp[Generic UI Components]
      BrandComp[Brand-Specific Components]
      CustomComp[Custom Components]
  end
  
  subgraph Context["Theme Access (Context API)"]
      direction LR
      UseTheme[useTheme Hook]
      UseWhiteLabel[useWhiteLabelConfig Hook]
  end
  
  FinalTheme --> Context
  Context --> Components
  
  style BaseTheme fill:#f9f,stroke:#333,stroke-width:2px
  style ModeThemes fill:#bbf,stroke:#333,stroke-width:2px
  style BrandThemes fill:#bfb,stroke:#333,stroke-width:2px
  style DeviceOverrides fill:#fbb,stroke:#333,stroke-width:2px
  style Context fill:#efe,stroke:#333,stroke-width:1px
  style UseTheme fill:#efe,stroke:#333,stroke-width:1px
  style UseWhiteLabel fill:#efe,stroke:#333,stroke-width:1px
`}
/>

The theme system is built around a clear file organization pattern. Here's the file structure with the responsibilities of each file:

<Mermaid
  chart={`
flowchart TB
  subgraph core/shared/styles
      theme[theme.ts\nBase theme and composition]
      typography[typography.ts\nText styles and fonts]
      layout[layout.ts\nLayout constants]
      shadows[shadows.ts\nElevation styles]
      mixins[mixins.ts\nReusable patterns]
      index[index.ts\nBarrel exports]
  end
  
  subgraph WhiteLabel[core/domains/white-label]
      configs[configs/\nBrand configurations]
      types[types.ts\nBrand type definitions]
      store[store.ts\nState management]
      service[service.ts\nBrand services]
      hooks[hooks.ts\nBrand hooks]
      loader[ThemeLoader.ts\nDynamic loading]
  end
  
  theme --> provider[ThemeProvider.tsx]
  typography --> provider
  WhiteLabel --> provider
  
  provider --> React[React Component Tree]
  
  style theme fill:#f5f,stroke:#333
  style typography fill:#f5f,stroke:#333
  style layout fill:#f5f,stroke:#333
  style shadows fill:#f5f,stroke:#333
  style mixins fill:#f5f,stroke:#333
  style index fill:#f5f,stroke:#333
  
  style configs fill:#bbf,stroke:#333
  style types fill:#bbf,stroke:#333
  style store fill:#bbf,stroke:#333
  style service fill:#bbf,stroke:#333
  style hooks fill:#bbf,stroke:#333
  style loader fill:#bbf,stroke:#333
  
  style provider fill:#afa,stroke:#333,stroke-width:2px
`}
/>

Core style files contain:

```
core/shared/styles/
├── theme.ts         # Base theme and theme composition
├── typography.ts    # Text styles and font definitions
├── layout.ts        # Layout constants and utilities
├── shadows.ts       # Shadow styles for different elevations
├── mixins.ts        # Reusable style patterns
└── index.ts         # Barrel exports
```

## Core Components

The theme system consists of these primary components:

1. **Base Theme Definition**
   * Core color palette, spacing, radius values
   * Light and dark mode variations
   * Typography scales and text styles

2. **Theme Provider**
   * React Context for theme distribution
   * Mode selection (light, dark, system)
   * Theme composition and overrides

3. **White Label Configuration**
   * Brand-specific theme overrides
   * Dynamic theme switching
   * Integration with app initialization

4. **Theme Hooks and Utilities**
   * `useTheme` hook for component access
   * Responsive styling utilities
   * Theme switching mechanisms

## Design Principles

<Tabs items={["Core Principles", "Implementation Principles", "Performance"]}>
  <Tab>
    Our theme management system follows these core design principles:

    * **(Do ✅) Single Source of Truth**
      * Theme values should be defined once and consumed throughout the application
      * Component styles should derive from theme values, not hardcoded constants

    * **(Do ✅) Composition over Inheritance**
      * Themes are composed by merging base themes with specific overrides
      * This allows for flexible theme customization without duplication

    * **(Do ✅) Platform Agnostic Base**
      * Core theme definitions should be platform-agnostic
      * Platform-specific adaptations occur at the component level

    * **(Don't ❌) Couple Themes to UI Components**
      * Theme definitions should not reference specific UI components
      * This ensures the theme system can evolve independently of the component library
  </Tab>

  <Tab>
    When implementing themes, follow these principles:

    * **(Do ✅) Consistent Naming Conventions**
      * Use semantic names for colors (e.g., `primary`, not `blue`)
      * Maintain consistent naming patterns across all theme properties

    * **(Do ✅) Typed Theme Objects**
      * Fully type all theme objects and their properties
      * Use TypeScript to ensure type safety when accessing theme values

    * **(Do ✅) Theme Versioning**
      * Keep track of theme versions for runtime switching
      * Use versioning to prevent flickering during theme changes

    * **(Don't ❌) Mix Concerns**
      * Keep theme definitions separate from application logic
      * Theme systems should focus only on styling concerns
  </Tab>

  <Tab>
    For optimal performance:

    * **(Do ✅) Memoize Theme Calculations**
      * Use React's useMemo for derivative theme values
      * Prevent unnecessary recalculations on re-renders

    * **(Do ✅) Optimize Theme Switching**
      * Minimize render cycles when switching themes
      * Consider using animation transitions for smooth changes

    * **(Do ✅) Lazy Load Brand-Specific Assets**
      * Load only the currently active brand assets
      * Cache brand configurations for faster switching

    * **(Don't ❌) Compute Styles in Render Methods**
      * Avoid creating new style objects on each render
      * Use StyleSheet.create for static styles
  </Tab>
</Tabs>

## Integration with Initialization Architecture

The theme system is integrated with our application's initialization architecture, specifically during the Pre-UI stage. This ensures that the appropriate theme is loaded and applied before any UI components are rendered.

### Theme Initialization Flow

<Mermaid
  chart={`
sequenceDiagram
  participant App as App Initialization
  participant Storage as Storage
  participant Theme as Theme Loader
  participant WL as White Label Config
  participant UI as UI Components
  
  App->>Theme: Initialize during Pre-UI stage
  Theme->>Storage: Get stored theme preferences
  Storage-->>Theme: Return user preferences
  Theme->>WL: Load brand configuration
  
  alt Remote Config Available
      WL->>API: Fetch remote brand config
      API-->>WL: Return brand config
  else Use Bundled Config
      WL->>WL: Load bundled config
  end
  
  WL-->>Theme: Return brand theme
  Theme->>Theme: Apply system preferences
  Theme->>Theme: Merge themes (base+mode+brand)
  Theme-->>App: Theme ready
  App->>UI: Render with theme
  
  Note over Theme,WL: High priority initialization task
  Note over Storage,API: Cached for performance
`}
/>

### Theme Switching Mechanism

<Mermaid
  chart={`
stateDiagram-v2
  [*] --> SystemDefault: App Launch
  
  state ThemeMode {
      SystemDefault --> Light: User sets Light
      SystemDefault --> Dark: User sets Dark
      Light --> Dark: Toggle
      Dark --> SystemDefault: Toggle
      SystemDefault --> SystemDefault: System Changes
      
      state SystemDefault {
          SysLight: Light Mode
          SysDark: Dark Mode
          [*] --> SysLight
          SysLight --> SysDark: OS changes
          SysDark --> SysLight: OS changes
      }
  }
  
  state BrandTheme {
      DefaultBrand --> BrandA: Switch Brand
      DefaultBrand --> BrandB: Switch Brand
      BrandA --> DefaultBrand: Reset
      BrandA --> BrandB: Switch Brand
      BrandB --> DefaultBrand: Reset
      BrandB --> BrandA: Switch Brand
  }
  
  ThemeMode --> FinalTheme
  BrandTheme --> FinalTheme
  FinalTheme --> UIAnimation: Apply theme
  UIAnimation --> [*]: Complete
`}
/>

For detailed implementation of theme initialization, refer to the [Theme Implementation Guide](/docs/ui-development/theme-management/implementation).

## Related Documentation

### Implementation Guides

<Cards>
  <Card icon={<ChevronRightIcon />} title="Theme Implementation" description="Detailed guide for implementing the theme system in components, including provider setup and hook usage." href="/docs/ui-development/theme-management/implementation" />

  <Card icon={<ChevronRightIcon />} title="White-Label Themes" description="Implementation guide for white-label theming, brand-specific configurations, and dynamic theme switching." href="/docs/ui-development/theme-management/white-label" />
</Cards>

### Architecture References

<Cards>
  <Card icon={<ChevronRightIcon />} title="App Initialization" description="Learn how the theme system integrates with the application initialization flow." href="/docs/architecture/app-initialization" />

  <Card icon={<ChevronRightIcon />} title="Core Architecture" description="Overall system architecture including state management and how theming fits into the application structure." href="/docs/architecture/core-architecture" />

  <Card icon={<ChevronRightIcon />} title="Project Structure" description="Learn where theme files are located in the project and how they're organized." href="/docs/architecture/project-structure" />
</Cards>

### Related UI Development

<Cards>
  <Card icon={<ChevronRightIcon />} title="UI Component Patterns" description="Guidelines for creating themed UI components that properly consume theme values." href="/docs/ui-development/component-patterns" />

  <Card icon={<ChevronRightIcon />} title="Assets Management" description="Learn how assets like images and icons integrate with the theming system." href="/docs/ui-development/assets" />
</Cards>

## Summary

The theme management system provides a flexible, performant foundation for styling our application with multi-brand support. By loading theme configurations during the Pre-UI stage, we ensure consistent styling from the very first rendered component.

Key principles to remember:

* Theme and white-label configuration are loaded during Pre-UI initialization
* Theme system is hierarchical (base → mode → brand → device)
* Components access theme values via the useTheme hook
* White-label support enables runtime switching between brands


# UTA UI Development: Theme Implementation
URL: https://dev.updatetheapp.com/docs/ui-development/theme-management/implementation
Documentation: https://dev.updatetheapp.com/docs/ui-development/theme-management/implementation

Practical guide for implementing the theme system in components, including provider setup and hooks.
        
***

title: Theme Implementation
description: Practical guide for implementing the theme system in components, including provider setup and hooks.
-----------------------------------------------------------------------------------------------------------------

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { ChevronRightIcon } from 'lucide-react';

# Theme Implementation Guide

This guide provides detailed implementation guidance for the application's theme system. It covers setup, management, and best practices for theme implementation.

## Theming Quickstart

<Callout type="info">
  Need to get up and running quickly? Here's the minimal code you need to implement theming.
</Callout>

```tsx
// 1. Import the ThemeProvider and default theme
import { ThemeProvider, defaultTheme } from '@core/shared/styles';

// 2. Wrap your app with ThemeProvider
function App() {
  return (
    <ThemeProvider initialTheme={defaultTheme}>
      <YourAppContent />
    </ThemeProvider>
  );
}

// 3. Use the theme in your components
import { useTheme } from '@core/shared/styles';

function MyComponent() {
  const theme = useTheme();
  
  return (
    <View style={{ 
      backgroundColor: theme.colors.background,
      padding: theme.spacing.m
    }}>
      <Text style={{ color: theme.colors.text }}>
        Themed Component
      </Text>
    </View>
  );
}
```

## Overview

This guide provides practical implementation details for the theme system in our React Native application. It covers theme definition, provider setup, typings, and component integration patterns. The focus is on code examples and best practices for day-to-day theme usage.

## Quick Start

<Tabs items={["Setup Provider", "Use in Component"]}>
  <Tab>
    Add the ThemeProvider to your application root:

    ```typescript
    // App.tsx
    import React from 'react';
    import { ThemeProvider } from '@/core/shared/styles/ThemeProvider';

    export default function App() {
      return (
        <ThemeProvider>
          {/* App content */}
        </ThemeProvider>
      );
    }
    ```
  </Tab>

  <Tab>
    Use theme values in your components:

    ```typescript
    // components/Button.tsx
    import React from 'react';
    import { TouchableOpacity, Text, StyleSheet } from 'react-native';
    import { useTheme } from '@/core/shared/styles/ThemeProvider';

    export function Button({ title, onPress }) {
      const theme = useTheme();
      
      return (
        <TouchableOpacity 
          style={{
            backgroundColor: theme.colors.primary,
            padding: theme.spacing.md,
            borderRadius: theme.radius.md,
          }}
          onPress={onPress}
        >
          <Text style={{ color: '#fff' }}>{title}</Text>
        </TouchableOpacity>
      );
    }
    ```
  </Tab>
</Tabs>

## Purpose & Scope

This document provides implementation guidance for:

* Setting up the theme context and provider
* Creating and organizing theme files
* Using themes in React Native components
* Creating responsive and adaptive theming
* Performance optimization techniques

This guide is intended for developers who need to work with the theme system in day-to-day development.

## Platform-Specific Theme Customization

### Mobile-Specific Theming

React Native applications often need platform-specific styling adjustments. Here's how to implement effective mobile theme customization:

```tsx
// In your theme configuration
export const theme = {
  // Base theme properties
  ...baseTheme,
  // Platform-specific overrides
  ...Platform.select({
    ios: {
      // iOS-specific theme values
      spacing: {
        xs: 4,
        s: 8,
        m: 16,
        l: 24,
        xl: 32,
      },
      // iOS-specific shadows
      shadows: {
        small: {
          shadowColor: '#000',
          shadowOffset: { width: 0, height: 1 },
          shadowOpacity: 0.2,
          shadowRadius: 1.41,
        },
        // Other shadow sizes...
      },
    },
    android: {
      // Android-specific theme values
      spacing: {
        xs: 4,
        s: 8,
        m: 16,
        l: 20,
        xl: 28,
      },
      // Android uses elevation instead of shadow properties
      shadows: {
        small: {
          elevation: 2,
        },
        // Other shadow sizes...
      },
    },
  }),
};
```

<Callout type="tip">
  For better maintainability, use a dedicated helper for platform-specific values:

  ```tsx
  const getPlatformValue = (ios: any, android: any) => Platform.OS === 'ios' ? ios : android;

  // Example usage
  const shadowStyle = getPlatformValue(
    { shadowColor: '#000', shadowOffset: {width: 0, height: 2}, shadowOpacity: 0.2, shadowRadius: 3 },
    { elevation: 4 }
  );
  ```
</Callout>

### Safe Area Handling

Mobile devices have notches, home indicators and other UI elements that require content padding. Use the theme system to handle these consistently:

```tsx
import { useSafeAreaInsets } from 'react-native-safe-area-context';

function ThemedScreen() {
  const theme = useTheme();
  const insets = useSafeAreaInsets();
  
  return (
    <View style={{
      flex: 1,
      backgroundColor: theme.colors.background,
      // Apply safe area padding using theme spacing
      paddingTop: insets.top + theme.spacing.m,
      paddingBottom: insets.bottom + theme.spacing.m,
      paddingLeft: insets.left + theme.spacing.m,
      paddingRight: insets.right + theme.spacing.m,
    }}>
      {/* Screen content */}
    </View>
  );
}
```

Customizing themes based on platform is crucial for meeting platform-specific design guidelines while maintaining a cohesive experience.

## Performance Considerations

### Performance Benchmarks

In our testing, theme switching should meet the following performance benchmarks:

| Operation            | Target Duration | Notes                   |
| -------------------- | --------------- | ----------------------- |
| Initial theme load   | \< 50ms         | From cached source      |
| Remote theme load    | \< 250ms        | First load with caching |
| Theme switch         | \< 100ms        | Including UI updates    |
| Dynamic color access | \< 1ms          | Single theme property   |

These benchmarks provide targets to maintain a responsive user experience. If your implementation exceeds these times, consider the optimization strategies below.

### Optimization Strategies

1. **Memoize theme-dependent values**
   ```tsx
   // Using useMemo to avoid recreating styles on every render
   const styles = React.useMemo(() => {
     return StyleSheet.create({
       container: {
         backgroundColor: theme.colors.background,
         padding: theme.spacing.m,
       },
       // Other styles...
     });
   }, [theme.colors.background, theme.spacing.m]);
   ```

2. **Pre-calculate derived values**
   ```tsx
   // In your theme definition, pre-calculate values that
   // would otherwise be calculated multiple times
   const theme = {
     colors: {
       primary: '#1976D2',
       // Derived colors pre-calculated
       primaryLight: lightenColor('#1976D2', 0.2),
       primaryDark: darkenColor('#1976D2', 0.2),
     },
     // Other theme properties...
   };
   ```

Theme management performance is critical for maintaining a responsive user experience, especially during theme switching.

## Prerequisites

Before implementing themes, ensure you are familiar with:

* [Theme Architecture](/docs/ui-development/theme-management) - Core concepts and architecture
* React Context API for state management
* React Native's StyleSheet API
* TypeScript type definitions

## Implementation Details

### Theme Definition

Themes are defined in `core/shared/styles/theme.ts` with TypeScript typings:

```typescript
// core/shared/styles/theme.ts
import { Platform } from 'react-native';

// Base color palette
export const baseColors = {
  // Primary palette
  primary: '#0066CC',
  primaryLight: '#4D94DB',
  primaryDark: '#004C99',
  
  // Secondary palette
  secondary: '#FF6B00',
  secondaryLight: '#FF9D4D',
  secondaryDark: '#CC5500',
  
  // Neutral palette
  background: '#FFFFFF',
  surface: '#F8F8F8',
  text: '#212121',
  textSecondary: '#757575',
  border: '#E0E0E0',
  
  // Feedback colors
  success: '#4CAF50',
  warning: '#FFC107',
  error: '#F44336',
  info: '#2196F3',
};

// Spacing scale
export const baseSpacing = {
  xs: 4,
  sm: 8,
  md: 16,
  lg: 24,
  xl: 32,
  xxl: 48,
};

// Border radius scale
export const baseRadius = {
  xs: 2,
  sm: 4,
  md: 8,
  lg: 16,
  round: 9999,
};

// Base theme used as the foundation
export const baseTheme = {
  colors: baseColors,
  spacing: baseSpacing,
  radius: baseRadius,
};

// Light theme extends base theme
export const lightTheme = {
  ...baseTheme,
  colors: {
    ...baseTheme.colors,
    // Light-mode specific overrides if needed
  },
};

// Dark theme extends base theme with dark mode overrides
export const darkTheme = {
  ...baseTheme,
  colors: {
    ...baseTheme.colors,
    background: '#121212',
    surface: '#1E1E1E',
    text: '#FFFFFF',
    textSecondary: '#BBBBBB',
    border: '#333333',
    // Other dark-mode specific overrides
  },
};
```

### Typography Definition

Typography styles are defined in a separate file to maintain clear organization:

```typescript
// core/shared/styles/typography.ts
import { Platform } from 'react-native';

// Font families
export const fontFamilies = {
  regular: Platform.select({
    ios: 'System',
    android: 'Roboto',
    default: 'System',
  }),
  medium: Platform.select({
    ios: 'System',
    android: 'Roboto-Medium',
    default: 'System',
  }),
  bold: Platform.select({
    ios: 'System',
    android: 'Roboto-Bold',
    default: 'System',
  }),
};

// Font sizes
export const fontSizes = {
  xs: 12,
  sm: 14,
  md: 16,
  lg: 18,
  xl: 20,
  xxl: 24,
  xxxl: 30,
};

// Line heights - usually 1.5x font size for good readability
export const lineHeights = {
  xs: 18,
  sm: 21,
  md: 24,
  lg: 27,
  xl: 30,
  xxl: 36,
  xxxl: 45,
};

// Text styles compositions
export const textStyles = {
  h1: {
    fontFamily: fontFamilies.bold,
    fontSize: fontSizes.xxxl,
    lineHeight: lineHeights.xxxl,
  },
  h2: {
    fontFamily: fontFamilies.bold,
    fontSize: fontSizes.xxl,
    lineHeight: lineHeights.xxl,
  },
  h3: {
    fontFamily: fontFamilies.bold,
    fontSize: fontSizes.xl,
    lineHeight: lineHeights.xl,
  },
  body: {
    fontFamily: fontFamilies.regular,
    fontSize: fontSizes.md,
    lineHeight: lineHeights.md,
  },
  bodySmall: {
    fontFamily: fontFamilies.regular,
    fontSize: fontSizes.sm,
    lineHeight: lineHeights.sm,
  },
  button: {
    fontFamily: fontFamilies.medium,
    fontSize: fontSizes.md,
    lineHeight: lineHeights.md,
  },
  caption: {
    fontFamily: fontFamilies.regular,
    fontSize: fontSizes.xs,
    lineHeight: lineHeights.xs,
  },
};
```

### Theme Provider Implementation

The ThemeProvider component leverages React Context to provide theme values to the component tree:

```typescript
// core/shared/styles/ThemeProvider.tsx
import React, { createContext, useContext, useState, useEffect } from 'react';
import { useColorScheme } from 'react-native';
import { lightTheme, darkTheme } from './theme';
import { textStyles } from './typography';

// Theme context type definition
export interface ThemeContextType {
  colors: typeof lightTheme.colors;
  spacing: typeof lightTheme.spacing;
  radius: typeof lightTheme.radius;
  textStyles: typeof textStyles;
  isDark: boolean | null; // null means system default
  toggleThemeMode: () => void;
  setThemeMode: (mode: 'light' | 'dark' | 'system') => void;
}

const ThemeContext = createContext<ThemeContextType | undefined>(undefined);

export const useTheme = () => {
  const context = useContext(ThemeContext);
  if (context === undefined) {
    throw new Error('useTheme must be used within a ThemeProvider');
  }
  return context;
};

export function ThemeProvider({ children }: { children: React.ReactNode }) {
  // Get device color scheme
  const deviceColorScheme = useColorScheme();
  
  // Theme mode preference (light, dark, or system)
  const [themeMode, setThemeMode] = useState<'light' | 'dark' | 'system'>('system');
  
  // Determine if dark mode is active
  const isDark = React.useMemo(() => {
    if (themeMode === 'system') {
      return deviceColorScheme === 'dark';
    }
    return themeMode === 'dark';
  }, [themeMode, deviceColorScheme]);
  
  // Get the base color theme based on dark/light
  const baseColorTheme = React.useMemo(() => {
    return isDark ? darkTheme : lightTheme;
  }, [isDark]);
  
  // Merge with brand theme if available
  // Note: In a full implementation, you would include brand theme merging here
  const theme = React.useMemo(() => {
    const mergedTheme = {
      ...baseColorTheme,
      textStyles,
    };
    
    return mergedTheme;
  }, [baseColorTheme]);
  
  // Toggle between light and dark mode
  const toggleThemeMode = () => {
    if (themeMode === 'light') {
      setThemeMode('dark');
    } else if (themeMode === 'dark') {
      setThemeMode('system');
    } else {
      setThemeMode('light');
    }
  };
  
  const contextValue: ThemeContextType = {
    ...theme,
    isDark,
    toggleThemeMode,
    setThemeMode,
  };
  
  return (
    <ThemeContext.Provider value={contextValue}>
      {children}
    </ThemeContext.Provider>
  );
}
```

### Using Themes in Components

Components can consume the theme through the provided hooks:

```typescript
// ui/components/Button.tsx
import React from 'react';
import { TouchableOpacity, Text, StyleSheet } from 'react-native';
import { useTheme } from '@/core/shared/styles/ThemeProvider';

interface ButtonProps {
  title: string;
  onPress: () => void;
  variant?: 'primary' | 'secondary' | 'outline';
  size?: 'small' | 'medium' | 'large';
  disabled?: boolean;
}

export function Button({
  title,
  onPress,
  variant = 'primary',
  size = 'medium',
  disabled = false,
}: ButtonProps) {
  const theme = useTheme();
  
  // Determine button styling based on variant
  const getButtonStyle = () => {
    switch (variant) {
      case 'primary':
        return {
          backgroundColor: theme.colors.primary,
          borderColor: theme.colors.primary,
        };
      case 'secondary':
        return {
          backgroundColor: theme.colors.secondary,
          borderColor: theme.colors.secondary,
        };
      case 'outline':
        return {
          backgroundColor: 'transparent',
          borderColor: theme.colors.primary,
        };
      default:
        return {
          backgroundColor: theme.colors.primary,
          borderColor: theme.colors.primary,
        };
    }
  };
  
  // Determine text color based on variant
  const getTextColor = () => {
    if (variant === 'outline') {
      return theme.colors.primary;
    }
    return '#FFFFFF';
  };
  
  // Determine padding based on size
  const getPadding = () => {
    switch (size) {
      case 'small':
        return theme.spacing.sm;
      case 'large':
        return theme.spacing.lg;
      default:
        return theme.spacing.md;
    }
  };
  
  return (
    <TouchableOpacity
      style={[
        styles.button,
        {
          ...getButtonStyle(),
          padding: getPadding(),
          borderRadius: theme.radius.md,
          opacity: disabled ? 0.6 : 1,
        },
      ]}
      onPress={onPress}
      disabled={disabled}
    >
      <Text
        style={[
          theme.textStyles.button,
          {
            color: getTextColor(),
          },
        ]}
      >
        {title}
      </Text>
    </TouchableOpacity>
  );
}

const styles = StyleSheet.create({
  button: {
    alignItems: 'center',
    justifyContent: 'center',
    borderWidth: 1,
  },
});
```

## Usage Patterns

### Responsive Theme Utilities

Create responsive styling utilities to adapt to different screen sizes:

```typescript
// core/shared/hooks/useResponsiveStyles.ts
import { useWindowDimensions } from 'react-native';
import { useTheme } from '@/core/shared/styles/ThemeProvider';

export function useResponsiveStyles() {
  const { width, height } = useWindowDimensions();
  const theme = useTheme();
  
  // Breakpoints
  const isSmallDevice = width < 375;
  const isMediumDevice = width >= 375 && width < 768;
  const isLargeDevice = width >= 768;
  
  // Responsive spacing
  const getResponsiveSpacing = (size: keyof typeof theme.spacing) => {
    const baseSpacing = theme.spacing[size];
    
    if (isSmallDevice) {
      return Math.max(baseSpacing * 0.8, 4); // Min 4px
    }
    if (isLargeDevice) {
      return baseSpacing * 1.2;
    }
    return baseSpacing;
  };
  
  // Responsive font sizing
  const getResponsiveFontSize = (size: number) => {
    if (isSmallDevice) {
      return size * 0.9;
    }
    if (isLargeDevice) {
      return size * 1.1;
    }
    return size;
  };
  
  return {
    isSmallDevice,
    isMediumDevice,
    isLargeDevice,
    getResponsiveSpacing,
    getResponsiveFontSize,
    screenWidth: width,
    screenHeight: height,
  };
}
```

### Theme Switcher Component

Create a component to allow users to switch between themes:

```typescript
// ui/components/ThemeSwitcher.tsx
import React from 'react';
import { View, Text, TouchableOpacity, StyleSheet } from 'react-native';
import { useTheme } from '@/core/shared/styles/ThemeProvider';
import { Icon } from '@/ui/components/Icon';

export function ThemeSwitcher() {
  const { isDark, toggleThemeMode, setThemeMode } = useTheme();
  
  return (
    <View style={styles.container}>
      <TouchableOpacity
        style={[styles.option, isDark === false && styles.selected]}
        onPress={() => setThemeMode('light')}
      >
        <Icon name="sun" />
        <Text>Light</Text>
      </TouchableOpacity>
      
      <TouchableOpacity
        style={[styles.option, isDark === true && styles.selected]}
        onPress={() => setThemeMode('dark')}
      >
        <Icon name="moon" />
        <Text>Dark</Text>
      </TouchableOpacity>
      
      <TouchableOpacity
        style={[styles.option, isDark === null && styles.selected]}
        onPress={() => setThemeMode('system')}
      >
        <Icon name="smartphone" />
        <Text>System</Text>
      </TouchableOpacity>
    </View>
  );
}

const styles = StyleSheet.create({
  container: {
    flexDirection: 'row',
    justifyContent: 'space-between',
    padding: 16,
  },
  option: {
    alignItems: 'center',
    padding: 8,
  },
  selected: {
    borderBottomWidth: 2,
    borderBottomColor: '#0066CC',
  },
});
```

## Best Practices & Security

<Tabs items={["Performance", "Security", "Accessibility"]}>
  <Tab>
    ### Performance Optimization

    * **(Do ✅) Memoize theme values**
      ```typescript
      // Good practice
      const buttonStyles = React.useMemo(() => ({
        container: {
          backgroundColor: theme.colors.primary,
          padding: theme.spacing.md,
        },
        text: {
          color: '#fff',
          ...theme.textStyles.button,
        },
      }), [theme.colors.primary, theme.spacing.md, theme.textStyles.button]);
      ```

    * **(Do ✅) Use StyleSheet.create for static styles**
      ```typescript
      // Static styles that don't depend on theme
      const styles = StyleSheet.create({
        container: {
          flex: 1,
          alignItems: 'center',
        },
      });

      // Then combine with dynamic styles
      <View style={[styles.container, { backgroundColor: theme.colors.background }]} />
      ```

    * **(Don't ❌) Create style objects in render**
      ```typescript
      // Avoid this pattern
      return (
        <View style={{ 
          margin: theme.spacing.md, // Creates new object on every render
          padding: theme.spacing.sm,
          backgroundColor: theme.colors.surface,
        }} />
      );
      ```
  </Tab>

  <Tab>
    ### Security Considerations

    * **(Do ✅) Validate dynamic theme values**
      * When loading themes from external sources, validate all color values
      * Ensure colors are in valid format (hex, rgb, rgba)
      * Protect against injection attacks if theme values come from APIs

    * **(Do ✅) Cache theme preferences securely**
      * Store theme preferences in secure storage if they contain sensitive info
      * Use AsyncStorage or SecureStore appropriately based on sensitivity

    * **(Don't ❌) Include sensitive information in themes**
      * Theme files should only contain styling information
      * Never include API keys, credentials, or business logic in theme files
  </Tab>

  <Tab>
    ### Accessibility Best Practices

    * **(Do ✅) Ensure sufficient color contrast**
      * All text should have a minimum contrast ratio of 4.5:1 against its background
      * Use tools like WebAIM's Contrast Checker when defining theme colors

    * **(Do ✅) Support dynamic text sizes**
      * Scale text sizes based on user's device settings
      * Test with accessibility features enabled

    * **(Do ✅) Provide visual indicators beyond color**
      * Don't rely solely on color to convey meaning
      * Add icons, patterns, or text labels for important UI elements

    ```typescript
    // Example of supporting dynamic text sizes
    import { useAccessibilityInfo } from '@react-native-community/hooks';

    function AccessibleText({ style, ...props }) {
      const { fontScale } = useAccessibilityInfo();
      
      return (
        <Text 
          style={[style, { fontSize: (style?.fontSize || 14) * fontScale }]} 
          {...props} 
        />
      );
    }
    ```
  </Tab>
</Tabs>

## Troubleshooting

### Common Issues and Solutions

| Issue                                                 | Possible Cause                         | Solution                                                          |
| ----------------------------------------------------- | -------------------------------------- | ----------------------------------------------------------------- |
| Theme not applying to components                      | Component not wrapped in ThemeProvider | Ensure the component is a descendant of ThemeProvider             |
| Error: "useTheme must be used within a ThemeProvider" | Using useTheme outside provider scope  | Check component hierarchy or add ThemeProvider higher in the tree |
| Inconsistent colors across app                        | Multiple theme definitions             | Ensure all theme values come from the central theme system        |
| Theme not updating on mode change                     | Missing dependencies in useMemo        | Add all theme dependencies to dependency arrays                   |
| Slow performance with themes                          | Creating style objects in render       | Move style creation outside render or use StyleSheet.create       |

## Migration Considerations

When migrating from hardcoded styles to the theme system:

1. **Audit existing styles**
   * Identify all hardcoded colors, spacing values, and text styles
   * Map them to corresponding theme values

2. **Incremental migration approach**
   * Start with core components used throughout the app
   * Work outward to more specialized components
   * Update one component family at a time

3. **Unit test coverage**
   * Add tests for theme-dependent rendering
   * Verify components render correctly in both light and dark modes

4. **Design system alignment**
   * Ensure the theme values match the design system specifications
   * Create a theme validator utility if needed

## Related Documents

### Core References

* [Theme Management Architecture](/docs/ui-development/theme-management) - Core concepts and architecture overview
* [White-Label Theme Implementation](/docs/ui-development/theme-management/white-label) - Brand-specific theming

### Architecture Documents

* [App Initialization](/docs/architecture/app-initialization) - Learn how themes integrate with app startup
* [Core Architecture](/docs/architecture/core-architecture) - Overall system design
* [Project Structure](/docs/architecture/project-structure) - Project organization including theme files

### UI Components

* [UI Component Patterns](/docs/ui-development/component-patterns) - Best practices for themed components
* [Assets Management](/docs/ui-development/assets) - Working with themed assets

<Cards>
  <Card icon={<ChevronRightIcon />} title="Theme Architecture" description="Reference document explaining core theming concepts and system design." href="/docs/ui-development/theme-management" />

  <Card icon={<ChevronRightIcon />} title="White-Label Implementation" description="Guide for implementing brand-specific theming." href="/docs/ui-development/theme-management/white-label" />
</Cards>

## Summary

Implementing the theme system in your components involves:

1. Setting up the ThemeProvider at the application root
2. Using the useTheme hook to access theme values in components
3. Creating well-structured, maintainable styles that derive from theme values
4. Optimizing performance by avoiding inline style creation
5. Supporting accessibility with proper contrast and text scaling

By following these patterns consistently, you ensure a cohesive visual experience across the application and make it easier to implement brand-specific theming.


# UTA UI Development: White-Label Themes
URL: https://dev.updatetheapp.com/docs/ui-development/theme-management/white-label
Documentation: https://dev.updatetheapp.com/docs/ui-development/theme-management/white-label

Implementation guide for white-label theming, brand-specific configurations, and dynamic theme switching.
        
***

title: White-Label Themes
description: Implementation guide for white-label theming, brand-specific configurations, and dynamic theme switching.
----------------------------------------------------------------------------------------------------------------------

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { ChevronRightIcon } from 'lucide-react';

# White-Label Themes

## Overview

This guide explains how to implement white-label theming in our React Native application, enabling the app to dynamically adapt its visual identity based on different brand configurations. It covers brand configuration structure, runtime theme switching, and integration with the app initialization flow.

## Quick Start

<Tabs items={["Define Brand Config", "Load Brand Theme"]}>
  <Tab>
    Create a brand configuration file:

    ```typescript
    // core/domains/white-label/configs/brandA.ts
    import { BrandConfig } from '../types';

    export const brandAConfig: BrandConfig = {
      id: 'brandA',
      name: 'Brand A',
      theme: {
        colors: {
          primary: '#00AA5B',
          primaryLight: '#4DC491',
          primaryDark: '#007A40',
          secondary: '#F9A826',
          secondaryLight: '#FFC670',
          secondaryDark: '#C78000',
        }
      },
      apiBaseUrl: 'https://api.brand-a.com',
      features: {
        enablePayments: true,
        enableSubscriptions: true,
        enableChat: false,
      },
      assets: {
        logoUrl: require('@/assets/brands/brandA/logo.png'),
        splashBackground: require('@/assets/brands/brandA/splash.png'),
      }
    };
    ```
  </Tab>

  <Tab>
    Load the brand configuration during initialization:

    ```typescript
    // core/domains/white-label/initialization.ts
    import { initializer, InitStage } from '@/core/shared/app/initialization';
    import { storage } from '@/core/shared/utils/storage';
    import { whiteLabelStore } from './store';
    import { brandAConfig } from './configs/brandA';
    import { brandBConfig } from './configs/brandB';
    import { defaultBrandConfig } from './configs/default';

    // Map of available brand configs
    const brandConfigs = {
      default: defaultBrandConfig,
      brandA: brandAConfig,
      brandB: brandBConfig,
    };

    // Register white-label initialization task
    initializer.registerTask({
      name: 'white-label:config',
      stage: InitStage.PRE_UI,
      priority: 'high',
      critical: true, // App should not proceed without brand config
      
      async execute() {
        try {
          // Get stored brand preference
          const storedBrandId = await storage.getString('selectedBrandId');
          const brandId = storedBrandId || 'default';
          
          // Load brand configuration
          const brandConfig = brandConfigs[brandId] || defaultBrandConfig;
          
          // Set in store for app-wide access
          whiteLabelStore.setBrandConfig(brandConfig);
        } catch (error) {
          console.error('Failed to load white-label config:', error);
          whiteLabelStore.setBrandConfig(defaultBrandConfig);
        }
      }
    });
    ```
  </Tab>
</Tabs>

## Purpose & Scope

This document provides implementation guidance for:

* Creating and organizing brand configurations
* Loading brand-specific themes during app initialization
* Switching brands at runtime
* Integrating white-label themes with the core theme system
* Handling brand-specific assets and feature flags

The guide is intended for developers implementing multi-brand or white-label solutions in our React Native application.

## Prerequisites

Before implementing white-label themes, ensure you are familiar with:

* [Theme Architecture](/docs/ui-development/theme-management) - Core concepts
* [Theme Implementation](/docs/ui-development/theme-management/implementation) - Basic theme setup
* [App Initialization Architecture](/docs/architecture/app-initialization) - Initialization flow
* React Context and State Management concepts

## Implementation Details

### Brand Configuration Structure

The white-label system is built around a standardized `BrandConfig` type that defines all customizable aspects of a brand:

```typescript
// core/domains/white-label/types.ts
import { ImageSourcePropType } from 'react-native';
import { ThemeOverrides } from '@/core/shared/styles/types';

export interface BrandConfig {
  id: string;                  // Unique identifier for the brand
  name: string;                // Display name
  theme: ThemeOverrides;       // Brand-specific theme overrides
  apiBaseUrl?: string;         // Optional custom API endpoint
  features: {                  // Feature flags for this brand
    [key: string]: boolean;
  };
  assets: {                    // Brand-specific assets
    logoUrl: ImageSourcePropType;
    splashBackground: ImageSourcePropType;
    [key: string]: ImageSourcePropType;
  };
  [key: string]: any;          // Additional brand-specific properties
}

// Define which theme properties can be overridden by brands
export interface ThemeOverrides {
  colors?: {
    [key: string]: string;     // Color overrides
  };
  radius?: {
    [key: string]: number;     // Border radius overrides
  };
  spacing?: {
    [key: string]: number;     // Spacing overrides
  };
}
```

### White-Label Store

The white-label configuration is managed through a central store:

```typescript
// core/domains/white-label/store.ts
import { create } from 'zustand';
import { defaultBrandConfig } from './configs/default';
import type { BrandConfig } from './types';

interface WhiteLabelState {
  brandConfig: BrandConfig;
  setBrandConfig: (config: BrandConfig) => void;
}

export const whiteLabelStore = create<WhiteLabelState>((set) => ({
  brandConfig: defaultBrandConfig,
  setBrandConfig: (config) => set({ brandConfig: config }),
}));
```

### White-Label Service

A service layer handles brand switching and persistence:

```typescript
// core/domains/white-label/service.ts
import { storage } from '@/core/shared/utils/storage';
import { whiteLabelStore } from './store';
import { ThemeLoader } from './ThemeLoader';
import type { BrandConfig } from './types';

export class WhiteLabelService {
  /**
   * Switch to a different brand configuration
   */
  static async switchBrand(brandId: string): Promise<boolean> {
    try {
      // Load brand configuration
      const brandConfig = await ThemeLoader.loadBrandConfig(brandId);
      
      if (!brandConfig) {
        console.error(`Brand config not found for ID: ${brandId}`);
        return false;
      }
      
      // Update store with new brand config
      whiteLabelStore.setBrandConfig(brandConfig);
      
      // Persist selection
      await storage.setString('selectedBrandId', brandId);
      
      return true;
    } catch (error) {
      console.error('Failed to switch brand:', error);
      return false;
    }
  }
  
  /**
   * Check if a feature is enabled for the current brand
   */
  static isFeatureEnabled(featureKey: string): boolean {
    const { brandConfig } = whiteLabelStore.getState();
    return !!brandConfig.features[featureKey];
  }
  
  /**
   * Get asset for the current brand
   */
  static getAsset(assetKey: keyof BrandConfig['assets']) {
    const { brandConfig } = whiteLabelStore.getState();
    return brandConfig.assets[assetKey];
  }
}
```

### Theme Loader

A specialized loader handles loading brand configurations from different sources:

```typescript
// core/domains/white-label/ThemeLoader.ts
import { storage } from '@/core/shared/utils/storage';
import { defaultBrandConfig } from './configs/default';
import type { BrandConfig } from './types';

export class ThemeLoader {
  // Cache for loaded brand configurations
  private static brandCache: Record<string, BrandConfig> = {};
  
  /**
   * Load a brand configuration by ID
   */
  static async loadBrandConfig(brandId?: string): Promise<BrandConfig> {
    const id = brandId || 'default';
    
    // Check cache first
    if (this.brandCache[id]) {
      return this.brandCache[id];
    }
    
    try {
      // Try to load from bundled configs first
      const bundledConfig = await this.loadBundledConfig(id);
      if (bundledConfig) {
        this.brandCache[id] = bundledConfig;
        return bundledConfig;
      }
      
      // Try to load from remote source
      const remoteConfig = await this.loadRemoteConfig(id);
      if (remoteConfig) {
        this.brandCache[id] = remoteConfig;
        return remoteConfig;
      }
      
      // Fallback to default
      return defaultBrandConfig;
    } catch (error) {
      console.error(`Error loading brand config for ${id}:`, error);
      return defaultBrandConfig;
    }
  }
  
  /**
   * Load bundled configuration
   */
  private static async loadBundledConfig(brandId: string): Promise<BrandConfig | null> {
    try {
      // Dynamic import of bundled configuration
      const { default: config } = await import(`./configs/${brandId}`);
      return config || null;
    } catch (error) {
      return null;
    }
  }
  
  /**
   * Load configuration from remote source
   */
  private static async loadRemoteConfig(brandId: string): Promise<BrandConfig | null> {
    try {
      // Check for cached remote config
      const cachedConfig = await storage.getObject(`brand_config_${brandId}`);
      if (cachedConfig) {
        return cachedConfig as BrandConfig;
      }
      
      // Fetch from remote API
      const response = await fetch(`https://api.example.com/brands/${brandId}/config`);
      if (!response.ok) {
        return null;
      }
      
      const config = await response.json();
      
      // Cache for future use
      await storage.setObject(`brand_config_${brandId}`, config);
      
      return config;
    } catch (error) {
      return null;
    }
  }
}
```

### Integration with Theme Provider

To integrate white-label themes with the theme system, modify the ThemeProvider:

```typescript
// core/shared/styles/ThemeProvider.tsx
import React, { createContext, useContext, useState, useEffect } from 'react';
import { useColorScheme } from 'react-native';
import { lightTheme, darkTheme } from './theme';
import { textStyles } from './typography';
import { useWhiteLabelConfig } from '@/core/domains/white-label/hooks';

// ... existing theme context code ...

export function ThemeProvider({ children }: { children: React.ReactNode }) {
  // Get device color scheme
  const deviceColorScheme = useColorScheme();
  
  // Get white-label configuration
  const { brandTheme } = useWhiteLabelConfig();
  
  // Theme mode preference (light, dark, or system)
  const [themeMode, setThemeMode] = useState<'light' | 'dark' | 'system'>('system');
  
  // Determine if dark mode is active
  const isDark = React.useMemo(() => {
    if (themeMode === 'system') {
      return deviceColorScheme === 'dark';
    }
    return themeMode === 'dark';
  }, [themeMode, deviceColorScheme]);
  
  // Get the base color theme based on dark/light
  const baseColorTheme = React.useMemo(() => {
    return isDark ? darkTheme : lightTheme;
  }, [isDark]);
  
  // Merge with brand theme
  const theme = React.useMemo(() => {
    // Start with base theme
    const mergedTheme = {
      ...baseColorTheme,
      textStyles,
    };
    
    // Apply brand overrides if available
    if (brandTheme) {
      if (brandTheme.colors) {
        mergedTheme.colors = {
          ...mergedTheme.colors,
          ...brandTheme.colors,
        };
      }
      
      if (brandTheme.radius) {
        mergedTheme.radius = {
          ...mergedTheme.radius,
          ...brandTheme.radius,
        };
      }
      
      if (brandTheme.spacing) {
        mergedTheme.spacing = {
          ...mergedTheme.spacing,
          ...brandTheme.spacing,
        };
      }
    }
    
    return mergedTheme;
  }, [baseColorTheme, brandTheme]);
  
  // ... rest of the ThemeProvider code ...
}
```

### White-Label Hooks

Create hooks for accessing white-label configuration in components:

```typescript
// core/domains/white-label/hooks.ts
import { useEffect, useState } from 'react';
import { whiteLabelStore } from './store';
import { WhiteLabelService } from './service';
import type { BrandConfig } from './types';

/**
 * Hook to access the current brand configuration
 */
export function useWhiteLabelConfig() {
  // Get current state from store
  const brandConfig = whiteLabelStore((state) => state.brandConfig);
  
  return {
    brandId: brandConfig.id,
    brandName: brandConfig.name,
    brandTheme: brandConfig.theme,
    apiBaseUrl: brandConfig.apiBaseUrl,
    assets: brandConfig.assets,
    isFeatureEnabled: (feature: string) => {
      return !!brandConfig.features[feature];
    },
    switchBrand: WhiteLabelService.switchBrand,
  };
}

/**
 * Hook to access available brand configurations for selection
 */
export function useAvailableBrands() {
  const [brands, setBrands] = useState<{ id: string; name: string }[]>([]);
  const [loading, setLoading] = useState(true);
  
  useEffect(() => {
    async function loadBrands() {
      try {
        // In a real implementation, this would fetch from an API or config file
        const availableBrands = [
          { id: 'default', name: 'Default Brand' },
          { id: 'brandA', name: 'Brand A' },
          { id: 'brandB', name: 'Brand B' },
        ];
        
        setBrands(availableBrands);
        setLoading(false);
      } catch (error) {
        console.error('Failed to load available brands:', error);
        setLoading(false);
      }
    }
    
    loadBrands();
  }, []);
  
  return { brands, loading };
}
```

## Usage Patterns

### Brand-Specific Components

Components can consume the brand configuration to render brand-specific UI:

```typescript
// ui/components/BrandLogo.tsx
import React from 'react';
import { Image, StyleSheet, ImageStyle } from 'react-native';
import { useWhiteLabelConfig } from '@/core/domains/white-label/hooks';

interface BrandLogoProps {
  size?: 'small' | 'medium' | 'large';
  style?: ImageStyle;
}

export function BrandLogo({ size = 'medium', style }: BrandLogoProps) {
  const { assets } = useWhiteLabelConfig();
  
  // Determine logo size
  const getSize = () => {
    switch (size) {
      case 'small':
        return { width: 80, height: 40 };
      case 'large':
        return { width: 240, height: 120 };
      default:
        return { width: 160, height: 80 };
    }
  };
  
  return (
    <Image
      source={assets.logoUrl}
      style={[getSize(), styles.logo, style]}
      resizeMode="contain"
    />
  );
}

const styles = StyleSheet.create({
  logo: {
    // Any default styles
  },
});
```

### Brand Switcher UI

Create a UI component to allow users to switch between brands:

```typescript
// features/settings/BrandSwitcher.tsx
import React, { useState } from 'react';
import { View, Text, TouchableOpacity, StyleSheet, Image } from 'react-native';
import { useWhiteLabelConfig, useAvailableBrands } from '@/core/domains/white-label/hooks';

export function BrandSwitcher() {
  const { brandId, switchBrand } = useWhiteLabelConfig();
  const { brands, loading } = useAvailableBrands();
  const [switching, setSwitching] = useState(false);
  
  const handleBrandSwitch = async (id: string) => {
    if (id === brandId || switching) return;
    
    setSwitching(true);
    await switchBrand(id);
    setSwitching(false);
  };
  
  if (loading) {
    return <Text>Loading brands...</Text>;
  }
  
  return (
    <View style={styles.container}>
      <Text style={styles.title}>Select Brand</Text>
      
      {brands.map((brand) => (
        <TouchableOpacity
          key={brand.id}
          style={[styles.brandItem, brand.id === brandId && styles.selectedBrand]}
          onPress={() => handleBrandSwitch(brand.id)}
          disabled={switching}
        >
          <Text style={styles.brandName}>{brand.name}</Text>
          {brand.id === brandId && (
            <Text style={styles.activeText}>Active</Text>
          )}
        </TouchableOpacity>
      ))}
    </View>
  );
}

const styles = StyleSheet.create({
  container: {
    padding: 16,
  },
  title: {
    fontSize: 18,
    fontWeight: 'bold',
    marginBottom: 16,
  },
  brandItem: {
    flexDirection: 'row',
    justifyContent: 'space-between',
    alignItems: 'center',
    padding: 12,
    borderRadius: 8,
    marginBottom: 8,
    backgroundColor: '#f0f0f0',
  },
  selectedBrand: {
    backgroundColor: '#e0f7e0',
    borderWidth: 1,
    borderColor: '#00AA5B',
  },
  brandName: {
    fontSize: 16,
  },
  activeText: {
    color: '#00AA5B',
    fontWeight: 'bold',
  },
});
```

### Feature Flag Usage

Use white-label feature flags to conditionally enable functionality:

```typescript
// features/payments/screens/PaymentsScreen.tsx
import React from 'react';
import { View, Text } from 'react-native';
import { useWhiteLabelConfig } from '@/core/domains/white-label/hooks';
import { PaymentForm } from '../components/PaymentForm';
import { FeatureDisabled } from '@/ui/components/FeatureDisabled';

export function PaymentsScreen() {
  const { isFeatureEnabled } = useWhiteLabelConfig();
  
  // Check if payments are enabled for this brand
  if (!isFeatureEnabled('enablePayments')) {
    return (
      <FeatureDisabled 
        title="Payments Unavailable"
        message="Payment processing is not available for your account."
      />
    );
  }
  
  return (
    <View>
      <PaymentForm />
    </View>
  );
}
```

## Animation Strategies

Implement smooth animations when switching between brands:

```typescript
// core/shared/styles/AnimatedThemeProvider.tsx
import React, { useEffect, useState } from 'react';
import { Animated, StyleSheet, View } from 'react-native';
import { ThemeProvider } from './ThemeProvider';
import { useWhiteLabelConfig } from '@/core/domains/white-label/hooks';

interface Props {
  children: React.ReactNode;
}

export function AnimatedThemeProvider({ children }: Props) {
  const { brandId } = useWhiteLabelConfig();
  const [prevBrandId, setPrevBrandId] = useState(brandId);
  const [isTransitioning, setIsTransitioning] = useState(false);
  const fadeAnim = useState(new Animated.Value(1))[0];
  
  useEffect(() => {
    // Brand has changed, animate transition
    if (brandId !== prevBrandId) {
      setIsTransitioning(true);
      
      // Fade out
      Animated.timing(fadeAnim, {
        toValue: 0,
        duration: 200,
        useNativeDriver: true,
      }).start(() => {
        // Update previous brand ID after fade out
        setPrevBrandId(brandId);
        
        // Fade in with new theme
        Animated.timing(fadeAnim, {
          toValue: 1,
          duration: 300,
          useNativeDriver: true,
        }).start(() => {
          setIsTransitioning(false);
        });
      });
    }
  }, [brandId, prevBrandId, fadeAnim]);
  
  return (
    <ThemeProvider>
      <Animated.View style={[styles.container, { opacity: fadeAnim }]}>
        {children}
      </Animated.View>
    </ThemeProvider>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
  },
});
```

## Best Practices & Security

<Tabs items={["Performance", "Security", "Testing"]}>
  <Tab>
    ### Performance Considerations

    * **(Do ✅) Cache brand configurations**
      * Store loaded brand configs in memory cache
      * Persist to device storage for faster startup

    * **(Do ✅) Lazy load brand-specific assets**
      * Only load assets for the current brand
      * Consider implementing asset preloading for faster switching

    * **(Do ✅) Optimize theme merging**
      * Use memoization to prevent unnecessary re-renders
      * Only merge the specific properties that differ

    * **(Don't ❌) Load all brand assets at startup**
      * This increases bundle size and startup time
      * Instead, load dynamically as needed
  </Tab>

  <Tab>
    ### Security Considerations

    * **(Do ✅) Validate remote configurations**
      * Always validate brand configs loaded from remote sources
      * Use schema validation to prevent invalid data

    * **(Do ✅) Secure API endpoints**
      * If loading brand configs from an API, use proper authentication
      * Implement rate limiting to prevent abuse

    * **(Do ✅) Handle sensitive brand information carefully**
      * Store API keys and credentials separately from theme data
      * Use secure storage for any sensitive brand-specific data

    * **(Don't ❌) Expose internal brand identifiers**
      * Don't display internal brand IDs or configuration details to users
      * Use display names and filtered information instead
  </Tab>

  <Tab>
    ### Testing Recommendations

    * **(Do ✅) Test all brand configurations**
      * Create automated tests for each brand configuration
      * Verify that brand-specific styles are correctly applied

    * **(Do ✅) Test brand switching**
      * Verify that UI updates correctly when switching brands
      * Test persistence of brand selection across app restarts

    * **(Do ✅) Test feature flags**
      * Verify that features are correctly enabled/disabled based on brand config
      * Test the feature fallback experiences

    * **(Do ✅) Visual regression testing**
      * Implement visual comparison tests for each brand
      * Ensure UI components render correctly with different brand themes
  </Tab>
</Tabs>

## Troubleshooting

### Common Issues and Solutions

| Issue                          | Possible Cause                   | Solution                                                |
| ------------------------------ | -------------------------------- | ------------------------------------------------------- |
| Brand styles not applying      | Incorrect theme merging          | Verify theme merging logic in ThemeProvider             |
| Missing brand assets           | Incorrect path or bundling issue | Check asset paths and bundle configuration              |
| Brand selection not persisting | Storage issue                    | Verify AsyncStorage implementation and permissions      |
| Feature flags not working      | Incorrect flag naming            | Ensure feature flag names match between code and config |
| Slow brand switching           | Large asset files                | Optimize asset sizes and implement progressive loading  |

## Related Documents

### Core References

* [Theme Management Architecture](/docs/ui-development/theme-management) - Core concepts and architecture overview
* [Theme Implementation Guide](/docs/ui-development/theme-management/implementation) - Basic theming implementation

### Architecture Documents

* [App Initialization](/docs/architecture/app-initialization) - Theme initialization during app startup
* [Core Architecture](/docs/architecture/core-architecture) - Overall application architecture
* [Project Structure](/docs/architecture/project-structure) - Project organization including brand assets

### UI & Assets

* [Asset Management](/docs/ui-development/assets) - Managing theme-specific assets
* [UI Component Patterns](/docs/ui-development/component-patterns) - Building brand-aware components

<Cards>
  <Card icon={<ChevronRightIcon />} title="Theme Architecture" description="Reference document explaining core theming concepts and system design." href="/docs/ui-development/theme-management" />

  <Card icon={<ChevronRightIcon />} title="Theme Implementation" description="Guide for implementing basic theming in components." href="/docs/ui-development/theme-management/implementation" />
</Cards>

## Summary

Implementing white-label themes enables your application to dynamically adapt its visual identity based on different brand configurations. Key implementation points include:

1. Creating a standardized brand configuration structure
2. Loading brand configurations during the Pre-UI initialization stage
3. Integrating with the core theme system through theme merging
4. Providing hooks and utilities for accessing brand-specific data
5. Implementing smooth animations for brand switching

By following these patterns, you can create a flexible, maintainable white-label solution that supports multiple brands within a single codebase.


# UTA UI Development: NativeWind Theme Integration
URL: https://dev.updatetheapp.com/docs/ui-development/theme-management/nativewind-integration
Documentation: https://dev.updatetheapp.com/docs/ui-development/theme-management/nativewind-integration

Implementation guide for integrating NativeWind (TailwindCSS for React Native) with our theme management system.
        
***

title: NativeWind Theme Integration
description: Implementation guide for integrating NativeWind (TailwindCSS for React Native) with our theme management system.
-----------------------------------------------------------------------------------------------------------------------------

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Card, Cards } from 'fumadocs-ui/components/card';
import { ChevronRightIcon } from 'lucide-react';
import { Callout } from 'fumadocs-ui/components/callout';

# NativeWind Theme Integration

## Overview

This guide explains how to integrate NativeWind (TailwindCSS for React Native) with our existing theme management system. By properly configuring both systems to work together, developers can leverage the utility-first approach of TailwindCSS while maintaining the benefits of our dynamic theming architecture.

<Callout type="info">
  NativeWind brings the utility-first CSS paradigm of TailwindCSS to React Native, enabling rapid UI development with pre-defined utility classes. Our integration approach ensures that NativeWind's styling remains consistent with our theme system's values and responds correctly to theme changes.
</Callout>

## Architecture

The integration between our theme system and NativeWind is built around three key components:

1. **TailwindCSS Configuration**: Using our theme tokens as the source of truth for TailwindCSS configuration values
2. **Theme Bridge Component**: A wrapper that syncs theme changes between our system and NativeWind
3. **Styled Component Patterns**: Consistent approaches for combining both styling methods

<Mermaid
  chart={`
flowchart TD
  subgraph ThemeSystem["Our Theme System"]
      ThemeTokens[Theme Tokens<br/>colors, spacing, etc.]
      ThemeProvider[ThemeProvider]
      ThemeHooks[useTheme Hook]
  end
  
  subgraph NativeWindSystem["NativeWind System"]
      TailwindConfig[tailwind.config.js]
      NativeWindProvider[NativeWindProvider]
      ClassNames[className props]
  end
  
  subgraph Bridge["Integration Layer"]
      ThemeBridge[ThemeNativeWindBridge]
      StyleComposition[Hybrid Component Styling]
  end
  
  ThemeTokens -->|"Source of truth"| TailwindConfig
  ThemeProvider -->|"Theme changes"| ThemeBridge
  ThemeBridge -->|"Updates"| NativeWindProvider
  
  StyleComposition -->|"Uses"| ThemeHooks
  StyleComposition -->|"Uses"| ClassNames
  
  style ThemeSystem fill:#f9f,stroke:#333,stroke-width:2px
  style NativeWindSystem fill:#bbf,stroke:#333,stroke-width:2px
  style Bridge fill:#bfb,stroke:#333,stroke-width:2px
`}
/>

## Getting Started

### Prerequisites

Before integrating NativeWind with our theme system, ensure you have:

* Familiarity with our [Theme Management Architecture](/docs/ui-development/theme-management)
* Basic understanding of [TailwindCSS](https://tailwindcss.com/) concepts
* Expo or React Native project set up

### Installation and Setup

1. Install NativeWind and its peer dependencies:

```bash
npm install nativewind tailwindcss@^3.4.17 react-native-reanimated@3.16.2 react-native-safe-area-context
```

2. Initialize TailwindCSS configuration:

```bash
npx tailwindcss init
```

3. Configure Babel preset by updating your `babel.config.js`:

```js
// babel.config.js
module.exports = function (api) {
  api.cache(true);
  return {
    presets: [
      ["babel-preset-expo", { jsxImportSource: "nativewind" }],
      "nativewind/babel",
    ],
  };
};
```

## Tailwind Configuration with Theme Tokens

The first step in the integration is to configure TailwindCSS to use our theme tokens. This ensures a single source of truth for all styling values in the application.

### Basic Configuration

Update your `tailwind.config.js` file to import and use our theme tokens:

```js
// tailwind.config.js
const baseTheme = require('./src/core/shared/styles/theme');

/** @type {import('tailwindcss').Config} */
module.exports = {
  content: ["./App.tsx", "./src/**/*.{js,jsx,ts,tsx}"],
  presets: [require("nativewind/preset")],
  theme: {
    // Use our theme colors
    colors: {
      primary: baseTheme.colors.primary,
      secondary: baseTheme.colors.secondary,
      background: baseTheme.colors.background,
      text: baseTheme.colors.text,
      // Map other colors from our theme
    },
    // Use our theme spacing
    spacing: {
      xs: baseTheme.spacing.xs + 'px',
      s: baseTheme.spacing.s + 'px',
      m: baseTheme.spacing.m + 'px',
      l: baseTheme.spacing.l + 'px',
      xl: baseTheme.spacing.xl + 'px',
      // Map other spacing values
    },
    // Map other theme properties as needed
    extend: {},
  },
  plugins: [],
};
```

### Create CSS File

Create a CSS file (e.g., `global.css`) with the Tailwind directives:

```css
/* global.css */
@tailwind base;
@tailwind components;
@tailwind utilities;
```

### Configure Metro

Modify your `metro.config.js` to use NativeWind:

```js
// metro.config.js
const { getDefaultConfig } = require("expo/metro-config");
const { withNativeWind } = require('nativewind/metro');
 
const config = getDefaultConfig(__dirname)
 
module.exports = withNativeWind(config, { input: './global.css' })
```

### Import CSS File

Import the CSS file in your App component:

```tsx
// App.tsx
import "./global.css";

export default function App() {
  return (
    // Your app content
  );
}
```

### Dark Mode Configuration

Configure dark mode support to work with our theme system:

```js
// tailwind.config.js
module.exports = {
  // ... other config
  presets: [require("nativewind/preset")],
  theme: {
    // ... base theme
    extend: {
      colors: {
        // Define dark mode specific colors if needed
      }
    }
  }
};
```

## Creating a Theme Bridge

To sync theme changes between our theme system and NativeWind, we need to create a bridge component:

```tsx
// ThemeNativeWindBridge.tsx
import React, { useEffect } from 'react';
import { useTheme } from '@core/shared/styles';
import { useColorScheme } from 'nativewind';

interface ThemeNativeWindBridgeProps {
  children: React.ReactNode;
}

export function ThemeNativeWindBridge({ children }: ThemeNativeWindBridgeProps) {
  const theme = useTheme();
  const { colorScheme, setColorScheme } = useColorScheme();
  
  // When our theme changes, update NativeWind
  useEffect(() => {
    // Map our theme mode to NativeWind color scheme
    const newColorScheme = theme.mode === 'dark' ? 'dark' : 'light';
    if (colorScheme !== newColorScheme) {
      setColorScheme(newColorScheme);
    }
  }, [theme.mode, colorScheme, setColorScheme]);
  
  return <>{children}</>;
}
```

### Integration with App Structure

Place the bridge component in your application hierarchy with the NativeWindProvider:

```tsx
// App.tsx
import "./global.css";
import { ThemeProvider } from '@core/shared/styles';
import { NativeWindProvider } from 'nativewind';
import { ThemeNativeWindBridge } from './ThemeNativeWindBridge';

export default function App() {
  return (
    <ThemeProvider>
      <NativeWindProvider>
        <ThemeNativeWindBridge>
          {/* Your app content */}
        </ThemeNativeWindBridge>
      </NativeWindProvider>
    </ThemeProvider>
  );
}
```

## Component Styling Patterns

There are several approaches to combining our theme system with NativeWind in components:

### 1. NativeWind-First Approach

Use NativeWind for most styling, with our theme system for dynamic values:

```tsx
import { useTheme } from '@core/shared/styles';
import { View, Text } from 'react-native';

export function CardComponent() {
  const theme = useTheme();
  
  return (
    <View className="p-4 rounded-lg bg-white dark:bg-gray-800">
      <Text 
        className="text-lg font-bold" 
        style={{ color: theme.colors.primary }} // Dynamic value from theme
      >
        Card Title
      </Text>
      <Text className="text-gray-600 dark:text-gray-300">
        Card content goes here
      </Text>
    </View>
  );
}
```

### 2. Theme-First Approach

Use our theme system for component structure and NativeWind for utility classes:

```tsx
import { useTheme } from '@core/shared/styles';
import { StyleSheet } from 'react-native';
import { View, Text } from 'react-native';

export function CardComponent() {
  const theme = useTheme();
  const styles = StyleSheet.create({
    container: {
      backgroundColor: theme.colors.cardBackground,
      padding: theme.spacing.m,
      borderRadius: theme.radius.m,
    },
    title: {
      color: theme.colors.text,
      fontSize: theme.typography.sizes.lg,
      fontWeight: 'bold',
    },
    content: {
      color: theme.colors.textSecondary,
    },
  });
  
  return (
    <View style={styles.container} className="shadow-md">
      <Text style={styles.title}>Card Title</Text>
      <Text style={styles.content} className="mt-2">
        Card content goes here
      </Text>
    </View>
  );
}
```

### 3. Hybrid Utility Function

Create utility functions that generate styles using both systems:

```tsx
// useHybridStyles.ts
import { useTheme } from '@core/shared/styles';
import { StyleSheet } from 'react-native';
import { useColorScheme } from 'nativewind';

export function useHybridStyles() {
  const theme = useTheme();
  const { colorScheme } = useColorScheme();
  const isDark = colorScheme === 'dark';
  
  return {
    createStyles: (stylesFn) => {
      return StyleSheet.create(stylesFn(theme, isDark));
    },
    theme,
    isDark,
  };
}

// Usage in component
function MyComponent() {
  const { createStyles, isDark } = useHybridStyles();
  
  const styles = createStyles((theme, isDark) => ({
    container: {
      backgroundColor: isDark ? theme.colors.darkBackground : theme.colors.background,
      padding: theme.spacing.m,
    },
  }));
  
  return (
    <View style={styles.container} className={isDark ? "shadow-white" : "shadow-black"}>
      {/* Component content */}
    </View>
  );
}
```

## White-Label Integration

NativeWind's CSS variable system works perfectly with our white-label theming approach. Here's how to implement a complete solution:

### Configure CSS Variables in Tailwind

First, set up your Tailwind configuration to use CSS variables for theme values:

```js
// tailwind.config.js
/** @type {import('tailwindcss').Config} */
module.exports = {
  content: ["./App.tsx", "./src/**/*.{js,jsx,ts,tsx}"],
  presets: [require("nativewind/preset")],
  theme: {
    colors: {
      // Define brand colors using CSS variables
      primary: "rgb(var(--color-primary) / <alpha-value>)",
      secondary: "rgb(var(--color-secondary) / <alpha-value>)",
      background: "rgb(var(--color-background) / <alpha-value>)",
      text: "rgb(var(--color-text) / <alpha-value>)",
      // Other theme colors
    },
    // Other theme properties
  },
  plugins: [
    // Set default values
    ({ addBase }) => 
      addBase({
        ":root": {
          // Default brand colors (RGB format)
          "--color-primary": "25 118 210",     // #1976d2
          "--color-secondary": "156 39 176",   // #9c27b0
          "--color-background": "255 255 255", // #ffffff
          "--color-text": "33 33 33",          // #212121
          // Other default values
        },
      }),
  ],
};
```

### Create Brand Themes with CSS Variables

Define your brand themes using NativeWind's `vars` function:

```tsx
// BrandThemes.ts
import { vars } from 'nativewind';
import { BrandConfig } from '@core/domains/white-label/types';

// Helper to convert hex color to RGB values
function hexToRgb(hex: string): string {
  // Remove # if present
  hex = hex.replace('#', '');
  
  // Parse hex values
  const r = parseInt(hex.substring(0, 2), 16);
  const g = parseInt(hex.substring(2, 4), 16);
  const b = parseInt(hex.substring(4, 6), 16);
  
  // Return RGB string
  return `${r} ${g} ${b}`;
}

// Create theme variables for each brand
export function createBrandTheme(brandConfig: BrandConfig, isDark: boolean = false) {
  const config = isDark ? brandConfig.darkMode : brandConfig;
  
  return vars({
    '--color-primary': hexToRgb(config.colors.primary),
    '--color-secondary': hexToRgb(config.colors.secondary),
    '--color-background': hexToRgb(config.colors.background),
    '--color-text': hexToRgb(config.colors.text),
    // Other brand-specific values
  });
}
```

### Enhanced Bridge Component

Create a more robust bridge component that applies both theme mode and brand variables:

```tsx
// ThemeNativeWindBridge.tsx
import React, { useMemo } from 'react';
import { View } from 'react-native';
import { useTheme } from '@core/shared/styles';
import { useWhiteLabelConfig } from '@core/domains/white-label';
import { useColorScheme } from 'nativewind';
import { createBrandTheme } from './BrandThemes';

interface ThemeNativeWindBridgeProps {
  children: React.ReactNode;
}

export function ThemeNativeWindBridge({ children }: ThemeNativeWindBridgeProps) {
  const theme = useTheme();
  const { brandConfig } = useWhiteLabelConfig();
  const { colorScheme, setColorScheme } = useColorScheme();
  
  // Set color scheme based on theme mode
  React.useEffect(() => {
    const newColorScheme = theme.mode === 'dark' ? 'dark' : 'light';
    if (colorScheme !== newColorScheme) {
      setColorScheme(newColorScheme);
    }
  }, [theme.mode, colorScheme, setColorScheme]);
  
  // Create brand variables based on current brand and theme mode
  const brandVariables = useMemo(() => {
    const isDark = theme.mode === 'dark';
    return createBrandTheme(brandConfig, isDark);
  }, [brandConfig, theme.mode]);
  
  // Apply both color scheme and brand variables
  return (
    <View style={brandVariables} className="flex-1">
      {children}
    </View>
  );
}
```

### Using Brand Themes in Components

Now you can use your brand-aware components with NativeWind:

```tsx
// BrandAwareButton.tsx
import React from 'react';
import { Text, TouchableOpacity } from 'react-native';

interface ButtonProps {
  label: string;
  onPress: () => void;
  variant?: 'primary' | 'secondary';
}

export function BrandAwareButton({ label, onPress, variant = 'primary' }: ButtonProps) {
  const baseClasses = "py-3 px-4 rounded-md items-center justify-center";
  const variantClasses = variant === 'primary' 
    ? "bg-primary" 
    : "bg-secondary";
    
  return (
    <TouchableOpacity 
      className={`${baseClasses} ${variantClasses}`}
      onPress={onPress}
    >
      <Text className="text-white font-bold text-base">
        {label}
      </Text>
    </TouchableOpacity>
  );
}
```

## Performance Considerations

Using both styling systems together can impact performance. Here are some best practices:

### Do ✅

* Memoize styles generated from both systems
* Use `React.memo` for components with complex styling
* Prefer static NativeWind classes for unchanging styles
* Use our theme system only for truly dynamic values

```tsx
// Good example
const MemoizedCard = React.memo(function Card({ title, content }) {
  const theme = useTheme();
  // Only recalculate styles when theme changes
  const dynamicStyles = React.useMemo(() => ({
    titleColor: { color: theme.colors.primary }
  }), [theme.colors.primary]);
  
  return (
    <View className="p-4 rounded-lg bg-white dark:bg-gray-800">
      <Text className="text-lg font-bold" style={dynamicStyles.titleColor}>
        {title}
      </Text>
      <Text className="text-gray-600 dark:text-gray-300">
        {content}
      </Text>
    </View>
  );
});
```

### Don't ❌

* Mix both systems for the same style property
* Generate NativeWind classes dynamically
* Create complex conditional classes inside render functions

```tsx
// Bad example - avoid this
function Card({ title, content }) {
  const theme = useTheme();
  // This is inefficient - mixing systems and recalculating each render
  return (
    <View 
      className={`p-${theme.isCompact ? '2' : '4'} rounded-lg`} 
      style={{ backgroundColor: theme.colors.cardBackground }}
    >
      <Text style={{ color: theme.colors.text, fontSize: 18 }}>
        {title}
      </Text>
      <Text className={theme.mode === 'dark' ? 'text-gray-300' : 'text-gray-600'}>
        {content}
      </Text>
    </View>
  );
}
```

## Migration Strategy

When migrating existing components to use NativeWind, follow this approach:

1. **Start with non-dynamic components** that don't rely heavily on theme changes
2. **Incrementally adopt** NativeWind for appropriate style properties
3. **Create a style guide** for which properties should use which system

### Migration Example

<Tabs items={["Before", "After"]}>
  <Tab>
    ```tsx
    // Before: Theme-only styling
    function Button({ onPress, label }) {
      const theme = useTheme();
      const styles = StyleSheet.create({
        button: {
          backgroundColor: theme.colors.primary,
          padding: theme.spacing.m,
          borderRadius: theme.radius.m,
          alignItems: 'center',
          justifyContent: 'center',
        },
        label: {
          color: theme.colors.buttonText,
          fontSize: theme.typography.sizes.m,
          fontWeight: 'bold',
        },
      });
      
      return (
        <TouchableOpacity style={styles.button} onPress={onPress}>
          <Text style={styles.label}>{label}</Text>
        </TouchableOpacity>
      );
    }
    ```
  </Tab>

  <Tab>
    ```tsx
    // After: Hybrid styling
    function Button({ onPress, label }) {
      const theme = useTheme();
      // Only keep truly dynamic styles in the theme system
      const styles = StyleSheet.create({
        button: {
          backgroundColor: theme.colors.primary,
        },
        label: {
          color: theme.colors.buttonText,
        },
      });
      
      return (
        <TouchableOpacity 
          style={styles.button} 
          className="py-3 px-4 rounded-md items-center justify-center"
          onPress={onPress}
        >
          <Text 
            style={styles.label} 
            className="text-base font-bold"
          >
            {label}
          </Text>
        </TouchableOpacity>
      );
    }
    ```
  </Tab>
</Tabs>

## Troubleshooting

Common issues when integrating NativeWind with our theme system:

| Issue                 | Possible Cause                 | Solution                                                  |
| --------------------- | ------------------------------ | --------------------------------------------------------- |
| Styles not applying   | Babel preset not configured    | Check babel.config.js and metro.config.js                 |
| Dark mode not working | Theme bridge not updating      | Verify useEffect dependencies in bridge component         |
| Inconsistent styling  | Mixed styling approaches       | Follow the style guide for consistent property assignment |
| Performance issues    | Excessive style recalculations | Use memoization and static classes where possible         |

## Related Documents

### Core References

* [Theme Management Architecture](/docs/ui-development/theme-management) - Core concepts and architecture overview
* [Theme Implementation Guide](/docs/ui-development/theme-management/implementation) - Basic theming implementation
* [White-Label Theme Implementation](/docs/ui-development/theme-management/white-label) - Brand-specific theming

### External Resources

* [NativeWind Official Documentation](https://www.nativewind.dev/docs) - Full reference for NativeWind
* [TailwindCSS Documentation](https://tailwindcss.com/docs) - Core concepts for TailwindCSS

<Cards>
  <Card icon={<ChevronRightIcon />} title="Theme Architecture" description="Reference document explaining core theming concepts and system design." href="/docs/ui-development/theme-management" />

  <Card icon={<ChevronRightIcon />} title="Theme Implementation" description="Guide for implementing basic theming in components." href="/docs/ui-development/theme-management/implementation" />
</Cards>

## Summary

Integrating NativeWind with our theme management system provides the best of both worlds - the utility-first approach of TailwindCSS with the dynamic theming capabilities of our custom system. By following the patterns outlined in this guide, developers can create components that are both rapidly styled and responsive to theme changes.

The key to successful integration is maintaining a single source of truth for theme values while leveraging each system's strengths. With proper configuration and the bridge component in place, both systems can work together seamlessly to create a consistent, brand-aware UI experience.


# UTA UI Development: Domain Integration
URL: https://dev.updatetheapp.com/docs/ui-development/integration/domain-integration
Documentation: https://dev.updatetheapp.com/docs/ui-development/integration/domain-integration

Connecting business components with domain logic and services
        
***

title: Domain Integration
description: Connecting business components with domain logic and services
--------------------------------------------------------------------------

import { Callout } from 'fumadocs-ui/components/callout';
import { Tabs, Tab } from 'fumadocs-ui/components/tabs';

# Domain Integration

## Overview

Domain integration is a critical aspect of our UI architecture, focusing on how business components connect with domain logic and services. This guide covers patterns and best practices for maintaining clean separation of concerns while enabling effective communication between UI and domain layers.

<Mermaid
  chart={`
flowchart TD
  subgraph UI["UI Layer"]
      F["Foundation Components"] --> P
      P["Pattern Components"] --> B
      B["Business Components"] --> BS["Business State"]
  end
  
  subgraph Domains["Domain Layer"]
      D["Domain Services"] --> DH
      DH["Domain Hooks"] --> DT
      DT["Domain Types"] --> DE
      DE["Domain Events"]
  end
  
  BS <--> DH
  B --"API Calls"--> D
  B --"Event Tracking"--> DE
  
  style UI fill:#e8f5e9,stroke:#388e3c
  style Domains fill:#fff8e1,stroke:#ffa000
  style B stroke:#d50000,stroke-width:2px
  style DH stroke:#d50000,stroke-width:2px
  style BS stroke:#1976d2,stroke-width:2px
`}
/>

## Design Principles

<Tabs items={["Separation of Concerns", "Unidirectional Data Flow", "Type Safety"]}>
  <Tab>
    <Callout type="info">
      **Separation of Concerns**

      * UI components handle presentation
      * Domain services handle business logic
      * Clear boundaries between layers

      **Why it matters:** This separation ensures that UI components remain reusable across different features, while domain logic can evolve independently. It enables specialized testing strategies for each layer and makes maintenance significantly easier when requirements change.
    </Callout>
  </Tab>

  <Tab>
    <Callout type="info">
      **Unidirectional Data Flow**

      * Data flows down from domains to UI
      * Actions flow up through callbacks
      * Predictable state management

      **Why it matters:** One-way data flow creates predictable patterns that are easier to debug and test. When data only flows in one direction, side effects are minimized, and the state of the application becomes more predictable and traceable.
    </Callout>
  </Tab>

  <Tab>
    <Callout type="info">
      **Type Safety**

      * Shared types between UI and domains
      * Runtime validation where needed
      * Clear error boundaries

      **Why it matters:** Strong typing ensures that UI components correctly consume domain data and services. It provides compile-time safety, better IDE support, and makes refactoring more reliable. Runtime validation adds an extra layer of safety for data coming from external sources.
    </Callout>
  </Tab>
</Tabs>

## Integration Patterns

### 1. Domain Hooks

The most common pattern for connecting UI to domain logic:

```typescript
// core/domains/products/hooks/useProduct.ts
export function useProduct(productId: string) {
  const [product, setProduct] = useState<Product | null>(null);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState<Error | null>(null);

  useEffect(() => {
    // Domain logic for fetching product
  }, [productId]);

  return { product, loading, error };
}

// ui/business/ProductCard/ProductCard.tsx
export function ProductCard({ productId }: { productId: string }) {
  const { product, loading, error } = useProduct(productId);
  
  if (loading) return <Skeleton />;
  if (error) return <ErrorDisplay error={error} />;
  
  return (
    <Card>
      <Text>{product.name}</Text>
      <PriceTag amount={product.price} />
    </Card>
  );
}
```

### 2. Domain Services

For more complex business logic:

```typescript
// core/domains/cart/services/cartService.ts
export class CartService {
  async addItem(productId: string, quantity: number): Promise<void> {
    // Domain logic for adding items
  }
  
  async removeItem(productId: string): Promise<void> {
    // Domain logic for removing items
  }
}

// ui/business/AddToCartButton/AddToCartButton.tsx
export function AddToCartButton({ productId }: { productId: string }) {
  const cartService = useCartService();
  
  const handlePress = async () => {
    try {
      await cartService.addItem(productId, 1);
    } catch (error) {
      // Error handling
    }
  };
  
  return <Button onPress={handlePress}>Add to Cart</Button>;
}
```

### 3. Domain Events

For cross-cutting concerns:

```typescript
// core/domains/events/analytics.ts
export const analytics = {
  trackEvent: (event: AnalyticsEvent) => {
    // Event tracking logic
  }
};

// ui/business/ProductCard/ProductCard.tsx
export function ProductCard({ productId }: { productId: string }) {
  const handlePress = () => {
    analytics.trackEvent({
      type: 'product_view',
      productId
    });
  };
  
  return <Card onPress={handlePress}>...</Card>;
}
```

## Best Practices

### Do's ✅

* (Do ✅) Use domain hooks for data fetching and state management
* (Do ✅) Keep UI components focused on presentation
* (Do ✅) Handle loading and error states consistently
* (Do ✅) Use shared types between UI and domains
* (Do ✅) Implement proper error boundaries

### Don'ts ❌

* (Don't ❌) Put business logic in UI components
* (Don't ❌) Duplicate domain logic in UI layer
* (Don't ❌) Skip error handling
* (Don't ❌) Mix UI and domain concerns
* (Don't ❌) Create tight coupling between layers

## Common Challenges

### 1. Loading States

<Tabs items={["Basic", "Intermediate", "Advanced"]}>
  <Tab>
    ```typescript
    // Simple loading state
    function ProductCard({ productId }: { productId: string }) {
      const { product, loading } = useProduct(productId);
      
      if (loading) return <Skeleton />;
      return <Card>{product.name}</Card>;
    }
    ```
  </Tab>

  <Tab>
    ```typescript
    // Loading state with fallback content
    function ProductCard({ productId }: { productId: string }) {
      const { product, loading } = useProduct(productId);
      
      return (
        <Card>
          {loading ? (
            <Skeleton style={styles.skeleton} testID="product-skeleton" />
          ) : (
            <Fragment>
              <Text>{product.name}</Text>
              <PriceTag amount={product.price} />
            </Fragment>
          )}
        </Card>
      );
    }
    ```
  </Tab>

  <Tab>
    ```typescript
    // Optimistic updates with loading
    function ProductCard({ productId }: { productId: string }) {
      const { product, loading, updateProduct } = useProduct(productId);
      const [optimisticData, setOptimisticData] = useState(product);
      const [updateState, setUpdateState] = useState<'idle' | 'pending' | 'success' | 'error'>('idle');
      
      const handleUpdate = async (newData: Partial<Product>) => {
        setUpdateState('pending');
        setOptimisticData({ ...product, ...newData });
        
        try {
          await updateProduct(newData);
          setUpdateState('success');
        } catch (error) {
          // Revert optimistic update
          setOptimisticData(product);
          setUpdateState('error');
        }
      };
      
      return (
        <Card>
          {loading ? <Skeleton /> : (
            <Fragment>
              <Text>{optimisticData.name}</Text>
              {updateState === 'pending' && <ActivityIndicator size="small" />}
              {updateState === 'error' && <ErrorIndicator />}
            </Fragment>
          )}
        </Card>
      );
    }
    ```
  </Tab>
</Tabs>

### 2. Error Handling

<Tabs items={["Basic", "Intermediate", "Advanced"]}>
  <Tab>
    ```typescript
    // Simple error handling
    function ProductCard({ productId }: { productId: string }) {
      const { product, error } = useProduct(productId);
      
      if (error) return <ErrorDisplay error={error} />;
      return <Card>{product.name}</Card>;
    }
    ```
  </Tab>

  <Tab>
    ```typescript
    // Error handling with typed errors
    function ProductCard({ productId }: { productId: string }) {
      const { product, error } = useProduct(productId);
      
      if (error) {
        if (error instanceof NotFoundError) {
          return <ProductNotFound productId={productId} />;
        } else if (error instanceof NetworkError) {
          return <NetworkErrorDisplay onRetry={() => {}} />;
        }
        return <GenericErrorDisplay error={error} />;
      }
      
      return <Card>{product.name}</Card>;
    }
    ```
  </Tab>

  <Tab>
    ```typescript
    // Advanced retry logic with error handling
    function ProductCard({ productId }: { productId: string }) {
      const { product, error, retry, retryCount } = useProductWithRetry(productId, {
        maxRetries: 3,
        retryDelay: 1000,
        retryBackoff: true
      });
      
      if (error) {
        return (
          <ErrorDisplay 
            error={error}
            onRetry={retry}
            retryCount={retryCount}
            retryLimit={3}
            retryInProgress={retryCount > 0 && retryCount <= 3}
          />
        );
      }
      
      return <Card>{product.name}</Card>;
    }
    ```
  </Tab>
</Tabs>

## Testing Strategies

### 1. Unit Testing

```typescript
// ui/business/ProductCard/__tests__/ProductCard.test.tsx
describe('ProductCard', () => {
  it('displays product name', () => {
    const { getByText } = render(
      <ProductCard productId="123" />
    );
    
    expect(getByText('Test Product')).toBeTruthy();
  });
  
  it('handles loading state', () => {
    const { getByTestId } = render(
      <ProductCard productId="123" />
    );
    
    expect(getByTestId('skeleton')).toBeTruthy();
  });
});
```

### 2. Integration Testing

```typescript
// ui/business/ProductCard/__tests__/ProductCard.integration.test.tsx
describe('ProductCard Integration', () => {
  it('fetches and displays product data', async () => {
    const { getByText } = render(
      <ProductCard productId="123" />
    );
    
    await waitFor(() => {
      expect(getByText('Test Product')).toBeTruthy();
    });
  });
});
```

## Related Documents

* [Feature Integration](/docs/ui-development/integration/feature-integration) - Composing UI components within features
* [Business Components](/docs/ui-development/architecture/business-components) - Guidelines for business component development
* [Domain Architecture](/docs/architecture/domains) - Overview of domain-driven design principles
* [API Client Architecture](/docs/api/client-architecture) - How domain services communicate with APIs
* [State Management](/docs/state-management) - Patterns for managing application state


# UTA UI Development: Feature Integration
URL: https://dev.updatetheapp.com/docs/ui-development/integration/feature-integration
Documentation: https://dev.updatetheapp.com/docs/ui-development/integration/feature-integration

Composing UI components within feature modules
        
***

title: Feature Integration
description: Composing UI components within feature modules
-----------------------------------------------------------

import { Callout } from 'fumadocs-ui/components/callout';
import { Tabs, Tab } from 'fumadocs-ui/components/tabs';
import { Steps, Step } from 'fumadocs-ui/components/steps';

# Feature Integration

## Overview

Feature integration focuses on composing UI components within feature modules, ensuring proper organization and maintainability. This guide covers patterns for structuring feature-specific UI components and their integration with the broader application architecture.

<Mermaid
  chart={`
flowchart TD
  subgraph FeatMod["Feature Module"]
      direction TB
      Nav["Feature Navigator"] --> Screens
      subgraph Screens["Screens"]
          S1["ListScreen"] --> FC1
          S2["DetailScreen"] --> FC1
          S2 --> FC2
      end
      
      subgraph FeatComp["Feature Components"]
          FC1["FilterPanel"] --> FC3
          FC2["DetailHeader"] --> FC3
          FC3["FeatureState"] --> H
      end
      
      H["Feature Hooks"]  
  end
  
  subgraph Shared["Shared UI Components"]
      BC["Business Components"] --> PC
      PC["Pattern Components"] --> FC
      FC["Foundation Components"]
  end
  
  Screens --> BC
  FeatComp --> BC
  
  style FeatMod fill:#fce4ec,stroke:#c2185b
  style Shared fill:#e3f2fd,stroke:#1976d2
  style Screens stroke:#d50000,stroke-width:2px
  style BC stroke:#d50000,stroke-width:2px
`}
/>

## Design Principles

<Tabs items={["Feature Encapsulation", "Component Composition", "Navigation Integration"]}>
  <Tab>
    <Callout type="info">
      **Feature Encapsulation**

      * Feature-specific UI components stay within feature boundaries
      * Clear separation between feature and shared components
      * Feature-specific state management

      **Why it matters:** Encapsulation ensures features can be developed, tested, and maintained independently. It prevents tight coupling between features, allows for parallel development, and makes features more portable. Well-encapsulated features can often be toggled on/off without affecting the rest of the application.
    </Callout>
  </Tab>

  <Tab>
    <Callout type="info">
      **Component Composition**

      * Build features from reusable business components
      * Leverage pattern components for common UI patterns
      * Use foundation components for basic UI elements

      **Why it matters:** Composition encourages reuse of existing components rather than creating feature-specific duplicates. This reduces code duplication, ensures consistency across the application, and speeds up development. When features share common components, changes to those components propagate consistently across all features.
    </Callout>
  </Tab>

  <Tab>
    <Callout type="info">
      **Navigation Integration**

      * Feature-specific navigation patterns
      * Deep linking support
      * Screen transitions and animations

      **Why it matters:** Well-designed navigation patterns ensure a cohesive user experience while keeping navigation logic organized. Feature-specific navigation can still integrate with the application's global navigation system while maintaining independent routing logic. This approach enables features to handle their own deep linking and transition animations.
    </Callout>
  </Tab>
</Tabs>

## Feature Structure

### Directory Organization

```
features/
└── product-catalog/
    ├── screens/
    │   ├── ProductListScreen.tsx
    │   ├── ProductDetailScreen.tsx
    │   └── index.ts
    ├── components/
    │   ├── ProductFilter.tsx
    │   ├── ProductSort.tsx
    │   └── index.ts
    ├── hooks/
    │   ├── useProductList.ts
    │   └── useProductFilter.ts
    ├── navigation/
    │   └── ProductCatalogNavigator.tsx
    └── index.ts
```

### Component Integration

```typescript
// features/product-catalog/screens/ProductListScreen.tsx
import { ProductCard } from '@/ui/business/ProductCard';
import { SearchBox } from '@/ui/patterns/SearchBox';
import { useProductList } from '../hooks/useProductList';

export function ProductListScreen() {
  const { products, loading, error } = useProductList();
  
  return (
    <Screen>
      <SearchBox />
      <ProductList>
        {products.map(product => (
          <ProductCard
            key={product.id}
            productId={product.id}
          />
        ))}
      </ProductList>
    </Screen>
  );
}
```

## Integration Patterns

### 1. Feature-Specific Components

<Tabs items={["Basic", "Advanced"]}>
  <Tab>
    ```typescript
    // features/product-catalog/components/ProductFilter.tsx
    import { FilterButton } from '@/ui/patterns/FilterButton';
    import { useProductFilter } from '../hooks/useProductFilter';

    export function ProductFilter() {
      const { filters, setFilter } = useProductFilter();
      
      return (
        <View>
          {filters.map(filter => (
            <FilterButton
              key={filter.id}
              active={filter.active}
              onPress={() => setFilter(filter.id)}
            >
              {filter.label}
            </FilterButton>
          ))}
        </View>
      );
    }
    ```
  </Tab>

  <Tab>
    ```typescript
    // features/product-catalog/components/ProductFilter.tsx
    import { FilterButton } from '@/ui/patterns/FilterButton';
    import { useProductFilter } from '../hooks/useProductFilter';
    import { useAnalytics } from '@/core/domains/analytics/hooks';

    export function ProductFilter() {
      const { filters, setFilter } = useProductFilter();
      const analytics = useAnalytics();
      
      const handleFilterPress = (filterId: string) => {
        analytics.trackEvent({
          type: 'filter_apply',
          filterId
        });
        setFilter(filterId);
      };
      
      return (
        <View>
          {filters.map(filter => (
            <FilterButton
              key={filter.id}
              active={filter.active}
              onPress={() => handleFilterPress(filter.id)}
            >
              {filter.label}
            </FilterButton>
          ))}
        </View>
      );
    }
    ```
  </Tab>
</Tabs>

### 2. Navigation Integration

```typescript
// features/product-catalog/navigation/ProductCatalogNavigator.tsx
import { createStackNavigator } from '@react-navigation/stack';
import { ProductListScreen } from '../screens/ProductListScreen';
import { ProductDetailScreen } from '../screens/ProductDetailScreen';

const Stack = createStackNavigator();

export function ProductCatalogNavigator() {
  return (
    <Stack.Navigator>
      <Stack.Screen
        name="ProductList"
        component={ProductListScreen}
        options={{
          title: 'Products'
        }}
      />
      <Stack.Screen
        name="ProductDetail"
        component={ProductDetailScreen}
        options={{
          title: 'Product Details'
        }}
      />
    </Stack.Navigator>
  );
}
```

### 3. State Management

```typescript
// features/product-catalog/hooks/useProductList.ts
import { useState, useEffect } from 'react';
import { useProducts } from '@/core/domains/products/hooks';

export function useProductList() {
  const [filters, setFilters] = useState<ProductFilter[]>([]);
  const { products, loading, error } = useProducts();
  
  const filteredProducts = useMemo(() => {
    return products.filter(product => 
      filters.every(filter => filter.predicate(product))
    );
  }, [products, filters]);
  
  return {
    products: filteredProducts,
    loading,
    error,
    filters,
    setFilters
  };
}
```

## Best Practices

### Do's ✅

* (Do ✅) Keep feature-specific components within feature boundaries
* (Do ✅) Use business components for domain integration
* (Do ✅) Implement proper loading and error states
* (Do ✅) Follow consistent navigation patterns
* (Do ✅) Maintain clear component hierarchy

### Don'ts ❌

* (Don't ❌) Create feature-specific foundation components
* (Don't ❌) Duplicate business logic in feature components
* (Don't ❌) Mix feature-specific and shared state
* (Don't ❌) Skip proper error handling
* (Don't ❌) Create tight coupling between features

## Testing Strategies

<Steps>
  <Step title="Feature Component Testing">
    ```typescript
    // features/product-catalog/components/__tests__/ProductFilter.test.tsx
    describe('ProductFilter', () => {
      it('applies filter when button is pressed', () => {
        const { getByText } = render(<ProductFilter />);
        
        fireEvent.press(getByText('Price: Low to High'));
        
        expect(getByText('Price: Low to High')).toHaveStyle({
          backgroundColor: expect.any(String)
        });
      });
      
      it('tracks filter usage with analytics', () => {
        const mockAnalytics = jest.spyOn(analyticsService, 'trackEvent');
        const { getByText } = render(<ProductFilter />);
        
        fireEvent.press(getByText('Price: Low to High'));
        
        expect(mockAnalytics).toHaveBeenCalledWith({
          type: 'filter_apply',
          filterId: 'price_low_to_high'
        });
      });
    });
    ```
  </Step>

  <Step title="Screen Integration Testing">
    ```typescript
    // features/product-catalog/screens/__tests__/ProductListScreen.test.tsx
    describe('ProductListScreen', () => {
      it('navigates to product detail on press', () => {
        const { getByTestId } = render(<ProductListScreen />);
        
        fireEvent.press(getByTestId('product-card-123'));
        
        expect(mockNavigation.navigate).toHaveBeenCalledWith(
          'ProductDetail',
          { productId: '123' }
        );
      });
      
      it('displays products from domain hook', async () => {
        // Mock domain hook response
        useProducts.mockReturnValue({
          products: mockProducts,
          loading: false
        });
        
        const { getAllByTestId } = render(<ProductListScreen />);
        
        await waitFor(() => {
          expect(getAllByTestId('product-card')).toHaveLength(mockProducts.length);
        });
      });
    });
    ```
  </Step>

  <Step title="Feature Navigation Testing">
    ```typescript
    // features/product-catalog/navigation/__tests__/ProductCatalogNavigator.test.tsx
    describe('ProductCatalogNavigator', () => {
      it('renders the correct initial screen', () => {
        const { getByTestId } = render(<ProductCatalogNavigator />);
        
        expect(getByTestId('product-list-screen')).toBeTruthy();
      });
      
      it('handles deep linking correctly', () => {
        const { getByText } = render(
          <NavigationContainer linking={linkingConfig}>
            <ProductCatalogNavigator />
          </NavigationContainer>
        );
        
        // Simulate deep link
        const { getState } = navigationRef.current;
        const state = getState();
        
        expect(state.routes[0].name).toBe('ProductDetail');
        expect(state.routes[0].params).toEqual({ productId: '123' });
      });
    });
    ```
  </Step>
</Steps>

## Related Documents

* [Domain Integration](/docs/ui-development/integration/domain-integration) - Connecting with domain logic
* [Navigation Patterns](/docs/ui-development/architecture/navigation) - Navigation architecture
* [Feature Architecture](/docs/architecture/features) - Feature module organization
* [Business Components](/docs/ui-development/architecture/business-components) - Business component development guidelines
* [State Management](/docs/state-management) - Managing application state
* [Performance Optimization](/docs/performance/optimization) - Optimizing feature performance


# UTA Feature Development: Communication Patterns
URL: https://dev.updatetheapp.com/docs/features/communication-patterns
Documentation: https://dev.updatetheapp.com/docs/features/communication-patterns

Guide to communication patterns between features, domains, and system components.
        
***

title: Communication Patterns
description: Guide to communication patterns between features, domains, and system components.
----------------------------------------------------------------------------------------------

# Communication Patterns

## Overview

This document outlines the various communication patterns available in our architecture for cross-feature and cross-domain communication. It provides guidelines on when and how to use each pattern while maintaining clean module boundaries.

## Purpose & Scope

This guide helps developers understand:

* Available communication methods
* When to use each pattern
* Implementation examples
* Best practices for maintaining loose coupling

## Communication Overview

Our architecture supports four primary communication patterns:

import { Card, Cards } from 'fumadocs-ui/components/card';
import { ChevronRightIcon } from 'lucide-react';

<Cards>
  <Card icon={<ChevronRightIcon />} title="Domain Services" description="Shared hooks and API services for accessing domain data across features." href="#pattern-1-domain-services" />

  <Card icon={<ChevronRightIcon />} title="Event System" description="Publish-subscribe pattern for loose coupling between components." href="#pattern-2-event-system" />

  <Card icon={<ChevronRightIcon />} title="Shared State" description="Server state via TanStack Query and client state via Zustand." href="#pattern-3-shared-state" />

  <Card icon={<ChevronRightIcon />} title="Navigation Parameters" description="Passing data between screens through navigation parameters." href="#pattern-4-navigation-parameters" />
</Cards>

<Mermaid
  chart={`
flowchart TD
subgraph Features[Feature Modules]
  FeatureA[Feature A]
  FeatureB[Feature B]
  FeatureC[Feature C]
end

subgraph Communication[Communication Patterns]
  Domains[Domain Services]
  Events[Event System]
  State[Shared State]
  Navigation[Navigation]
end

FeatureA --> Domains
FeatureA --> Events
FeatureA --> State
FeatureA --> Navigation

Domains --> FeatureB
Events --> FeatureB
State --> FeatureB
Navigation --> FeatureB

Domains --> FeatureC
Events --> FeatureC
State --> FeatureC
Navigation --> FeatureC

style Domains fill:#f9f,stroke:#333,stroke-width:2px
style Events fill:#bbf,stroke:#333,stroke-width:2px
style State fill:#bfb,stroke:#333,stroke-width:2px
style Navigation fill:#fbb,stroke:#333,stroke-width:2px
`}
/>

* **Domain Services** - Shared hooks and API services
* **Event System** - Publish-subscribe pattern
* **Shared State** - Query cache and global state
* **Navigation Parameters** - Data passing through navigation

## Pattern 1: Domain Services

### Overview

Features access shared business logic through domain hooks and services, maintaining a clean separation between UI and business logic.

<Mermaid
  chart={`
sequenceDiagram
participant F as Feature Component
participant H as Domain Hook
participant S as Domain Service
participant A as API Client
participant B as Backend

F->>H: useProducts()
H->>S: getProducts()
S->>A: client.get('/products')
A->>B: HTTP Request
B-->>A: HTTP Response
A-->>S: Response Data
S-->>H: Processed Data
H-->>F: Cached & Typed Data
`}
/>

### When to Use

* Accessing domain data (products, users, orders)
* Performing business operations
* Sharing data between features

### Benefits

* Type-safe data access
* Shared caching through TanStack Query
* Consistent data across features
* Clear separation of concerns

### Implementation

```typescript
// features/product-catalog/screens/ProductListScreen.tsx
import { useProducts } from '@/core/domains/products/hooks';
import { formatCurrency } from '@/core/shared/utils/number';

export function ProductListScreen() {
  const { data: products, isLoading } = useProducts();
  
  return (
    <FlatList
      data={products}
      renderItem={({ item }) => (
        <ProductCard
          product={item}
          price={formatCurrency(item.price)}
        />
      )}
    />
  );
}
```

```typescript
// features/shopping-cart/components/CartSummary.tsx
import { useCart } from '@/core/domains/cart/hooks';
import { useProducts } from '@/core/domains/products/hooks';

export function CartSummary() {
  const { data: cart } = useCart();
  const { data: products } = useProducts();
  
  const cartItems = cart?.items.map(item => {
    const product = products?.find(p => p.id === item.productId);
    return { ...item, product };
  });
  
  // Render cart with product details
}
```

### Benefits

* Type-safe data access
* Shared caching through TanStack Query
* Consistent data across features

## Pattern 2: Event System

### Overview

A publish-subscribe pattern for loose coupling between components that shouldn't directly depend on each other.

<Mermaid
  chart={`
flowchart LR
subgraph Publishers[Event Publishers]
  AuthService[Auth Service]
  PushNotification[Push Notification Service]
  SocketService[WebSocket Service]
end

subgraph EventBus[Event Bus]
  EventEmitter[Event Emitter]
end

subgraph Subscribers[Event Subscribers]
  AppComponent[App Component]
  ProfileFeature[Profile Feature]
  CartFeature[Cart Feature]
end

AuthService -->|emit| EventEmitter
PushNotification -->|emit| EventEmitter
SocketService -->|emit| EventEmitter

EventEmitter -->|subscribe| AppComponent
EventEmitter -->|subscribe| ProfileFeature
EventEmitter -->|subscribe| CartFeature

style EventEmitter fill:#bbf,stroke:#333,stroke-width:2px
`}
/>

### When to Use

* System-wide notifications
* Authentication state changes
* Real-time updates
* Cross-domain reactions

### Benefits

* Loose coupling between components
* Flexibility to add new subscribers
* Supports one-to-many communication
* Allows cross-feature coordination

### Implementation

```typescript
// core/shared/utils/events.ts
export class EventEmitter<T extends Record<string, any>> {
  private listeners = new Map<keyof T, Set<(data: any) => void>>();

  on<K extends keyof T>(
    event: K,
    listener: (data: T[K]) => void
  ): () => void {
    if (!this.listeners.has(event)) {
      this.listeners.set(event, new Set());
    }
    this.listeners.get(event)!.add(listener);
    
    // Return unsubscribe function
    return () => {
      this.listeners.get(event)?.delete(listener);
    };
  }

  emit<K extends keyof T>(event: K, data: T[K]): void {
    this.listeners.get(event)?.forEach(listener => listener(data));
  }
}
```

```typescript
// core/domains/auth/events.ts
export type AuthEvents = {
  'auth:login': { userId: string; token: string };
  'auth:logout': void;
  'auth:sessionExpired': void;
  'auth:tokenRefreshed': { accessToken: string };
};

export const authEvents = new EventEmitter<AuthEvents>();
```

```typescript
// Usage in features
import { authEvents } from '@/core/domains/auth/events';

// In App.tsx
useEffect(() => {
  const unsubscribe = authEvents.on('auth:sessionExpired', () => {
    navigation.reset({
      index: 0,
      routes: [{ name: 'Login' }],
    });
  });
  
  return unsubscribe;
}, [navigation]);

// In auth domain
authEvents.emit('auth:sessionExpired');
```

### Benefits

* Loose coupling between components
* System-wide event handling
* Clean separation of concerns

## Pattern 3: Shared State

### Overview

Shared state includes both server state via TanStack Query's caching layer and client state via Zustand stores.

<Mermaid
  chart={`
flowchart TD
subgraph ServerState[Server State]
  QueryCache[TanStack Query Cache]
  QueryClient[Query Client]
end

subgraph ClientState[Client State]
  Store1[Auth Store]
  Store2[UI Store]
  Store3[Settings Store]
end

subgraph Features[Feature Modules]
  Feature1[Feature A]
  Feature2[Feature B]
  Feature3[Feature C]
end

QueryCache --> QueryClient
QueryClient --> QueryCache

Feature1 --> QueryClient
QueryClient --> Feature1
Feature2 --> QueryClient
QueryClient --> Feature2
Feature3 --> QueryClient
QueryClient --> Feature3

Feature1 --> Store1
Store1 --> Feature1
Feature1 --> Store2
Store2 --> Feature1
Feature2 --> Store1
Store1 --> Feature2
Feature2 --> Store3
Store3 --> Feature2
Feature3 --> Store2
Store2 --> Feature3
Feature3 --> Store3
Store3 --> Feature3

style QueryCache fill:#bfb,stroke:#333,stroke-width:2px
style Store1 fill:#bfb,stroke:#333,stroke-width:2px
style Store2 fill:#bfb,stroke:#333,stroke-width:2px
style Store3 fill:#bfb,stroke:#333,stroke-width:2px
`}
/>

### When to Use

* Persistent data from API responses (TanStack Query)
* Global UI state (modals, themes, etc.)
* User preferences
* Cached data needed across features

### Benefits

* Automatic data synchronization
* Built-in caching and invalidation
* Persistent state across app reloads
* Optimized rendering performance for state that needs to be accessible across features.
* Session information

### Implementation

#### Via Query Cache

```typescript
// Sharing data through TanStack Query cache
import { useQueryClient } from '@tanstack/react-query';
import { productQueryKeys } from '@/core/domains/products/queryKeys';

export function useSharedProductData() {
  const queryClient = useQueryClient();
  
  // Read from cache
  const cachedProducts = queryClient.getQueryData(
    productQueryKeys.all()
  );
  
  // Invalidate to trigger refetch
  const refreshProducts = () => {
    queryClient.invalidateQueries({
      queryKey: productQueryKeys.all()
    });
  };
  
  return { cachedProducts, refreshProducts };
}
```

#### Via Global Store

```typescript
// core/shared/store/appStore.ts
import { create } from 'zustand';

interface AppState {
  theme: 'light' | 'dark';
  isOffline: boolean;
  setTheme: (theme: 'light' | 'dark') => void;
  setOfflineStatus: (status: boolean) => void;
}

export const useAppStore = create<AppState>((set) => ({
  theme: 'light',
  isOffline: false,
  setTheme: (theme) => set({ theme }),
  setOfflineStatus: (status) => set({ isOffline: status }),
}));
```

### Benefits

* Efficient data sharing
* Automatic synchronization
* Reduced API calls

## Pattern 4: Navigation Parameters

### Overview

Passing data between screens through navigation parameters.

<Mermaid
  chart={`
sequenceDiagram
participant ProductList as ProductList Screen
participant Navigation as Navigation Container
participant ProductDetail as ProductDetail Screen
participant ProductData as Product Domain

ProductList->>Navigation: navigate('ProductDetail', { productId: '123' })
Navigation->>ProductDetail: Route params: { productId: '123' }
ProductDetail->>ProductDetail: const { productId } = useRoute().params
ProductDetail->>ProductData: useProduct(productId)
ProductData-->>ProductDetail: Product data

Note over ProductList,ProductDetail: Directly pass minimal identifiers
`}
/>

### When to Use

* Screen-to-screen data transfer
* Deep linking with parameters
* Temporary state during navigation flow

### Benefits

* Decoupled screen implementations
* Support for deep linking
* Type-safe data passing
* Maintains clear navigation history

### Implementation

```typescript
// Navigation types
export type RootStackParamList = {
  ProductList: undefined;
  ProductDetail: { productId: string };
  CartReview: { items: CartItem[] };
};

// Navigating with params
navigation.navigate('ProductDetail', { 
  productId: product.id 
});

// Receiving params
export function ProductDetailScreen({ route }: Props) {
  const { productId } = route.params;
  const { data: product } = useProduct(productId);
  
  return <ProductDetails product={product} />;
}
```

### Benefits

* Type-safe parameter passing
* Works with deep linking
* Clear data flow

## Choosing the Right Pattern

Use this decision tree to select the appropriate communication pattern:

```
Need to share data between features?
├─ Is it domain data?
│  └─ YES → Use Domain Services (hooks)
├─ Is it a system event?
│  └─ YES → Use Event System
├─ Is it global app state?
│  └─ YES → Use Shared State (store/cache)
└─ Is it navigation-related?
   └─ YES → Use Navigation Parameters
```

## Anti-Patterns to Avoid

### 1. Direct Feature Imports

❌ **Wrong**: Features importing from each other

```typescript
// features/cart/components/CartItem.tsx
import { ProductCard } from '@/features/products/components'; // Don't do this!
```

✅ **Correct**: Use shared UI components

```typescript
// ui/ProductCard/ProductCard.tsx
export function ProductCard({ product }: Props) { }

// features/cart/components/CartItem.tsx
import { ProductCard } from '@/ui/ProductCard';
```

### 2. Prop Drilling

❌ **Wrong**: Passing data through multiple levels

```typescript
<App userData={userData}>
  <Screen userData={userData}>
    <Component userData={userData}>
      <DeepChild userData={userData} />
    </Component>
  </Screen>
</App>
```

✅ **Correct**: Use appropriate state management

```typescript
// Use domain hooks or global state
const { data: userData } = useCurrentUser();
```

### 3. Circular Dependencies

❌ **Wrong**: Domains depending on each other

```typescript
// core/domains/products/hooks.ts
import { useUser } from '@/core/domains/users/hooks'; // Avoid!

// core/domains/users/hooks.ts
import { useProducts } from '@/core/domains/products/hooks'; // Circular!
```

✅ **Correct**: Compose in features

```typescript
// features/product-detail/screens/ProductDetailScreen.tsx
const { data: product } = useProduct(id);
const { data: owner } = useUser(product?.ownerId);
```

## Best Practices

### 1. Keep Communication Minimal

* Only share what's necessary
* Prefer local state when possible
* Avoid over-engineering

### 2. Document Communication Points

```typescript
/**
 * Emits 'product:stockUpdate' event when stock changes
 * Listens to 'order:completed' to update stock
 */
export function useProductStock() {
  // Implementation
}
```

### 3. Type Everything

```typescript
// Define event types
type ProductEvents = {
  'product:created': { id: string };
  'product:updated': { id: string; changes: Partial<Product> };
  'product:deleted': { id: string };
};

// Define navigation params
type NavigationParams = {
  ProductDetail: { productId: string; referrer?: string };
};
```

### 4. Handle Errors Gracefully

```typescript
// Event handling with error boundaries
try {
  eventEmitter.emit('user:login', { userId });
} catch (error) {
  console.error('Failed to emit login event:', error);
  // Handle error appropriately
}
```

## Examples by Use Case

### User Authentication Flow

```typescript
// 1. Login action in auth domain
export function useLogin() {
  return useMutation({
    mutationFn: authApi.login,
    onSuccess: (data) => {
      // Update auth store
      authStore.setTokens(data.tokens);
      
      // Emit login event
      authEvents.emit('auth:login', {
        userId: data.user.id,
        token: data.tokens.access,
      });
      
      // Navigate to home
      navigation.reset({
        index: 0,
        routes: [{ name: 'Home' }],
      });
    },
  });
}

// 2. Listen in App.tsx for navigation
useEffect(() => {
  const unsubscribe = authEvents.on('auth:logout', () => {
    navigation.reset({
      index: 0,
      routes: [{ name: 'Login' }],
    });
  });
  
  return unsubscribe;
}, []);

// 3. Listen in features for data clearing
useEffect(() => {
  const unsubscribe = authEvents.on('auth:logout', () => {
    queryClient.clear();
  });
  
  return unsubscribe;
}, []);
```

### Real-time Product Updates

```typescript
// 1. WebSocket connection in domain
// core/domains/products/realtime.ts
export function useProductUpdates() {
  useEffect(() => {
    const ws = new WebSocket(PRODUCT_WS_URL);
    
    ws.onmessage = (event) => {
      const update = JSON.parse(event.data);
      
      // Update cache
      queryClient.setQueryData(
        productQueryKeys.detail(update.id),
        update
      );
      
      // Emit event
      productEvents.emit('product:updated', update);
    };
    
    return () => ws.close();
  }, []);
}

// 2. Listen in features
export function ProductListItem({ productId }: Props) {
  const [highlighted, setHighlighted] = useState(false);
  
  useEffect(() => {
    const unsubscribe = productEvents.on(
      'product:updated',
      (update) => {
        if (update.id === productId) {
          setHighlighted(true);
          setTimeout(() => setHighlighted(false), 2000);
        }
      }
    );
    
    return unsubscribe;
  }, [productId]);
}
```

## Testing Communication

### Testing Events

```typescript
import { authEvents } from '@/core/domains/auth/events';

describe('Auth Events', () => {
  it('should emit login event', () => {
    const listener = jest.fn();
    authEvents.on('auth:login', listener);
    
    authEvents.emit('auth:login', {
      userId: '123',
      token: 'abc',
    });
    
    expect(listener).toHaveBeenCalledWith({
      userId: '123',
      token: 'abc',
    });
  });
});
```

### Testing Navigation

```typescript
import { NavigationContainer } from '@react-navigation/native';
import { render, fireEvent } from '@testing-library/react-native';

describe('Navigation', () => {
  it('should navigate with params', () => {
    const { getByText } = render(
      <NavigationContainer>
        <ProductListScreen />
      </NavigationContainer>
    );
    
    fireEvent.press(getByText('Product 1'));
    
    expect(mockNavigate).toHaveBeenCalledWith(
      'ProductDetail',
      { productId: '1' }
    );
  });
});
```

## Design Principles

### Core Architectural Principles

1. **Loose Coupling**
   * Features should not be directly dependent on each other
   * Communication should occur through well-defined interfaces
   * Implementation details should be hidden behind abstractions

2. **Clear Boundaries**
   * Feature modules must maintain strict boundaries
   * Communication across boundaries should be explicit and controlled
   * No circular dependencies between features

3. **Single Responsibility**
   * Each communication pattern serves a specific purpose
   * The pattern chosen should match the type of data being shared
   * Complex flows should be decomposed into manageable parts

### Trade-offs and Design Decisions

| Pattern         | Benefits                  | Drawbacks                      | When To Choose                         |
| --------------- | ------------------------- | ------------------------------ | -------------------------------------- |
| Domain Services | Type-safe, shared caching | Can create domain dependencies | For domain data that needs persistence |
| Event System    | Loose coupling, flexible  | Harder to trace, debug         | For system-wide notifications          |
| Shared State    | Centralized, reactive     | Potential for overuse          | For truly global state                 |
| Navigation      | Simple, direct            | Limited to screen flow         | For screen-to-screen transitions       |

### Constraints and Considerations

* Features must never import directly from other features
* Communication patterns should be used consistently across the app
* Performance implications must be considered for each pattern
* Type safety should be maintained across all communication boundaries

## Implementation Considerations

### Performance Implications

* **Domain Services**: Use staleTime and cacheTime to optimize refetching
* **Event System**: Limit subscribers to avoid memory leaks
* **Shared State**: Be selective about what goes into global state
* **Navigation**: Pass IDs rather than large objects between screens

### Security Considerations

* **Domain Services**: Validate data at domain boundaries
* **Event System**: Don't emit sensitive data in events
* **Shared State**: Be cautious about storing sensitive information
* **Navigation**: Sanitize parameters from deep links

### Scalability Aspects

* **Domain Services**: Scale well with additional domains
* **Event System**: Use namespaced events for growing systems
* **Shared State**: Split into domain-specific stores as app grows
* **Navigation**: Use nested navigators for complex flows

## Summary

Our communication patterns provide flexible options for different scenarios:

1. **Domain Services**: Primary method for data access
2. **Events**: System-wide notifications and reactions
3. **Shared State**: Cached data and global state
4. **Navigation**: Screen-to-screen data passing

Choose the simplest pattern that meets your needs and maintain clear boundaries between features.

## Related Documents

* [Core Architecture](/docs/architecture/core-architecture) - Overview of the application's hybrid architecture
* [Project Structure](/docs/architecture/project-structure) - Directory structure and organization
* [State Management](/docs/state-management) - Detailed state management patterns
* [API Integration](/docs/api/client-architecture) - API client implementation patterns
* [Testing Guide](/docs/guides/testing)


# UTA Feature Development: Shared Utilities Guide
URL: https://dev.updatetheapp.com/docs/features/shared-utilities
Documentation: https://dev.updatetheapp.com/docs/features/shared-utilities

Guidelines for organizing and using shared hooks, utilities, and types versus domain-specific code.
        
***

title: Shared Utilities Guide
description: Guidelines for organizing and using shared hooks, utilities, and types versus domain-specific code.
----------------------------------------------------------------------------------------------------------------

# Shared Utilities Guide

## Overview

This guide provides clear rules and examples for organizing shared hooks, utilities, and types in `core/shared/` versus domain-specific code in `core/domains/`. It ensures clean architecture boundaries and prevents mixing domain logic with truly reusable utilities.

## Purpose & Scope

This guide helps developers make correct decisions about where to place code, maintaining the distinction between:

* Generic, reusable utilities that belong in `core/shared/`
* Domain-specific logic that belongs in `core/domains/[domain]/`

## Shared Hooks (`core/shared/hooks/`)

### What Belongs Here

Generic React hooks that:

* Are truly reusable across multiple features/domains
* Contain no business logic or domain knowledge
* Don't depend on domain types or APIs

### Examples of Shared Hooks

```typescript
// core/shared/hooks/useDebounce.ts
import { useState, useEffect } from 'react';

export function useDebounce<T>(value: T, delay: number): T {
  const [debouncedValue, setDebouncedValue] = useState<T>(value);

  useEffect(() => {
    const handler = setTimeout(() => {
      setDebouncedValue(value);
    }, delay);

    return () => {
      clearTimeout(handler);
    };
  }, [value, delay]);

  return debouncedValue;
}
```

```typescript
// core/shared/hooks/useLocalStorage.ts
import { useState, useEffect } from 'react';

export function useLocalStorage<T>(
  key: string,
  initialValue: T
): [T, (value: T) => void] {
  const [storedValue, setStoredValue] = useState<T>(() => {
    try {
      const item = window.localStorage.getItem(key);
      return item ? JSON.parse(item) : initialValue;
    } catch (error) {
      console.error(`Error loading localStorage key "${key}":`, error);
      return initialValue;
    }
  });

  const setValue = (value: T) => {
    try {
      setStoredValue(value);
      window.localStorage.setItem(key, JSON.stringify(value));
    } catch (error) {
      console.error(`Error setting localStorage key "${key}":`, error);
    }
  };

  return [storedValue, setValue];
}
```

```typescript
// core/shared/hooks/useMediaQuery.ts
import { useState, useEffect } from 'react';

export function useMediaQuery(query: string): boolean {
  const [matches, setMatches] = useState(false);

  useEffect(() => {
    const media = window.matchMedia(query);
    setMatches(media.matches);

    const listener = (event: MediaQueryListEvent) => {
      setMatches(event.matches);
    };

    media.addEventListener('change', listener);
    return () => media.removeEventListener('change', listener);
  }, [query]);

  return matches;
}
```

### What DOESN'T Belong Here

Domain-specific hooks that should stay in `core/domains/[domain]/hooks.ts`:

```typescript
// ❌ WRONG: This belongs in core/domains/products/hooks.ts
export function useProducts() {
  return useQuery({
    queryKey: ['products'],
    queryFn: productApi.getAll
  });
}

// ❌ WRONG: This belongs in core/domains/auth/hooks.ts  
export function useCurrentUser() {
  return useQuery({
    queryKey: ['currentUser'],
    queryFn: authApi.getCurrentUser
  });
}
```

## Shared Utilities (`core/shared/utils/`)

### What Belongs Here

General-purpose JavaScript/TypeScript functions that:

* Have no domain-specific logic
* Don't depend on React or domain types
* Are useful across multiple features/domains

### Organization

```
core/shared/utils/
├── date.ts           # Date formatting and manipulation
├── string.ts         # String utilities
├── number.ts         # Number formatting and calculations
├── validation.ts     # Generic validators
├── array.ts          # Array utilities
└── index.ts         # Barrel exports
```

### Examples of Shared Utilities

```typescript
// core/shared/utils/date.ts
export function formatDate(date: Date, format: string = 'MM/dd/yyyy'): string {
  // Implementation
  return formattedDate;
}

export function addDays(date: Date, days: number): Date {
  const result = new Date(date);
  result.setDate(result.getDate() + days);
  return result;
}

export function isDateInPast(date: Date): boolean {
  return date < new Date();
}
```

```typescript
// core/shared/utils/string.ts
export function capitalizeFirst(str: string): string {
  return str.charAt(0).toUpperCase() + str.slice(1);
}

export function truncate(str: string, maxLength: number): string {
  return str.length > maxLength ? `${str.slice(0, maxLength)}...` : str;
}

export function slugify(str: string): string {
  return str
    .toLowerCase()
    .replace(/[^\w ]+/g, '')
    .replace(/ +/g, '-');
}
```

```typescript
// core/shared/utils/number.ts
export function formatCurrency(amount: number, currency: string = 'USD'): string {
  return new Intl.NumberFormat('en-US', {
    style: 'currency',
    currency,
  }).format(amount);
}

export function clamp(value: number, min: number, max: number): number {
  return Math.min(Math.max(value, min), max);
}

export function roundTo(value: number, decimals: number): number {
  return Math.round(value * Math.pow(10, decimals)) / Math.pow(10, decimals);
}
```

### What DOESN'T Belong Here

Domain-specific utilities that should stay in domain folders:

```typescript
// ❌ WRONG: This belongs in core/domains/products/utils.ts (if needed)
export function calculateProductDiscount(price: number, discountPercentage: number) {
  return price * (1 - discountPercentage / 100);
}

// ❌ WRONG: This belongs in core/domains/auth/utils.ts
export function parseJWT(token: string) {
  const base64Url = token.split('.')[1];
  // JWT parsing logic
}
```

## Shared Types (`core/shared/types/`)

### What Belongs Here

TypeScript types that:

* Are used across multiple domains
* Define generic cross-domain patterns (not component-specific props)
* Represent common API response patterns
* Define application-wide constants

**Important**: Component-specific props (like `ButtonProps`, `CardProps`) should be co-located with their components following the [Feature Implementation Decision Tree](/docs/guides/feature-implementation-decision-tree), not placed in shared types.

### Organization

```
core/shared/types/
├── ui.ts            # Cross-domain UI patterns (BaseComponentProps, LoadingState)
├── api.ts           # Generic API types
├── global.ts        # Application-wide types
├── constants.ts     # Shared constants
└── index.ts        # Barrel exports
```

### Examples of Shared Types

```typescript
// core/shared/types/ui.ts
// Note: Component-specific props like ButtonProps should be co-located 
// with their components per the Feature Implementation Decision Tree.
// Only truly cross-domain interface patterns belong here.

export interface BaseComponentProps {
  testID?: string;
  accessible?: boolean;
  accessibilityLabel?: string;
}

export interface LoadingState {
  isLoading: boolean;
  error?: Error | null;
}

export interface PaginationMeta {
  page: number;
  pageSize: number;
  total: number;
  hasMore: boolean;
}
```

```typescript
// core/shared/types/api.ts
export interface ApiResponse<T> {
  data: T;
  error?: string;
  status: number;
}

export interface PaginatedResponse<T> {
  items: T[];
  total: number;
  page: number;
  pageSize: number;
  hasMore: boolean;
}

export interface ErrorResponse {
  message: string;
  code: string;
  details?: Record<string, any>;
}
```

```typescript
// core/shared/types/global.ts
export interface Theme {
  colors: {
    primary: string;
    secondary: string;
    text: string;
    background: string;
    error: string;
  };
  spacing: {
    xs: number;
    sm: number;
    md: number;
    lg: number;
    xl: number;
  };
}

export type AsyncState<T> = 
  | { status: 'idle' }
  | { status: 'loading' }
  | { status: 'success'; data: T }
  | { status: 'error'; error: Error };
```

### What DOESN'T Belong Here

Domain-specific types that should stay in domain folders:

```typescript
// ❌ WRONG: This belongs in core/domains/products/types.ts
export interface Product {
  id: string;
  name: string;
  price: number;
  category: string;
}

// ❌ WRONG: This belongs in core/domains/users/types.ts
export interface User {
  id: string;
  email: string;
  profile: UserProfile;
}
```

Component-specific types that should be co-located with components:

```typescript
// ❌ WRONG: This belongs in ui/foundation/Button/types.ts
export interface ButtonProps {
  variant?: 'primary' | 'secondary';
  onPress: () => void;
  children: React.ReactNode;
}

// ❌ WRONG: This belongs in ui/patterns/Modal/types.ts  
export interface ModalProps {
  visible: boolean;
  onClose: () => void;
  children: React.ReactNode;
}
```

## Migration Checklist

When reviewing existing code to implement this structure:

### Step 1: Audit Current Code

* [ ] List all hooks in the project
* [ ] List all utility functions
* [ ] List all type definitions

### Step 2: Categorize by Domain

* [ ] Identify which hooks are domain-specific
* [ ] Identify which utilities are domain-specific
* [ ] Identify which types are domain-specific

### Step 3: Move Generic Code to Shared

* [ ] Move truly generic hooks to `shared/hooks/`
* [ ] Move general utilities to `shared/utils/`
* [ ] Move cross-domain types to `shared/types/`

### Step 4: Keep Domain Code in Domains

* [ ] Ensure domain hooks stay in `domains/[domain]/hooks.ts`
* [ ] Keep domain utilities in domains (if needed)
* [ ] Keep domain types in `domains/[domain]/types.ts`

### Step 5: Update Imports

* [ ] Fix all import paths
* [ ] Ensure no circular dependencies
* [ ] Update barrel exports

## Best Practices

### Naming Conventions

All files must follow our [File Naming Conventions](/docs/coding-standards/file-naming-conventions):

* **Hooks**: Always prefix with `use` (e.g., `useDebounce`)
* **Utils**: Use descriptive verb/noun combinations (e.g., `formatDate`)
* **Types**: Use PascalCase for interfaces/types (e.g., `ButtonProps`)

### File Organization

* Keep files focused on a single responsibility
* Group related utilities in the same file
* Use barrel exports for clean imports

### Documentation

```typescript
/**
 * Debounces a value by the specified delay
 * @param value - The value to debounce
 * @param delay - Delay in milliseconds
 * @returns The debounced value
 */
export function useDebounce<T>(value: T, delay: number): T {
  // Implementation
}
```

### Testing

* Write unit tests for all shared utilities
* Test edge cases and error conditions
* Ensure utilities work in isolation

## Common Pitfalls

### 1. Domain Logic in Shared

❌ **Wrong**: Putting business logic in shared utilities

```typescript
// core/shared/utils/product.ts
export function calculateProductTax(product: Product) {
  // This is domain logic!
}
```

✅ **Correct**: Keep domain logic in domains

```typescript
// core/domains/products/utils.ts
export function calculateProductTax(product: Product) {
  // Domain-specific calculation
}
```

### 2. Over-Abstraction

❌ **Wrong**: Creating overly generic utilities

```typescript
// Too abstract to be useful
export function processData<T>(data: T, processor: (d: T) => T): T {
  return processor(data);
}
```

✅ **Correct**: Create specific, useful utilities

```typescript
// Clear purpose and use case
export function sortByDate<T extends { date: Date }>(items: T[]): T[] {
  return items.sort((a, b) => a.date.getTime() - b.date.getTime());
}
```

### 3. Circular Dependencies

❌ **Wrong**: Shared utilities depending on domains

```typescript
// core/shared/utils/validation.ts
import { Product } from '@/core/domains/products'; // ❌ domains shouldn't be in shared

export function validateProduct(product: Product) {
  // This creates circular dependency
}
```

✅ **Correct**: Keep shared utilities independent

```typescript
// core/shared/utils/validation.ts
export function validateEmail(email: string): boolean {
  // Generic validation, no domain dependencies
  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email);
}
```

## Related Documents

* [Core Architecture Reference](/docs/architecture/core-architecture)
* [Project Structure Reference](/docs/architecture/project-structure)
* [Domain Architecture Guide](/docs/architecture/domain-architecture)
* [File Naming Conventions](/docs/coding-standards/file-naming-conventions)
* [Coding Standards](/docs/coding-standards)
* [Testing Guide](/docs/guides/testing)


# UTA Implementation Guides: Implementation Guides
URL: https://dev.updatetheapp.com/docs/guides
Documentation: https://dev.updatetheapp.com/docs/guides

Step-by-step instructions and practical tutorials for building React Native applications with UTA patterns and best practices.
        
***

title: Implementation Guides
description: Step-by-step instructions and practical tutorials for building React Native applications with UTA patterns and best practices.
-------------------------------------------------------------------------------------------------------------------------------------------

import { Card, Cards } from 'fumadocs-ui/components/card';
import { Callout } from 'fumadocs-ui/components/callout';
import { AlertTriangle, Rocket, Users, Code2, Shield, Database, Palette, CheckCircle2 } from 'lucide-react';

# Implementation Guides

**Practical, step-by-step guides for building React Native applications with UTA patterns.** Each guide includes real-world examples, code samples, and troubleshooting tips to help you implement features effectively.

<Callout type="info" icon={<AlertTriangle />}>
  **Work in Progress**: This guides section is actively being developed. Some guides may be incomplete or under revision. We're committed to providing comprehensive, production-ready guidance for the UTA ecosystem.

  **Coming Soon**: More implementation guides, video tutorials, and interactive examples.
</Callout>

## How to Use These Guides

Each guide is designed to be **practical and immediately actionable**:

* **Prerequisites listed upfront** - Know what you need before starting
* **Step-by-step instructions** - Clear, numbered steps with code examples
* **Real-world examples** - Production-tested implementations
* **Troubleshooting sections** - Common issues and their solutions
* **Next steps** - Links to related guides and advanced topics

***

## 🚀 **Getting Started**

**New to UTA?** Start here for essential setup and team onboarding.

<Cards>
  <Card icon={<Rocket />} title="Getting Started with UTA" href="/docs/guides/getting-started" description="Complete 30-minute setup guide from installation to building your first feature with UTA patterns." />

  <Card icon={<Users />} title="Team Onboarding Checklist" href="/docs/guides/team-onboarding-checklist" description="Comprehensive checklist to get your entire team productive with UTA patterns and workflows." />
</Cards>

***

## ⚡ **Core Development**

**Essential patterns and frameworks** for building maintainable React Native applications.

<Cards>
  <Card icon={<Code2 />} title="Feature Implementation Decision Tree" href="/docs/guides/feature-implementation-decision-tree" description="Decision framework to determine the best UTA patterns for implementing any new feature or component." />

  <Card icon={<Code2 />} title="Project Structure Migration" href="/docs/guides/project-structure-migration" description="Step-by-step guide to migrate existing React Native projects to UTA patterns and architecture." />

  <Card icon={<Code2 />} title="AI-Assisted Development" href="/docs/guides/ai-assisted-development" description="Leverage AI effectively with UTA's standardized patterns for faster, more accurate development." />
</Cards>

***

## 🔐 **Authentication Implementation**

**Complete authentication solutions** with security best practices and multiple provider support.

<Cards>
  <Card icon={<Shield />} title="Authentication Flow" href="/docs/guides/authentication-flow" description="Complete implementation guide for authentication including social providers and security best practices." />

  <Card icon={<Shield />} title="Biometric Authentication" href="/docs/guides/biometric-authentication" description="Implement Face ID, Touch ID, and fingerprint authentication with proper fallbacks and error handling." />

  <Card icon={<Shield />} title="Social Authentication" href="/docs/guides/social-authentication" description="Integration guide for Google, Apple, Facebook, and other social authentication providers." />

  <Card icon={<Shield />} title="Multi-Account Management" href="/docs/guides/multi-account-management" description="Handle multiple user accounts, account switching, and cross-account data management." />
</Cards>

***

## 📊 **State Management**

**Master UTA's state management patterns** with Zustand and TanStack Query.

<Cards>
  <Card icon={<Database />} title="Server State Management" href="/docs/guides/server-state-management" description="TanStack Query patterns for API data, caching, background updates, and optimistic updates." />

  <Card icon={<Database />} title="Client State Management" href="/docs/guides/client-state-management" description="Zustand patterns for global UI state, user preferences, and persistent data management." />
</Cards>

***

## 🎨 **UI & Feature Implementation**

**Build beautiful, consistent interfaces** and advanced feature patterns.

<Cards>
  <Card icon={<Palette />} title="Styling Implementation" href="/docs/guides/styling-implementation" description="Design token system, theme management, and consistent styling patterns across your application." />

  <Card icon={<Palette />} title="Feature Flag Implementation" href="/docs/guides/feature-flag-implementation" description="Progressive feature rollouts, A/B testing, and environment-specific feature control." />
</Cards>

**Specialized Topics:**

* [App Initialization Guides](/docs/guides/app-initialization) - Application setup and configuration patterns
* [Offline Implementation Guides](/docs/guides/offline) - Offline-first strategies and data synchronization

***

## 👥 **Team & Quality**

**Establish processes and standards** for consistent, high-quality development.

<Cards>
  <Card icon={<CheckCircle2 />} title="Code Review Templates" href="/docs/guides/code-review-templates" description="Standardized code review processes and templates that ensure quality and consistency." />

  <Card icon={<CheckCircle2 />} title="Common Pitfalls & Solutions" href="/docs/guides/common-pitfalls-solutions" description="Learn from common mistakes and their solutions to avoid development roadblocks." />

  <Card icon={<CheckCircle2 />} title="Technical Documentation Guidelines" href="/docs/guides/technical-documentation-guidelines" description="Standards and best practices for writing clear, maintainable technical documentation." />
</Cards>

***

## 🎯 **Quick Reference**

**Looking for something specific?** Here are the most popular guides:

* **Just starting?** → [Getting Started with UTA](/docs/guides/getting-started)
* **Need to implement auth?** → [Authentication Flow](/docs/guides/authentication-flow)
* **Team onboarding?** → [Team Onboarding Checklist](/docs/guides/team-onboarding-checklist)
* **Migrating existing project?** → [Project Structure Migration](/docs/guides/project-structure-migration)
* **Debugging issues?** → [Common Pitfalls & Solutions](/docs/guides/common-pitfalls-solutions)

<Callout type="success">
  **Need help?** Each guide includes troubleshooting sections and links to related documentation. For architecture-level questions, see the [UTA Ecosystem Overview](/docs/uta-ecosystem).
</Callout>

***

## 📝 **Contributing to Guides**

Found an issue or want to improve a guide? We welcome contributions:

* **Report issues** with specific guides
* **Suggest improvements** or additional examples
* **Share your implementations** for real-world scenarios
* **Request new guides** for topics you need

*Help us make UTA guides the best resource for React Native development!*


# UTA Implementation Guides: Getting Started with UTA
URL: https://dev.updatetheapp.com/docs/guides/getting-started
Documentation: https://dev.updatetheapp.com/docs/guides/getting-started

Complete setup guide for the UTA ecosystem - from installation to building your first feature in 30 minutes.
        
***

title: Getting Started with UTA
description: Complete setup guide for the UTA ecosystem - from installation to building your first feature in 30 minutes.
-------------------------------------------------------------------------------------------------------------------------

import { Steps, Step } from 'fumadocs-ui/components/steps';
import { Callout } from 'fumadocs-ui/components/callout';
import { Tabs, Tab } from 'fumadocs-ui/components/tabs';
import { Card, Cards } from 'fumadocs-ui/components/card';

# Getting Started with UTA

## Overview

This comprehensive guide will take you from zero to shipping your first UTA-powered React Native app in 30 minutes. You'll set up the complete ecosystem, understand the architecture, and build your first feature following UTA patterns.

<Callout type="info">
  **⏱️ Time to First Feature**: \~30 minutes

  By the end of this guide, you'll have:

  * A working UTA project with standardized architecture
  * Your first feature implemented using UTA patterns
  * Understanding of the three-layer architecture
  * Ready-to-extend codebase for your specific needs
</Callout>

## Prerequisites

Before starting, ensure you have:

* **Node.js 18+** and **npm/yarn** installed
* **React Native development environment** set up ([React Native CLI setup](https://reactnative.dev/docs/environment-setup))
* **Basic knowledge** of React Native and TypeScript
* **iOS Simulator** or **Android Emulator** running

<Callout type="warning">
  **First time with React Native?** Complete the [React Native Environment Setup](https://reactnative.dev/docs/environment-setup) first, then return to this guide.
</Callout>

## Quick Start

<Steps>
  <Step>
    ### Create Your UTA Project

    Clone and set up the UTA template:

    <Tabs items={["npm", "yarn"]}>
      <Tab value="npm">
        ```bash
        # Clone the UTA template
        git clone https://github.com/your-org/react-native-uta.git MyUTAApp
        cd MyUTAApp

        # Install dependencies
        npm install

        # iOS setup (if on macOS)
        cd ios && pod install && cd ..
        ```
      </Tab>

      <Tab value="yarn">
        ```bash
        # Clone the UTA template
        git clone https://github.com/your-org/react-native-uta.git MyUTAApp
        cd MyUTAApp

        # Install dependencies
        yarn install

        # iOS setup (if on macOS)
        cd ios && pod install && cd ..
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step>
    ### Launch Your App

    Start the development server and run your app:

    <Tabs items={["iOS", "Android"]}>
      <Tab value="iOS">
        ```bash
        # Start Metro bundler
        npm start

        # In a new terminal, run iOS
        npm run ios
        ```
      </Tab>

      <Tab value="Android">
        ```bash
        # Start Metro bundler
        npm start

        # In a new terminal, run Android
        npm run android
        ```
      </Tab>
    </Tabs>

    You should see the UTA welcome screen with example features.
  </Step>

  <Step>
    ### Explore the Project Structure

    Familiarize yourself with the UTA architecture:

    ```
    src/
    ├── core/                    # Core systems (non-UI)
    │   ├── auth/               # Authentication logic
    │   ├── api/                # API clients and types
    │   ├── state/              # Global state management
    │   └── shared/             # Shared utilities
    ├── features/               # Feature modules
    │   ├── auth/              # Authentication feature
    │   ├── profile/           # User profile feature
    │   └── dashboard/         # Dashboard feature
    ├── ui/                     # UI components (no business logic)
    │   ├── foundation/        # Basic UI building blocks
    │   ├── components/        # Complex UI components
    │   └── patterns/          # Reusable UI patterns
    └── navigation/            # Navigation configuration
    ```

    <Callout type="success">
      **UTA Philosophy**: Every file has a clear purpose and location. No more "where should this go?" decisions!
    </Callout>
  </Step>

  <Step>
    ### Understand the Three-Layer Architecture

    UTA uses a standardized three-layer architecture:

    1. **Core Layer** (`/src/core/`) - Business logic, state, API clients
    2. **Features Layer** (`/src/features/`) - Feature-specific implementations
    3. **UI Layer** (`/src/ui/`) - Reusable UI components

    For detailed explanation, see the [UI Development Architecture](/docs/ui-development/architecture).
  </Step>
</Steps>

## Build Your First Feature

Now let's build a "Settings" feature to demonstrate UTA patterns:

<Steps>
  <Step>
    ### Create the Feature Structure

    Following UTA conventions, create your feature module:

    ```bash
    # Create feature directory structure
    mkdir -p src/features/settings/{components,screens,hooks}
    ```

    ```
    src/features/settings/
    ├── components/           # Feature-specific components
    ├── screens/             # Screen components for navigation
    ├── hooks/               # Feature-specific hooks
    └── index.ts            # Public API exports
    ```
  </Step>

  <Step>
    ### Create a Settings Screen

    Create your first screen using UTA patterns:

    ```typescript
    // src/features/settings/screens/SettingsScreen.tsx
    import React from 'react';
    import { ScrollView } from 'react-native';
    import { ScreenContainer } from '@/ui/foundation/ScreenContainer';
    import { Header } from '@/ui/components/Header';
    import { SettingsList } from '../components/SettingsList';

    export function SettingsScreen() {
      return (
        <ScreenContainer>
          <Header title="Settings" showBackButton />
          <ScrollView>
            <SettingsList />
          </ScrollView>
        </ScreenContainer>
      );
    }
    ```
  </Step>

  <Step>
    ### Create Feature Components

    Build feature-specific components:

    ```typescript
    // src/features/settings/components/SettingsList.tsx
    import React from 'react';
    import { View } from 'react-native';
    import { List } from '@/ui/components/List';
    import { useSettingsData } from '../hooks/useSettingsData';

    export function SettingsList() {
      const { settings, updateSetting } = useSettingsData();

      return (
        <View>
          <List
            data={settings}
            renderItem={({ item }) => (
              <List.Item
                title={item.title}
                subtitle={item.subtitle}
                trailing={item.component}
                onPress={() => updateSetting(item.key)}
              />
            )}
          />
        </View>
      );
    }
    ```
  </Step>

  <Step>
    ### Add Navigation

    Register your screen in the navigation system:

    ```typescript
    // src/navigation/AppNavigator.tsx
    import { SettingsScreen } from '@/features/settings/screens/SettingsScreen';

    // Add to your navigator
    <Stack.Screen 
      name="Settings" 
      component={SettingsScreen}
      options={{ title: 'Settings' }}
    />
    ```
  </Step>

  <Step>
    ### Test Your Feature

    Run your app and navigate to the Settings screen:

    ```bash
    # Reload your app
    npm start

    # Navigate to Settings in your app
    # You should see your new feature working!
    ```
  </Step>
</Steps>

## Next Steps

Congratulations! 🎉 You've successfully set up UTA and built your first feature. Here's what to explore next:

<Cards>
  <Card title="UI Development" href="/docs/ui-development/getting-started">
    Learn to build components following UTA's three-layer architecture
  </Card>

  <Card title="State Management" href="/docs/state-management/state-management-architecture">
    Master Zustand patterns for client and server state
  </Card>

  <Card title="Authentication" href="/docs/guides/authentication-flow">
    Implement secure user authentication flows
  </Card>

  <Card title="API Integration" href="/docs/api/client-architecture">
    Connect to APIs using React Query patterns
  </Card>
</Cards>

## Common First Steps

### Adding a New Feature

Follow the [Feature Implementation Decision Tree](/docs/guides/feature-implementation-decision-tree) to determine the best approach for your specific feature.

### Team Collaboration

Review the [Team Onboarding Checklist](/docs/guides/team-onboarding-checklist) to ensure all team members can contribute effectively.

### Code Quality

Set up [Code Review Templates](/docs/guides/code-review-templates) to maintain UTA standards across your team.

## Need Help?

<Callout type="info">
  **Getting Stuck?** Check the [Common Pitfalls & Solutions](/docs/guides/common-pitfalls-solutions) guide for answers to frequently encountered issues.
</Callout>

### Resources

* **Architecture**: [UTA Ecosystem Overview](/docs/uta-ecosystem) for the big picture
* **Patterns**: [AI-Assisted Development](/docs/guides/ai-assisted-development) for productivity tips
* **Troubleshooting**: [Common Pitfalls & Solutions](/docs/guides/common-pitfalls-solutions)

***

**Welcome to the UTA ecosystem!** You're now ready to build React Native apps the standardized way. 🚀


# UTA Implementation Guides: Team Onboarding Checklist
URL: https://dev.updatetheapp.com/docs/guides/team-onboarding-checklist
Documentation: https://dev.updatetheapp.com/docs/guides/team-onboarding-checklist

Step-by-step onboarding process to ensure every team member writes consistent code
        
***

title: Team Onboarding Checklist
description: Step-by-step onboarding process to ensure every team member writes consistent code
-----------------------------------------------------------------------------------------------

import { Steps, Step } from 'fumadocs-ui/components/steps';
import { Callout } from 'fumadocs-ui/components/callout';
import { Tabs, Tab } from 'fumadocs-ui/components/tabs';

# Team Onboarding Checklist

## Overview

This checklist ensures every team member - from fresher to senior developer - understands and follows our standards to achieve "single author" code consistency. Follow these steps in order during your first week.

<Callout type="warning">
  **Mandatory**: Complete each section before moving to the next. Your mentor will review your progress at each checkpoint.
</Callout>

## Week 1: Foundation

<Steps>
  <Step>
    ### Day 1: Understanding the Vision

    **Goal**: Understand why consistency matters and our "single author" philosophy.

    #### Read & Understand:

    1. [ ] This onboarding guide completely
    2. [ ] [Project Structure Reference](/docs/architecture/project-structure) - Understand folder organization
    3. [ ] [Feature Implementation Decision Tree](/docs/guides/feature-implementation-decision-tree) - **Most Important!**

    #### Exercise:

    Given these scenarios, determine where each code should go:

    1. A date formatting function used by checkout and profile features
    2. A new API endpoint for fetching user preferences
    3. A loading spinner used across the entire app
    4. A cart total calculation function

    <details>
      <summary>Check Your Answers</summary>

      1. `core/shared/utils/date.ts` (used by 2 features, almost shared)
      2. `core/domains/users/api.ts` (user-related API)
      3. `ui/foundation/LoadingSpinner/` (atomic component, no business logic)
      4. `features/cart/utils/calculateTotal.ts` (cart-specific logic)
    </details>

    #### Checkpoint with Mentor:

    * [ ] Explain the folder structure
    * [ ] Demonstrate using the decision tree
  </Step>

  <Step>
    ### Day 2: TypeScript & React Patterns

    **Goal**: Master our exact coding patterns.

    #### Read & Practice:

    1. [ ] [TypeScript & React Patterns](/docs/coding-standards/typescript-react-patterns)
    2. [ ] [File Naming Conventions](/docs/coding-standards/file-naming-conventions)

    #### Coding Exercise:

    Create a simple ProductCard component following ALL patterns:

    ```typescript
    // Your task: Create a ProductCard that:
    // 1. Displays product name, price, and image
    // 2. Has an onPress handler
    // 3. Shows a discount badge if product is on sale
    // 4. Follows our EXACT component structure
    // 5. Uses proper TypeScript types
    // 6. Includes proper error handling
    ```

    #### Review Checklist:

    * [ ] Imports in correct order
    * [ ] Interface not type for props
    * [ ] Function declaration not arrow function
    * [ ] Styles in StyleSheet not inline
    * [ ] Proper error handling for missing data
    * [ ] File in correct location

    #### Checkpoint with Mentor:

    * [ ] Code review of ProductCard
    * [ ] Fix any pattern violations
  </Step>

  <Step>
    ### Day 3: State Management & Data Fetching

    **Goal**: Understand when and how to manage different types of state.

    #### Read:

    1. [ ] [Client State Management Guide](/docs/guides/client-state-management)
    2. [ ] [Server State Management Guide](/docs/guides/server-state-management)
    3. [ ] Review existing domain hooks in `core/domains/*/hooks.ts`

    #### Exercise:

    Implement a product search feature:

    1. Create search input with debouncing
    2. Fetch results using React Query
    3. Display results with proper loading/error states
    4. Add filtering capabilities

    #### Must Include:

    * [ ] Debounced search (useDebounce hook)
    * [ ] React Query for data fetching
    * [ ] Proper error boundaries
    * [ ] Loading skeletons
    * [ ] Empty state handling

    #### Common Mistakes to Avoid:

    * ❌ Manual loading/error state management
    * ❌ Fetching in components directly
    * ❌ Global state for search results
    * ✅ Domain hooks for data fetching
    * ✅ Local state for UI-only data

    #### Checkpoint with Mentor:

    * [ ] Review state management choices
    * [ ] Verify React Query usage
  </Step>

  <Step>
    ### Day 4: Common Pitfalls Review

    **Goal**: Learn from others' mistakes.

    #### Study:

    1. [ ] [Common Pitfalls & Solutions](/docs/guides/common-pitfalls-solutions) - **Read thoroughly!**
    2. [ ] Identify which pitfalls you've made before

    #### Exercise - Fix the Code:

    Your mentor will provide you with intentionally problematic code. Your task:

    1. Identify all issues
    2. Explain why each is wrong
    3. Fix following our patterns

    Common issues to look for:

    * Wrong file locations
    * State mutations
    * Missing error handling
    * Performance problems
    * TypeScript anti-patterns

    #### Self-Assessment:

    Rate your understanding (1-5) of:

    * [ ] Where code belongs: \_\_\_
    * [ ] State management choices: \_\_\_
    * [ ] TypeScript patterns: \_\_\_
    * [ ] Performance optimization: \_\_\_
    * [ ] Error handling: \_\_\_

    #### Checkpoint with Mentor:

    * [ ] Review fixed code
    * [ ] Discuss any scores below 4
  </Step>

  <Step>
    ### Day 5: Real Feature Implementation

    **Goal**: Implement a complete feature following all standards.

    #### Your First Feature:

    Implement a "Favorites" feature that allows users to:

    1. Mark products as favorites
    2. View list of favorite products
    3. Remove items from favorites
    4. Persist favorites locally

    #### Required Deliverables:

    <Tabs items={["Domain Layer", "Feature Layer", "UI Components"]}>
      <Tab>
        ```
        core/domains/favorites/
        ├── types.ts        # Favorite type definitions
        ├── store.ts        # Zustand store for favorites
        ├── hooks.ts        # useFavorites, useToggleFavorite
        ├── utils.ts        # Helper functions
        └── index.ts        # Barrel exports
        ```
      </Tab>

      <Tab>
        ```
        features/favorites/
        ├── screens/
        │   └── FavoritesScreen/
        │       ├── FavoritesScreen.tsx
        │       ├── FavoritesScreen.test.tsx
        │       └── index.ts
        ├── components/
        │   └── FavoriteButton/
        │       ├── FavoriteButton.tsx
        │       └── index.ts
        └── navigation.tsx
        ```
      </Tab>

      <Tab>
        ```
        ui/
        ├── foundation/
        │   └── HeartIcon/     # If basic icon component
        │       ├── HeartIcon.tsx
        │       └── index.ts
        └── business/
            └── FavoriteButton/  # If domain-aware (uses favorites domain)
                ├── FavoriteButton.tsx
                └── index.ts
        ```
      </Tab>
    </Tabs>

    #### Implementation Checklist:

    * [ ] Used Feature Decision Tree for all code placement
    * [ ] Created domain for business logic
    * [ ] Used Zustand for client state
    * [ ] Added proper TypeScript types
    * [ ] Included error handling
    * [ ] Added loading states
    * [ ] Wrote tests
    * [ ] No code duplication

    #### Final Review:

    * [ ] Run TypeScript check: `npx tsc --noEmit`
    * [ ] All imports use @/ prefix
    * [ ] No console warnings
    * [ ] Code looks like our examples

    #### Checkpoint with Mentor:

    * [ ] Complete feature review
    * [ ] Production readiness assessment
  </Step>
</Steps>

## Week 2: Advanced Patterns

### Advanced Topics to Master:

1. **Performance Optimization**
   * [ ] Memoization strategies
   * [ ] List rendering optimization
   * [ ] Image optimization

2. **Testing Patterns**
   * [ ] Component testing
   * [ ] Hook testing
   * [ ] Integration testing

3. **Advanced TypeScript**
   * [ ] Generic components
   * [ ] Type guards
   * [ ] Utility types

4. **Architecture Decisions**
   * [ ] When to create new domains
   * [ ] Feature vs shared code
   * [ ] Performance vs maintainability

## For Mentors

### Onboarding Review Checklist

<Callout type="info">
  Use this to track each developer's progress and identify areas needing more support.
</Callout>

#### Developer: \_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_ Start Date: \_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_

**Day 1 Review:**

* [ ] Understands folder structure
* [ ] Can use decision tree correctly
* [ ] Questions addressed: \_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_

**Day 2 Review:**

* [ ] Component follows exact structure
* [ ] TypeScript usage correct
* [ ] Areas for improvement: \_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_

**Day 3 Review:**

* [ ] State management choices appropriate
* [ ] React Query used correctly
* [ ] Understanding level: \_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_

**Day 4 Review:**

* [ ] Identified all code issues
* [ ] Fixes follow patterns
* [ ] Weak areas: \_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_

**Day 5 Review:**

* [ ] Feature is production-ready
* [ ] All standards followed
* [ ] Ready for independent work: Yes/No

### Common Issues by Experience Level

<Tabs items={["Freshers", "Juniors", "Seniors"]}>
  <Tab>
    **Common Fresher Mistakes:**

    1. Overwhelmed by structure → Start with decision tree
    2. Copy-paste without understanding → Explain the "why"
    3. Fear of asking questions → Encourage questions
    4. Skipping error handling → Show real consequences

    **Support Strategies:**

    * Pair programming for first features
    * Daily check-ins first week
    * Provide working examples
    * Celebrate small wins
  </Tab>

  <Tab>
    **Common Junior Mistakes:**

    1. Overengineering solutions → Show our patterns are sufficient
    2. Bringing habits from other projects → Reset expectations
    3. Skipping documentation → Emphasize team benefits
    4. Inconsistent patterns → More code reviews

    **Support Strategies:**

    * Code review all PRs initially
    * Discuss architectural decisions
    * Share pitfall examples
    * Gradual independence
  </Tab>

  <Tab>
    **Common Senior Mistakes:**

    1. "I know better" syndrome → Emphasize team consistency
    2. Creating new patterns → Redirect to existing ones
    3. Skipping "simple" standards → No exceptions
    4. Working in isolation → Encourage collaboration

    **Support Strategies:**

    * Involve in standard improvements
    * Make them mentors
    * Respect experience while enforcing standards
    * Focus on team benefits
  </Tab>
</Tabs>

## Continuous Learning

### Weekly Team Practices

1. **Code Review Sessions**
   * Review real PRs together
   * Discuss pattern violations
   * Share better approaches

2. **Pattern of the Week**
   * Deep dive into one pattern
   * Share examples
   * Q\&A session

3. **Pitfall Sharing**
   * Share mistakes made
   * How they were fixed
   * Update documentation

### Success Metrics

You're successfully onboarded when:

* [ ] PRs require minimal pattern corrections
* [ ] You help others with standards
* [ ] Code is indistinguishable from team style
* [ ] You contribute to documentation improvements

## Quick Reference Links

**Must Read Daily Until Memorized:**

1. [Feature Implementation Decision Tree](/docs/guides/feature-implementation-decision-tree)
2. [TypeScript & React Patterns](/docs/coding-standards/typescript-react-patterns)
3. [Common Pitfalls & Solutions](/docs/guides/common-pitfalls-solutions)

**Reference When Needed:**

* [Project Structure](/docs/architecture/project-structure)
* [State Management Guide](/docs/guides/client-state-management)
* [API Integration Patterns](/docs/api)

## Final Words

<Callout type="success">
  **Remember**: The goal isn't to restrict creativity, but to channel it within consistent patterns. When every developer follows these standards, we achieve:

  * ✅ Faster onboarding
  * ✅ Easier maintenance
  * ✅ Better collaboration
  * ✅ Higher quality code
  * ✅ "Single author" consistency
</Callout>

Welcome to the team! 🎉

## Decision Making Flow

When you receive a new feature request, follow this flow:

```mermaid
flowchart TD
    Start[New Feature Request] --> Analyze[Analyze Requirements]
    Analyze --> CheckExisting{Similar Feature Exists?}
    
    CheckExisting -->|Yes| ExtendPattern[Extend Existing Pattern]
    CheckExisting -->|No| CreateNew[Create New Pattern]
    
    ExtendPattern --> CreateADR{Significant Change?}
    CreateNew --> CreateADR
    
    CreateADR -->|Yes| WriteADR[Write ADR using template]
    CreateADR -->|No| ImplementFeature[Implement Feature]
    WriteADR --> ImplementFeature
    
    ImplementFeature --> WriteTests[Write Tests 90%+ coverage]
    WriteTests --> UpdateDocs[Update Documentation]
    UpdateDocs --> SelfReview[Self Review with Checklist]
    SelfReview --> CodeReview[Submit for Code Review]
    CodeReview --> Done[Feature Complete]
```

### Key Decision Points

1. **Similar Feature Check**: Always look for existing patterns first
2. **ADR Requirement**: Significant architectural changes need documentation
3. **Test Coverage**: Non-negotiable 90%+ requirement
4. **Documentation**: Must be updated in the same PR


# UTA Implementation Guides: Implementation Workflow Guide
URL: https://dev.updatetheapp.com/docs/guides/implementation-workflow
Documentation: https://dev.updatetheapp.com/docs/guides/implementation-workflow

How to effectively use our documentation, reference implementations, and examples to build React Native applications
        
***

title: Implementation Workflow Guide
description: How to effectively use our documentation, reference implementations, and examples to build React Native applications
---------------------------------------------------------------------------------------------------------------------------------

import { Callout } from 'fumadocs-ui/components/callout';
import { Steps, Step } from 'fumadocs-ui/components/steps';

# Implementation Workflow Guide

**The complete guide to using UTA's Documentation → Examples → Implementation flow for efficient React Native development**

## Overview

This guide explains how to leverage our three-tier learning system to build React Native applications efficiently. Whether you're implementing authentication, building UI components, or setting up API clients, this workflow will help you move from concept to working code quickly.

## The Three-Tier System

<Callout type="info">
  **🎯 The UTA Learning Path**

  1. **📚 Documentation** - Learn concepts, patterns, and best practices
  2. **🔬 Reference Implementations** - Study working, production-ready code
  3. **🚀 Your Implementation** - Build with confidence using proven patterns
</Callout>

### Tier 1: Documentation

Comprehensive guides covering architectural decisions, patterns, and best practices. Start here to understand the "why" behind our approaches.

### Tier 2: Reference Implementations

Complete, copy-paste ready code examples that demonstrate the documentation concepts in action. These are production-quality implementations you can use immediately.

### Tier 3: Your Implementation

Your actual project code, built using the patterns and examples from tiers 1 and 2.

## Implementation Workflow

<Steps>
  <Step>
    ### Start with Documentation

    Begin by reading the relevant documentation to understand the architectural patterns and best practices.

    **Example Scenario:** You need to implement authentication

    * Read [Authentication Flow Implementation Guide](/docs/guides/authentication-flow)
    * Review [API Authentication Architecture](/docs/api/authentication)
    * Understand the security considerations and token management patterns
  </Step>

  <Step>
    ### Study Reference Implementations

    Examine the working code examples that demonstrate the concepts from the documentation.

    **For Authentication:**

    * Study [Authentication Domain Reference](/docs/reference-implementations/core/domains/auth)
    * Review [API Client Reference](/docs/reference-implementations/core/shared/api)
    * Understand how the hooks, services, and types work together
  </Step>

  <Step>
    ### Copy and Customize

    Use the reference implementations as your starting point, customizing them for your specific needs.

    **Implementation Steps:**

    * Copy the TypeScript interfaces and types
    * Adapt the service implementations for your API endpoints
    * Customize the hooks for your state management approach
    * Modify the UI components to match your design system
  </Step>

  <Step>
    ### Test and Iterate

    Use the testing patterns from the reference implementations to ensure your code works correctly.

    **Testing Approach:**

    * Copy the test examples and adapt them
    * Ensure all authentication flows work as expected
    * Test error handling and edge cases
    * Validate accessibility and performance
  </Step>
</Steps>

## Domain-Specific Workflows

### Authentication Implementation

<Callout type="info">
  **🔐 Authentication Quick Start**

  Perfect example of the three-tier workflow in action:
</Callout>

**1. Documentation Phase**

* Start with [Authentication Flow Guide](/docs/guides/authentication-flow)
* Review [API Authentication Architecture](/docs/api/authentication)
* Understand token management and security patterns

**2. Reference Implementation Phase**

* Study [Authentication Domain](/docs/reference-implementations/core/domains/auth)
* Copy the service patterns and hook implementations
* Review the testing strategies

**3. Implementation Phase**

```typescript
// Your project - copy from reference implementation
import { useAuth } from '@/core/domains/auth/hooks/useAuth';
import { authService } from '@/core/domains/auth/services/authService';

// Customize API endpoints for your backend
const authService = new AuthService('https://your-api.com');

// Use the proven hook patterns
export function LoginScreen() {
  const { login, isLoading } = useAuth();
  
  const handleLogin = async (credentials) => {
    await login(credentials);
    // Navigation handled by auth state change
  };
  
  return (
    // Your UI implementation
  );
}
```

### UI Component Development

**1. Documentation Phase**

* Read [Foundation Components Guide](/docs/ui-development/architecture/foundation-guide)
* Study [Interactive Elements](/docs/ui-development/architecture/foundation-guide/interactive-elements)
* Understand design token usage and accessibility requirements

**2. Reference Implementation Phase**

* Examine [Button Reference Implementation](/docs/reference-implementations/ui/foundation/Button)
* Study [Input Reference Implementation](/docs/reference-implementations/ui/foundation/Input)
* Review the component architecture and testing patterns

**3. Implementation Phase**

```typescript
// Your project - adapt from reference implementation
import { Button } from '@/ui/foundation/Button';

// Use proven component patterns
export function SubmitForm() {
  return (
    <Button
      variant="primary"
      loading={isSubmitting}
      onPress={handleSubmit}
    >
      Submit Application
    </Button>
  );
}
```

### API Client Setup

**1. Documentation Phase**

* Study [API Client Architecture](/docs/api/client-architecture)
* Review authentication integration patterns
* Understand error handling strategies

**2. Reference Implementation Phase**

* Copy [API Client Reference](/docs/reference-implementations/core/shared/api)
* Study the interceptor patterns and error handling
* Review the TypeScript type definitions

**3. Implementation Phase**

```typescript
// Your project - customize from reference
import { ApiClient } from '@/core/shared/api/ApiClient';

// Configure for your environment
const apiClient = new ApiClient(process.env.EXPO_PUBLIC_API_URL);

// Use proven service patterns
export class ProductService {
  async getProducts() {
    return apiClient.get('/products');
  }
}
```

## Advanced Workflows

### Feature Development

For complete features that combine multiple domains:

**1. Documentation Phase**

* Review [Feature Implementation Decision Tree](/docs/guides/feature-implementation-decision-tree)
* Study domain-specific guides
* Plan the feature architecture

**2. Reference Implementation Phase**

* Combine multiple reference implementations
* Study integration patterns between domains
* Review testing strategies for features

**3. Implementation Phase**

* Build incrementally, testing each component
* Use proven integration patterns
* Follow the established architectural principles

### State Management Integration

**1. Documentation Phase**

* Read [State Management Overview](/docs/state-management)
* Study [State Management Architecture](/docs/state-management/state-management-architecture) - Core patterns and decisions
* Review [Server State Management](/docs/state-management/server-state) - API data and caching
* Understand [Client State Management](/docs/state-management/client-state) - Application state patterns
* Learn [Component State](/docs/state-management/component-state) - Local component state best practices
* Study [Integration Patterns](/docs/state-management/integration-patterns) - How different state layers work together

**2. Reference Implementation Phase**

* Study [Product Domain Reference](/docs/reference-implementations/core/domains/products)
* Review React Query integration patterns for server state
* Examine Zustand patterns for client state management
* Study component state patterns and state lifting strategies

**3. Implementation Phase**

* Implement query hooks for server state management
* Set up Zustand stores for application state
* Apply proper component state patterns
* Integrate different state management layers consistently
* Handle loading, error, and success states across all state types

## Best Practices

### Customization Strategy

**✅ DO: Smart Customization**

* Copy the core patterns and adapt the details
* Maintain the architectural principles
* Keep the TypeScript type safety
* Follow the testing patterns

**❌ DON'T: Wholesale Changes**

* Don't rewrite everything from scratch
* Don't ignore the architectural patterns
* Don't skip the testing implementations
* Don't remove TypeScript types

### File Organization

Follow the established structure from reference implementations:

```
src/
├── core/
│   ├── domains/          # Business logic domains
│   └── shared/           # Shared utilities and services
├── features/             # Application features
├── ui/                   # UI component library
└── app/                  # App-specific code
```

### Progressive Enhancement

**Start Simple, Add Complexity Gradually:**

1. **Basic Implementation** - Copy reference implementation as-is
2. **Customization** - Adapt for your specific needs
3. **Enhancement** - Add advanced features incrementally
4. **Optimization** - Optimize for performance and user experience

## Common Patterns

### Error Handling

All reference implementations include comprehensive error handling:

```typescript
// Pattern from reference implementations
try {
  const result = await apiClient.get('/data');
  return result;
} catch (error) {
  if (error instanceof ApiError) {
    // Handle specific API errors
    throw new UserFriendlyError(error.message);
  }
  // Handle network errors, etc.
  throw error;
}
```

### Loading States

Consistent loading state management:

```typescript
// Pattern from reference implementations
const { data, isLoading, error } = useQuery({
  queryKey: ['products'],
  queryFn: () => productService.getProducts(),
});

if (isLoading) return <LoadingSpinner />;
if (error) return <ErrorMessage error={error} />;
```

### Type Safety

Comprehensive TypeScript usage:

```typescript
// Patterns from reference implementations
interface ProductFilters {
  category?: string;
  priceRange?: { min: number; max: number };
}

function useProducts(filters: ProductFilters = {}) {
  return useQuery({
    queryKey: ['products', filters],
    queryFn: () => productService.getProducts(filters),
  });
}
```

## Troubleshooting

### Common Issues and Solutions

**Issue: "I can't find the right starting point"**

* Solution: Start with the [Architecture Overview](/docs/architecture) to understand the big picture

**Issue: "The reference implementation doesn't match my needs exactly"**

* Solution: Use it as a foundation and customize the specific parts you need

**Issue: "I'm not sure which patterns to follow"**

* Solution: Follow the examples in reference implementations - they demonstrate proven patterns

**Issue: "The code seems complex"**

* Solution: Start with simpler examples and build up complexity gradually

### Getting Help

1. **Check the Documentation** - Most questions are covered in the guides
2. **Study Reference Implementations** - See working examples of complex patterns
3. **Review Testing Patterns** - Understand how to verify your implementation
4. **Ask Specific Questions** - Reference the exact guide or implementation you're working with

## Success Metrics

You'll know you're using the workflow effectively when:

* ✅ You can quickly find relevant documentation and examples
* ✅ You spend less time debugging architectural issues
* ✅ Your code follows consistent patterns across features
* ✅ You can easily onboard new team members
* ✅ Testing and maintenance become straightforward

***

**Ready to build?** Start with the [Architecture Overview](/docs/architecture) and then dive into the specific guides and reference implementations for your use case!


# UTA Implementation Guides: Feature Implementation Decision Tree
URL: https://dev.updatetheapp.com/docs/guides/feature-implementation-decision-tree
Documentation: https://dev.updatetheapp.com/docs/guides/feature-implementation-decision-tree

A step-by-step guide to determine where and how to implement new features, functions, and code in the codebase
        
***

title: Feature Implementation Decision Tree
description: A step-by-step guide to determine where and how to implement new features, functions, and code in the codebase
---------------------------------------------------------------------------------------------------------------------------

import { Steps, Step } from 'fumadocs-ui/components/steps';
import { Callout } from 'fumadocs-ui/components/callout';
import { Tabs, Tab } from 'fumadocs-ui/components/tabs';

# Feature Implementation Decision Tree

## Overview

This guide provides a systematic approach to determine **where** to place new code, **when** to create new structures, and **how** to implement features consistently. By following this decision tree, you'll maintain our codebase's clarity and ensure that every developer's code looks like it was written by a single person.

<Callout type="info">
  **Why this matters**: Consistent code placement reduces cognitive load, speeds up development, and makes code reviews more focused on logic rather than structure. Studies show that developers spend up to 60% of their time understanding existing code - clear organization dramatically reduces this overhead.
</Callout>

## Quick Decision Flow

```mermaid
flowchart TD
    Start[New Feature/Function Request] --> Q1{Is it a UI component?}
    
    Q1 -->|Yes| Q2{What type of UI component?}
    Q1 -->|No| Q3{Is it business logic?}
    
    Q2 -->|Atomic/Basic| Foundation[ui/foundation/]
    Q2 -->|Composed Pattern| Patterns[ui/patterns/]
    Q2 -->|Domain-aware| Q2B{Used by 3+ features?}
    Q2 -->|Feature-specific| Feature[feature's components/]
    
    Q2B -->|Yes| Business[ui/business/]
    Q2B -->|No| Feature
    
    Q3 -->|Yes| Q4{Does a domain exist for it?}
    Q3 -->|No| Q5{Is it a utility function?}
    
    Q4 -->|Yes| Domain[Add to existing domain]
    Q4 -->|No| NewDomain[Create new domain]
    
    Q5 -->|Yes| Q6{Is it feature-specific?}
    Q5 -->|No| Q7{Is it navigation related?}
    
    Q6 -->|Yes| FeatureUtils[Place in feature's utils/]
    Q6 -->|No| SharedUtils[Place in core/shared/utils/]
    
    Q7 -->|Yes| Nav[Add to navigation/]
    Q7 -->|No| Q8{Is it configuration?}
    
    Q8 -->|Yes| Config[Add to core/config/]
    Q8 -->|No| Review[Review with senior developer]
```

<Callout type="tip">
  **Pro tip**: Bookmark this page! Most placement decisions can be made in under 2 minutes using this flow. If you're spending more time than that, it's likely an edge case worth discussing with the team.
</Callout>

## UI Component Decision Tree

Understanding our three-layer UI architecture is crucial for maintaining clean separation of concerns:

```mermaid
flowchart TD
    UIComponent[UI Component] --> Q1{Single responsibility?<br/>No business logic?}
    
    Q1 -->|Yes| Q2{Basic building block?}
    Q1 -->|No| Q3{Composed from other components?}
    
    Q2 -->|Yes| Foundation[ui/foundation/<br/>Button, Text, Input]
    
    Q3 -->|Yes| Q4{Domain-agnostic?}
    Q3 -->|No| Q5{Contains business logic?}
    
    Q4 -->|Yes| Patterns[ui/patterns/<br/>Modal, Form, DataTable]
    
    Q5 -->|Yes| Q6{Used by 3+ features?}
    
    Q6 -->|Yes| Business[ui/business/<br/>ProductCard, UserAvatar]
    Q6 -->|No| FeatureComp[features/&lbrack;name&rbrack;/components/]
```

## Detailed Decision Process

<Steps>
  <Step>
    ### Step 1: Identify the Code Type

    First, understand what you're building. This categorization drives all subsequent decisions:

    | Code Type            | Description                         | Key Questions                                          |
    | -------------------- | ----------------------------------- | ------------------------------------------------------ |
    | **UI Component**     | Visual elements users interact with | Does it render JSX? Does it have styles?               |
    | **Business Logic**   | Core application functionality      | Does it manage data? Does it implement business rules? |
    | **Utility Function** | Helper functions and tools          | Is it a pure function? Is it reusable?                 |
    | **Navigation**       | Screen routing and navigation logic | Does it handle screen transitions?                     |
    | **Configuration**    | App settings and constants          | Is it app-wide configuration?                          |
    | **API Integration**  | Backend communication               | Does it fetch/send data to servers?                    |

    <Callout type="info">
      **Learning moment**: This categorization aligns with the **Separation of Concerns** principle. By clearly identifying what type of code you're writing, you ensure each piece has a single, well-defined responsibility.
    </Callout>
  </Step>

  <Step>
    ### Step 2: Determine Scope

    Understanding scope helps maintain proper code organization and reusability:

    ```mermaid
    flowchart LR
        Scope[Determine Scope] --> Global[Global/Shared]
        Scope --> Feature[Feature-Specific]
        Scope --> Domain[Domain-Specific]
        
        Global --> Example1[Used by 3+ features]
        Feature --> Example2[Used by 1 feature only]
        Domain --> Example3[Related to specific business entity]
    ```

    **The 3+ Rule Explained**:

    * Code used by **3 or more features** should be shared to avoid duplication
    * Code used by **1-2 features** can remain feature-specific to avoid premature abstraction
    * This threshold balances reusability with simplicity

    <Callout type="tip">
      **Real-world example**: A `formatCurrency()` function used in checkout, product listing, and order history should be in `core/shared/utils/`. A `calculateCheckoutTax()` function only used in checkout should stay in `features/checkout/utils/`.
    </Callout>
  </Step>

  <Step>
    ### Step 3: Apply Location Rules

    Now that you know the type and scope, here's exactly where your code belongs:

    <Tabs items={["UI Components", "Business Logic", "Utilities", "API Code"]}>
      <Tab>
        ### UI Component Placement

        Our three-layer architecture ensures clean separation and maximum reusability:

        ```
        # Foundation (atomic, no business logic)
        src/ui/foundation/
        ├── Button/
        │   ├── Button.tsx          # Component implementation
        │   ├── Button.test.tsx     # Tests co-located
        │   ├── types.ts           # TypeScript types
        │   └── index.ts           # Barrel export
        ├── Input/
        ├── Text/
        ├── Card/
        └── Icon/

        # Patterns (composed from foundation)
        src/ui/patterns/
        ├── Modal/
        │   ├── Modal.tsx
        │   ├── Modal.test.tsx
        │   ├── types.ts
        │   ├── components/        # Sub-components
        │   │   ├── ModalHeader.tsx
        │   │   └── ModalBody.tsx
        │   └── index.ts
        ├── Form/
        ├── DataTable/
        └── SearchBox/

        # Business (domain-aware, 3+ features)
        src/ui/business/
        ├── ProductCard/
        │   ├── ProductCard.tsx
        │   ├── ProductCard.test.tsx
        │   ├── types.ts
        │   └── index.ts
        ├── UserAvatar/
        └── OrderStatus/

        # Feature-specific
        src/features/shopping-cart/components/
        ├── CartItem/
        │   ├── CartItem.tsx
        │   ├── CartItem.test.tsx
        │   └── index.ts
        └── CartSummary/
        ```

        ### Component Guidelines by Layer

        **Foundation Components** ✨

        * **Purpose**: Basic building blocks of your UI
        * **Characteristics**:
          * Single responsibility
          * Zero business logic
          * Use design tokens exclusively
          * Highly reusable
        * **Examples**: Button, Input, Text, Icon, Card
        * **Think of them as**: LEGO blocks - simple, combinable, universal

        **Pattern Components** 🎨

        * **Purpose**: Common UI patterns built from foundation components
        * **Characteristics**:
          * Composed from foundation components
          * Handle complex UI interactions
          * Domain-agnostic (no business logic)
          * Reusable across different contexts
        * **Examples**: Modal, Form, DataTable, Accordion, Tabs
        * **Think of them as**: Pre-built LEGO structures - save time, ensure consistency

        **Business Components** 💼

        * **Purpose**: Domain-aware components used across multiple features
        * **Characteristics**:
          * Can use domain hooks for data
          * Encapsulate business logic
          * Shared by 3+ features
          * Handle their own loading/error states
        * **Examples**: ProductCard, UserAvatar, OrderStatus, PricingDisplay
        * **Think of them as**: Smart components that understand your business

        <Callout type="info">
          **Why this architecture?** This three-layer approach prevents business logic from leaking into presentational components, maximizes reusability, and makes it crystal clear where each component belongs. It's based on proven patterns from companies like Airbnb and Shopify.
        </Callout>
      </Tab>

      <Tab>
        ### Business Logic Placement

        Business logic lives in domains, organized by business entities:

        ```
        # Domain exists - add to it
        src/core/domains/products/
        ├── api.ts          # API calls
        ├── hooks.ts        # React Query hooks
        ├── types.ts        # TypeScript types
        ├── utils.ts        # Domain utilities
        ├── store.ts        # Zustand store (if needed)
        └── index.ts        # Barrel exports

        # No domain exists - create new one
        src/core/domains/notifications/
        ├── api.ts
        ├── hooks.ts
        ├── types.ts
        ├── queryKeys.ts    # Query key factory
        └── index.ts

        # Feature-specific logic (rare)
        src/features/product-search/
        └── utils/
            └── searchFilters.ts
        ```

        **When to create a new domain:**

        * You have a distinct business entity (User, Product, Order)
        * Multiple features will interact with this entity
        * It has its own API endpoints
        * It represents a cohesive business concept

        <Callout type="tip">
          **Domain-Driven Design**: Our domain structure follows DDD principles. Each domain is a bounded context that encapsulates all logic related to a specific business concept. This makes the codebase mirror the business structure.
        </Callout>
      </Tab>

      <Tab>
        ### Utility Function Placement

        Utilities are organized by scope and usage:

        ```
        # Global utilities (used across features)
        src/core/shared/utils/
        ├── date.ts         # Date formatting/parsing
        ├── currency.ts     # Money formatting
        ├── validation.ts   # Common validators
        ├── string.ts       # String manipulation
        └── array.ts        # Array helpers

        # Feature utilities (feature-specific)
        src/features/checkout/utils/
        ├── calculateTax.ts
        ├── validateCard.ts
        └── formatAddress.ts

        # Domain utilities (domain-specific)
        src/core/domains/orders/utils.ts
        ```

        **Guidelines for utilities:**

        * Pure functions (no side effects)
        * Well-tested (aim for 100% coverage)
        * Single responsibility
        * Named clearly (verb + noun)

        **Examples:**

        ```typescript
        // ✅ Good utility function
        export function formatCurrency(amount: number, currency = 'USD'): string {
          return new Intl.NumberFormat('en-US', {
            style: 'currency',
            currency,
          }).format(amount);
        }

        // ❌ Bad - does too much, has side effects
        export function processPayment(amount: number) {
          const formatted = formatCurrency(amount);
          console.log(formatted); // Side effect!
          updateDatabase(amount); // Side effect!
          return formatted;
        }
        ```
      </Tab>

      <Tab>
        ### API Integration Placement

        API code follows a consistent pattern within domains:

        ```
        # Domain API (strongly preferred)
        src/core/domains/users/api.ts
        export const getUser = async (id: string): Promise<User> => {
          return apiClient.get(`/users/${id}`);
        };

        export const updateUserProfile = async (
          id: string, 
          data: UpdateProfileDTO
        ): Promise<User> => {
          return apiClient.put(`/users/${id}/profile`, data);
        };

        # Corresponding hooks
        src/core/domains/users/hooks.ts
        export function useUser(id: string) {
          return useQuery({
            queryKey: userQueryKeys.detail(id),
            queryFn: () => getUser(id),
          });
        }

        # Feature-specific API (very rare)
        src/features/onboarding/api/
        └── onboardingSteps.ts

        # Shared API utilities
        src/core/api/
        ├── client.ts       # Axios instance setup
        ├── interceptors.ts # Request/response interceptors
        └── types.ts        # Shared API types
        ```

        **API Organization Principles:**

        * Group by domain, not by HTTP method
        * Co-locate API functions with their hooks
        * Use consistent naming: `get*`, `create*`, `update*`, `delete*`
        * Always return typed responses

        <Callout type="info">
          **Why domains?** Organizing APIs by domain (rather than having a single massive API file) keeps related code together, makes it easier to find endpoints, and naturally enforces boundaries between different parts of your application.
        </Callout>
      </Tab>
    </Tabs>
  </Step>

  <Step>
    ### Step 4: Check Existing Patterns

    Before creating anything new, always look for existing patterns:

    ```typescript
    // 1. Search for similar functionality
    // Look in: ui/foundation/* for basic components
    // Look in: ui/patterns/* for composed patterns
    // Look in: ui/business/* for domain components
    // Look in: core/domains/*/api.ts for API patterns
    // Look in: core/domains/*/hooks.ts for data fetching patterns
    // Look in: features/*/components/ for feature UI patterns

    // 2. Follow existing naming conventions
    // API: getUser, createUser, updateUser, deleteUser
    // Hooks: useUser, useUsers, useCreateUser
    // Components: UserCard, UserList, UserDetail
    // Utils: formatDate, validateEmail, calculateTotal
    ```

    <Callout type="warning">
      **Important**: Creating new patterns without checking existing ones is a major source of inconsistency. When in doubt, ask: "Have we solved this problem before?"
    </Callout>
  </Step>
</Steps>

## Common Scenarios

Let's walk through real decisions you'll face daily:

### Scenario 1: Creating a New UI Component

<Callout type="info">
  **Question**: "I need to create a button that shows a loading spinner. Where does it go?"
</Callout>

**Decision Process:**

1. Is it a basic component with single responsibility? → YES
2. Does it contain business logic? → NO
3. **Answer**: Create in `ui/foundation/Button/`

```typescript
// ui/foundation/Button/Button.tsx
import React from 'react';
import { TouchableOpacity, Text, ActivityIndicator } from 'react-native';
import { theme } from '@/core/shared/styles';

interface ButtonProps {
  loading?: boolean;
  onPress: () => void;
  children: React.ReactNode;
}

export function Button({ loading, children, onPress, ...props }: ButtonProps) {
  return (
    <TouchableOpacity 
      onPress={onPress} 
      disabled={loading}
      style={styles.button}
      {...props}
    >
      {loading ? (
        <ActivityIndicator color={theme.colors.white} />
      ) : (
        <Text style={styles.text}>{children}</Text>
      )}
    </TouchableOpacity>
  );
}
```

### Scenario 2: Creating a Product Display Component

<Callout type="info">
  **Question**: "I need a component to display product information with price, image, and add to cart."
</Callout>

**Decision Process:**

1. Does it use domain data (Product)? → YES
2. Contains business logic (pricing, cart)? → YES
3. Used by multiple features? → YES (catalog, search, recommendations)
4. **Answer**: Create in `ui/business/ProductCard/`

```typescript
// ui/business/ProductCard/ProductCard.tsx
import React from 'react';
import { View, Image, Text } from 'react-native';
import { Card } from '@/ui/foundation/Card';
import { Button } from '@/ui/foundation/Button';
import { PriceDisplay } from '@/ui/patterns/PriceDisplay';
import { useProduct } from '@/core/domains/products/hooks';
import { useCart } from '@/core/domains/cart/hooks';

interface ProductCardProps {
  productId: string;
  variant?: 'compact' | 'full';
}

export function ProductCard({ productId, variant = 'full' }: ProductCardProps) {
  const { data: product, isLoading } = useProduct(productId);
  const { addItem } = useCart();
  
  if (isLoading) return <ProductCardSkeleton />;
  if (!product) return null;
  
  const handleAddToCart = () => {
    addItem({ productId: product.id, quantity: 1 });
  };
  
  return (
    <Card variant={variant}>
      <Image source={{ uri: product.imageUrl }} style={styles.image} />
      <Text style={styles.name}>{product.name}</Text>
      <PriceDisplay 
        price={product.price} 
        salePrice={product.salePrice}
      />
      <Button onPress={handleAddToCart}>
        Add to Cart
      </Button>
    </Card>
  );
}
```

### Scenario 3: Creating a Modal Pattern

<Callout type="info">
  **Question**: "I need a reusable modal component for forms and confirmations."
</Callout>

**Decision Process:**

1. Is it composed from other components? → YES
2. Is it domain-agnostic? → YES
3. Is it a common UI pattern? → YES
4. **Answer**: Create in `ui/patterns/Modal/`

```typescript
// ui/patterns/Modal/Modal.tsx
import React from 'react';
import { View, Modal as RNModal } from 'react-native';
import { Button } from '@/ui/foundation/Button';
import { Card } from '@/ui/foundation/Card';
import { IconButton } from '@/ui/foundation/IconButton';

interface ModalProps {
  visible: boolean;
  onClose: () => void;
  title?: string;
  children: React.ReactNode;
}

export function Modal({ visible, onClose, title, children }: ModalProps) {
  return (
    <RNModal
      visible={visible}
      transparent
      animationType="fade"
      onRequestClose={onClose}
    >
      <View style={styles.overlay}>
        <Card style={styles.modal}>
          {title && (
            <View style={styles.header}>
              <Text style={styles.title}>{title}</Text>
              <IconButton icon="close" onPress={onClose} />
            </View>
          )}
          {children}
        </Card>
      </View>
    </RNModal>
  );
}
```

## Special Cases

### When to Create Business Components

Create a business component when ALL of these are true:

* (Do ✅) It works with domain entities (Product, User, Order)
* (Do ✅) It's used by 3+ features
* (Do ✅) It contains business logic or calculations
* (Do ✅) It needs domain hooks for data

Examples that qualify:

* `ProductCard` - displays product with pricing logic
* `UserAvatar` - shows user with online status
* `OrderStatusBadge` - shows order state with business rules

Examples that don't qualify:

* (Don't ❌) `Button` - just styling variations → Foundation
* (Don't ❌) `LoadingSpinner` - no business logic → Foundation
* (Don't ❌) `CheckoutForm` - feature-specific → Feature component

### When to Create Pattern Components

Create a pattern component when:

* (Do ✅) It's a common UI pattern (Modal, Tabs, Accordion)
* (Do ✅) It's composed from foundation components
* (Do ✅) It's completely domain-agnostic
* (Do ✅) It handles complex UI interactions

Examples:

* `DataTable` - complex table with sorting/filtering
* `DatePicker` - date selection interface
* `Wizard` - multi-step form navigation

### When to Create Foundation Components

Create a foundation component when:

* (Do ✅) It's an atomic building block
* (Do ✅) It has single responsibility
* (Do ✅) It's purely presentational
* (Do ✅) It only uses design tokens for styling

Examples:

* `Button`, `Input`, `Text` - basic elements
* `Card`, `Surface` - layout components
* `Icon`, `Avatar` - simple display components

## Feature Development Checklists

### Pre-Development Checklist

Before writing any code, ensure:

* [ ] **ADR created** for significant architectural decisions
* [ ] **File placement determined** using the decision tree above
* [ ] **Dependencies identified** - What domains/features will you integrate with?
* [ ] **Performance requirements defined** - Response time, memory usage, etc.
* [ ] **Security implications assessed** - Auth requirements, data sensitivity
* [ ] **Similar features reviewed** - Check existing patterns to follow
* [ ] **API contracts defined** - If creating new endpoints
* [ ] **Error scenarios mapped** - Happy, sad, mad, and bad paths

### During Development Checklist

While implementing, verify:

* [ ] **Following naming conventions** exactly as documented
* [ ] **Code aligns with patterns** from similar features
* [ ] **Error handling matches** team standards
* [ ] **Documentation written** alongside code (not after!)
* [ ] **Tests written** for all new functionality
* [ ] **Design tokens used** for all UI styling
* [ ] **No magic numbers/strings** - Use constants
* [ ] **Accessibility considered** - ARIA labels, keyboard navigation

### Pre-Merge Checklist

Before creating PR:

* [ ] **All checklist items** verified above
* [ ] **Documentation updated** in same PR
* [ ] **No TypeScript errors** - Run `npx tsc --noEmit`
* [ ] **Linting passes** - Run `npm run lint`
* [ ] **Tests passing** with >90% coverage
* [ ] **Bundle size checked** - No unexpected increases
* [ ] **Performance tested** - No regressions
* [ ] **Code review self-check** using team template

## Enforcement Checklist

Use this final checklist before committing any code:

* [ ] Code is in the correct location per this guide
* [ ] UI components are in the right layer (foundation/patterns/business)
* [ ] Foundation components use design tokens exclusively
* [ ] Business components use domain hooks appropriately
* [ ] File naming conventions are followed exactly
* [ ] Imports use correct path aliases (@/)
* [ ] Tests are co-located with code
* [ ] Barrel exports (index.ts) are updated
* [ ] No code duplication with existing components

## Quick Reference Card

```
📁 src/
├── 🎨 ui/                    → UI Component Library
│   ├── 🧱 foundation/       → Atomic components (Button, Text, Input)
│   ├── 🎭 patterns/         → Composed patterns (Modal, Form, DataTable)
│   └── 💼 business/         → Domain-aware (ProductCard, UserAvatar)
├── 🏗️ core/
│   ├── 🏢 domains/          → Business logic by entity
│   ├── 🔧 shared/           → Shared utilities & hooks
│   │   └── 🎨 styles/       → Design tokens & theme
│   ├── 🌐 api/              → API client setup
│   └── ⚙️ config/           → App configuration
├── 🎯 features/             → User-facing features
│   └── [feature]/
│       ├── 📱 screens/      → Feature screens
│       ├── 🧩 components/   → Feature-specific components
│       ├── 🧭 navigation.tsx → Feature navigation
│       └── 🔨 utils/        → Feature utilities
└── 🚦 navigation/           → Root navigation setup
```

## For AI Assistants

<Callout type="warning">
  **AI Instructions**: Follow this decision tree exactly. Each file placement decision should be traceable through this guide.
</Callout>

When implementing features:

1. Always determine the component layer first (foundation/patterns/business)
2. Foundation components must have zero business logic
3. Patterns must be composed from foundation only
4. Business components should use domain hooks
5. Check for existing similar components before creating new ones
6. Follow the exact folder structure shown above

## Related Documents

* [UI Architecture Overview](/docs/ui-development/architecture) - Deep dive into our UI layers
* [Project Structure Reference](/docs/architecture/project-structure) - Complete codebase organization
* [File Naming Conventions](/docs/coding-standards/file-naming-conventions) - Naming standards
* [Domain Architecture Guide](/docs/architecture/domain-architecture) - Understanding domains
* [Component Development Guide](/docs/guides/component-development) - Best practices


# UTA Implementation Guides: AI Documentation Workflow
URL: https://dev.updatetheapp.com/docs/guides/ai-documentation-workflow
Documentation: https://dev.updatetheapp.com/docs/guides/ai-documentation-workflow

How to properly use AI assistants with system rules to maintain consistent, accurate documentation
        
***

title: AI Documentation Workflow
description: How to properly use AI assistants with system rules to maintain consistent, accurate documentation
---------------------------------------------------------------------------------------------------------------

import { Callout } from 'fumadocs-ui/components/callout';
import { Steps, Step } from 'fumadocs-ui/components/steps';

# AI Documentation Workflow

## Overview

This guide establishes the proper workflow for using AI assistants to create and maintain documentation while ensuring consistency with our system rules and preventing contradictions.

<Callout type="warning">
  **Critical Requirement**: All AI-generated documentation must follow this workflow to prevent architectural contradictions and maintain single-author consistency across the project.
</Callout>

## Pre-Documentation Checklist

Before asking AI to write or modify ANY documentation:

<Steps>
  <Step>
    ### Step 1: Identify Authoritative Sources

    Always identify and reference the authoritative source for the topic:

    ```bash
    □ Check the Feature Implementation Decision Tree first
    □ Verify current implementation examples in codebase
    □ Identify any existing documentation on the topic
    □ Note any system rules that apply
    ```

    **Primary Sources (in order of authority):**

    1. **Feature Implementation Decision Tree** - Authoritative for all placement decisions
    2. **Existing implementations** - Actual code in the codebase
    3. **AI Coding Standards** - Single author consistency rules
    4. **Documentation Guidelines** - Structure and format rules
  </Step>

  <Step>
    ### Step 2: Search for Existing Patterns

    ```bash
    □ Search codebase for similar implementations
    □ Check multiple component examples for consistency
    □ Verify patterns match the decision tree guidance
    □ Look for any conflicting guidance in existing docs
    ```

    **Required Search Commands:**

    ```bash
    # Search for existing component structures
    find ui/foundation -name "types.ts" -type f

    # Search for existing pattern examples  
    grep -r "interface.*Props" ui/

    # Check for contradictory guidance
    grep -r "ButtonProps" content/docs/
    ```
  </Step>

  <Step>
    ### Step 3: Verify No Contradictions Exist

    ```bash
    □ Cross-reference multiple documentation sources
    □ Check if guidance matches actual implementations
    □ Identify any outdated or conflicting information
    □ Note discrepancies for correction
    ```

    If contradictions are found, **STOP** and resolve them before proceeding.
  </Step>
</Steps>

## Proper AI Prompting Format

### ❌ WRONG Prompting

```
"Document how to create component types"
"Write documentation about ButtonProps"
"Create a guide for type organization"
```

### ✅ CORRECT Prompting

```
"Based on the Feature Implementation Decision Tree at /docs/guides/feature-implementation-decision-tree, 
I need to document component type placement. I've verified that:

1. Foundation components use co-located types (confirmed in ui/foundation/Button/types.ts)
2. The decision tree shows types.ts files within component directories
3. All examples follow this pattern consistently

Please follow:
- @ai-coding-standards for single author consistency
- @technical-documentation-guidelines for structure
- @documentation-writing-best-practices for DRY principle

Reference the decision tree as the authoritative source and ensure all examples align with it."
```

## Required AI Response Format

AI responses MUST start with verification:

```
"Based on the Feature Implementation Decision Tree, component types belong in [exact location]..."
"I found consistent patterns in [specific files] that confirm this approach..."
"This aligns with the authoritative guidance in [reference document]..."
```

## Documentation Verification Process

After AI generates documentation:

<Steps>
  <Step>
    ### Step 1: Verify Accuracy

    ```bash
    □ Does the guidance match the Feature Implementation Decision Tree?
    □ Are the examples consistent with existing implementations?
    □ Does it reference the correct authoritative sources?
    □ Are file paths accurate per the actual project structure?
    ```
  </Step>

  <Step>
    ### Step 2: Check for Contradictions

    ```bash
    □ Search for conflicting guidance in other docs
    □ Verify examples match the recommended patterns
    □ Ensure no outdated information is referenced
    □ Check that terminology is consistent project-wide
    ```
  </Step>

  <Step>
    ### Step 3: Cross-Reference Links

    ```bash
    □ Do all internal links point to correct documents?
    □ Are cross-references accurate and helpful?
    □ Is the documentation following DRY principle?
    □ Are we referencing the single source of truth?
    ```
  </Step>
</Steps>

## Preventing Common Mistakes

### Mistake 1: Ignoring the Decision Tree

**Problem**: Writing placement guidance without consulting the Feature Implementation Decision Tree.

**Solution**: Always reference the decision tree first and use it as the authoritative source.

**Example Prevention**:

```markdown
// ❌ WRONG
Place ButtonProps in core/shared/types/ for reusability.

// ✅ CORRECT  
Per the [Feature Implementation Decision Tree](/docs/guides/feature-implementation-decision-tree), 
ButtonProps belongs in ui/foundation/Button/types.ts as foundation components use co-located types.
```

### Mistake 2: Creating Contradictory Examples

**Problem**: Showing examples that contradict established patterns.

**Solution**: Always verify examples against actual implementations.

**Example Prevention**:

```typescript
// ❌ WRONG - Shows ButtonProps in shared types
// core/shared/types/ui.ts
export interface ButtonProps { ... }

// ✅ CORRECT - Shows actual pattern from codebase
// ui/foundation/Button/types.ts
export interface ButtonProps { ... }
```

### Mistake 3: Missing Cross-References

**Problem**: Not linking to authoritative sources.

**Solution**: Always reference the decision tree and related documentation.

**Example Prevention**:

```markdown
// ❌ WRONG
Component types should be co-located.

// ✅ CORRECT
Component types should be co-located with their components, as specified in the 
[Feature Implementation Decision Tree](/docs/guides/feature-implementation-decision-tree).
```

## Quality Assurance Checklist

Before publishing any AI-generated documentation:

### Content Accuracy

* [ ] All file paths exist and are correct
* [ ] Examples match actual implementations
* [ ] Guidance aligns with authoritative sources
* [ ] No contradictory information introduced

### Consistency

* [ ] Terminology matches project standards
* [ ] Format follows documentation guidelines
* [ ] Cross-references are accurate and helpful
* [ ] Tone matches existing documentation

### Architectural Alignment

* [ ] Placement decisions reference decision tree
* [ ] Examples follow established patterns
* [ ] Import paths are accurate
* [ ] Component organization follows three-layer architecture

## Update Workflow for Contradictions

When contradictions are discovered:

<Steps>
  <Step>
    ### Step 1: Identify Root Source

    ```bash
    □ Find the authoritative source (usually decision tree)
    □ Identify all contradictory documentation
    □ List specific files that need updating
    □ Verify the correct pattern in actual code
    ```
  </Step>

  <Step>
    ### Step 2: Plan Updates

    ```bash
    □ Update contradictory files to match authoritative source
    □ Add cross-references to prevent future contradictions
    □ Include clarifying notes about common misconceptions
    □ Update any related examples or patterns
    ```
  </Step>

  <Step>
    ### Step 3: Apply Changes

    ```bash
    □ Update all conflicting documentation
    □ Add proper cross-references
    □ Verify consistency across all updated files
    □ Test that all links still work
    ```
  </Step>
</Steps>

## Success Criteria

Documentation following this workflow will achieve:

✅ **Consistency**: All guidance aligns with authoritative sources
✅ **Accuracy**: Examples match actual implementations
✅ **Maintainability**: Single source of truth prevents drift
✅ **Usability**: Clear, non-contradictory guidance for developers

## Tools and Commands

### Essential Search Commands

```bash
# Find component type patterns
find ui/ -name "types.ts" -exec grep -l "interface.*Props" {} \;

# Search for contradictory guidance
grep -r "ButtonProps" content/docs/ | grep -v "ui/foundation"

# Verify file paths in documentation
grep -r "ui/foundation/Button" content/docs/
```

### Verification Scripts

```bash
# Check for common contradictions
./scripts/check-documentation-consistency.sh

# Verify all internal links work
./scripts/verify-doc-links.sh

# Validate examples against actual code
./scripts/validate-doc-examples.sh
```

## Related Documentation

* [Feature Implementation Decision Tree](/docs/guides/feature-implementation-decision-tree) - Primary reference for all placement decisions
* [AI Coding Standards](.cursor/rules/ai-coding-standards.mdc) - Single author consistency requirements
* [Documentation Writing Best Practices](.cursor/rules/documentation-writing-best-practices.mdc) - DRY principle and cross-referencing
* [Technical Documentation Guidelines](.cursor/rules/technical-documentation-guidelines.mdc) - Structure and format requirements

<Callout type="info">
  **Remember**: The Feature Implementation Decision Tree is the authoritative source for all architectural decisions. When in doubt, reference it first and ensure all documentation aligns with its guidance.
</Callout>


# UTA Implementation Guides: Project Structure Migration Guide
URL: https://dev.updatetheapp.com/docs/guides/project-structure-migration
Documentation: https://dev.updatetheapp.com/docs/guides/project-structure-migration

Step-by-step guide for migrating to the hybrid architecture with domain-based business logic and feature-based UI organization.
        
***

title: Project Structure Migration Guide
description: Step-by-step guide for migrating to the hybrid architecture with domain-based business logic and feature-based UI organization.
--------------------------------------------------------------------------------------------------------------------------------------------

# Project Structure Migration Guide

## Overview

This guide provides practical implementation steps for migrating from the legacy project structure to the new hybrid architecture that combines feature-based UI organization with domain-based business logic. It offers concrete examples, code snippets, and troubleshooting tips to help developers successfully transition existing code and implement new features according to the architectural guidelines.

## When To Use

Use this guide when:

* Starting development on a new feature that should follow the hybrid architecture
* Refactoring existing code to align with the new architectural patterns
* Extracting domain logic currently embedded within UI components
* Creating reusable domain services that can be used across multiple features
* Resolving circular dependencies caused by incorrect code organization

## Implementation Patterns

import { Step, Steps } from 'fumadocs-ui/components/steps';

### Migrating Existing Code

<Steps>
  <Step>
    #### Analyze the Current Code Structure

    Before migrating, analyze your code to identify:

    * Business domain logic currently mixed with UI
    * API calls that should be in domain services
    * Shared utilities that are truly generic vs. domain-specific
    * Circular dependencies that need resolution

    ```typescript
    // Example: UI component with embedded domain logic to refactor
    // ProductList.tsx
    const ProductList = () => {
      const [products, setProducts] = useState([]);
      const [loading, setLoading] = useState(false);
      
      // Domain logic mixed with UI - this should be extracted
      const fetchProducts = async () => {
        setLoading(true);
        try {
          const response = await axios.get('/api/products');
          setProducts(response.data);
        } catch (error) {
          console.error('Failed to fetch products', error);
        } finally {
          setLoading(false);
        }
      };
      
      useEffect(() => {
        fetchProducts();
      }, []);
      
      // Rendering logic...
    }
    ```
  </Step>

  <Step>
    #### Extract Domain Logic

    Create a new domain directory structure and move business logic there:

    ```bash
    mkdir -p src/core/domains/products
    touch src/core/domains/products/api.ts
    touch src/core/domains/products/types.ts
    touch src/core/domains/products/hooks.ts
    ```

    Define domain types:

    ```typescript
    // src/core/domains/products/types.ts
    export interface Product {
      id: string;
      name: string;
      description: string;
      price: number;
      imageUrl?: string;
    }

    export interface ProductFilters {
      category?: string;
      minPrice?: number;
      maxPrice?: number;
    }
    ```

    Create API service methods:

    ```typescript
    // src/core/domains/products/api.ts
    import { apiClient } from '@/core/shared/api/client';
    import type { Product, ProductFilters } from './types';

    export const getProducts = async (filters?: ProductFilters): Promise<Product[]> => {
      const response = await apiClient.get('/products', { params: filters });
      return response.data;
    };

    export const getProduct = async (id: string): Promise<Product> => {
      const response = await apiClient.get(`/products/${id}`);
      return response.data;
    };
    ```
  </Step>

  <Step>
    #### Create Domain Query Hooks

    Implement React hooks that use TanStack Query to manage the data:

    ```typescript
    // src/core/domains/products/hooks.ts
    import { useQuery } from '@tanstack/react-query';
    import * as productsApi from './api';
    import type { Product, ProductFilters } from './types';

    // Query keys
    const PRODUCTS_KEY = 'products';

    export const useProducts = (filters?: ProductFilters) => {
      return useQuery({
        queryKey: [PRODUCTS_KEY, filters],
        queryFn: () => productsApi.getProducts(filters)
      });
    };

    export const useProduct = (id: string) => {
      return useQuery({
        queryKey: [PRODUCTS_KEY, id],
        queryFn: () => productsApi.getProduct(id),
        enabled: !!id
      });
    };
    ```
  </Step>

  <Step>
    #### Update UI Components

    Refactor UI components to use the domain hooks:

    ```typescript
    // src/features/product-catalog/screens/ProductListScreen.tsx
    import { useProducts } from '@/core/domains/products/hooks';
    import type { ProductFilters } from '@/core/domains/products/types';

    const ProductListScreen = () => {
      const [filters, setFilters] = useState<ProductFilters>({});
      
      // Use domain hook instead of local state + fetch
      const { data: products, isLoading, error } = useProducts(filters);
      
      // Filter handling logic...
      
      // UI rendering...
      return (
        <View>
          {isLoading ? (
            <LoadingSpinner />
          ) : error ? (
            <ErrorMessage error={error} />
          ) : (
            <ProductGrid products={products || []} />
          )}
        </View>
      );
    };
    ```
  </Step>
</Steps>

### Creating New Features With Hybrid Architecture

<Steps>
  <Step>
    #### Plan Domain and Feature Boundaries

    Identify the domains your feature will interact with and determine what new domain entities might be needed:

    ```
    Feature: Shopping Cart

    Domains needed:
    - products (existing): Product information, pricing
    - cart (new): Cart items, calculation logic
    - user (existing): User information for checkout
    ```
  </Step>

  <Step>
    #### Create Domain Logic First

    Always start by implementing the domain logic before UI components:

    ```typescript
    // src/core/domains/cart/types.ts
    import type { Product } from '@/core/domains/products/types';

    export interface CartItem {
      productId: string;
      quantity: number;
      productSnapshot?: Partial<Product>;
    }

    export interface Cart {
      items: CartItem[];
      subtotal: number;
      tax: number;
      total: number;
    }
    ```

    ```typescript
    // src/core/domains/cart/store.ts
    import { create } from 'zustand';
    import { persist } from 'zustand/middleware';
    import type { Cart, CartItem } from './types';

    interface CartState {
      cart: Cart;
      addItem: (item: CartItem) => void;
      removeItem: (productId: string) => void;
      updateQuantity: (productId: string, quantity: number) => void;
      clearCart: () => void;
    }

    export const useCartStore = create<CartState>()(
      persist(
        (set, get) => ({
          cart: {
            items: [],
            subtotal: 0,
            tax: 0,
            total: 0,
          },
          
          // Cart methods implementation...
          addItem: (item) => {
            // Implementation
          },
          
          removeItem: (productId) => {
            // Implementation
          },
          
          updateQuantity: (productId, quantity) => {
            // Implementation
          },
          
          clearCart: () => {
            // Implementation
          },
        }),
        {
          name: 'cart-storage',
        }
      )
    );
    ```
  </Step>

  <Step>
    #### Create Domain Hooks

    Create hooks that expose domain functionality to UI components:

    ```typescript
    // src/core/domains/cart/hooks.ts
    import { useCartStore } from './store';
    import type { CartItem } from './types';

    export const useCart = () => {
      const { cart, addItem, removeItem, updateQuantity, clearCart } = useCartStore();
      
      const totalItems = cart.items.reduce((sum, item) => sum + item.quantity, 0);
      
      return {
        cart,
        totalItems,
        addItem,
        removeItem,
        updateQuantity,
        clearCart,
        isEmpty: cart.items.length === 0,
      };
    };
    ```
  </Step>

  <Step>
    #### Build Feature UI Components

    Now implement the feature UI components:

    ```typescript
    // src/features/shopping-cart/components/CartItem/CartItem.tsx
    import { useCart } from '@/core/domains/cart/hooks';
    import { formatCurrency } from '@/core/shared/utils/number';

    type CartItemProps = {
      productId: string;
      quantity: number;
      name: string;
      price: number;
    };

    const CartItem = ({ productId, quantity, name, price }: CartItemProps) => {
      const { updateQuantity, removeItem } = useCart();
      
      return (
        <View style={styles.container}>
          <Text style={styles.name}>{name}</Text>
          <Text style={styles.price}>{formatCurrency(price)}</Text>
          {/* Quantity controls */}
          {/* Remove button */}
        </View>
      );
    };
    ```

    ```typescript
    // src/features/shopping-cart/screens/CartScreen/CartScreen.tsx
    import { useCart } from '@/core/domains/cart/hooks';
    import { CartItem } from '../../components/CartItem';

    const CartScreen = () => {
      const { cart, totalItems, clearCart } = useCart();
      
      if (cart.isEmpty) {
        return <EmptyCartMessage />;
      }
      
      return (
        <View style={styles.container}>
          <FlatList
            data={cart.items}
            renderItem={({ item }) => (
              <CartItem
                productId={item.productId}
                quantity={item.quantity}
                name={item.productSnapshot?.name || ''}
                price={item.productSnapshot?.price || 0}
              />
            )}
            keyExtractor={(item) => item.productId}
          />
          
          <CartSummary
            subtotal={cart.subtotal}
            tax={cart.tax}
            total={cart.total}
          />
          
          <Button
            title="Proceed to Checkout"
            onPress={handleCheckout}
          />
        </View>
      );
    };
    ```
  </Step>
</Steps>

## Common Challenges

### Circular Dependencies

**Problem**: You have modules that import from each other, creating a circular dependency.

**Solution**:

1. Identify the cycle in the dependency graph
2. Extract shared types to a separate file
3. Use interfaces instead of direct imports when possible

```typescript
// Before: Circular dependency between products and cart

// core/domains/products/types.ts
import { CartItem } from '@/core/domains/cart/types'; // Circular!

// core/domains/cart/types.ts  
import { Product } from '@/core/domains/products/types'; // Circular!

// After: Resolving with proper interfaces

// core/domains/products/types.ts
export interface Product {
  id: string;
  name: string;
  price: number;
}

// core/domains/cart/types.ts
export interface CartItem {
  productId: string;
  quantity: number;
  productSnapshot?: {
    name?: string;
    price?: number;
  };
}
```

### Domain Boundary Decisions

**Problem**: Unsure where to place code that seems to belong to multiple domains.

**Solution**:

* Identify the primary responsibility of the code
* Consider which domain would be most affected by changes to this code
* If truly shared, create a new domain or place in appropriate shared folder

### Refactoring Large Components

**Problem**: Large components with mixed concerns are difficult to migrate.

**Solution**:

1. Start by extracting pure UI components
2. Move data fetching to custom hooks
3. Extract business logic to domain services
4. Finally, reconnect using the clean architecture pattern

## Performance Considerations

### Minimize Re-renders

* Use selector functions when accessing domain state to prevent unnecessary re-renders
* Consider memoization for expensive calculations
* Keep state updates granular to avoid cascading re-renders

```typescript
// Good: Using selectors for performance
const totalItems = useCartStore(state => state.cart.items.reduce(
  (sum, item) => sum + item.quantity, 0
));

// Bad: Will cause re-renders on any cart change
const { cart } = useCartStore();
const totalItems = cart.items.reduce((sum, item) => sum + item.quantity, 0);
```

### Lazy Loading Domains

For large applications, consider implementing lazy loading of domain logic:

```typescript
// Dynamic import example
const ProductDetail = () => {
  const [productService, setProductService] = useState(null);
  
  useEffect(() => {
    // Dynamically import the domain logic when needed
    import('@/core/domains/products/service').then(module => {
      setProductService(module);
    });
  }, []);
  
  if (!productService) return <Loading />;
  
  // Rest of component using productService
};
```

## Examples

### Full Migration Example: User Profile Feature

This example shows how to migrate a user profile feature from the old structure to the new hybrid architecture:

```typescript
// Old structure: Everything in the feature folder
// features/profile/ProfileScreen.jsx

const ProfileScreen = () => {
  const [profile, setProfile] = useState(null);
  const [loading, setLoading] = useState(true);
  
  useEffect(() => {
    fetchUserProfile();
  }, []);
  
  const fetchUserProfile = async () => {
    setLoading(true);
    try {
      const response = await fetch('/api/user/profile');
      const data = await response.json();
      setProfile(data);
    } catch (error) {
      console.error(error);
    } finally {
      setLoading(false);
    }
  };
  
  const updateProfile = async (updates) => {
    try {
      const response = await fetch('/api/user/profile', {
        method: 'PUT',
        body: JSON.stringify(updates),
      });
      const updatedProfile = await response.json();
      setProfile(updatedProfile);
    } catch (error) {
      console.error(error);
    }
  };
  
  // Rendering logic...
};
```

After migration:

```typescript
// Domain logic: core/domains/users/types.ts
export interface UserProfile {
  id: string;
  name: string;
  email: string;
  avatar?: string;
  preferences: {
    notifications: boolean;
    theme: 'light' | 'dark' | 'system';
  };
}

// Domain logic: core/domains/users/api.ts
import { apiClient } from '@/core/shared/api/client';
import type { UserProfile } from './types';

export const getUserProfile = async (): Promise<UserProfile> => {
  const response = await apiClient.get('/user/profile');
  return response.data;
};

export const updateUserProfile = async (updates: Partial<UserProfile>): Promise<UserProfile> => {
  const response = await apiClient.put('/user/profile', updates);
  return response.data;
};

// Domain logic: core/domains/users/hooks.ts
import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
import * as usersApi from './api';
import type { UserProfile } from './types';

const USER_PROFILE_KEY = 'userProfile';

export const useUserProfile = () => {
  return useQuery({
    queryKey: [USER_PROFILE_KEY],
    queryFn: usersApi.getUserProfile
  });
};

export const useUpdateUserProfile = () => {
  const queryClient = useQueryClient();
  
  return useMutation({
    mutationFn: usersApi.updateUserProfile,
    onSuccess: (data) => {
      queryClient.setQueryData([USER_PROFILE_KEY], data);
    }
  });
};

// UI component: features/profile/screens/ProfileScreen/ProfileScreen.tsx
import { useUserProfile, useUpdateUserProfile } from '@/core/domains/users/hooks';

const ProfileScreen = () => {
  const { data: profile, isLoading, error } = useUserProfile();
  const { mutate: updateProfile, isPending: isUpdating } = useUpdateUserProfile();
  
  const handleUpdateProfile = (updates) => {
    updateProfile(updates);
  };
  
  if (isLoading) return <LoadingSpinner />;
  if (error) return <ErrorMessage error={error} />;
  
  // Rendering logic using profile data and handleUpdateProfile...
};
```

This migration:

1. Separates domain logic (data types, API calls) from UI concerns
2. Uses TanStack Query for data fetching and caching
3. Makes testing easier by isolating business logic
4. Improves reusability of the user profile functionality

## Related Resources

* [Project Structure Reference](/docs//architecture/project-structure) - Comprehensive reference for the project's directory structure
* [Core Architecture](/docs//architecture/core-architecture) - Overview of the application's hybrid architecture approach
* [State Management Guide](/docs/guides/client-state-management) - Implementation patterns for client state
* [Server State Guide](/docs/guides/server-state-management) - Implementation patterns for server state


# UTA Implementation Guides: AI-Assisted Development Guide
URL: https://dev.updatetheapp.com/docs/guides/ai-assisted-development
Documentation: https://dev.updatetheapp.com/docs/guides/ai-assisted-development

Team-wide AI prompt templates and guidelines for consistent code generation
        
***

title: AI-Assisted Development Guide
description: Team-wide AI prompt templates and guidelines for consistent code generation
----------------------------------------------------------------------------------------

import { Callout } from 'fumadocs-ui/components/callout';
import { Tabs, Tab } from 'fumadocs-ui/components/tabs';
import { Steps, Step } from 'fumadocs-ui/components/steps';

# AI-Assisted Development Guide

## Overview

This guide helps you leverage AI assistants effectively while maintaining our codebase's consistency. By using standardized prompts and following these guidelines, AI-generated code will seamlessly integrate with our existing patterns, making it indistinguishable from human-written code.

<Callout type="info">
  **Why standardized prompts?** AI assistants are powerful but need proper context. Our templates provide the exact context needed to generate code that follows our patterns, uses our conventions, and integrates perfectly with existing code.
</Callout>

## Getting Started with AI Assistance

<Tabs items={["Quick Start", "Understanding AI", "Best Practices"]}>
  <Tab>
    ### Quick Start Guide

    1. **Choose the right template** from our Core Prompt Templates below
    2. **Fill in the placeholders** with your specific requirements
    3. **Review and refine** the generated code against our standards
    4. **Run validation** before committing: `npx tsc --noEmit && npm run lint`

    <Callout type="tip">
      **Time saver**: Using our templates typically reduces development time by 40% while maintaining 100% standard compliance.
    </Callout>
  </Tab>

  <Tab>
    ### Understanding AI Limitations

    AI assistants are excellent at:

    * Following patterns when given clear examples
    * Generating boilerplate code quickly
    * Suggesting multiple implementation approaches
    * Catching common mistakes

    But they need help with:

    * Understanding your specific project context
    * Following non-standard conventions
    * Making architectural decisions
    * Maintaining consistency without examples

    Our templates bridge these gaps by providing the necessary context.
  </Tab>

  <Tab>
    ### Best Practices Summary

    1. **Always provide context** - Use our templates
    2. **Review critically** - AI can make mistakes
    3. **Iterate** - Refine outputs to match standards exactly
    4. **Learn from outputs** - Understand why code is structured certain ways
    5. **Share improvements** - Update templates based on experience
  </Tab>
</Tabs>

## Core Prompt Templates

### Feature Implementation Template

Use this template when implementing complete features:

```
Context: Working on UTA DevHub React Native application
Tech Stack: React Native, TypeScript, React Query, Zustand
Standards: Follow patterns in /docs/standards/
Architecture: Three-layer UI (foundation/patterns/business), Domain-driven design

Task: Implement [feature description]

Requirements:
- Must follow existing patterns in features/[similar-feature]
- Use established error handling from core/shared/errors
- Include tests matching team coverage standards (90%+)
- Documentation must include usage examples
- Follow our exact file placement rules (see decision tree)

Constraints:
- No new dependencies without ADR
- Must maintain backward compatibility
- Performance budget: [specific metrics]
- Use design tokens from core/shared/styles/

Example to follow:
[Reference similar implemented feature]
```

<Callout type="info">
  **Pro tip**: The more specific your examples, the better the output. Always reference a similar feature that already exists in your codebase.
</Callout>

### Component Generation Template

For creating new UI components:

```
Generate a React Native component for UTA DevHub following these specifications:

Component: [ComponentName]
Purpose: [Brief description]
Type: [foundation | pattern | business | feature-specific]
Location: [exact folder path based on type]

Requirements:
1. Use TypeScript with strict mode
2. Include proper error boundaries
3. Follow our naming convention: PascalCase for components
4. Import design tokens from '@/core/shared/styles'
5. Use our standard loading/error states
6. Include comprehensive JSDoc documentation
7. Export through index.ts barrel file
8. Follow our exact component structure (see example)

Component Structure:
// 1. Imports (in our specific order)
// 2. Type definitions (interfaces, not types for objects)
// 3. Component function declaration (not arrow function)
// 4. Hooks in order: state, context, custom
// 5. Event handlers
// 6. Render
// 7. Styles using StyleSheet

Example Pattern:
[Include code snippet from similar component]
```

### Hook Generation Template

For custom React hooks:

```
Generate a custom React hook for UTA DevHub:

Hook: use[HookName]
Purpose: [What it manages/provides]
Location: [domain hooks or shared hooks based on scope]

Requirements:
1. Follow our hook structure pattern
2. Use React Query for server state
3. Use Zustand for client state if needed
4. Include proper TypeScript types
5. Export consistent return object
6. Handle loading, error, and success states
7. Include JSDoc with usage examples

Return Object Pattern:
{
  // State
  data: T | undefined;
  // Status
  isLoading: boolean;
  error: Error | null;
  // Actions
  refetch: () => void;
  // Mutations if applicable
  create: (data: T) => Promise<void>;
}

Reference: See similar hooks in core/domains/*/hooks.ts
```

### Test Generation Template

For comprehensive test coverage:

```
Generate comprehensive tests for [ComponentName] following UTA DevHub standards:

Test Requirements:
1. Use Jest and React Testing Library
2. File name: [ComponentName].test.tsx
3. Achieve 90%+ coverage minimum
4. Test happy path, error states, and edge cases
5. Mock API calls using our apiClient mock
6. Follow AAA pattern (Arrange, Act, Assert)
7. Include accessibility tests
8. Test user interactions thoroughly

Test Structure:
describe('[ComponentName]', () => {
  // Setup and mocks
  
  describe('Rendering', () => {
    // Initial render tests
  });
  
  describe('User Interactions', () => {
    // Click, type, etc.
  });
  
  describe('Error States', () => {
    // Error handling
  });
  
  describe('Edge Cases', () => {
    // Boundary conditions
  });
});

Reference: See [SimilarComponent].test.tsx for patterns
```

## Specific Use Case Templates

<Tabs items={["API Integration", "State Management", "UI Components", "Error Handling"]}>
  <Tab>
    ### API Integration Template

    Creating consistent API integrations:

    ```
    Create an API integration for [resource] in UTA DevHub:

    Domain: [domain name]
    Resource: [resource name]
    Endpoints needed: [list CRUD operations]

    Requirements:
    1. Add to core/domains/[domain]/api.ts
    2. Use our configured apiClient from core/api/client
    3. Follow RESTful conventions
    4. Include proper TypeScript types in types.ts
    5. Create corresponding React Query hooks
    6. Handle all error scenarios

    API Function Pattern:
    export const get[Resource] = async (id: string): Promise<[Resource]> => {
      return apiClient.get(`/[resources]/${id}`);
    };

    export const create[Resource] = async (data: Create[Resource]DTO): Promise<[Resource]> => {
      return apiClient.post('/[resources]', data);
    };

    Hook Pattern:
    export function use[Resource](id: string) {
      return useQuery({
        queryKey: [domain]QueryKeys.[resource](id),
        queryFn: () => get[Resource](id),
        staleTime: 5 * 60 * 1000,
      });
    }
    ```

    <Callout type="tip">
      **Remember**: Always group API functions by domain, not by HTTP method. This keeps related logic together and makes the codebase more navigable.
    </Callout>
  </Tab>

  <Tab>
    ### State Management Template

    Choosing and implementing the right state solution:

    ```
    Create state management for [feature] in UTA DevHub:

    Type: [client state (Zustand) | server state (React Query)]
    Scope: [global | feature-specific | domain-specific]
    Location: [exact path based on scope]

    For Zustand Store:
    1. Create interface with clear sections (state, computed, actions)
    2. Use immer for complex updates
    3. Include TypeScript types
    4. Add persistence if needed
    5. Export typed hooks

    Store Pattern:
    interface [Feature]Store {
      // State
      items: Item[];
      selectedId: string | null;
      
      // Computed
      get selectedItem(): Item | undefined;
      
      // Actions
      setItems: (items: Item[]) => void;
      selectItem: (id: string) => void;
      
      // Async Actions
      fetchItems: () => Promise<void>;
    }

    For React Query:
    1. Define query keys using factory pattern
    2. Create hooks for each operation
    3. Include optimistic updates
    4. Handle cache invalidation
    ```
  </Tab>

  <Tab>
    ### UI Component Template

    Creating components that fit our architecture:

    ```
    Create a UI component for UTA DevHub:

    Determine component type first:
    1. Foundation? (atomic, no business logic)
    2. Pattern? (composed, domain-agnostic)
    3. Business? (domain-aware, 3+ features)
    4. Feature-specific? (single feature only)

    Foundation Component Requirements:
    - Single responsibility
    - No business logic
    - Use only design tokens
    - Accept all styling props
    - Fully accessible

    Pattern Component Requirements:
    - Compose foundation components only
    - Handle complex UI behavior
    - Remain domain-agnostic
    - Provide flexible API

    Business Component Requirements:
    - Can use domain hooks
    - Encapsulate business logic
    - Used by 3+ features
    - Handle loading/error states

    Always include:
    - TypeScript props interface
    - JSDoc documentation
    - Accessibility attributes
    - Memoization where appropriate
    - Tests in same folder
    ```
  </Tab>

  <Tab>
    ### Error Handling Template

    Implementing robust error handling:

    ```
    Implement error handling for [feature] in UTA DevHub:

    Error Handling Requirements:
    1. Use our standard error types
    2. Provide user-friendly messages
    3. Log errors appropriately
    4. Include recovery actions
    5. Handle all error paths

    Try-Catch Pattern:
    try {
      // Input validation first
      const validated = [schema].parse(data);
      
      // Main operation
      const result = await [operation](validated);
      
      // Success handling
      showToast({ type: 'success', message: '[Success message]' });
      return result;
      
    } catch (error) {
      // Type-safe error handling
      if (error instanceof ZodError) {
        showToast({ type: 'error', message: 'Invalid input' });
        throw new ValidationError('[Context]', error);
      }
      
      if (error instanceof ApiError) {
        showToast({ type: 'error', message: error.message });
        throw error;
      }
      
      // Unknown errors
      logger.error('[Context] failed', { error });
      showToast({ type: 'error', message: 'Something went wrong' });
      throw new Error('[Fallback message]');
    }

    Error Boundary Pattern:
    - Wrap features with error boundaries
    - Provide fallback UI
    - Include retry mechanism
    - Log to error service
    ```
  </Tab>
</Tabs>

## AI Tool Configuration

### GitHub Copilot Settings

Create `.github/copilot-instructions.md` in your project:

```markdown
# UTA DevHub Coding Standards for GitHub Copilot

## CRITICAL: File Organization
- UI Components: ui/foundation/, ui/patterns/, ui/business/
- Features: features/[feature-name]/
- Business Logic: core/domains/[domain]/
- Shared Code: core/shared/
- ALWAYS follow our decision tree for file placement

## Naming Conventions (STRICTLY ENFORCED)
- Components: PascalCase (UserProfile.tsx)
- Hooks: camelCase starting with 'use' (useUserData.ts)
- Utilities: camelCase (formatDate.ts)
- Types: PascalCase interfaces, no 'I' prefix
- Files: Match component/function name exactly

## Required Patterns
- Function declarations for components (no arrow functions)
- Interfaces for objects, types for unions/primitives
- React Query for ALL server state
- Zustand for client state (no useState for shared state)
- Design tokens for ALL styling (no hardcoded values)

## Import Order (EXACT)
1. React/React Native
2. Third-party libraries
3. Absolute imports with @/
4. Relative imports (same folder only)

## Never Generate
- Any TypeScript 'any' types
- Direct API calls (use domain hooks)
- Inline styles or magic numbers
- Arrow function components
- Console.log statements
```

### VS Code Settings

Add to `.vscode/settings.json`:

```json
{
  "editor.formatOnSave": true,
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": true,
    "source.organizeImports": true
  },
  "typescript.preferences.importModuleSpecifier": "non-relative",
  "typescript.preferences.includePackageJsonAutoImports": "off",
  "ai-assistant.prompts": {
    "component": "Use UTA DevHub component template",
    "hook": "Use UTA DevHub hook template",
    "test": "Use UTA DevHub test template"
  }
}
```

## Code Review with AI

Use AI to help review code for compliance:

### AI Review Prompt

```
Review this UTA DevHub code for compliance:

Code to review:
[paste code here]

Check for:
1. File placement - does it follow our decision tree?
2. Naming conventions - exact compliance required
3. Import order - must match our standard
4. TypeScript usage - no 'any', proper types
5. Pattern consistency - matches similar features?
6. Error handling - all paths covered?
7. Performance - unnecessary re-renders?
8. Tests - 90%+ coverage included?

Compare against:
- Feature Implementation Decision Tree
- TypeScript & React Patterns
- Common Pitfalls guide

Output format:
- ✅ Compliant areas
- ❌ Issues found (with fixes)
- 💡 Suggestions for improvement
- 📚 Documentation updates needed
```

## Working with AI Effectively

<Steps>
  <Step>
    ### Before Using AI

    **Preparation is key to good outputs:**

    1. **Identify the pattern** - Find similar code in your codebase
    2. **Prepare context** - Gather relevant files and documentation
    3. **Choose template** - Select the appropriate prompt template
    4. **Set constraints** - Specify performance/compatibility requirements

    <Callout type="tip">
      **Example**: Before asking AI to create a new modal component, find an existing modal in your codebase to use as a reference pattern.
    </Callout>
  </Step>

  <Step>
    ### During AI Generation

    **Guide the AI for better results:**

    1. **Provide examples** - Include similar implemented features
    2. **Be specific** - Vague prompts lead to inconsistent code
    3. **Iterate** - Refine output to match standards exactly
    4. **Verify imports** - AI often gets import paths wrong

    <Callout type="warning">
      **Common issue**: AI often uses arrow functions for components. Always convert to function declarations as per our standards.
    </Callout>
  </Step>

  <Step>
    ### After Generation

    **Validate and refine the output:**

    1. **Run checks** - `npx tsc --noEmit && npm run lint`
    2. **Compare patterns** - Ensure consistency with existing code
    3. **Update tests** - AI-generated tests often need refinement
    4. **Document decisions** - Add comments for non-obvious choices

    <Callout type="info">
      **Quality check**: Good AI-generated code should be indistinguishable from human-written code following our standards.
    </Callout>
  </Step>
</Steps>

## Common AI Mistakes to Fix

Be aware of these frequent AI errors:

### Import Issues

```typescript
// ❌ AI often generates
import Button from '@/ui/Button';
import { useState } from 'react';

// ✅ Fix to our standard
import React, { useState } from 'react';
import { Button } from '@/ui/foundation/Button';
```

### Component Structure

```typescript
// ❌ AI often generates
const MyComponent: React.FC<Props> = ({ prop1 }) => {
  // implementation
};

// ✅ Fix to our standard
export function MyComponent({ prop1 }: Props) {
  // implementation
}
```

### State Management

```typescript
// ❌ AI might suggest
const [users, setUsers] = useState([]);
useEffect(() => {
  fetch('/api/users').then(/*...*/);
}, []);

// ✅ Fix to use React Query
const { data: users = [] } = useUsers();
```

### Type Definitions

```typescript
// ❌ AI might use 'any' or weak types
const handleData = (data: any) => {
  // process data
};

// ✅ Always use specific types
interface UserData {
  id: string;
  name: string;
  email: string;
}

const handleData = (data: UserData) => {
  // process data
};
```

## Metrics and Continuous Improvement

Track these metrics to improve AI assistance:

1. **Code Review Cycles**: Should decrease as prompts improve
2. **Pattern Violations**: Target zero violations in AI-generated code
3. **Generation Time**: Should decrease as you refine templates
4. **Developer Satisfaction**: Survey team on AI tool effectiveness

<Callout type="success">
  **Success indicator**: When AI-generated code passes code review on first submission, your templates are working perfectly!
</Callout>

## Sharing Knowledge

### Contributing Back

When you discover improvements:

1. **Update templates** - Refine prompts based on experience
2. **Share patterns** - Document new patterns that work well
3. **Report issues** - Note where AI consistently struggles
4. **Train the team** - Share tips in team meetings

### Template Evolution

Our templates should evolve with:

* New patterns we adopt
* Lessons learned from AI outputs
* Changes in our architecture
* Feedback from the team

## Related Documents

* [Feature Implementation Decision Tree](/docs/guides/feature-implementation-decision-tree) - Where code belongs
* [TypeScript & React Patterns](/docs/coding-standards/typescript-react-patterns) - Our coding standards
* [Code Review Templates](/docs/guides/code-review-templates) - Reviewing AI-generated code
* [Common Pitfalls & Solutions](/docs/guides/common-pitfalls-solutions) - Mistakes to avoid


# UTA Implementation Guides: Authentication Flow Implementation Guide
URL: https://dev.updatetheapp.com/docs/guides/authentication-flow
Documentation: https://dev.updatetheapp.com/docs/guides/authentication-flow

Implementing core authentication using TanStack Query, Zustand, Axios interceptors, and Secure Storage.
        
***

title: Authentication Flow Implementation Guide
description: Implementing core authentication using TanStack Query, Zustand, Axios interceptors, and Secure Storage.
--------------------------------------------------------------------------------------------------------------------

import { Callout } from 'fumadocs-ui/components/callout';

# GUIDE-05: Authentication Flow Implementation Guide

## Overview

This guide provides practical patterns for implementing secure authentication flows (login, register, logout, session management) in React Native applications, aligned with our core architecture (**DOC-01**). It leverages TanStack Query for API interactions, Zustand for client-side auth state, an Axios interceptor for seamless token refresh, and `secureStorage` (**DOC-04**) for persistent, secure token storage.

<Callout type="info">
  **🚀 Production-Ready Implementation Available**

  Want to skip the manual setup? Check out our [Authentication Reference Implementation](/docs/reference-implementations/core/domains/auth) for a complete, copy-paste ready solution with:

  * TypeScript authentication hooks and services
  * Secure token management with automatic refresh
  * Authentication context and protected routes
  * Comprehensive testing patterns

  Perfect for getting authentication working quickly in your project!
</Callout>

<Callout type="info">
  **🚀 Production-Ready Implementation Available**

  Want to skip the manual setup? Check out our [Authentication Reference Implementation](/docs/reference-implementations/core/domains/auth) for a complete, copy-paste ready solution with:

  * TypeScript authentication hooks and services
  * Secure token management with automatic refresh
  * Authentication context and protected routes
  * Comprehensive testing patterns

  Perfect for getting authentication working quickly in your project!
</Callout>

## When To Use

Use these patterns when implementing:

* Email/Password authentication (Login, Register).
* Token-based session management with automatic refresh.
* Secure persistence of authentication tokens across app launches.
* Integration of authentication state with TanStack Query (**GUIDE-01**) and Zustand (**GUIDE-02**).
* Basic structure for handling authentication-related API calls.
* Protected routes based on authentication status.

*Note: Social Login and Biometric Login are covered in **GUIDE-07** and **GUIDE-08**, respectively.*

<Callout type="info">
  **🚀 Production-Ready Implementation Available**

  Want to skip the manual setup? Check out our [Authentication Reference Implementation](/docs/reference-implementations/core/domains/auth) for a complete, copy-paste ready solution with TypeScript hooks, secure token management, authentication context, and testing patterns.
</Callout>

## Implementation Patterns

### 1. Sequence Diagram (Login Flow)

<Mermaid
  chart={`
sequenceDiagram
participant U as User
participant UI as Login Screen
participant Hook as useAuth Hook
participant Mutation as useLoginMutation (TQ)
participant AS as Auth Service
participant QC as Query Cache (TQ)
participant ZS as Zustand Store
participant SS as Secure Storage
participant AC as API Client (Axios)
participant BE as Backend API

U->>UI: Enter credentials
UI->>Hook: Call login(credentials)
Hook->>Mutation: mutate(credentials)
Mutation->>AS: Call authService.login()
AS->>AC: Axios POST /auth/login
AC->>BE: Request
BE-->>AC: Response {token, refreshToken, user}
AC-->>AS: Success
AS-->>Mutation: Return success data

Note right of Mutation: onSuccess callback execution
Mutation->>ZS: setTokens()
Mutation->>ZS: setUser()
Mutation->>AC: apiClient.setAuthHeader(token)
Mutation->>SS: Store tokens securely
Mutation->>QC: queryClient.setQueryData(user)

Mutation-->>Hook: Update mutation status (success)
Hook-->>UI: Update component state (loading/error)
UI-->>U: Navigate to authenticated screen
`}
/>

*(Token refresh happens transparently within the API Client interceptor on subsequent API calls if needed)*

### 2. Authentication Service

Defines functions for interacting with authentication-related backend endpoints (**DOC-03**).

```typescript
// src/core/api/services/authService.ts
import { apiClient } from '../apiClient';
import { API_ENDPOINTS } from '../constants';
import type {
  User,
  LoginCredentials,
  LoginResponse,
  RegisterData,
  RefreshTokenRequest,
  RefreshTokenResponse // Assuming a response type for refresh
} from '../types/authTypes'; // Adjust path as needed

export const authService = {
  login: async (credentials: LoginCredentials): Promise<LoginResponse> => {
    const { data } = await apiClient.post(API_ENDPOINTS.LOGIN, credentials);
    return data;
  },

  register: async (userData: RegisterData): Promise<LoginResponse> => {
    const { data } = await apiClient.post(API_ENDPOINTS.REGISTER, userData);
    return data;
  },

  logout: async (): Promise<void> => {
    // Backend endpoint to invalidate session/token if applicable
    await apiClient.post(API_ENDPOINTS.LOGOUT);
    // Note: Local state clearing happens in useAuth hook
  },

  refreshToken: async (request: RefreshTokenRequest): Promise<RefreshTokenResponse> => {
    // This call might bypass interceptors depending on setup
    // Ensure it doesn't trigger the refresh logic itself if called by the interceptor
    const { data } = await apiClient.post(API_ENDPOINTS.REFRESH_TOKEN, request);
    return data; // Expect { token: string, refreshToken: string }
  },

  // Fetching current user data - uses the active auth token from apiClient header
  getCurrentUser: async (): Promise<User> => {
     const { data } = await apiClient.get(API_ENDPOINTS.CURRENT_USER);
     return data;
  },

  // --- Password Management (Optional) --- 
  forgotPassword: async (email: string): Promise<void> => {
    await apiClient.post(API_ENDPOINTS.FORGOT_PASSWORD, { email });
  },

  resetPassword: async (token: string, password: string): Promise<void> => {
    await apiClient.post(API_ENDPOINTS.RESET_PASSWORD, { token, password });
  },
};
```

### 3. Zustand Authentication Store

Manage authentication state using Zustand.

```typescript
// src/features/auth/state/useAuthStore.ts
import { create } from 'zustand';
import { persist, createJSONStorage } from 'zustand/middleware';
import AsyncStorage from '@react-native-async-storage/async-storage';
import type { User } from '@/core/api/types'; // Adjust path

interface AuthState {
  token: string | null;
  refreshToken: string | null;
  isLoggedIn: boolean;
  user: User | null;
  
  // Actions
  setTokens: (tokens: { token: string; refreshToken: string }) => void;
  setUser: (user: User) => void;
  clearAuthState: () => void;
}

export const useAuthStore = create<AuthState>(
  persist(
    (set) => ({
      // Initial state
      token: null,
      refreshToken: null,
      isLoggedIn: false,
      user: null,
      
      // Actions
      setTokens: ({ token, refreshToken }) => set({ 
        token, 
        refreshToken, 
        isLoggedIn: true 
      }),
      setUser: (user) => set({ user }),
      clearAuthState: () => set({ 
        token: null, 
        refreshToken: null, 
        isLoggedIn: false, 
        user: null 
      }),
    }),
    {
      name: 'auth-storage',
      storage: createJSONStorage(() => AsyncStorage),
    }
  )
);

// Selector hooks - create custom hooks for common state selections
export const useAuthToken = () => useAuthStore((state) => state.token);
export const useRefreshToken = () => useAuthStore((state) => state.refreshToken);
export const useIsLoggedIn = () => useAuthStore((state) => state.isLoggedIn);
export const useUser = () => useAuthStore((state) => state.user);
```

### 4. Authentication Hook (`useAuth`)

Combines Zustand state access with TanStack Query mutations for a unified auth interface.

```typescript
// src/features/auth/hooks/useAuth.ts
import { useCallback } from 'react';
import { useMutation, useQueryClient } from '@tanstack/react-query';
import { authService } from '@/core/api/services/authService'; // Adjust path
import { apiClient } from '@/core/api/apiClient'; // Adjust path
import { secureStorage } from '@/core/security/storage/secureStorage'; // Adjust path
import { queryKeys } from '@/core/query/queryKeys'; // Adjust path
import { useAuthStore, useAuthToken, useRefreshToken, useIsLoggedIn, useUser } from '../state/useAuthStore'; // Adjust path

export const useAuth = () => {
  const queryClient = useQueryClient();
  
  // Get state and actions from Zustand store
  const setTokens = useAuthStore((state) => state.setTokens);
  const setUser = useAuthStore((state) => state.setUser);
  const clearAuthState = useAuthStore((state) => state.clearAuthState);
  
  // Auth state from Zustand store
  const token = useAuthToken();
  const refreshToken = useRefreshToken();
  const isLoggedIn = useIsLoggedIn();
  const user = useUser();

  // Login mutation (using TanStack Query)
  const loginMutation = useMutation({
    mutationFn: authService.login,
    onSuccess: async (data) => {
      // Update auth state in Zustand store
      setTokens({ token: data.token, refreshToken: data.refreshToken });
      setUser(data.user);
      
      // Update API client with the new token
      apiClient.setAuthHeader(data.token);
      
      // Store tokens securely for persistence
      await secureStorage.setItem('auth_token', data.token);
      await secureStorage.setItem('refresh_token', data.refreshToken);
      
      // Update the query cache with the new user data
      queryClient.setQueryData(queryKeys.users.current(), data.user);
    },
    onError: (error) => {
      console.error('Login failed:', error);
      // Error handling ideally done in the component calling mutate
    },
  });

  // Register Mutation
  const registerMutation = useMutation({
    mutationFn: (userData: RegisterData) => authService.register(userData),
    onSuccess: handleAuthSuccess, // Reuse the same success logic
     onError: (error) => {
      console.error('Registration failed:', error);
    },
  });

  // Logout Function
  const logout = useCallback(async () => {
    console.log('Executing logout...');
    try {
      // Optional: Call backend logout endpoint.

      // Remove auth header from API client
      apiClient.clearAuthHeader();

      // Clear tokens from secure storage
      await secureStorage.removeItem('auth_token');
      await secureStorage.removeItem('refresh_token');

      // Clear all queries from cache to ensure no stale data
      queryClient.clear();
    },
    // Even if the server-side logout fails, proceed with client-side cleanup
    onError: async (error) => {
      console.error('Logout error:', error);
      // Proceed with client-side cleanup anyway
      clearAuthState();
      apiClient.clearAuthHeader();
      await secureStorage.removeItem('auth_token');
      await secureStorage.removeItem('refresh_token');
      queryClient.clear();
    },
  });

  // Token refresh logic is handled by the API client interceptor.

  return {
    // State
    isLoggedIn,
    token,
    refreshToken, // Expose if needed for manual refresh trigger (e.g., on specific errors)
    user,

    // Actions (Mutations)
    login: loginMutation.mutate, // Use this in components
    loginAsync: loginMutation.mutateAsync, // For promise-based usage
    register: registerMutation.mutate,
    registerAsync: registerMutation.mutateAsync,

    // Status from Mutations
    isLoggingIn: loginMutation.isLoading,
    loginError: loginMutation.error,
    isRegistering: registerMutation.isLoading,
    registerError: registerMutation.error,

    // Logout Action
    logout,
  };
};
```

### 5. Secure Token Storage (`secureStorage`)

Uses `expo-secure-store` for native platforms. (Ensure alignment with **DOC-04**).

```typescript
// src/core/security/storage/secureStorage.ts
import * as SecureStore from 'expo-secure-store';
// Consider platform checks if web support needed

export const secureStorage = {
  async setItem(key: string, value: string): Promise<void> {
    try {
        await SecureStore.setItemAsync(key, value);
    } catch (error) {
        console.error(`[SecureStorage] Error setting item ${key}:`, error);
        // Handle error appropriately (e.g., log, analytics)
    }
  },

  // Use this for highly sensitive items requiring biometrics (as per **DOC-04**)
  async setSecureItem(key: string, value: string): Promise<void> {
    try {
        await SecureStore.setItemAsync(key, value, {
            requireAuthentication: true, // Require biometrics/passcode
            authenticationPrompt: 'Authenticate to save sensitive data'
        });
    } catch (error) {
        console.error(`[SecureStorage] Error setting SECURE item ${key}:`, error);
    }
  },

  async getItem(key: string): Promise<string | null> {
    try {
        return await SecureStore.getItemAsync(key);
    } catch (error) {
        console.error(`[SecureStorage] Error getting item ${key}:`, error);
        return null;
    }
  },

  async removeItem(key: string): Promise<void> {
    try {
        await SecureStore.deleteItemAsync(key);
    } catch (error) {
        console.error(`[SecureStorage] Error removing item ${key}:`, error);
    }
  }
};
```

### 6. Auth Provider (`AuthProvider`)

Responsible for initializing the auth state from secure storage on app startup.

```typescript
// src/features/auth/providers/AuthProvider.tsx
import React, { useEffect, useState, useCallback } from 'react';
import { useQueryClient } from '@tanstack/react-query';
import { secureStorage } from '@/core/security/storage/secureStorage'; // Adjust path (**DOC-04**)
import { useAuthStore } from '../state/useAuthStore'; // Adjust path
import { apiClient } from '@/core/api/apiClient'; // Adjust path (**DOC-03**)
import { queryKeys } from '@/core/query/queryKeys'; // Adjust path (**DOC-03**)
import { authService } from '@/core/api/services/authService'; // Adjust path
import { isTokenExpired } from '@/core/auth/utils/tokenUtils'; // Adjust path, assumes JWT helper
import LoadingScreen from '@/features/core/screens/LoadingScreen'; // Adjust path for your loading screen

// This provider focuses on initializing state from storage.
// Token refresh is primarily handled by the API Client Interceptor.
export const AuthProvider: React.FC<{ children: React.ReactNode }> = ({ children }) => {
  const queryClient = useQueryClient();
  const setTokens = useAuthStore((state) => state.setTokens);
  const setUser = useAuthStore((state) => state.setUser);
  const clearAuthState = useAuthStore((state) => state.clearAuthState);
  const [isInitializing, setIsInitializing] = useState(true);

  // Function to handle full logout locally
  const handleLocalLogout = useCallback(async () => {
      dispatch(clearAuthState());
      apiClient.removeAuthHeader();
      await secureStorage.removeItem('auth_token');
      await secureStorage.removeItem('refresh_token');
      queryClient.clear();
      console.log('[AuthProvider] Local logout performed.');
  }, [dispatch, queryClient]);

  // Function to attempt token refresh (used during init if token is expired)
  const attemptTokenRefreshOnInit = useCallback(async (storedRefreshToken: string) => {
    try {
      console.log('[AuthProvider] Attempting token refresh during initialization...');
      const response = await authService.refreshToken({ refreshToken: storedRefreshToken });

      // Update Redux state
      dispatch(setTokens({ token: response.token, refreshToken: response.refreshToken }));
      // Set API header
      apiClient.setAuthHeader(response.token);
      // Update secure storage
      await secureStorage.setItem('auth_token', response.token);
      await secureStorage.setItem('refresh_token', response.refreshToken);

      // Fetch and cache user data after successful refresh
      try {
         const userData = await authService.getCurrentUser(); // Uses the new token implicitly
         dispatch(setUser(userData));
         queryClient.setQueryData(queryKeys.users.current(), userData);
         console.log('[AuthProvider] Token refresh and user fetch successful during init.');
      } catch (userFetchError) {
         console.error('[AuthProvider] Failed to fetch user after token refresh:', userFetchError);
         // Logout if user data is critical and fetch fails
         await handleLocalLogout();
         return false;
      }
      return true;
    } catch (error) {
      console.error('[AuthProvider] Initialization: Token refresh failed:', error);
      await handleLocalLogout(); // Logout if refresh fails
      return false;
    }
  }, [dispatch, queryClient, handleLocalLogout]);

  // Initialize auth state from secure storage on app start
  useEffect(() => {
    const initAuth = async () => {
      setIsInitializing(true);
      console.log('[AuthProvider] Initializing authentication state...');
      let storedToken: string | null = null;
      let storedRefreshToken: string | null = null;

      try {
        // Read tokens from secure storage
        [storedToken, storedRefreshToken] = await Promise.all([
          secureStorage.getItem('auth_token'),
          secureStorage.getItem('refresh_token'),
        ]);

        if (storedToken && storedRefreshToken) {
          // Check if the access token is still valid
          if (!isTokenExpired(storedToken)) {
            console.log('[AuthProvider] Valid token found in storage.');
            // Restore state: Token is still valid
            dispatch(setTokens({ token: storedToken, refreshToken: storedRefreshToken }));
            apiClient.setAuthHeader(storedToken);

             // Attempt to fetch user data (might hit cache or network)
            try {
               const userData = await queryClient.fetchQuery({
                   queryKey: queryKeys.users.current(),
                   queryFn: authService.getCurrentUser,
                   staleTime: 5 * 60 * 1000 // e.g., user data is fresh for 5 mins
               });
               dispatch(setUser(userData));
               console.log('[AuthProvider] User data restored/fetched.');
            } catch (userFetchError) {
                 console.error('[AuthProvider] Failed to fetch initial user data (token likely valid):", userFetchError);
                 // Decide if this is critical. Maybe the user can continue without fresh user data temporarily?
                 // await handleLocalLogout(); // Uncomment if app cannot function without user data
            }
          } else {
            console.log('[AuthProvider] Expired token found, attempting refresh...');
            // Token expired, try to refresh using the refresh token
            await attemptTokenRefreshOnInit(storedRefreshToken);
            // Success/failure (including logout) is handled within attemptTokenRefreshOnInit
          }
        } else {
          console.log('[AuthProvider] No tokens found in storage. Ensuring logged out state.');
          // No tokens found, ensure clean logged-out state
          await handleLocalLogout();
        }
      } catch (error) {
        console.error('[AuthProvider] Error during authentication initialization:', error);
        await handleLocalLogout(); // Logout on any unexpected error during init
      } finally {
        console.log('[AuthProvider] Initialization complete.');
        setIsInitializing(false);
      }
    };

    initAuth();
    // Dependencies ensure this runs only once on mount
  }, [dispatch, queryClient, attemptTokenRefreshOnInit, handleLocalLogout]);

  // Render loading screen while initializing
  if (isInitializing) {
    return <LoadingScreen message="Initializing session..." />;
  }

  // Render children once initialization is complete
  return <>{children}</>;
};
```

### 7. API Client with Token Handling Interceptor

Handles automatic token injection into requests and triggers refresh on 401 errors.

```typescript
// src/core/api/apiClient.ts
import axios, { AxiosError, InternalAxiosRequestConfig } from 'axios';
import { store } from '@/core/store'; // Adjust path
import { API_BASE_URL, API_ENDPOINTS } from './constants'; // Ensure API_ENDPOINTS is imported
import { secureStorage } from '@/core/security/storage/secureStorage'; // Adjust path (**DOC-04**)
import { authService } from './services/authService'; // Adjust path
import { setTokens, clearAuthState } from '@/features/auth/state/authSlice'; // Adjust path, import clearAuthState

// Create API client instance
export const apiClient = axios.create({
  baseURL: API_BASE_URL,
  timeout: 15000, // Example timeout: 15 seconds
  headers: {
    'Content-Type': 'application/json',
  },
});

// Method to dynamically set Authorization header
apiClient.setAuthHeader = (token: string) => {
  apiClient.defaults.headers.common['Authorization'] = `Bearer ${token}`;
  console.log('[ApiClient] Auth header set.');
};

// Method to remove Authorization header
apiClient.removeAuthHeader = () => {
  delete apiClient.defaults.headers.common['Authorization'];
  console.log('[ApiClient] Auth header removed.');
};


// --- Token Refresh Logic State --- 
let isRefreshing = false;
// Queue for requests awaiting token refresh
let failedQueue: Array<{ resolve: (value: unknown) => void; reject: (reason?: any) => void }> = [];

// Function to process the queue after refresh attempt
const processQueue = (error: AxiosError | null, token: string | null = null) => {
  failedQueue.forEach(prom => {
    if (error) {
      prom.reject(error); // Reject queued request if refresh failed
    } else {
      prom.resolve(token); // Resolve queued request with new token
    }
  });
  failedQueue = []; // Clear the queue
};

// --- Request Interceptor: Adds Auth Token
// Injects the current token from Zustand store into outgoing requests.
apiClient.interceptors.request.use(
  (config) => {
    if (config.headers && !config.headers['Authorization']) {
      const token = useAuthStore.getState().token; // Get token from Zustand store for **every request**
      if (token) {
        config.headers['Authorization'] = `Bearer ${token}`;
      }
    }
    return config;
  },
  (error) => Promise.reject(error)
);


// --- Response Interceptor ---
// Handles 401 errors by attempting token refresh.
apiClient.interceptors.response.use(
  (response) => response, // Pass through successful responses
  async (error: AxiosError) => {
    const originalRequest = error.config as InternalAxiosRequestConfig & { _retry?: boolean };

    // Check for 401 Unauthorized error
    if (error.response?.status === 401 && originalRequest && !originalRequest._retry) {
      console.log('[ApiClient] Received 401 error.');

      if (isRefreshing) {
        // If refresh is already in progress, queue this request
        console.log('[ApiClient] Token refresh in progress, queuing request:', originalRequest.url);
        return new Promise((resolve, reject) => {
          failedQueue.push({ resolve, reject });
        })
          .then(newToken => {
            // Retry the original request with the NEW token from successful refresh
            console.log('[ApiClient] Retrying queued request with new token:', originalRequest.url);
            if (originalRequest.headers) {
                originalRequest.headers['Authorization'] = `Bearer ${newToken}`;
            }
            return apiClient(originalRequest); // Re-run the request
          })
          .catch(err => {
            console.log('[ApiClient] Queued request failed after refresh attempt.');
            return Promise.reject(err); // Propagate error if refresh failed
          });
      }

      // --- Start Token Refresh Process --- 
      console.log('[ApiClient] Initiating token refresh...');
      originalRequest._retry = true; // Mark request as retried
      isRefreshing = true;

      // Get refresh token (try Zustand first, then secure storage as fallback)
      let currentRefreshToken = useAuthStore.getState().refreshToken;

      if (!currentRefreshToken) {
          console.log('[ApiClient] Refresh token not in Zustand store, checking secure storage...');
          currentRefreshToken = await secureStorage.getItem('refresh_token');
      }

      // If no refresh token is found anywhere, logout immediately
      if (!currentRefreshToken) {
        console.error('[ApiClient] Refresh Error: No refresh token available. Logging out.');
        isRefreshing = false;
        store.dispatch(clearAuthState()); // Dispatch logout action
        apiClient.removeAuthHeader(); // Ensure header is cleared
        processQueue(new AxiosError('No refresh token available', '401'), null); // Reject queued requests
        return Promise.reject(error); // Reject original request
      }

      try {
        // Attempt to refresh the token via authService
        console.log('[ApiClient] Calling refreshToken API...');
        const refreshResponse = await authService.refreshToken({ refreshToken: currentRefreshToken });
        const { token: newToken, refreshToken: newRefreshToken } = refreshResponse;
        console.log('[ApiClient] Token refresh successful.');

        // --- Update State and Storage --- 
        useAuthStore.getState().setTokens({ token: newToken, refreshToken: newRefreshToken });
        await secureStorage.setItem('auth_token', newToken);
        await secureStorage.setItem('refresh_token', newRefreshToken);
        apiClient.setAuthHeader(newToken); // Update default header for subsequent requests

        // Update the header of the original request being retried
        if (originalRequest.headers) {
            originalRequest.headers['Authorization'] = `Bearer ${newToken}`;
        }

        // Process the queue with the new token (resolves promises for queued requests)
        processQueue(null, newToken);

        // Retry the original request with the new token
        console.log('[ApiClient] Retrying original request with new token:', originalRequest.url);
        return apiClient(originalRequest);

      } catch (refreshError: any) {
        console.error('[ApiClient] Token refresh API call failed:', refreshError);
        // --- Handle Refresh Failure --- 
        // Clear tokens and logout
        useAuthStore.getState().clearAuthState();
        apiClient.removeAuthHeader();
        await secureStorage.removeItem('auth_token');
        await secureStorage.removeItem('refresh_token');

        // Reject the queue
        processQueue(refreshError as AxiosError, null);

        // Reject the original request and any subsequent ones in the queue
        return Promise.reject(refreshError);
      } finally {
        isRefreshing = false; // Reset refreshing state
        console.log('[ApiClient] Token refresh process finished.');
      }
    }

    // For non-401 errors or requests already retried, just reject
    return Promise.reject(error);
  }
);
```

### 8. Protected Route Components (Conceptual)

Guards access to routes based on authentication status.

```typescript
// src/navigation/guards/AuthGuard.tsx
import React from 'react';
import { useAuthStore } from '@/features/auth/state/useAuthStore'; // Import Zustand store
import { Navigate, useLocation } from 'react-router-dom'; // Example using React Router DOM
// For React Navigation, the logic is usually handled in the navigator setup (see below)

interface AuthGuardProps {
  children: React.ReactNode;
}

// This component is more relevant for web React Router setups.
// For React Navigation, see the navigator example.
export const AuthGuard: React.FC<AuthGuardProps> = ({ children }) => {
  const isLoggedIn = useAuthStore((state) => state.isLoggedIn);
  const location = useLocation();

  if (!isLoggedIn) {
    // Redirect to login, saving the intended destination
    console.log('[AuthGuard] Not logged in, redirecting to /login');
    return <Navigate to="/login" state={{ from: location }} replace />;
  }

  // User is logged in, render the protected content
  return <>{children}</>;
};

// --- React Navigation Approach --- 
// src/navigation/RootNavigator.tsx
import { useAuthStore } from '@/features/auth/state/useAuthStore';
import AuthStack from './AuthStack'; // Navigator for Login, Register etc.
import AppStack from './AppStack';   // Navigator for authenticated screens
import LoadingScreen from '@/features/core/screens/LoadingScreen';
import { useAuthInitialization } from '@/core/auth/hooks/useAuthInitialization'; // Conceptual hook for init status

const RootNavigator = () => {
   const isLoggedIn = useAuthStore((state) => state.isLoggedIn);
   const { isInitializing } = useAuthInitialization(); // Get status from AuthProvider or similar

   if (isInitializing) {
       return <LoadingScreen />;
   }

   // Render the appropriate navigator based on login state
   return isLoggedIn ? <AppStack /> : <AuthStack />;
}

// In your main App.tsx or NavigationContainer setup:
<NavigationContainer>
    <RootNavigator />
</NavigationContainer>
*/
```

## Common Challenges

### 1. Handling Deep Links and Authentication

When a user opens the app via a deep link (e.g., `myapp://reset-password/abc`), ensure correct routing based on auth status.

```typescript
// src/navigation/linking.ts (Conceptual Example for React Navigation)
import { getStateFromPath } from '@react-navigation/native';
import { useAuthStore } from '@/features/auth/state/useAuthStore'; // Zustand store access

const PROTECTED_STACK = 'AppStack'; // Name of your authenticated navigator
const AUTH_STACK = 'AuthStack';     // Name of your unauthenticated navigator
const LOGIN_SCREEN = 'Login';      // Name of your login screen

const linking = {
  prefixes: ['myapp://', 'https://myapp.com'],
  config: {
    screens: {
      [AUTH_STACK]: {
        screens: {
           Login: 'login',
           Register: 'register',
           ForgotPassword: 'forgot-password',
           ResetPassword: 'reset-password/:token',
        }
      },
      [PROTECTED_STACK]: {
        screens: {
          Dashboard: 'dashboard',
          Profile: 'profile',
          // ... other authenticated screens
        },
      },
      NotFound: '*' // Catch-all route
    },
  },

  // Custom function to adjust initial navigation state based on auth
  getStateFromPath: (path, options) => {
    // Default navigation state determination
    const defaultState = getStateFromPath(path, options);

    // Check auth status directly from the Zustand store
    const isLoggedIn = useAuthStore.getState().isLoggedIn;

    // Determine the target stack/screen from the path
    const targetRoute = defaultState?.routes[0];
    const targetStackName = targetRoute?.name;
    const isProtectedTarget = targetStackName === PROTECTED_STACK;
    const isAuthTarget = targetStackName === AUTH_STACK;

    console.log(`[Linking] Path: "${path}", LoggedIn: ${isLoggedIn}, TargetStack: ${targetStackName}`);

    // --- Routing Logic --- 
    // 1. Trying to access protected route while logged out?
    if (isProtectedTarget && !isLoggedIn) {
      console.log(`[Linking] Blocked: Accessing protected route "${path}" while logged out. Redirecting to Login.`);
      // Redirect to the login screen, optionally pass original path
      return {
        routes: [{ name: AUTH_STACK, state: { routes: [{ name: LOGIN_SCREEN, params: { returnTo: path }}]} }],
      };
    }

    // 2. Trying to access auth route (Login/Register) while already logged in?
    if (isAuthTarget && isLoggedIn) {
        console.log(`[Linking] Blocked: Accessing auth route "${path}" while logged in. Redirecting to default authenticated screen.`);
        // Redirect to the main authenticated stack (e.g., Dashboard)
        // Adapt the target screen as needed for your app's default logged-in view
        return {
            routes: [{ name: PROTECTED_STACK, state: { routes: [{ name: 'Dashboard' }]}}],
        };
    }

    // 3. Otherwise, proceed with the default determined state
    console.log(`[Linking] Proceeding with default state for path: "${path}"`);
    return defaultState;
  },
};

export default linking;
```

**Key Idea:** Access the Zustand store *directly* (outside React hooks) within `getStateFromPath` using `useAuthStore.getState()` to check `isLoggedIn`. Modify the initial navigation state returned by `getStateFromPath` based on the user's auth status and the target route's protection level.

### 2. Handling Specific API Errors in Login/Register

The `useAuth` hook exposes `loginError` and `registerError` from the mutations. Map backend error codes to user-friendly messages in the UI.

**Challenge:** Displaying meaningful feedback (e.g., "Invalid Credentials", "Email Taken").

**Solution:** Inspect the error object in the component using the mutation.

```typescript
// Inside LoginScreen.tsx or similar component using useAuth
import { Alert } from 'react-native';
import { useAuth } from '@/features/auth/hooks/useAuth';
import { useEffect } from 'react';

// ... component setup ...
const { login, isLoggingIn, loginError } = useAuth();

useEffect(() => {
  if (loginError) {
    let message = 'An unknown error occurred. Please try again.';
    // AxiosError structure: error.response.data contains backend payload
    const backendError = (loginError as any)?.response?.data;
    const errorCode = backendError?.code; // Adjust based on your API's error structure
    const errorMessage = backendError?.message;

    console.error('[LoginScreen] Login Error Details:', backendError);

    switch (errorCode) {
      case 'INVALID_CREDENTIALS':
        message = 'Incorrect email or password. Please check your details and try again.';
        break;
      case 'ACCOUNT_LOCKED':
        message = 'Your account is currently locked due to too many failed attempts. Please contact support.';
        break;
      case 'EMAIL_NOT_VERIFIED':
          message = 'Please verify your email address before logging in.';
          break;
      // Add other specific error codes from your backend API
      default:
          // Use backend message if available and code is unknown
          if (errorMessage) {
              message = errorMessage;
          }
          break;
    }
    Alert.alert('Login Failed', message);
    // Reset error state in mutation if needed, though TanStack Query usually handles this
    // loginMutation.reset();
  }
}, [loginError]); // Run effect when loginError changes

const handleLoginSubmit = (values: LoginCredentials) => {
    login(values); // Trigger the mutation
};

// ... rest of component ...
```

**(Do ✅)** Define constants for backend error codes.
**(Consider 🤔)** Centralizing error code-to-message mapping in a utility function if used in multiple places.

### 3. Understanding Token Refresh Robustness

The Axios interceptor handles automatic token refresh.

**Key Robustness Features:**

* **(Concurrency Handling ✅):** If multiple API calls fail with 401 while a refresh is ongoing (`isRefreshing === true`), subsequent requests are added to `failedQueue`. They only proceed *after* the initial refresh attempt concludes (success or failure).
* **(Infinite Loop Prevention ✅):** The interceptor checks `!originalRequest._retry` and the request URL (`originalRequest.url !== API_ENDPOINTS.REFRESH_TOKEN`) to prevent the refresh logic from triggering itself or retrying indefinitely.
* **(Refresh Failure Handling ✅):** If the `refreshToken` API call fails, the interceptor logs the user out (dispatches `clearAuthState`, removes header/storage) and rejects all queued requests, ensuring a clean state.

**(Be Aware ❗):** Ensure the backend's `/auth/refresh-token` endpoint *does not* require the (expired) *access token* for authorization. It should only rely on the provided `refreshToken` in the request body.

## Related Documents

* **DOC-01:** Core Architecture Reference
* **DOC-03:** API & State Management Reference
* **DOC-04:** Security & Offline Framework Reference
* **GUIDE-01:** Server State Management Guide
* **GUIDE-02:** State Management Implementation Guide
* **GUIDE-06:** Offline Support Implementation Guide
* **GUIDE-07:** Social Login Implementation Guide
* **GUIDE-08:** Biometric Authentication Implementation Guide


# UTA Implementation Guides: Biometric Authentication
URL: https://dev.updatetheapp.com/docs/guides/biometric-authentication
Documentation: https://dev.updatetheapp.com/docs/guides/biometric-authentication

Implementing fingerprint/face login using device hardware
        
***

title: Biometric Authentication
description: Implementing fingerprint/face login using device hardware
lastUpdated: 2024-07-26 # Add date
version: 1.0
------------

# GUIDE-08: Biometric Authentication Implementation Guide

## Overview

This guide provides practical patterns for implementing biometric authentication (Fingerprint, Face ID) in React Native applications. It allows users to log in quickly using their device's secure hardware after an initial standard authentication.

This implementation leverages `expo-local-authentication`, our `secureStorage` wrapper (using `expo-secure-store`), and integrates with the core authentication flow defined in **GUIDE-05**.

The expected outcome is a seamless and secure secondary login method for returning users.

## When To Use

Apply these patterns when:

* You want to offer users a faster way to log back in after they have successfully authenticated at least once using standard methods (e.g., email/password, social login).
* You need to securely store sensitive information (like credentials or refresh tokens) contingent on successful biometric verification.
* The target platform supports biometric hardware (most modern iOS and Android devices).

**Prerequisites:**

* `expo-local-authentication` library installed (`npx expo install expo-local-authentication`).
* `secureStorage` helper (using `expo-secure-store`) configured, ideally with a `setSecureItem` method that utilizes hardware security features (See **DOC-04**).
* Core Authentication flow implemented (**GUIDE-05**), providing the `useAuth` hook.

**Alternatives:**

* **Password/PIN:** The primary fallback mechanism.
* **Magic Links / OTP:** Different authentication methods altogether.

## Implementation Patterns

This section details the core logic and the main hook used for biometric authentication.

### Process Flow

<Mermaid
  chart={`
sequenceDiagram
  participant User
  participant LoginScreen as Login Screen
  participant BioHook as useBiometricAuth Hook
  participant ExpoLA as Expo LocalAuthentication
  participant Storage as secureStorage
  participant AuthHook as useAuth Hook

  User->>LoginScreen: Tap "Login with Biometrics"
  LoginScreen->>BioHook: call loginWithBiometrics()
  BioHook->>ExpoLA: authenticateAsync()
  ExpoLA-->>User: Prompt for Biometrics
  User-->>ExpoLA: Provide Biometrics
  ExpoLA-->>BioHook: Return Auth Result (success/failure)
  alt Authentication Successful
      BioHook->>Storage: getItem(BIOMETRIC_CREDENTIALS_KEY)
      Storage-->>BioHook: Return stored credentials
      BioHook->>AuthHook: login(retrievedCredentials)
      Note right of AuthHook: Reuses standard login mutation (**GUIDE-05**)
      AuthHook-->>LoginScreen: Update loading/error state
  else Authentication Failed/Cancelled
      BioHook-->>LoginScreen: Return failure indication / Show Alert
  end
`}
/>

### `useBiometricAuth` Hook

This hook encapsulates interactions with `expo-local-authentication` and `secureStorage`.

```typescript
// src/features/auth/hooks/useBiometricAuth.ts
import * as React from 'react';
import * as LocalAuthentication from 'expo-local-authentication';
import { secureStorage } from '@/core/security/storage/secureStorage'; // Adjust path
import { useAuth } from './useAuth'; // Import the core auth hook (**GUIDE-05**)
import { Platform, Alert } from 'react-native';

// Constants for storage keys
const BIOMETRIC_ENABLED_KEY = 'biometric_auth_enabled';
const BIOMETRIC_CREDENTIALS_KEY = 'biometric_credentials';

// Type for stored credentials (adapt based on chosen strategy)
type StoredCredentials = {
  email: string;
  password?: string; // Store password OR...
  refreshToken?: string; // ...refresh token (preferred)
};

export const useBiometricAuth = () => {
  const { login, isLoggingIn } = useAuth(); // Get login mutation trigger and status

  // State for biometric capabilities and user preference
  const [isSupported, setIsSupported] = React.useState(false);
  const [isEnrolled, setIsEnrolled] = React.useState(false);
  const [isEnabled, setIsEnabled] = React.useState(false); // User has opted-in
  const [isLoading, setIsLoading] = React.useState(false); // Loading for biometric ops

  // --- Capability Checks ---
  const checkSupport = React.useCallback(async () => {
    try {
      const supported = await LocalAuthentication.hasHardwareAsync();
      setIsSupported(supported);
      if (supported) {
        const enrolled = await LocalAuthentication.isEnrolledAsync();
        setIsEnrolled(enrolled);
      } else {
        setIsEnrolled(false);
      }
    } catch (error) {
      console.error('Error checking biometric support:', error);
      setIsSupported(false);
      setIsEnrolled(false);
    }
  }, []);

  const checkEnabledStatus = React.useCallback(async () => {
    try {
      const enabledStatus = await secureStorage.getItem(BIOMETRIC_ENABLED_KEY);
      setIsEnabled(enabledStatus === 'true');
    } catch (error) {
      console.error('Error checking biometric enabled status:', error);
      setIsEnabled(false);
    }
  }, []);

  // Run checks on component mount
  React.useEffect(() => {
    checkSupport();
    checkEnabledStatus();
  }, [checkSupport, checkEnabledStatus]);

  // --- Core Functions ---

  /**
   * Enables biometric login after user confirmation.
   * Stores provided credentials securely.
   * @param credentials - The credentials (e.g., email/password or email/refreshToken) to store.
   *                    Ensure these are valid at the time of calling.
   */
  const enableBiometricLogin = React.useCallback(async (credentials: StoredCredentials) => {
    if (!isSupported || !isEnrolled) {
      Alert.alert('Biometrics Unavailable', 'Biometric authentication is not supported or not enrolled on this device.');
      return false;
    }

    // Validate credentials input
    if (!credentials.email || (!credentials.password && !credentials.refreshToken)) {
        Alert.alert('Error', 'Cannot enable biometrics without valid credentials to store.');
        return false;
    }

    setIsLoading(true);
    try {
      // Prompt user to confirm identity before storing credentials
      const result = await LocalAuthentication.authenticateAsync({
        promptMessage: 'Confirm identity to enable biometric login',
      });

      if (result.success) {
        // Use setSecureItem to leverage hardware-backed storage if available
        const dataToStore = JSON.stringify(credentials);
        // See **DOC-04** for secureStorage implementation details
        await secureStorage.setSecureItem(BIOMETRIC_CREDENTIALS_KEY, dataToStore);
        await secureStorage.setItem(BIOMETRIC_ENABLED_KEY, 'true');
        setIsEnabled(true);
        console.log('Biometric login enabled and credentials stored.');
        return true;
      } else {
        console.log('User failed or cancelled biometric prompt during enable.');
        return false;
      }
    } catch (error) {
      console.error('Error enabling biometric login:', error);
      Alert.alert('Error', 'Could not enable biometric login. Please try again.');
      return false;
    } finally {
      setIsLoading(false);
    }
  }, [isSupported, isEnrolled]); // Dependencies: support/enrollment status

  /**
   * Disables biometric login and removes stored credentials.
   */
  const disableBiometricLogin = React.useCallback(async () => {
    setIsLoading(true);
    try {
      // Consider requiring biometric auth here too for security
      await secureStorage.removeItem(BIOMETRIC_CREDENTIALS_KEY);
      await secureStorage.setItem(BIOMETRIC_ENABLED_KEY, 'false'); // Or removeItem
      setIsEnabled(false);
      console.log('Biometric login disabled.');
      return true;
    } catch (error) {
      console.error('Error disabling biometric login:', error);
      Alert.alert('Error', 'Could not disable biometric login. Please try again.');
      return false;
    } finally {
      setIsLoading(false);
    }
  }, []);

  /**
   * Attempts to log the user in using stored biometric credentials.
   */
  const loginWithBiometrics = React.useCallback(async () => {
    if (!isSupported || !isEnrolled || !isEnabled) {
      console.log('Biometric login not available/enabled.');
      return false;
    }

    setIsLoading(true);
    try {
      // 1. Prompt user for biometrics
      const result = await LocalAuthentication.authenticateAsync({
        promptMessage: 'Sign in with biometrics',
        disableDeviceFallback: true, // Prevent fallback to device passcode for login
      });

      if (result.success) {
        // 2. Retrieve stored credentials
        // Uses secureStorage configured in **DOC-04**
        const storedData = await secureStorage.getItem(BIOMETRIC_CREDENTIALS_KEY);
        if (!storedData) {
          throw new Error('Biometric credentials not found after successful auth. Please enable it again.');
        }
        const credentials = JSON.parse(storedData) as StoredCredentials;

        // 3. Use credentials with the standard login flow (**GUIDE-05**)
        if (credentials.email && credentials.password) {
          await login(credentials); // Trigger useAuth login mutation
          console.log('Biometric login successful using stored credentials.');
          // Success/error is handled by the main login mutation observer
          return true; // Biometric step succeeded
        } else if (credentials.email && credentials.refreshToken) {
           // Strategy: Implement login via refresh token if backend supports it
           console.warn('Biometric login with refresh token not implemented yet.');
           // Example: await loginWithRefreshToken(credentials.refreshToken);
           throw new Error('Login with refresh token not supported yet.');
        } else {
           throw new Error('Invalid stored biometric credentials format.');
        }
      } else {
        console.log('User failed or cancelled biometric prompt during login.');
        return false;
      }
    } catch (error: any) {
      console.error('Error during biometric login:', error);
      Alert.alert('Biometric Login Failed', error.message || 'Please use your password.');
      return false;
    } finally {
      setIsLoading(false);
    }
  }, [isSupported, isEnrolled, isEnabled, login]); // Dependencies: status flags and login function

  // --- Return Hook API ---
  return {
    isSupported, // Does the device have biometric hardware?
    isEnrolled, // Has the user set up biometrics on the device?
    isEnabled, // Has the user opted-in within the app?
    canLoginWithBiometrics: isSupported && isEnrolled && isEnabled, // Convenience check
    isLoading, // True during biometric-specific async operations (enable/disable/auth)
    isLoggingIn, // True when the underlying useAuth().login mutation is running (**GUIDE-05**)
    checkSupport, // Function to re-check hardware/enrollment
    checkEnabledStatus, // Function to re-check opt-in status
    enableBiometricLogin, // Function to enable and store credentials
    disableBiometricLogin, // Function to disable and remove credentials
    loginWithBiometrics, // Function to attempt login
  };
};
```

## Examples

These examples show how to integrate the `useBiometricAuth` hook into UI components.

### Login Screen Button

Offer biometric login alongside the standard password field.

```typescript
// src/features/auth/screens/LoginScreen/LoginScreen.tsx
import React from 'react';
import {
  View, Text, TouchableOpacity,
  ActivityIndicator, StyleSheet
} from 'react-native';
import { useBiometricAuth } from '@/features/auth/hooks/useBiometricAuth';
import { useAuth } from '@/features/auth/hooks/useAuth'; // **GUIDE-05** hook
// Assuming styles (colors, spacing, typography) are imported

export const LoginScreen = ({ navigation }) => {
  const { isLoggingIn } = useAuth(); // Get status from standard login
  const {
    canLoginWithBiometrics,
    loginWithBiometrics,
    isLoading: isBiometricLoading, // Biometric-specific loading
  } = useBiometricAuth();

  const handleBiometricLogin = async () => {
    await loginWithBiometrics();
    // Successful login navigation is handled by root navigator observing `isLoggedIn` state
  };

  // Disable buttons if either standard login or biometric check is running
  const isBusy = isLoggingIn || isBiometricLoading;

  return (
    <View style={styles.container}>
      {/* ... Email/Password Form (ensure fields are disabled if isBusy) ... */}

      {/* Conditionally render the biometric button */}
      {canLoginWithBiometrics && (
        <TouchableOpacity
          style={[styles.biometricButton, isBusy && styles.buttonDisabled]}
          onPress={handleBiometricLogin}
          disabled={isBusy}
        >
          {isBiometricLoading ? (
              <ActivityIndicator size="small" color={/* colors.primary */ '#007AFF'} />
          ) : (
            <>
              {/* Replace Text with actual Icon component */}
              <Text style={{fontSize: 24}}> बायो </Text> {/* Replace with actual icon */}
              <Text style={styles.biometricText}>Sign in with Biometrics</Text>
            </>
          )}
        </TouchableOpacity>
      )}

      {/* ... Footer with Sign Up link ... */}
    </View>
  );
};

const styles = StyleSheet.create({
    container: { flex: 1, padding: 20, justifyContent: 'center' },
    biometricButton: {
        flexDirection: 'row',
        alignItems: 'center',
        justifyContent: 'center',
        padding: 12,
        marginTop: 20,
        borderWidth: 1,
        borderColor: '#007AFF',
        borderRadius: 8,
    },
    buttonDisabled: {
        opacity: 0.5,
        backgroundColor: '#e0e0e0'
    },
    biometricText: {
        marginLeft: 10,
        color: '#007AFF',
        fontSize: 16,
        fontWeight: '500',
    },
    // ... other necessary styles for form, footer etc.
});
```

### Settings Screen Toggle

Allow users to enable or disable the feature.

```typescript
// src/features/settings/screens/SecuritySettingsScreen.tsx
import React from 'react';
import { View, Text, Switch, Alert, StyleSheet } from 'react-native';
import { useBiometricAuth } from '@/features/auth/hooks/useBiometricAuth';
import { useAuth } from '@/features/auth/hooks/useAuth'; // Need user context from **GUIDE-05**

export const SecuritySettingsScreen = () => {
  const { user } = useAuth(); // Get current user data (needed for email)
  const {
    isSupported,
    isEnrolled,
    isEnabled,
    enableBiometricLogin,
    disableBiometricLogin,
    isLoading: isBiometricLoading, // Loading state from the hook
  } = useBiometricAuth();

  const handleToggle = async (newValue: boolean) => {
    if (newValue) {
      // --- Enabling Biometrics ---
      if (!user?.email) {
        Alert.alert('Error', 'Cannot enable biometrics - user information unavailable.');
        return;
      }

      // Security Best Practice: Prompt for password before storing credentials.
      // Storing refreshToken is generally safer than password if backend supports it.
      Alert.prompt(
        'Confirm Password',
        'Please enter your current password to enable biometric login.',
        async (password) => {
          if (!password) return; // User cancelled prompt

          // !! WARNING: Ideally, verify password with backend before proceeding !!
          // This example proceeds directly for simplicity.
          // See "Security Considerations" section below.
          const success = await enableBiometricLogin({
            email: user.email,
            password: password, // Or pass refreshToken if using that strategy
          });

          if (!success) {
            // Enabling failed (e.g., user cancelled biometric prompt)
            // UI should ideally reflect this (switch might toggle back automatically
            // if `isEnabled` state didn't change, or manually revert it).
            Alert.alert('Failed', 'Could not enable biometric login.');
          }
        },
        'secure-text' // Use secure text input for password
      );
    } else {
      // --- Disabling Biometrics ---
      const success = await disableBiometricLogin();
      if (!success) {
          Alert.alert('Failed', 'Could not disable biometric login.');
          // UI might need to revert toggle state
      }
    }
  };

  // Don't show the toggle if hardware isn't supported or biometrics aren't enrolled
  if (!isSupported || !isEnrolled) {
    return (
      <View style={styles.container}>
        <Text style={styles.infoText}>
          Biometric login is not available.
          { !isSupported ? ' Your device does not support it.' : ' Please set up fingerprint or face recognition in your device settings.' }
        </Text>
      </View>
    );
  }

  // Render the toggle if supported and enrolled
  return (
    <View style={styles.container}>
      <View style={styles.row}>
        <Text style={styles.label}>Enable Biometric Login</Text>
        <Switch
          value={isEnabled} // Reflects the current opt-in state
          onValueChange={handleToggle} // Calls enable/disable logic
          disabled={isBiometricLoading} // Disable while processing
        />
      </View>
      <Text style={styles.note}>Allows you to log in using your device's fingerprint or face recognition after the initial password login.</Text>
    </View>
  );
};

const styles = StyleSheet.create({
    container: { flex: 1, padding: 20 },
    row: {
        flexDirection: 'row',
        justifyContent: 'space-between',
        alignItems: 'center',
        marginBottom: 15,
        paddingVertical: 10,
        borderBottomWidth: 1,
        borderBottomColor: '#eee',
    },
    label: { fontSize: 16, flex: 1, marginRight: 10 }, // Allow text to wrap
    note: { fontSize: 13, color: 'gray', marginTop: -5 },
    infoText: { fontSize: 14, color: 'gray', textAlign: 'center', padding: 20 },
});
```

## Common Challenges

* **Credential Storage Strategy:** Deciding whether to store `password` or `refreshToken` is crucial. Refresh tokens are generally more secure if your backend supports re-authentication via refresh tokens. Storing passwords, even securely, increases risk.
* **`SecureStore` Item Invalidation:** Biometric enrollment changes (adding/removing fingers/faces) or OS updates can sometimes invalidate items stored in `SecureStore` that require authentication. Your logic should gracefully handle cases where stored credentials (`BIOMETRIC_CREDENTIALS_KEY`) cannot be retrieved, prompting the user to re-enable the feature.
* **Error Handling:** Provide clear feedback to the user if `LocalAuthentication.authenticateAsync` fails (e.g., too many attempts, hardware error, user cancellation).
* **Platform Differences:** While `expo-local-authentication` abstracts many differences, subtle variations in prompts or behavior might exist between iOS and Android. Test thoroughly on both.
* **Enabling Flow Security:** The step where credentials are stored (`enableBiometricLogin`) is critical. Ideally, verify the user's current password against the backend before storing it or the refresh token.

## Performance Considerations

* **Minimal Overhead:** Biometric checks (`hasHardwareAsync`, `isEnrolledAsync`, `authenticateAsync`) are generally fast native calls.
* **Secure Storage Speed:** Reading/writing to `SecureStore` is typically quick but involves cryptographic operations.
* **Login Speed:** The main benefit is avoiding password typing. The subsequent call to `useAuth().login` (from **GUIDE-05**) still involves a network request, so the overall login time depends heavily on network latency and backend response time after the biometric check succeeds.

## Do's and Don'ts

* (Do ✅) Prefer storing **refresh tokens** over passwords if possible. This minimizes the risk if the device's secure storage is compromised.
* (Do ✅) Use `secureStorage.setSecureItem` (or configure `requireAuthentication: true` with `SecureStore`) when storing the credentials/token to bind them to *successful biometric authentication*. (See **DOC-04**).
* (Do ✅) Always require explicit **user consent** and a successful biometric prompt *before* storing credentials (i.e., during the `enableBiometricLogin` flow).
* (Don't ❌) Automatically enable biometric login or store credentials without explicit user interaction and confirmation.
* (Do ✅) Provide a **fallback** to standard password login in case biometrics fail or are unavailable.
* (Consider 🤔) Requiring biometric authentication (or password confirmation) to *disable* the feature for added security.
* (Be Aware ❗) Of Keychain (iOS) and Keystore (Android) behavior regarding item persistence and invalidation, especially after OS updates or changes to device biometrics. Stored items might become inaccessible. (See **DOC-04**).
* (Do ✅) **Verify user identity** (e.g., re-prompt for password) *before* storing credentials during the `enableBiometricLogin` flow, especially if storing passwords directly.

## Related Documents

* **GUIDE-05:** Authentication Flow Implementation Guide (Core login flow)
* **DOC-04:** Security & Offline Framework Reference (SecureStorage details)


# UTA Implementation Guides: Social Authentication
URL: https://dev.updatetheapp.com/docs/guides/social-authentication
Documentation: https://dev.updatetheapp.com/docs/guides/social-authentication

Implementing Google, Facebook, and Apple Sign-In
        
***

title: Social Authentication
description: Implementing Google, Facebook, and Apple Sign-In
lastUpdated: 2024-07-26 # Add date
version: 1.2 # Increment version
--------------------------------

# GUIDE-07: Social Authentication Implementation Guide

## Overview

This guide provides practical patterns for integrating third-party social logins (Google, Facebook, Apple) into your React Native application, ensuring alignment with our core architecture.

It leverages:

* `expo-auth-session` for web-based OAuth flows (Google, Facebook).
* `expo-apple-authentication` for native Apple Sign-In.
* A dedicated `socialLogin` method in `authService` (see **GUIDE-05**).
* A TanStack Query mutation (`useSocialLoginMutation`) to handle the backend verification step.
* Standard updates to Zustand store and Secure Storage upon successful login.

The expected outcome is a seamless login experience for users preferring social providers, integrated cleanly into the existing authentication state management.

## When To Use

Apply these patterns when:

* You want to offer alternative login methods besides email/password.
* You aim to reduce registration friction by using existing social profiles.
* Your target audience frequently uses Google, Facebook, or Apple accounts.

**Prerequisites:**

* Core Authentication Flow (**GUIDE-05**) is implemented.
* Required Expo modules are installed: `expo-auth-session`, `expo-crypto`, `expo-web-browser`, `expo-apple-authentication`.
* Backend endpoint for social login verification (`/auth/social-login`) is available and returns the standard `LoginResponse`.
* OAuth Client IDs/Secrets and App configurations are completed on Google Cloud Console, Facebook Developer Portal, and Apple Developer Portal.
* Client IDs and configuration are securely stored and accessible (e.g., via `expo-constants`).

**Alternatives:**

* Email/Password Login (**GUIDE-05**)
* Passwordless flows (Magic Links, OTP) - requires separate implementation.

## Implementation Patterns

### Process Flow Diagram (Google/Facebook Example)

<Mermaid
  chart={`
sequenceDiagram
  participant User
  participant AppUI as SocialAuthButtons
  participant AuthHook as Provider Hook (e.g., useGoogleAuth)
  participant ExpoAuth as expo-auth-session
  participant Provider as Social Provider (e.g., Google)
  participant Backend as Backend API (/auth/social-login)
  participant Mutation as useSocialLoginMutation
  participant AppState as Zustand/Storage/QueryCache

  User->>AppUI: Tap "Sign in with Google"
  AppUI->>AuthHook: call signIn()
  AuthHook->>ExpoAuth: promptAsync()
  ExpoAuth-->>Provider: Initiate OAuth flow
  User-->>Provider: Authenticate on provider site
  Provider-->>ExpoAuth: Return authorization code/token
  ExpoAuth-->>AuthHook: Receive response (success/error/cancel)

  alt Login Successful
      AuthHook->>Mutation: mutate({ provider: 'google', token: accessToken })
      Mutation->>Backend: Verify token, find/create user
      Backend-->>Mutation: Return { user, token, refreshToken }
      Mutation-->>AppState: Update Zustand, SecureStorage, QueryCache
      Note over AppUI, AppState: App navigates based on state change
  else Login Failed/Cancelled
      AuthHook-->>AppUI: Update loading/error state
      AppUI->>User: Show error message or do nothing
  end
`}
/>

### 1. Extend `authService`

*(Ensure this is present as per **GUIDE-05**)*

Confirm the existence of a method for backend social login verification.

```typescript
// src/core/api/services/authService.ts
import { apiClient } from '../apiClient';
import { API_ENDPOINTS } from '../constants';
import type {
  LoginResponse, // Reuse the same response as standard login
} from '../types/authTypes';

// Interface for the social login payload to the backend
interface SocialLoginRequest {
  provider: 'google' | 'facebook' | 'apple';
  token: string; // Access token (Google/FB) or Identity token (Apple)
  userData?: { // Optional: Extra data for Apple sign-up
    email?: string | null;
    fullName?: {
        givenName?: string | null;
        familyName?: string | null;
    } | null;
  };
}

export const authService = {
  // ... existing login, register, refreshToken methods ...

  socialLogin: async (payload: SocialLoginRequest): Promise<LoginResponse> => {
    const { data } = await apiClient.post(API_ENDPOINTS.SOCIAL_LOGIN, payload);
    // Expects backend to return { user, token, refreshToken }
    return data;
  },

  // ... other methods ...
};
```

### 2. Create `useSocialLoginMutation`

This central mutation handles the state update logic after successful backend verification.

```typescript
// src/features/auth/hooks/useSocialLoginMutation.ts
import { useMutation, useQueryClient } from '@tanstack/react-query';
import { authService, SocialLoginRequest } from '@/core/api/services/authService';
import { secureStorage } from '@/core/security/storage/secureStorage';
import { apiClient } from '@/core/api/apiClient';
import { queryKeys } from '@/core/query/queryKeys';
import { useAuthStore } from '../state/useAuthStore';
// Import Alert or your preferred UI feedback mechanism
import { Alert } from 'react-native';

export const useSocialLoginMutation = () => {
  const queryClient = useQueryClient();
  const setTokens = useAuthStore((state) => state.setTokens);
  const setUser = useAuthStore((state) => state.setUser);

  return useMutation({
    mutationFn: (payload: SocialLoginRequest) => authService.socialLogin(payload),
    onSuccess: async (data) => {
      // 1. Update client state (Zustand)
      setTokens({ token: data.token, refreshToken: data.refreshToken });
      setUser(data.user);
      apiClient.setAuthHeader(data.token);
      await secureStorage.setItem('auth_token', data.token);
      await secureStorage.setItem('refresh_token', data.refreshToken);
      queryClient.setQueryData(queryKeys.users.current(), data.user);
    },
    onError: (error: any) => {
      console.error('Social login mutation failed:', error);
      // Provide user feedback for backend errors
      const message = error?.response?.data?.message || 'Social login failed. Please try again.';
      Alert.alert('Login Error', message);
    },
  });
};
```

### 3. Implement Provider-Specific Hooks

These hooks encapsulate the frontend interaction with each provider's SDK.

**Google Sign-In (`expo-auth-session`)**

```typescript
// src/features/auth/hooks/useGoogleAuth.ts
import * as React from 'react';
import * as WebBrowser from 'expo-web-browser';
import * as Google from 'expo-auth-session/providers/google';
import Constants from 'expo-constants';
import { useSocialLoginMutation } from './useSocialLoginMutation';
import { Alert } from 'react-native';

WebBrowser.maybeCompleteAuthSession();

export const useGoogleAuth = () => {
  const socialLoginMutation = useSocialLoginMutation();

  const [request, response, promptAsync] = Google.useAuthRequest({
    expoClientId: Constants.expoConfig?.extra?.googleExpoClientId,
    iosClientId: Constants.expoConfig?.extra?.googleIosClientId,
    androidClientId: Constants.expoConfig?.extra?.googleAndroidClientId,
    webClientId: Constants.expoConfig?.extra?.googleWebClientId,
  });

  React.useEffect(() => {
    if (response?.type === 'success') {
      const { authentication } = response;
      if (authentication?.accessToken) {
        socialLoginMutation.mutate({
          provider: 'google',
          token: authentication.accessToken,
        });
      } else {
        console.error('Google Auth Success: No access token received');
        Alert.alert('Login Error', 'Could not get Google access token. Please try again.');
      }
    } else if (response?.type === 'error') {
      console.error('Google Auth Error:', response.error);
      Alert.alert('Login Error', 'Google authentication failed. Please try again.');
    } else if (response?.type === 'cancel') {
      console.log('Google Auth Cancelled by user');
    }
  }, [response, socialLoginMutation]);

  const signIn = React.useCallback(async () => {
    if (!request) {
      Alert.alert('Setup Issue', 'Google Auth configuration not ready.');
      return;
    }
    try {
      await promptAsync();
    } catch (error) {
      console.error('Error triggering Google promptAsync:', error);
      Alert.alert('Error', 'Could not start Google Sign-In. Please check your connection.');
    }
  }, [promptAsync, request]);

  return {
    signIn,
    isLoading: socialLoginMutation.isLoading || !request,
    error: socialLoginMutation.error, // Expose error from the mutation
  };
};
```

**Facebook Sign-In (`expo-auth-session`)**

```typescript
// src/features/auth/hooks/useFacebookAuth.ts
import * as React from 'react';
import * as WebBrowser from 'expo-web-browser';
import * as Facebook from 'expo-auth-session/providers/facebook';
import Constants from 'expo-constants';
import { useSocialLoginMutation } from './useSocialLoginMutation';
import { Alert } from 'react-native';

WebBrowser.maybeCompleteAuthSession();

export const useFacebookAuth = () => {
  const socialLoginMutation = useSocialLoginMutation();

  const [request, response, promptAsync] = Facebook.useAuthRequest({
    clientId: Constants.expoConfig?.extra?.facebookAppId,
  });

  React.useEffect(() => {
    if (response?.type === 'success') {
      const { authentication } = response;
      if (authentication?.accessToken) {
        socialLoginMutation.mutate({
          provider: 'facebook',
          token: authentication.accessToken,
        });
      } else {
        console.error('Facebook Auth Success: No access token received');
        Alert.alert('Login Error', 'Could not get Facebook access token. Please try again.');
      }
    } else if (response?.type === 'error') {
      console.error('Facebook Auth Error:', response.error);
       Alert.alert('Login Error', 'Facebook authentication failed. Please try again.');
    } else if (response?.type === 'cancel') {
      console.log('Facebook Auth Cancelled by user');
    }
  }, [response, socialLoginMutation]);

  const signIn = React.useCallback(async () => {
    if (!request) {
        Alert.alert('Setup Issue', 'Facebook Auth configuration not ready.');
        return;
    }
    try {
      await promptAsync();
    } catch(error) {
      console.error('Error triggering Facebook promptAsync:', error);
      Alert.alert('Error', 'Could not start Facebook Sign-In. Please check your connection.');
    }
  }, [promptAsync, request]);

  return {
    signIn,
    isLoading: socialLoginMutation.isLoading || !request,
    error: socialLoginMutation.error,
  };
};
```

**Apple Sign-In (`expo-apple-authentication`)**

```typescript
// src/features/auth/hooks/useAppleAuth.ts
import * as React from 'react';
import * as AppleAuthentication from 'expo-apple-authentication';
import { Platform, Alert } from 'react-native';
import { useSocialLoginMutation } from './useSocialLoginMutation';

export const useAppleAuth = () => {
  const socialLoginMutation = useSocialLoginMutation();
  const [isAvailable, setIsAvailable] = React.useState(false);

  React.useEffect(() => {
    if (Platform.OS === 'ios') {
      AppleAuthentication.isAvailableAsync().then(setIsAvailable);
    }
  }, []);

  const signIn = React.useCallback(async () => {
    if (!isAvailable) {
      Alert.alert('Not Available', 'Apple Sign-In is not available on this device.');
      return;
    }

    try {
      const credential = await AppleAuthentication.signInAsync({
        requestedScopes: [
          AppleAuthentication.AppleAuthenticationScope.FULL_NAME,
          AppleAuthentication.AppleAuthenticationScope.EMAIL,
        ],
      });

      if (credential.identityToken) {
        socialLoginMutation.mutate({
          provider: 'apple',
          token: credential.identityToken,
          userData: {
              email: credential.email,
              fullName: credential.fullName,
          }
        });
      } else {
        console.error('Apple Sign-In Success: No identity token received.');
        Alert.alert('Login Error', 'Could not get Apple identity token. Please try again.');
      }

    } catch (error: any) {
      if (error.code === 'ERR_REQUEST_CANCELED') {
        console.log('Apple Sign-In Cancelled by user.');
      } else {
        console.error('Apple Sign-In Error:', error);
        Alert.alert('Login Error', 'Apple Sign-In failed. Please try again.');
      }
    }
  }, [isAvailable, socialLoginMutation]);

  return {
    isAvailable,
    signIn,
    isLoading: socialLoginMutation.isLoading,
    error: socialLoginMutation.error,
  };
};
```

## Examples

### 1. Standalone `SocialAuthButtons` Component

This component groups the social login buttons and can be imported into other screens.

```typescript
// src/features/auth/components/SocialAuthButtons/SocialAuthButtons.tsx
import React from 'react';
import { View, TouchableOpacity, Text, ActivityIndicator, StyleSheet } from 'react-native';
import { useGoogleAuth } from '../../hooks/useGoogleAuth';
import { useFacebookAuth } from '../../hooks/useFacebookAuth';
import { useAppleAuth } from '../../hooks/useAppleAuth';
// Import icons if you have them
// import { GoogleIcon, FacebookIcon, AppleIcon } from '@/ui/icons';

export const SocialAuthButtons = () => {
  const { signIn: googleSignIn, isLoading: isGoogleLoading } = useGoogleAuth();
  const { signIn: facebookSignIn, isLoading: isFacebookLoading } = useFacebookAuth();
  const { signIn: appleSignIn, isLoading: isAppleLoading, isAvailable: isAppleAvailable } = useAppleAuth();

  // Unified loading state to disable all buttons during any social auth attempt
  const isLoading = isGoogleLoading || isFacebookLoading || isAppleLoading;

  return (
    <View style={styles.container}>
      {/* Google Button */}
      <TouchableOpacity
        style={[styles.button, styles.googleButton, isLoading && styles.buttonDisabled]}
        onPress={googleSignIn}
        disabled={isLoading}
      >
        {isGoogleLoading ? (
          <ActivityIndicator color="#fff" />
        ) : (
          // Replace Text with <GoogleIcon ... /> if available
          <Text style={styles.buttonText}>Sign in with Google</Text>
        )}
      </TouchableOpacity>

      {/* Facebook Button */}
      <TouchableOpacity
        style={[styles.button, styles.facebookButton, isLoading && styles.buttonDisabled]}
        onPress={facebookSignIn}
        disabled={isLoading}
      >
        {isFacebookLoading ? (
          <ActivityIndicator color="#fff" />
        ) : (
           // Replace Text with <FacebookIcon ... /> if available
          <Text style={styles.buttonText}>Sign in with Facebook</Text>
        )}
      </TouchableOpacity>

      {/* Apple Button (Conditionally Rendered) */}
      {isAppleAvailable && (
        <TouchableOpacity
          style={[styles.button, styles.appleButton, isLoading && styles.buttonDisabled]}
          onPress={appleSignIn}
          disabled={isLoading}
        >
          {isAppleLoading ? (
            <ActivityIndicator color="#fff" />
          ) : (
            // Replace Text with <AppleIcon ... /> if available
            <Text style={styles.buttonText}>Sign in with Apple</Text>
          )}
        </TouchableOpacity>
      )}
    </View>
  );
};

// Add appropriate styles
const styles = StyleSheet.create({
  container: { /* ... */ width: '100%', alignItems: 'center' },
  button: {
    flexDirection: 'row',
    alignItems: 'center',
    justifyContent: 'center',
    paddingVertical: 12,
    paddingHorizontal: 20,
    borderRadius: 8,
    width: '80%',
    marginBottom: 15,
    minHeight: 48, // Ensure consistent button height
  },
  buttonDisabled: {
      opacity: 0.6,
  },
  googleButton: { backgroundColor: '#DB4437' },
  facebookButton: { backgroundColor: '#4267B2' },
  appleButton: { backgroundColor: '#000000' },
  buttonText: { color: '#fff', marginLeft: 10, fontWeight: '500', fontSize: 16 },
});
```

### 2. Integration into Login/Register Screen

Import and use the `SocialAuthButtons` component within your existing screens.

```typescript
// src/features/auth/screens/LoginScreen/LoginScreen.tsx
import React from 'react';
import { View, Text, StyleSheet /* ... other imports */ } from 'react-native';
import { useAuth } from '@/features/auth/hooks/useAuth';
import { SocialAuthButtons } from '../../components/SocialAuthButtons/SocialAuthButtons';
// Assuming Formik, Button, TextInput etc. are imported

export const LoginScreen = ({ navigation }) => {
  const { isLoggingIn } = useAuth(); // Status from standard login

  // ... handleLoginSubmit using useAuth().login ...

  return (
    <View style={styles.container}>
      <Text style={styles.title}>Welcome Back</Text>

      {/* ... Email/Password Formik Form ... */}
      {/* Disable form submit button if isLoggingIn is true */}

      <View style={styles.dividerContainer}>
        <View style={styles.divider} />
        <Text style={styles.dividerText}>OR</Text>
        <View style={styles.divider} />
      </View>

      {/* Add the social buttons component */}
      {/* The component handles its own loading state internally */}
      <SocialAuthButtons />

      {/* ... Footer ... */}
    </View>
  );
};

// Add necessary styles
const styles = StyleSheet.create({
    container: { /* ... */ },
    title: { /* ... */ },
    dividerContainer: { flexDirection: 'row', alignItems: 'center', marginVertical: 20 },
    divider: { flex: 1, height: 1, backgroundColor: '#ccc' },
    dividerText: { marginHorizontal: 10, color: '#888' },
    // ... other styles
});
```

## Common Challenges

1. Configuration Errors: Double-check client IDs, bundle identifiers (iOS), package names/key hashes (Android), and authorized redirect URIs in each provider's developer console. Mismatches are common causes of errors, often resulting in provider-specific error messages during the `promptAsync` step.
2. Backend Verification Logic: The backend (`/auth/social-login`) *must* securely verify the incoming token with the provider before trusting it (e.g., using Google's `tokeninfo` endpoint, Facebook's Debug Token API, or validating the Apple JWT signature and claims). Failing to do this is a major security vulnerability.
3. User Account Merging: Define a clear backend strategy for linking social profiles to existing email/password accounts. Common approaches include automatic linking if emails match or prompting the user if a conflict occurs.
4. Expo Go Limitations: Social logins often rely on native configurations (URL schemes, entitlements) that may not work correctly in the Expo Go app. Testing in development builds (`npx expo run:ios`/`android`) or release builds is recommended.
5. Platform Availability: Apple Sign-In is iOS-only. Use the `isAvailable` flag from the hook to conditionally render the Apple button.
6. Token Handling: Ensure the correct token (`accessToken` for Google/Facebook, `identityToken` for Apple) is extracted from the provider response and sent to your backend.
7. Error Feedback: Provide clear user feedback if the social login process fails at any stage (provider interaction, network error, backend verification failure).

## Performance Considerations

* **Network Latency:** Social logins involve multiple network round trips (app \<-> Expo Auth Service \<-> Social Provider \<-> Expo Auth Service \<-> App \<-> Your Backend \<-> Social Provider \<-> Your Backend). This inherently takes longer than a direct email/password check.
* **Provider Availability:** Downtime or issues with the social provider's authentication service are outside your control but will impact the user experience.
* **Backend Verification Time:** The speed of your `/auth/social-login` endpoint in verifying the token and looking up/creating the user significantly affects the overall login time.

Optimization is generally focused on providing clear loading states in the UI rather than speeding up the external dependencies.

## Security Considerations

* **(Do ✅)** **ALWAYS** verify the social provider token on your **backend** before issuing your application's session tokens. *This is the most critical security step.*
* **(Do ✅)** Use the **`state` parameter** in OAuth flows (`expo-auth-session` handles this automatically) to prevent **CSRF attacks**.
* **(Don't ❌)** Store provider **access tokens** long-term unless absolutely necessary for specific API calls; rely on your application's *own* session tokens.
* **(Do ✅)** Handle user data (like **name** and **email**) obtained from social providers according to your **privacy policy** and user consent.
* **(Be Aware ❗)** Of the specific **scopes** you request (e.g., `email`, `profile`) and only ask for *necessary* permissions.

## Related Documents

* **GUIDE-05:** Authentication Flow Implementation Guide (Core Flow)
* **DOC-03:** API & State Management Reference
* **DOC-04:** Security & Offline Framework Reference


# UTA Implementation Guides: Multi-Account Support
URL: https://dev.updatetheapp.com/docs/guides/multi-account-management
Documentation: https://dev.updatetheapp.com/docs/guides/multi-account-management

Managing multiple user sessions within the application
        
***

title: Multi-Account Support
description: Managing multiple user sessions within the application
-------------------------------------------------------------------

# GUIDE-09: Multi-Account Support Implementation Guide

## Overview

This guide provides patterns for allowing users to be logged into multiple accounts simultaneously within the application and switch between them easily.

Key components of this approach:

* **`Account` Interface:** Defines the structure for storing individual account details, including tokens and user information.
* **`useAccountsStore` (Zustand):** A dedicated Zustand store manages the list of all logged-in accounts and keeps track of the currently active account ID.
* **Secure Persistence:** The `useAccountsStore` (containing sensitive tokens) must be persisted securely using Zustand's persist middleware configured with `secureStorage`.
* **Modified Auth Flow:** The standard login/register success handlers (`useAuth` or `useSocialLoginMutation`) are updated to add or update accounts in the `accountsSlice`.
* **`switchAccount` Logic:** A mechanism to change the active account, involving updating Zustand state, the API client header, and potentially fetching data for the newly active account.

## When To Use

Apply these patterns when your application needs to support users logged into multiple accounts concurrently (e.g., personal and work accounts) and allow seamless switching without repeated logins.

## Prerequisites

1. **Core Auth Flow:** The standard authentication flow (**GUIDE-05**) with Zustand (`useAuthStore`) and TanStack Query mutations must be implemented.
2. **Zustand Persist Middleware:** Zustand's persist middleware should be configured with appropriate storage (**GUIDE-02**).
3. **Secure Storage Module:** `secureStorage` module (**DOC-04**) must be available.
4. **Persist Configuration:** Zustand's persist middleware must be configured with `secureStorage` to securely store the accounts data containing tokens.

## Implementation Patterns

### 1. `Account` Interface

Define a type for storing account information.

```typescript
// src/features/accounts/types/index.ts (or a shared location)
import { User } from '@/core/api/types/userTypes'; // Adjust path

export interface Account {
  id: string; // Unique identifier for the account entry (e.g., user ID from backend)
  email: string; // User email for identification
  user: User; // Snapshot of user details
  token: string; // Access token for this account
  refreshToken: string; // Refresh token for this account
  lastUsed: Date; // Timestamp of last usage
  accountType: string; // Type of account (e.g., personal, work)
}
```

### 2. Ensuring Secure Storage for Zustand Persist

Configure Zustand's persist middleware to use `expo-secure-store` through our `secureStorage` module.

```typescript
// src/core/store/createSecureStore.ts
import { StateStorage } from 'zustand/middleware';
import { secureStorage } from '@/core/security/storage/secureStorage'; // Adjust import

// Create a storage adapter that uses secureStorage
export const createSecureStorage = (prefix: string): StateStorage => ({
  getItem: async (key) => {
    const value = await secureStorage.getItem(`${prefix}.${key}`);
    return value;
  },
  setItem: async (key, value) => {
    await secureStorage.setItem(`${prefix}.${key}`, value);
  },
  removeItem: async (key) => {
    await secureStorage.removeItem(`${prefix}.${key}`);
  },
});
```

### 3. Accounts Store (Zustand)

Create a Zustand store to manage the list of accounts and the active ID.

```typescript
// src/features/accounts/state/useAccountsStore.ts
import { create } from 'zustand';
import { persist, createJSONStorage } from 'zustand/middleware';
import { createSecureStorage } from '@/core/store/createSecureStorage'; // Adjust path
import type { Account } from '../types'; // Adjust path
import type { User } from '@/core/api/types/userTypes'; // Import User type

interface AccountsState {
  accounts: Record<string, Account>; // Object storing accounts by ID
  activeAccountId: string | null; // Currently active account ID
  
  // Actions
  addAccount: (account: Account) => void;
  removeAccount: (accountId: string) => void;
  setActiveAccount: (accountId: string) => void;
  updateAccountUser: (params: { accountId: string; user: User }) => void;
  clearAccounts: () => void;
}

// Create secure storage for accounts
const secureStorage = createSecureStorage('accounts');

// Create the Zustand store with persistence
export const useAccountsStore = create<AccountsState>(
  persist(
    (set) => ({
      // Initial state
      accounts: {},
      activeAccountId: null,
      
      // Actions
      addAccount: (account) => set((state) => ({
        accounts: { ...state.accounts, [account.id]: account }
      })),
      
      removeAccount: (accountId) => set((state) => {
        const newAccounts = { ...state.accounts };
        delete newAccounts[accountId];
        
        return {
          accounts: newAccounts,
          // If we removed the active account, set activeAccountId to null
          activeAccountId: state.activeAccountId === accountId ? null : state.activeAccountId
        };
      }),
      
      setActiveAccount: (accountId) => set({
        activeAccountId: accountId
      }),
      
      updateAccountUser: ({ accountId, user }) => set((state) => {
        // Only update if the account exists
        if (!state.accounts[accountId]) return state;
        
        return {
          accounts: {
            ...state.accounts,
            [accountId]: {
              ...state.accounts[accountId],
              user
            }
          }
        };
      }),
      
      clearAccounts: () => set({
        accounts: {},
        activeAccountId: null
      })
    }),
    {
      name: 'accounts-storage',
      storage: createJSONStorage(() => secureStorage),
    }
  )
);

// Helper selectors for common data access patterns
export const useAllAccounts = () => useAccountsStore((state) => Object.values(state.accounts));
export const useAccountById = (id: string) => useAccountsStore((state) => state.accounts[id]);
export const useActiveAccountId = () => useAccountsStore((state) => state.activeAccountId);
export const useActiveAccount = () => {
  const { accounts, activeAccountId } = useAccountsStore();
  return activeAccountId ? accounts[activeAccountId] : null;
};
```

### 4. No Additional Configuration Needed

With Zustand's persist middleware already configured in our `useAccountsStore`, no additional persistence setup is required. The middleware handles:

* Automatic persistence of state changes
* Secure storage through our custom storage adapter
* Hydration on app startup

This approach simplifies our implementation compared to Redux, as we don't need to set up a separate persistence layer.

### 5. Modify Auth Success Handling

Update the login/register success handler to store account info in both contexts.

```typescript
// src/features/auth/hooks/useAuth.ts
import { /* ... existing imports ... */ } from 'react';
import { useMutation, useQueryClient } from '@tanstack/react-query';
import { nanoid } from 'nanoid'; // Or any other UUID generator
import { authService } from '@/core/api/services/authService';
import { apiClient } from '@/core/api/apiClient';
import { secureStorage } from '@/core/security/storage/secureStorage';
import { useAuthStore } from '@/features/auth/state/useAuthStore'; // Import the auth store
import { useAccountsStore } from '@/features/accounts/state/useAccountsStore';

export const useLoginMutation = () => {
  const queryClient = useQueryClient();
  
  // Get actions from Zustand stores
  const setTokens = useAuthStore((state) => state.setTokens);
  const setUser = useAuthStore((state) => state.setUser);
  const addAccount = useAccountsStore((state) => state.addAccount);
  const setActiveAccount = useAccountsStore((state) => state.setActiveAccount);

  return useMutation({
    mutationFn: authService.login,
    onSuccess: async (data) => {
      // Create a unique account ID for this login
      // In practice, you'd usually use a user ID from the backend
      const accountId = data.user.id || nanoid();

      // Create the account object for multi-account storage
      const newAccount = {
        id: accountId,
        user: data.user,
        token: data.token,
        refreshToken: data.refreshToken,
        lastActive: new Date().toISOString(),
      };

      // Add the account to accounts store
      addAccount(newAccount);

      // Set this account as active
      setActiveAccount(newAccount.id);

      // ALSO update the standard auth state (to drive the current UI view)
      setTokens({ token: data.token, refreshToken: data.refreshToken });
      setUser(data.user);

      // Configure API client with the token
      apiClient.setAuthHeader(data.token);

      // Store tokens securely - optional, as the accounts are already persisted securely
      await secureStorage.setItem('auth_token', data.token);
      await secureStorage.setItem('refresh_token', data.refreshToken);

      // Pre-populate query cache
      queryClient.setQueryData(['user', 'current'], data.user);
    },
    // ... other mutation options
  });
};
```

### 6. Implement Account Switching Hook (`useSwitchAccount`)

Create a dedicated hook for account switching.

```typescript
// src/features/accounts/hooks/useSwitchAccount.ts
import { useCallback } from 'react';
import { useQueryClient } from '@tanstack/react-query';
import { apiClient } from '@/core/api/apiClient';
import { useAuthStore } from '@/features/auth/state/useAuthStore';
import { useAccountsStore, useActiveAccountId, useAccountById } from '@/features/accounts/state/useAccountsStore';
import { userService } from '@/core/api/services/userService';

export const useSwitchAccount = () => {
  const queryClient = useQueryClient();
  const activeAccountId = useActiveAccountId();
  
  // Get actions from Zustand stores
  const clearAuthState = useAuthStore((state) => state.clearAuthState);
  const setTokens = useAuthStore((state) => state.setTokens);
  const setUser = useAuthStore((state) => state.setUser);
  const setActiveAccount = useAccountsStore((state) => state.setActiveAccount);
  const updateAccountUser = useAccountsStore((state) => state.updateAccountUser);

  const switchToAccount = useCallback(async (targetAccountId: string) => {
    // Safety check: do nothing if target is already active
    if (targetAccountId === activeAccountId) return;

    // 1. Get target account details from Zustand store
    const targetAccount = useAccountById(targetAccountId);
    if (!targetAccount) {
      console.error(`Account with ID ${targetAccountId} not found`);
      return;
    }

    // 2. Clear current *active* auth state
    clearAuthState();

    // 3. Set API client header with the target account's token
    apiClient.setAuthHeader(targetAccount.token);

    // 4. Set the active auth state with the target account
    setTokens({ token: targetAccount.token, refreshToken: targetAccount.refreshToken });
    setUser(targetAccount.user);

    // 5. Update active account ID in the accounts store
    setActiveAccount(targetAccountId);

    try {
      // 6. Optional: Fetch fresh user data to ensure it's up-to-date
      // (useful if account was added some time ago)
      const userData = await userService.getCurrentUser();
      setUser(userData);
      updateAccountUser({ accountId: targetAccountId, user: userData });

    } catch (error) {
      console.error('Error refreshing user data when switching accounts:', error);
      // Don't block account switching on failed refresh
    }

  }, [queryClient, activeAccountId, clearAuthState, setTokens, setUser, setActiveAccount, updateAccountUser]);

  return { switchToAccount };
};
```

### 7. Account Removal/Logout

Implement an extended logout to handle account removal:

1. Implement `removeCurrentAccount` in `useAuth` that:
   1. Gets the current `activeAccountId` from the accounts store.
   2. Call `removeAccount(activeAccountId)` from the accounts store actions.
   3. If other accounts remain, call `switchToAccount` with the ID of another account.
   4. If no accounts remain, call the main `logout()` function.
2. Implement `logoutAll` that:
   1. Call `clearAccounts()` from the accounts store actions.
   2. Call the standard logout flow to clear everything else.

### 8. Account Selection UI

Create a profile selector component that displays all available accounts.

```typescript
// src/features/accounts/components/AccountSelector.tsx
import React from 'react';
import { FlatList, Pressable, Text, Image, StyleSheet } from 'react-native';
import { useAllAccounts, useActiveAccountId } from '../state/useAccountsStore';
import { useSwitchAccount } from '../hooks/useSwitchAccount';

const AccountSelector = () => {
  const accounts = useAllAccounts();
  const activeAccountId = useActiveAccountId();
  const { switchToAccount } = useSwitchAccount();

  return (
    <FlatList
      data={accounts}
      keyExtractor={(item) => item.id}
      renderItem={({ item }) => (
        <Pressable 
          style={[styles.accountItem, activeAccountId === item.id && styles.activeItem]}
          onPress={() => switchToAccount(item.id)}
        >
          <Image source={{ uri: item.user.avatarUrl }} style={styles.avatar} />
          <Text style={styles.userName}>{item.user.name}</Text>
          {activeAccountId === item.id && (
            <Text style={styles.activeIndicator}>Active</Text>
          )}
        </Pressable>
      )}
    />
  );
};

const styles = StyleSheet.create({
  accountItem: {
    paddingVertical: 12,
    paddingHorizontal: 10,
    borderBottomWidth: 1,
    borderBottomColor: '#eee',
    flexDirection: 'row',
    alignItems: 'center',
  },
  activeAccountItem: { backgroundColor: '#e0f0ff' }, // Light blue for active
  switchingAccountItem: { opacity: 0.6 }, // Dim slightly while switching
  accountInfo: { flex: 1, marginLeft: 10 },
  accountName: { fontWeight: '500', fontSize: 15 },
  accountEmail: { color: '#555', fontSize: 12 },
  activeMarker: { color: '#007AFF', fontSize: 20, fontWeight: 'bold' },
  addButton: {
      marginTop: 15,
      paddingVertical: 12,
      alignItems: 'center',
      borderWidth: 1,
      borderColor: '#007AFF',
      borderRadius: 6,
  },
  addButtonText: {
      color: '#007AFF',
      fontWeight: '500',
      fontSize: 15,
  },
});
```

## Considerations & Challenges

* **(Be Aware ❗)** **Secure Persistence:** Ensuring the `accountsSlice` containing multiple tokens is stored *only* using the `securePersistStorage` engine is critical. Misconfiguration (e.g., accidentally persisting it via AsyncStorage) could expose all stored tokens.
* **(Be Aware ❗)** **Token Refresh:** The standard API interceptor (**GUIDE-05**) typically refreshes the token for the *currently active* session only. Implementing background refresh for inactive accounts is significantly more complex (managing multiple timers, secure token access) and generally not implemented unless specifically required and carefully designed.
* **(Do ✅)** **State Synchronization:** When switching accounts, ensure all relevant user-specific data is cleared/refetched. Use TanStack Query's `queryClient.removeQueries` or `queryClient.invalidateQueries` targeting user-specific keys, and `queryClient.fetchQuery` for immediate essential data reloading.
* **(Consider 🤔)** **Backend Support:** This pattern assumes the backend issues independent tokens per login and treats each as a separate session. If the backend has its own server-side multi-session management, this client-side approach might need adjustment or simplification.
* **(Do ✅)** **UI/UX:** Clearly indicate the active account throughout the app (e.g., in a profile header). Provide an intuitive and easily accessible way to switch accounts (e.g., via profile menu).
* **(Do ✅)** **Error Handling:** Implement robust error handling during the `switchAccount` process, especially if fetching essential data for the new account fails. Decide whether to revert the switch or force a logout.

## Related Documents

* **GUIDE-05:** Authentication Flow Implementation Guide
* **GUIDE-02:** State Management Implementation Guide (Redux)
* **GUIDE-07:** Social Login Implementation Guide
* **DOC-03:** API & State Management Reference
* **DOC-04:** Security & Offline Framework Reference


# UTA Implementation Guides: Server State Management Guide
URL: https://dev.updatetheapp.com/docs/guides/server-state-management
Documentation: https://dev.updatetheapp.com/docs/guides/server-state-management

Practical patterns for managing server state using TanStack Query.
        
***

title: Server State Management Guide
description: Practical patterns for managing server state using TanStack Query.
-------------------------------------------------------------------------------

# GUIDE-01: Server State Management Guide

## Overview

This guide provides practical patterns for efficiently managing server state in React Native applications using TanStack Query. It explains how to implement data fetching, caching, and synchronization while maintaining a clear separation from client state.

## When To Use

Use these patterns when working with any data that:

* Originates from your backend API
* Needs to be cached for performance
* Requires loading/error states
* Might become stale and need refreshing
* Could be modified by multiple users

## Server State Characteristics

<Mermaid
  chart={`
flowchart TD
ServerState[Server State] --> A[Asynchronous]
ServerState --> S[Shared ownership]
ServerState --> P[Potentially stale]
ServerState --> U[Update-sensitive]
ServerState --> N[Network-dependent]
`}
/>

Server state has fundamentally different characteristics from client state:

* It requires managing loading, error, and success states
* It's shared between the client and server
* It may become outdated and need refreshing
* It needs to reflect changes made by other users
* It's affected by network conditions

## Implementation Patterns

### Basic Query Pattern

```typescript
// src/features/products/api/productHooks.ts
import { useQuery } from '@tanstack/react-query';
import { productService } from '@/core/api/services/productService';
import { queryKeys } from '@/core/query/queryKeys';

export const useProductsQuery = (filters = {}) => {
  return useQuery({
    queryKey: queryKeys.products.list(filters),
    queryFn: () => productService.getProducts(filters),
    staleTime: 5 * 60 * 1000, // 5 minutes
  });
};

// Usage in a component
const ProductList = () => {
  const [filters, setFilters] = useState({});
  const { data, isLoading, error } = useProductsQuery(filters);
  
  if (isLoading) return <LoadingIndicator />;
  if (error) return <ErrorDisplay error={error} />;
  
  return (
    <FlatList
      data={data}
      renderItem={({ item }) => <ProductItem product={item} />}
    />
  );
};
```

### Mutation Pattern

```typescript
// src/features/products/api/productHooks.ts
import { useMutation, useQueryClient } from '@tanstack/react-query';
import { productService } from '@/core/api/services/productService';
import { queryKeys } from '@/core/query/queryKeys';

export const useUpdateProductMutation = () => {
  const queryClient = useQueryClient();
  
  return useMutation({
    mutationFn: ({ id, data }) => productService.updateProduct(id, data),
    onSuccess: (updatedProduct) => {
      // Update the cache with the new data
      queryClient.setQueryData(
        queryKeys.products.detail(updatedProduct.id),
        updatedProduct
      );
      
      // Invalidate any lists that might contain this product
      queryClient.invalidateQueries({ queryKey: queryKeys.products.list() });
    },
  });
};

// Usage in a component
const ProductForm = ({ product }) => {
  const { mutate, isLoading } = useUpdateProductMutation();
  
  const handleSubmit = (formData) => {
    mutate({ id: product.id, data: formData });
  };
  
  return (
    <Form onSubmit={handleSubmit} isSubmitting={isLoading} />
  );
};
```

### Infinite Query Pattern

```typescript
// src/features/products/api/productHooks.ts
import { useInfiniteQuery } from '@tanstack/react-query';
import { productService } from '@/core/api/services/productService';
import { queryKeys } from '@/core/query/queryKeys';

export const useProductsInfiniteQuery = (filters = {}) => {
  return useInfiniteQuery({
    queryKey: queryKeys.products.list(filters),
    queryFn: ({ pageParam = 1 }) => 
      productService.getProducts({ ...filters, page: pageParam }),
    getNextPageParam: (lastPage) => lastPage.nextPage || undefined,
  });
};

// Usage in a component
const ProductListInfinite = () => {
  const { 
    data, 
    fetchNextPage, 
    hasNextPage, 
    isFetchingNextPage,
    isLoading,
    error
  } = useProductsInfiniteQuery();
  
  if (isLoading) return <LoadingIndicator />;
  if (error) return <ErrorDisplay error={error} />;
  
  return (
    <FlatList
      data={data.pages.flatMap(page => page.products)}
      renderItem={({ item }) => <ProductItem product={item} />}
      onEndReached={() => hasNextPage && fetchNextPage()}
      ListFooterComponent={isFetchingNextPage ? <LoadingIndicator /> : null}
    />
  );
};
```

### Dependent Queries

```typescript
// src/features/orders/api/orderHooks.ts
import { useQuery } from '@tanstack/react-query';
import { orderService } from '@/core/api/services/orderService';
import { productService } from '@/core/api/services/productService';
import { queryKeys } from '@/core/query/queryKeys';

export const useOrderDetailsQuery = (orderId) => {
  // First query - get order details
  const orderQuery = useQuery({
    queryKey: queryKeys.orders.detail(orderId),
    queryFn: () => orderService.getOrder(orderId),
  });
  
  // Second query - depends on first query results
  const productIds = orderQuery.data?.items.map(item => item.productId) || [];
  
  const productsQuery = useQuery({
    queryKey: queryKeys.products.byIds(productIds),
    queryFn: () => productService.getProductsByIds(productIds),
    // Only run this query if we have product IDs
    enabled: productIds.length > 0,
  });
  
  return {
    order: orderQuery.data,
    products: productsQuery.data,
    isLoading: orderQuery.isLoading || productsQuery.isLoading,
    error: orderQuery.error || productsQuery.error,
  };
};
```

### Query Invalidation

```typescript
// src/features/cart/api/cartHooks.ts
import { useMutation, useQueryClient } from '@tanstack/react-query';
import { cartService } from '@/core/api/services/cartService';
import { queryKeys } from '@/core/query/queryKeys';

export const useAddToCartMutation = () => {
  const queryClient = useQueryClient();
  
  return useMutation({
    mutationFn: ({ productId, quantity }) => 
      cartService.addItem(productId, quantity),
    onSuccess: () => {
      // Invalidate the cart queries
      queryClient.invalidateQueries({ queryKey: queryKeys.cart.all });
      
      // Invalidate product availability
      queryClient.invalidateQueries({ 
        queryKey: queryKeys.products.availability,
        exact: false 
      });
    },
  });
};
```

### Optimistic Updates

```typescript
// src/features/todos/api/todoHooks.ts
import { useMutation, useQueryClient } from '@tanstack/react-query';
import { todoService } from '@/core/api/services/todoService';
import { queryKeys } from '@/core/query/queryKeys';

export const useToggleTodoMutation = () => {
  const queryClient = useQueryClient();
  
  return useMutation({
    mutationFn: (todoId) => todoService.toggleCompleted(todoId),
    
    // Update UI optimistically before the server responds
    onMutate: async (todoId) => {
      // Cancel outgoing refetches
      await queryClient.cancelQueries({ queryKey: queryKeys.todos.all });
      
      // Get snapshot of current data
      const previousTodos = queryClient.getQueryData(queryKeys.todos.all);
      
      // Optimistically update the cache
      queryClient.setQueryData(
        queryKeys.todos.all,
        (old) => old.map(todo => 
          todo.id === todoId 
            ? { ...todo, completed: !todo.completed } 
            : todo
        )
      );
      
      // Return snapshot for rollback
      return { previousTodos };
    },
    
    // If error occurs, roll back to previous state
    onError: (err, todoId, context) => {
      queryClient.setQueryData(
        queryKeys.todos.all,
        context.previousTodos
      );
    },
    
    // Always refetch after error or success
    onSettled: () => {
      queryClient.invalidateQueries({ queryKey: queryKeys.todos.all });
    },
  });
};
```

### Prefetching

```typescript
// src/features/products/screens/ProductListScreen.tsx
import { useQueryClient } from '@tanstack/react-query';
import { productService } from '@/core/api/services/productService';
import { queryKeys } from '@/core/query/queryKeys';

const ProductListScreen = () => {
  const queryClient = useQueryClient();
  const navigation = useNavigation();
  
  const handleProductPress = (productId) => {
    // Prefetch product details before navigating
    queryClient.prefetchQuery({
      queryKey: queryKeys.products.detail(productId),
      queryFn: () => productService.getProduct(productId),
    });
    
    // Navigate to the product details screen
    navigation.navigate('ProductDetails', { productId });
  };
  
  // Rest of component...
};
```

## Cross-Feature Data Sharing

### Query Key Factory

```typescript
// src/core/query/queryKeys.ts
export const queryKeys = {
  // User domain
  users: {
    all: ['users'] as const,
    current: () => [...queryKeys.users.all, 'current'] as const,
    detail: (id: string) => [...queryKeys.users.all, 'detail', id] as const,
    preferences: () => [...queryKeys.users.all, 'preferences'] as const,
  },
  
  // Product domain
  products: {
    all: ['products'] as const,
    list: (filters?: object) => [...queryKeys.products.all, 'list', filters] as const,
    detail: (id: string) => [...queryKeys.products.all, 'detail', id] as const,
    byIds: (ids: string[]) => [...queryKeys.products.all, 'byIds', ids] as const,
    availability: ['products', 'availability'] as const,
  },
  
  // Cart domain
  cart: {
    all: ['cart'] as const,
    items: () => [...queryKeys.cart.all, 'items'] as const,
    summary: () => [...queryKeys.cart.all, 'summary'] as const,
  },
  
  // Order domain
  orders: {
    all: ['orders'] as const,
    list: (filters?: object) => [...queryKeys.orders.all, 'list', filters] as const,
    detail: (id: string) => [...queryKeys.orders.all, 'detail', id] as const,
  },
};
```

### Sharing Data Between Features

```typescript
// src/features/profile/api/profileHooks.ts
import { useQuery } from '@tanstack/react-query';
import { userService } from '@/core/api/services/userService';
import { queryKeys } from '@/core/query/queryKeys';

export const useCurrentUserQuery = (options = {}) => 
  useQuery({
    queryKey: queryKeys.users.current(),
    queryFn: userService.getCurrentUser,
    ...options
  });

// In a different feature
// src/features/checkout/screens/CheckoutScreen.tsx
import { useCurrentUserQuery } from '@/features/profile/api/profileHooks';

const CheckoutScreen = () => {
  // Reuse user data query from profile feature
  const { data: user } = useCurrentUserQuery();
  
  // Feature-specific queries
  const { data: cartItems } = useCartItemsQuery();
  
  return (
    <View>
      <Text>Checkout for: {user?.name}</Text>
      {/* Rest of component */}
    </View>
  );
};
```

### Initial Data from Existing Query

```typescript
// src/features/products/api/productHooks.ts
export const useProductQuery = (productId: string) => {
  const queryClient = useQueryClient();
  
  return useQuery({
    queryKey: queryKeys.products.detail(productId),
    queryFn: () => productService.getProduct(productId),
    // Use data from the list query if available
    initialData: () => {
      const productLists = queryClient.getQueriesData({
        queryKey: queryKeys.products.list(),
        exact: false,
      });
      
      // Look through all product lists in the cache
      for (const [, data] of productLists) {
        const product = data?.find(p => p.id === productId);
        if (product) return product;
      }
      
      return undefined;
    },
    // Only consider initialData fresh if list was fetched recently
    initialDataUpdatedAt: () => {
      const listQueries = queryClient.getQueryCache().findAll({
        queryKey: queryKeys.products.list(),
        exact: false,
      });
      
      // Get the most recent updated timestamp
      const latestUpdatedAt = Math.max(
        ...listQueries.map(q => q.state.dataUpdatedAt)
      );
      
      return latestUpdatedAt > 0 ? latestUpdatedAt : undefined;
    },
  });
};
```

## Common Challenges

### 1. Managing Loading States

```typescript
// src/ui/components/QueryRenderer.tsx
import React from 'react';
import { UseQueryResult } from '@tanstack/react-query';

interface QueryRendererProps<TData> {
  query: UseQueryResult<TData>;
  LoadingComponent?: React.ReactNode;
  ErrorComponent?: React.ComponentType<{ error: Error }>;
  children: (data: TData) => React.ReactNode;
}

export function QueryRenderer<TData>({
  query,
  LoadingComponent = <DefaultLoader />,
  ErrorComponent = DefaultError,
  children,
}: QueryRendererProps<TData>) {
  const { data, isLoading, error } = query;
  
  if (isLoading) {
    return LoadingComponent;
  }
  
  if (error) {
    return <ErrorComponent error={error as Error} />;
  }
  
  return children(data as TData);
}

// Usage
const ProductScreen = () => {
  const productsQuery = useProductsQuery();
  
  return (
    <QueryRenderer
      query={productsQuery}
      LoadingComponent={<ProductSkeleton />}
      ErrorComponent={({ error }) => (
        <ProductLoadError error={error} onRetry={productsQuery.refetch} />
      )}
    >
      {(products) => (
        <ProductList products={products} />
      )}
    </QueryRenderer>
  );
};
```

### 2. Handling Stale Data

```typescript
// src/features/dashboard/api/dashboardHooks.ts
export const useDashboardDataQuery = () => {
  return useQuery({
    queryKey: queryKeys.dashboard.summary(),
    queryFn: dashboardService.getSummary,
    // Configure stale time based on data freshness needs
    staleTime: 5 * 60 * 1000, // 5 minutes
    // Auto-refresh every 10 minutes
    refetchInterval: 10 * 60 * 1000,
    // Refresh when window/screen regains focus
    refetchOnWindowFocus: true,
    // Refresh when device reconnects
    refetchOnReconnect: true,
  });
};

// In the component
const DashboardScreen = () => {
  const { data, isLoading, isFetching, dataUpdatedAt, refetch } = useDashboardDataQuery();
  
  const lastUpdated = useMemo(() => {
    return new Date(dataUpdatedAt).toLocaleTimeString();
  }, [dataUpdatedAt]);
  
  return (
    <View>
      <View style={styles.header}>
        <Text>Dashboard</Text>
        <Text>Last updated: {lastUpdated}</Text>
        <Button 
          title="Refresh" 
          onPress={() => refetch()} 
          disabled={isFetching} 
        />
      </View>
      
      {isLoading ? (
        <LoadingIndicator />
      ) : (
        <DashboardContent data={data} />
      )}
      
      {/* Show small indicator when background refreshing */}
      {!isLoading && isFetching && (
        <ActivityIndicator size="small" style={styles.refreshIndicator} />
      )}
    </View>
  );
};
```

### 3. Network Connectivity Issues

```typescript
// src/core/hooks/useOnlineStatus.ts
export const useOnlineStatus = () => {
  const [isOnline, setIsOnline] = useState(true);
  
  useEffect(() => {
    const unsubscribe = NetInfo.addEventListener(state => {
      setIsOnline(!!state.isConnected && !!state.isInternetReachable);
    });
    
    return () => unsubscribe();
  }, []);
  
  return isOnline;
};

// Using in queries
export const useProductsQuery = (filters = {}) => {
  const isOnline = useOnlineStatus();
  
  return useQuery({
    queryKey: queryKeys.products.list(filters),
    queryFn: () => productService.getProducts(filters),
    // Don't retry when offline
    retry: isOnline ? 3 : false,
    // Show stale data longer when offline
    staleTime: isOnline ? 5 * 60 * 1000 : Infinity,
    // Don't refetch when offline
    refetchOnWindowFocus: isOnline,
    refetchOnReconnect: false,
    // Add error handler
    onError: (error) => {
      if (!isOnline) {
        // Show offline-specific error message
        Toast.show({
          type: 'info',
          text: 'You are currently offline. Some data may not be up to date.'
        });
      }
    },
  });
};
```

## Performance Considerations

### Selective Invalidation

```typescript
// ❌ BAD: Invalidate too much
queryClient.invalidateQueries(); // Invalidates ALL queries

// ✅ GOOD: Invalidate only what's necessary
queryClient.invalidateQueries({ 
  queryKey: queryKeys.products.detail(productId) 
});
```

### Pagination Optimization

```typescript
// src/features/products/api/productHooks.ts
export const useProductsInfiniteQuery = (filters = {}) => {
  return useInfiniteQuery({
    queryKey: queryKeys.products.list(filters),
    queryFn: ({ pageParam = 1 }) => 
      productService.getProducts({ ...filters, page: pageParam }),
    getNextPageParam: (lastPage) => lastPage.nextPage || undefined,
    // Keep previous data while fetching next page
    keepPreviousData: true,
    // Improve performance with structural sharing
    structuralSharing: true,
  });
};
```

### Strategic Prefetching

```typescript
// src/features/products/screens/CategoryScreen.tsx
export const CategoryScreen = ({ categoryId }) => {
  const queryClient = useQueryClient();
  
  // Prefetch subcategories when component mounts
  useEffect(() => {
    queryClient.prefetchQuery({
      queryKey: queryKeys.categories.subcategories(categoryId),
      queryFn: () => categoryService.getSubcategories(categoryId),
    });
  }, [categoryId, queryClient]);
  
  // Prefetch popular products on hover/focus
  const prefetchPopularProducts = useCallback(() => {
    queryClient.prefetchQuery({
      queryKey: queryKeys.products.popular(categoryId),
      queryFn: () => productService.getPopularProducts(categoryId),
    });
  }, [categoryId, queryClient]);
  
  return (
    <View>
      <TouchableOpacity 
        onPressIn={prefetchPopularProducts}
        onPress={() => navigation.navigate('PopularProducts', { categoryId })}
      >
        <Text>View Popular Products</Text>
      </TouchableOpacity>
      
      {/* Rest of component */}
    </View>
  );
};
```

### Cache Time Configuration

```typescript
// src/core/query/queryClient.ts
import { QueryClient } from '@tanstack/react-query';

export const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      // How long data stays fresh (not refetched)
      staleTime: 5 * 60 * 1000, // 5 minutes
      // How long unused data stays in cache before garbage collection
      cacheTime: 30 * 60 * 1000, // 30 minutes
      retry: 1,
      refetchOnWindowFocus: false,
      refetchOnMount: true,
    },
    mutations: {
      retry: 1,
    },
  },
});
```

## Examples

### Authentication Flow

```typescript
// src/features/auth/api/authHooks.ts
import { useMutation, useQueryClient } from '@tanstack/react-query';
import { userService } from '@/core/api/services/userService';
import { queryKeys } from '@/core/query/queryKeys';
import { useAuthStore } from '../state/authStore';

export const useLoginMutation = () => {
  const setAuthToken = useAuthStore((state) => state.setAuthToken);
  const setUser = useAuthStore((state) => state.setUser);
  const queryClient = useQueryClient();
  
  return useMutation({
    mutationFn: userService.login,
    onSuccess: (data) => {
      // 1. Update client state with auth token (Zustand)
      setAuthToken(data.token);
      setUser(data.user);
      
      // 2. Store user data in query cache (server state)
      queryClient.setQueryData(queryKeys.users.current(), data.user);
      
      // 3. Setup auth header for future API calls
      apiClient.defaults.headers.common['Authorization'] = `Bearer ${data.token}`;
    },
  });
};

export const useLogoutMutation = () => {
  const queryClient = useQueryClient();
  const logout = useAuthStore((state) => state.logout);
  
  return useMutation({
    mutationFn: userService.logout,
    onSuccess: () => {
      // 1. Clear client state (Zustand)
      logout();
      
      // 2. Reset the query cache to clear all server state
      queryClient.clear();
      
      // 3. Remove auth header from API client
      delete apiClient.defaults.headers.common['Authorization'];
    },
  });
};
```

### Real-Time Data Updates

```typescript
// src/features/notifications/api/notificationHooks.ts
import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
import { notificationService } from '@/core/api/services/notificationService';
import { queryKeys } from '@/core/query/queryKeys';
import { useEffect } from 'react';
import { socket } from '@/core/api/socket';
import { useNotificationStore } from '../state/useNotificationStore';

export const useNotificationsQuery = () => {
  const queryClient = useQueryClient();
  const socket = useWebsocket();
  
  // Regular query for initial data
  const query = useQuery({
    queryKey: queryKeys.notifications.list(),
    queryFn: notificationService.getNotifications,
  });
  
  // Listen for real-time updates
  useEffect(() => {
    if (!socket) return;
    
    const showNotification = useNotificationStore((state) => state.showNotificationBanner);
    
    const handleNewNotification = (notification) => {
      // Update cache with new data
      queryClient.setQueryData(
        queryKeys.notifications.list(),
        (oldData = []) => [notification, ...oldData]
      );
      
      // Show notification UI
      showNotification(notification);
    };
    
    socket.on('notification', handleNewNotification);
    
    return () => {
      socket.off('notification', handleNewNotification);
    };
  }, [socket, queryClient, showNotification]);
  
  return query;
};
```

### Complex Forms with Server Validation

```typescript
// src/features/profile/components/ProfileForm/ProfileForm.tsx
import { useState } from 'react';
import { useForm } from 'react-hook-form';
import { useUpdateProfileMutation } from '../../api/profileHooks';
import { useNavigation } from '@react-navigation/native';

export const ProfileForm = ({ initialData }) => {
  // Local form state
  const { control, handleSubmit, setError } = useForm({
    defaultValues: initialData
  });
  
  // Server mutation state
  const { mutate, isLoading } = useUpdateProfileMutation({
    onError: (error) => {
      // Handle server validation errors
      if (error.response?.data?.fieldErrors) {
        // Map server errors back to form fields
        Object.entries(error.response.data.fieldErrors).forEach(
          ([field, message]) => setError(field, { message })
        );
      }
    },
    onSuccess: () => {
      // Navigation on success
      navigation.navigate('ProfileSuccess');
    }
  });
  
  const navigation = useNavigation();
  
  const onSubmit = (data) => {
    mutate(data);
  };
  
  return (
    <Form 
      control={control} 
      onSubmit={handleSubmit(onSubmit)} 
      isLoading={isLoading}
    />
  );
};
```

## Related Documents

* **DOC-01:** Core Architecture Reference
* **DOC-03:** API & State Management Reference
* **GUIDE-02:** State Management Implementation Guide
* **GUIDE-06:** Offline Support Implementation Guide


# UTA Implementation Guides: State Management Implementation Guide
URL: https://dev.updatetheapp.com/docs/guides/client-state-management
Documentation: https://dev.updatetheapp.com/docs/guides/client-state-management

Patterns for implementing client state management using Zustand.
        
***

title: State Management Implementation Guide
description: Patterns for implementing client state management using Zustand.
-----------------------------------------------------------------------------

# GUIDE-02: State Management Implementation Guide

## Overview

This guide provides practical implementation patterns for managing client state using Zustand, a lightweight and efficient state management library for React Native applications. It covers store creation, usage in components, handling asynchronous logic, persistence, and best practices within the context of our application architecture.

## When To Use

Use these patterns when managing state that is:

* **Global**: Accessible and potentially modified by multiple parts of the application (e.g., UI state, user preferences).
* **Client-Side**: Not directly tied to server data (e.g., modal visibility, theme settings).
* **Synchronous**: Changes are typically immediate and don't involve network requests (though async logic can be handled within stores).
* **Persistent (Optional)**: Needs to survive app restarts (e.g., theme preference) using middleware like `persist`.

**Important**: Server state (e.g., API data) should be managed by **TanStack Query** (**GUIDE-01**), not Zustand.

## Implementation Patterns

### 1. Store Creation

Zustand stores are created using the `create` function, defining state and methods to update it in a single object. Each feature typically has its own store for modularity.

```typescript
// src/features/settings/state/useSettingsStore.ts
import { create } from 'zustand';

type ThemeMode = 'light' | 'dark' | 'system';

interface SettingsState {
  theme: ThemeMode;
  language: string;
  notificationsEnabled: boolean;
  setTheme: (theme: ThemeMode) => void;
  setLanguage: (language: string) => void;
  toggleNotifications: () => void;
  resetSettings: () => void;
}

export const useSettingsStore = create<SettingsState>((set) => ({
  theme: 'system',
  language: 'en',
  notificationsEnabled: true,
  setTheme: (theme) => set({ theme }),
  setLanguage: (language) => set({ language }),
  toggleNotifications: () => set((state) => ({ notificationsEnabled: !state.notificationsEnabled })),
  resetSettings: () => set({ theme: 'system', language: 'en', notificationsEnabled: true }),
}));
```

* **Key Concepts**:
  * The `create` function returns a hook (e.g., `useSettingsStore`) for accessing state and methods
  * Stores are feature-specific, aligning with the modular architecture
  * Use TypeScript interfaces for type safety

### 2. Using Stores in Components

Access and update state using the store's hook in React components.

```typescript
// src/features/settings/components/ThemeSelector.tsx
import React from 'react';
import { View, Text, TouchableOpacity, StyleSheet } from 'react-native';
import { useSettingsStore } from '../state/useSettingsStore';

type ThemeMode = 'light' | 'dark' | 'system';

export const ThemeSelector = () => {
  const { theme, setTheme } = useSettingsStore();

  const handleThemeChange = (newTheme: ThemeMode) => {
    setTheme(newTheme);
  };

  return (
    <View style={styles.container}>
      <Text style={styles.title}>Select Theme:</Text>
      <View style={styles.optionsContainer}>
        <ThemeOption 
          label="Light" 
          selected={theme === 'light'} 
          onPress={() => handleThemeChange('light')} 
        />
        <ThemeOption 
          label="Dark" 
          selected={theme === 'dark'} 
          onPress={() => handleThemeChange('dark')} 
        />
        <ThemeOption 
          label="System" 
          selected={theme === 'system'} 
          onPress={() => handleThemeChange('system')} 
        />
      </View>
    </View>
  );
};

interface ThemeOptionProps {
  label: string;
  selected: boolean;
  onPress: () => void;
}

const ThemeOption = ({ label, selected, onPress }: ThemeOptionProps) => (
  <TouchableOpacity
    style={[styles.option, selected && styles.selectedOption]}
    onPress={onPress}
  >
    <Text style={[styles.optionText, selected && styles.selectedText]}>{label}</Text>
  </TouchableOpacity>
);

const styles = StyleSheet.create({
  container: {
    padding: 16,
  },
  title: {
    fontSize: 18,
    fontWeight: 'bold',
    marginBottom: 16,
  },
  optionsContainer: {
    flexDirection: 'row',
    justifyContent: 'space-between',
  },
  option: {
    flex: 1,
    padding: 12,
    backgroundColor: '#f0f0f0',
    borderRadius: 8,
    alignItems: 'center',
    marginHorizontal: 4,
  },
  selectedOption: {
    backgroundColor: '#007AFF',
  },
  optionText: {
    fontWeight: '500',
  },
  selectedText: {
    color: 'white',
  },
});
```

* **Key Concepts**:
  * The store hook provides direct access to state and methods, simplifying component logic
  * Components re-render only when subscribed state changes, optimizing performance

### 3. Asynchronous Logic (Use Sparingly)

While TanStack Query handles server-side async operations, Zustand can manage client-side async logic within store methods.

**Example**: Simulating a complex client-side task.

```typescript
// src/features/complexProcess/state/useProcessingStore.ts
import { create } from 'zustand';

// Simulated async task
const simulateComplexClientTask = async (input: string): Promise<string> => {
  await new Promise((resolve) => setTimeout(resolve, 1500));
  if (input === 'fail') throw new Error('Client task failed');
  return `Processed: ${input}`;
};

interface ProcessingState {
  status: 'idle' | 'loading' | 'succeeded' | 'failed';
  result: string | null;
  error: string | null;
  processData: (input: string) => Promise<void>;
  reset: () => void;
}

export const useProcessingStore = create<ProcessingState>((set) => ({
  status: 'idle',
  result: null,
  error: null,
  processData: async (input) => {
    set({ status: 'loading', error: null });
    try {
      const result = await simulateComplexClientTask(input);
      set({ status: 'succeeded', result });
    } catch (error: any) {
      set({ status: 'failed', error: error.message });
    }
  },
  reset: () => set({ status: 'idle', result: null, error: null }),
}));
```

```typescript
// Usage in a component
import React from 'react';
import { View, Button, Text } from 'react-native';
import { useProcessingStore } from '../state/useProcessingStore';

const ProcessingComponent = () => {
  const { status, result, error, processData, reset } = useProcessingStore();

  return (
    <View>
      <Button
        title="Start Processing"
        onPress={() => processData('some input')}
        disabled={status === 'loading'}
      />
      {status === 'loading' && <Text>Processing...</Text>}
      {status === 'succeeded' && <Text>Success: {result}</Text>}
      {status === 'failed' && <Text>Error: {error}</Text>}
      <Button title="Reset" onPress={reset} />
    </View>
  );
};
```

* **Recommendation**: Avoid using Zustand for server-side async operations; use TanStack Query instead.

### 4. Selectors for Optimized Access

Client State Management supports optimized component rendering through selectors, allowing components to subscribe to specific state slices.

```typescript
// src/features/settings/state/settingsSelectors.ts
import { useSettingsStore } from './useSettingsStore';

export const useTheme = () => useSettingsStore((state) => state.theme);
export const useLanguage = () => useSettingsStore((state) => state.language);
export const useNotificationsEnabled = () => useSettingsStore((state) => state.notificationsEnabled);
```

```typescript
// Usage in a component
import React from 'react';
import { View, Text } from 'react-native';
import { useTheme, useLanguage } from '../state/settingsSelectors';

const SettingsDisplay = () => {
  const theme = useTheme();
  const language = useLanguage();

  return (
    <View>
      <Text>Theme: {theme}</Text>
      <Text>Language: {language}</Text>
    </View>
  );
};
```

* **Benefit**: Selectors ensure components only re-render when the selected state changes, improving performance

### 5. Persistence with Middleware

To persist state across app restarts, use the `persist` middleware with AsyncStorage.

```typescript
// src/features/settings/state/useSettingsStore.ts
import { create } from 'zustand';
import { persist, createJSONStorage } from 'zustand/middleware';
import AsyncStorage from '@react-native-async-storage/async-storage';

type ThemeMode = 'light' | 'dark' | 'system';

interface SettingsState {
  theme: ThemeMode;
  language: string;
  notificationsEnabled: boolean;
  setTheme: (theme: ThemeMode) => void;
  setLanguage: (language: string) => void;
  toggleNotifications: () => void;
  resetSettings: () => void;
}

export const useSettingsStore = create(
  persist<SettingsState>(
    (set) => ({
      theme: 'system',
      language: 'en',
      notificationsEnabled: true,
      setTheme: (theme) => set({ theme }),
      setLanguage: (language) => set({ language }),
      toggleNotifications: () => set((state) => ({ notificationsEnabled: !state.notificationsEnabled })),
      resetSettings: () => set({ theme: 'system', language: 'en', notificationsEnabled: true }),
    }),
    {
      name: 'settings-storage',
      storage: createJSONStorage(() => AsyncStorage),
      partialize: (state) => ({ theme: state.theme, language: state.language }),
    }
  )
);
```

* **Key Concepts**:
  * The `persist` middleware saves state to AsyncStorage
  * Use `partialize` to specify which parts of the state to persist

## Common Challenges

* **Multiple Stores**: Organize multiple stores by feature (e.g., `useSettingsStore`, `useUiStore`) for clarity
* **State Mutations**: Always use `set` to update state; direct mutations won't trigger re-renders or persist changes
* **Overusing Stores**: Avoid storing server state in Zustand; use TanStack Query for API data

## Performance Considerations

* **Fine-Grained Subscriptions**: Use selectors to subscribe to specific state slices, reducing unnecessary re-renders
* **Store Scope**: Keep stores focused on specific domains to avoid large, complex state objects
* **Middleware Overhead**: Be cautious with middleware like `persist`, as it may impact performance for large states

## Examples

### Managing UI State (Modal Visibility)

```typescript
// src/features/ui/state/useUiStore.ts
import { create } from 'zustand';

interface UiState {
  isSidebarOpen: boolean;
  activeModal: string | null;
  openSidebar: () => void;
  closeSidebar: () => void;
  toggleSidebar: () => void;
  openModal: (modalId: string) => void;
  closeModal: () => void;
}

export const useUiStore = create<UiState>((set) => ({
  isSidebarOpen: false,
  activeModal: null,
  openSidebar: () => set({ isSidebarOpen: true }),
  closeSidebar: () => set({ isSidebarOpen: false }),
  toggleSidebar: () => set((state) => ({ isSidebarOpen: !state.isSidebarOpen })),
  openModal: (modalId) => set({ activeModal: modalId }),
  closeModal: () => set({ activeModal: null }),
}));
```

```typescript
// src/features/ui/components/ModalManager.tsx
import React from 'react';
import { View, Button } from 'react-native';
import { useUiStore } from '../state/useUiStore';
import { SomeModalComponent } from './SomeModalComponent';

export const ModalManager = () => {
  const { activeModal, openModal, closeModal } = useUiStore();

  return (
    <View>
      <Button title="Open Modal" onPress={() => openModal('myModal')} />
      {activeModal === 'myModal' && (
        <SomeModalComponent isVisible={true} onClose={closeModal} />
      )}
    </View>
  );
};
```

## Best Practices

* (Do ✅) Use multiple feature-specific stores rather than one large global store
* (Do ✅) Leverage selectors for optimized component rendering
* (Don't ❌) Store server state or API responses in Zustand
* (Do ✅) Use TypeScript for type safety
* (Consider 🤔) Isolating store logic into separate files for better organization

## Related Documents

* [Core Architecture Reference](/docs/architecture/core-architecture)
* [State Management Architecture](/docs/state-management/index)
* [API & State Management Reference](/docs/state-management)
* [Server State Management Guide](/docs/guides/server-state-management)

***


# UTA Implementation Guides: Styling Implementation Guide
URL: https://dev.updatetheapp.com/docs/guides/styling-implementation
Documentation: https://dev.updatetheapp.com/docs/guides/styling-implementation

Guidelines for implementing styles using StyleSheet and Unistyles.
        
***

title: Styling Implementation Guide
description: Guidelines for implementing styles using StyleSheet and Unistyles.
-------------------------------------------------------------------------------

# Styling Implementation Guide

## Overview

This guide details the patterns and best practices for styling components in our React Native application. We primarily use `React Native StyleSheet` for core styling and `Unistyles` for advanced features like theming, responsive styles, and performance optimization.

## When To Use

* **`StyleSheet.create`**: For standard, static component styles.
* **`Unistyles` (`createStyleSheet`, `useStyles`)**:
  * When styles need to adapt based on theme (light/dark mode).
  * For responsive styles that change based on screen size or orientation.
  * When accessing theme variables (colors, spacing, fonts) directly within styles.
  * For performance-critical components where Unistyles' optimizations are beneficial.

## Implementation Patterns

### 1. Basic Styling with `StyleSheet.create`

Use `StyleSheet.create` for simple, non-dynamic styles. This is the most performant method for static styles.

```typescript
// src/ui/components/BasicButton/styles.ts
import { StyleSheet } from 'react-native';

export const styles = StyleSheet.create({
  container: {
    paddingVertical: 12,
    paddingHorizontal: 24,
    borderRadius: 8,
    backgroundColor: '#007AFF', // Example static color
    alignItems: 'center',
    justifyContent: 'center',
  },
  text: {
    color: '#FFFFFF',
    fontSize: 16,
    fontWeight: '600',
  },
  disabledContainer: {
    backgroundColor: '#B0B0B0',
  },
});
```

```typescript
// src/ui/components/BasicButton/BasicButton.tsx
import React from 'react';
import { TouchableOpacity, Text, TouchableOpacityProps } from 'react-native';
import { styles } from './styles';

interface BasicButtonProps extends TouchableOpacityProps {
  title: string;
}

export const BasicButton: React.FC<BasicButtonProps> = ({ title, style, disabled, ...props }) => {
  return (
    <TouchableOpacity
      style={[
        styles.container,
        disabled && styles.disabledContainer,
        style, // Allow consuming components to override styles
      ]}
      disabled={disabled}
      {...props}
    >
      <Text style={styles.text}>{title}</Text>
    </TouchableOpacity>
  );
};
```

### 2. Theming and Dynamic Styles with `Unistyles`

Define themes and breakpoints, then create stylesheets that adapt.

**a) Define Themes and Breakpoints:**

```typescript
// src/core/styles/theme.ts
export const lightTheme = {
    colors: {
        background: '#FFFFFF',
        text: '#111111',
        primary: '#007AFF',
        card: '#F5F5F5',
        border: '#DDDDDD',
    },
    spacing: {
        sm: 4,
        md: 8,
        lg: 16,
        xl: 24,
    },
    // ... other theme variables (typography, radii)
} as const // Use 'as const' for stricter typing

export const darkTheme = {
    colors: {
        background: '#121212',
        text: '#FFFFFF',
        primary: '#0A84FF',
        card: '#1E1E1E',
        border: '#333333',
    },
    spacing: {
        sm: 4,
        md: 8,
        lg: 16,
        xl: 24,
    },
    // ... other theme variables
} as const

// Define breakpoints for responsive design
export const breakpoints = {
    xs: 0,
    sm: 576,
    md: 768,
    lg: 992,
    xl: 1200,
} as const

// Type definition for themes
type AppTheme = typeof lightTheme

// Extend Unistyles registry
declare module 'react-native-unistyles' {
    export interface UnistylesThemes extends AppTheme {}
    export interface UnistylesBreakpoints extends typeof breakpoints {}
}
```

**b) Register Unistyles:**

```typescript
// src/core/styles/unistyles.ts (or in your App.tsx setup)
import { UnistylesRegistry } from 'react-native-unistyles'
import { lightTheme, darkTheme, breakpoints } from './theme'

UnistylesRegistry
    .addThemes({ light: lightTheme, dark: darkTheme })
    .addBreakpoints(breakpoints)
    .addConfig({
        // Optionally set initial theme
        // initialTheme: 'light',
        adaptiveThemes: true, // Enable automatic theme switching based on system
    })
```

**c) Create a Unistyles Stylesheet:**

```typescript
// src/ui/components/ThemedCard/styles.ts
import { createStyleSheet } from 'react-native-unistyles'

export const stylesheet = createStyleSheet((theme, runtime) => ({
  container: {
    backgroundColor: theme.colors.card,
    borderRadius: theme.spacing.md,
    padding: theme.spacing.lg,
    borderWidth: 1,
    borderColor: theme.colors.border,
    shadowColor: theme.colors.text, // Shadow color might differ significantly
    shadowOffset: {
      width: 0,
      // Responsive shadow based on screen height
      height: runtime.screen.height > 800 ? 4 : 2, 
    },
    shadowOpacity: theme.name === 'dark' ? 0.3 : 0.1, // Different opacity for dark mode
    shadowRadius: theme.spacing.sm,
    elevation: 3,
    // Responsive padding using breakpoints
    paddingHorizontal: {
        xs: theme.spacing.md,
        md: theme.spacing.lg, // Apply larger padding on medium screens and up
    }
  },
  title: {
    fontSize: 18,
    fontWeight: 'bold',
    color: theme.colors.primary,
    marginBottom: theme.spacing.sm,
  },
  content: {
    fontSize: 14,
    color: theme.colors.text,
    // Different line height based on breakpoint
    lineHeight: {
        xs: 18,
        lg: 20
    }
  },
}));
```

**d) Use the Stylesheet in a Component:**

```typescript
// src/ui/components/ThemedCard/ThemedCard.tsx
import React from 'react';
import { View, Text, ViewProps } from 'react-native';
import { useStyles } from 'react-native-unistyles';
import { stylesheet } from './styles'; // Import the unistyles sheet

interface ThemedCardProps extends ViewProps {
  title?: string;
  children: React.ReactNode;
}

export const ThemedCard: React.FC<ThemedCardProps> = ({ title, children, style }) => {
  // Use the useStyles hook to get themed styles
  const { styles } = useStyles(stylesheet);

  return (
    <View style={[styles.container, style]}> // Apply themed styles
      {title && <Text style={styles.title}>{title}</Text>}
      <View>
        {typeof children === 'string' ? (
           <Text style={styles.content}>{children}</Text>
        ) : (
            children
        )}
      </View>
    </View>
  );
};
```

### 3. Combining `StyleSheet` and `Unistyles`

You can mix both approaches. Use `StyleSheet` for static parts and `useStyles` for theme-dependent parts.

```typescript
// styles.ts
import { StyleSheet } from 'react-native';
import { createStyleSheet as createUnistylesSheet } from 'react-native-unistyles';

// Static styles
export const staticStyles = StyleSheet.create({
    icon: {
        width: 24,
        height: 24,
        marginRight: 8,
    },
    // ... other static styles
});

// Dynamic/Themed styles
export const dynamicStylesheet = createUnistylesSheet((theme) => ({
    container: {
        flexDirection: 'row',
        alignItems: 'center',
        padding: theme.spacing.md,
        backgroundColor: theme.colors.background,
    },
    text: {
        color: theme.colors.text,
        fontSize: 16,
    },
}));
```

```typescript
// Component.tsx
import React from 'react';
import { View, Text } from 'react-native';
import { useStyles } from 'react-native-unistyles';
import { staticStyles, dynamicStylesheet } from './styles';
import Icon from 'react-native-vector-icons/MaterialIcons'; // Example icon

export const MixedStyleComponent = () => {
    const { styles: dynamicStyles } = useStyles(dynamicStylesheet);

    return (
        <View style={dynamicStyles.container}> 
            <Icon name="info" size={24} style={staticStyles.icon} color={dynamicStyles.text.color} />
            <Text style={dynamicStyles.text}>Styled Text</Text>
        </View>
    );
}
```

### 4. Responsive Styles (Breakpoints)

Unistyles allows defining styles specific to breakpoints.

```typescript
// styles.ts
import { createStyleSheet } from 'react-native-unistyles'

export const stylesheet = createStyleSheet((theme, runtime) => ({
    container: {
        flexDirection: {
            xs: 'column', // Column layout on small screens
            md: 'row'    // Row layout on medium screens and up
        },
        padding: theme.spacing.md,
        alignItems: 'center'
    },
    image: {
        width: '100%', // Full width on small screens
        height: 150,
        marginBottom: {
            xs: theme.spacing.md,
            md: 0 // No margin bottom on larger screens (row layout)
        },
        marginRight: {
            xs: 0,
            md: theme.spacing.lg // Add margin right for row layout
        },
        // Specific width on larger screens
        width: {
            md: 150
        }
    },
    textContainer: {
        flex: 1 // Take remaining space in row layout
    },
    title: {
        fontSize: {
            xs: 18,
            lg: 22 // Larger font on large screens
        },
        fontWeight: 'bold',
        color: theme.colors.primary
    }
}));
```

### 5. Global Styles and Style Utilities

Define reusable style patterns and utilities in the `core/styles` directory.

```typescript
// src/core/styles/typography.ts
import { TextStyle } from 'react-native';

export const typography = {
    h1: {
        fontSize: 32,
        fontWeight: 'bold',
    } as TextStyle,
    h2: {
        fontSize: 24,
        fontWeight: 'bold',
    } as TextStyle,
    body: {
        fontSize: 16,
    } as TextStyle,
    caption: {
        fontSize: 12,
        color: '#666666',
    } as TextStyle,
};

// src/core/styles/layout.ts
export const layout = {
    center: {
        alignItems: 'center',
        justifyContent: 'center',
    },
    row: {
        flexDirection: 'row',
    },
    // ... other layout utilities
};

// src/core/styles/index.ts
export * from './theme';
export * from './typography';
export * from './layout';
export * from './unistyles'; // Assuming Unistyles setup is here or imported
```

```typescript
// Usage in a component's stylesheet
import { createStyleSheet } from 'react-native-unistyles';
import { typography, layout } from '@/core/styles'; // Import global styles

export const stylesheet = createStyleSheet((theme) => ({
    container: {
        ...layout.center, // Spread layout utility
        padding: theme.spacing.lg,
    },
    title: {
        ...typography.h1, // Spread typography style
        color: theme.colors.primary,
        marginBottom: theme.spacing.md,
    },
}));
```

## Common Challenges

* **Over-reliance on Inline Styles:** While convenient for quick adjustments, excessive inline styles (`style={{ color: 'red' }}`) hurt performance and maintainability. Prefer `StyleSheet.create` or Unistyles.
* **Performance with Dynamic Styles:** Creating new style objects in the render function (`style={{ backgroundColor: props.isActive ? 'blue' : 'grey' }}`) can cause unnecessary re-renders. Use `StyleSheet.flatten` with conditional styles from `StyleSheet.create` or leverage Unistyles variants/dynamic functions.
* **Specificity and Overrides:** Understanding how styles cascade and override each other is important. Styles passed via the `style` prop typically override styles defined within the component.
* **Platform Differences:** Some style properties behave differently or are unavailable on iOS vs. Android (e.g., `elevation` vs. `shadow*`). Test on both platforms or use platform-specific code (`Platform.select`) when necessary.

## Performance Considerations

* **(Do ✅) Use `StyleSheet.create`** for static styles. React Native optimizes these by sending them over the bridge only once.
* **(Do ✅) Use `Unistyles`** for themed and responsive styles. It's highly optimized for dynamic style generation.
* **(Don't ❌) Use Inline Styles** (`style={{...}}`) frequently, especially within loops or frequently re-rendering components, as it creates new objects on every render.
* **(Don't ❌) Create Style Objects in Render:** Avoid defining style objects directly within the component function body. Define them outside using `StyleSheet.create` or `createStyleSheet` from Unistyles.
* **(Consider 🤔) `StyleSheet.flatten`:** Use `StyleSheet.flatten([styles.base, conditionalStyle])` when conditionally applying styles from `StyleSheet.create`, but be aware it has a minor performance cost compared to purely static styles.

## Examples

### Themed Button using Unistyles

```typescript
// src/ui/components/ThemedButton/styles.ts
import { createStyleSheet } from 'react-native-unistyles'

export const stylesheet = createStyleSheet((theme) => ({
    container: {
        paddingVertical: theme.spacing.md,
        paddingHorizontal: theme.spacing.lg,
        borderRadius: 8,
        backgroundColor: theme.colors.primary,
        alignItems: 'center',
        opacity: 1, // Default opacity
    },
    text: {
        color: theme.colors.background, // Text color contrasts with primary
        fontSize: 16,
        fontWeight: 'bold',
    },
    // Variant for disabled state
    disabled: {
        backgroundColor: theme.colors.border, // Use a disabled color from theme
        opacity: 0.6,
    },
    // Variant for secondary style
    secondary: {
        backgroundColor: theme.colors.card,
        borderWidth: 1,
        borderColor: theme.colors.primary,
    },
    secondaryText: {
        color: theme.colors.primary,
    },
}));
```

```typescript
// src/ui/components/ThemedButton/ThemedButton.tsx
import React from 'react';
import { TouchableOpacity, Text, TouchableOpacityProps } from 'react-native';
import { useStyles } from 'react-native-unistyles';
import { stylesheet } from './styles';

interface ThemedButtonProps extends TouchableOpacityProps {
  title: string;
  variant?: 'primary' | 'secondary';
}

export const ThemedButton: React.FC<ThemedButtonProps> = ({ title, style, disabled, variant = 'primary', ...props }) => {
  const { styles } = useStyles(stylesheet);

  const isSecondary = variant === 'secondary';

  return (
    <TouchableOpacity
      style={[
        styles.container,
        isSecondary && styles.secondary, // Apply secondary container style
        disabled && styles.disabled, // Apply disabled style
        style,
      ]}
      disabled={disabled}
      {...props}
    >
      <Text style={[styles.text, isSecondary && styles.secondaryText]}>
        {title}
      </Text>
    </TouchableOpacity>
  );
};
```

## Related Documents

* **DOC-01:** Core Architecture Reference
* **DOC-02:** Project Structure Reference

***


# UTA Implementation Guides: Feature Flag Implementation Guide
URL: https://dev.updatetheapp.com/docs/guides/feature-flag-implementation
Documentation: https://dev.updatetheapp.com/docs/guides/feature-flag-implementation

Patterns for implementing feature flags using a context provider.
        
***

title: Feature Flag Implementation Guide
description: Patterns for implementing feature flags using a context provider.
------------------------------------------------------------------------------

# Feature Flag Implementation Guide

## Overview

This guide outlines the implementation of a feature flag system using a React Context provider. It allows toggling features on/off based on configuration retrieved from a remote source or local defaults, potentially considering user context (like role or ID).

## When To Use

Use feature flags to:

* Gradually roll out new features to specific user segments or percentages.
* Perform A/B testing by enabling features for different groups.
* Quickly disable problematic features in production without a full deployment.
* Manage different feature sets for various environments (development, staging, production).
* Control access to premium or beta features.

## Implementation Patterns

### 1. Define Flag Types and Context

Establish the structure for flags and the context used for evaluation.

```typescript
// src/core/featureFlags/types/featureFlags.ts
export interface FeatureFlags {
  // Example flags - Define your actual flags here
  enableNewDashboard: boolean;
  showAdvancedAnalytics: boolean;
  useOptimizedImageLoading: boolean;
  enableOfflineMode: boolean;
  allowMultiAccount: boolean;
}

// Context provided to the flag evaluation logic
export interface FlagEvaluationContext {
  user?: {
    id: string;
    email?: string;
    role?: string; // e.g., 'admin', 'beta_tester', 'premium_user'
    groups?: string[];
  };
  device?: {
    platform: 'ios' | 'android' | 'web';
    version: string;
  };
  environment: 'development' | 'staging' | 'production';
  // Add other relevant context, like region, app version etc.
}
```

### 2. Feature Flag Provider

A context provider that fetches flag configurations and makes them available.

```typescript
// src/core/featureFlags/context/FeatureFlagContext.tsx
import React, { createContext, useState, useEffect, useContext, useMemo, useCallback } from 'react';
import type { FeatureFlags, FlagEvaluationContext } from '../types/featureFlags';
import { featureFlagService } from '../services/featureFlagService'; // Service to fetch flags
import { useAuth } from '@/features/auth/hooks/useAuth'; // To get user context
import { Platform } from 'react-native';
import Constants from 'expo-constants'; // For environment/app info

interface FeatureFlagContextType {
  flags: FeatureFlags;
  isLoading: boolean;
  error: Error | null;
  refreshFlags: () => Promise<void>;
  getFlag: (flagName: keyof FeatureFlags, defaultValue?: boolean) => boolean;
  trackExposure: (flagName: keyof FeatureFlags) => void; // For analytics
}

// Define default flags (important fallback)
const defaultFlags: FeatureFlags = {
  enableNewDashboard: false,
  showAdvancedAnalytics: false,
  useOptimizedImageLoading: true,
  enableOfflineMode: false,
  allowMultiAccount: true,
};

const FeatureFlagContext = createContext<FeatureFlagContextType>({
  flags: defaultFlags,
  isLoading: true,
  error: null,
  refreshFlags: async () => {},
  getFlag: (flagName, defaultValue) => defaultFlags[flagName] ?? defaultValue ?? false,
  trackExposure: () => {},
});

export const FeatureFlagProvider: React.FC<{ children: React.ReactNode }> = ({ children }) => {
  const [flags, setFlags] = useState<FeatureFlags>(defaultFlags);
  const [isLoading, setIsLoading] = useState(true);
  const [error, setError] = useState<Error | null>(null);
  const { user } = useAuth(); // Get user from auth context

  // Memoize the evaluation context to avoid unnecessary fetches
  const evaluationContext = useMemo((): FlagEvaluationContext => ({
    user: user ? {
        id: user.id,
        email: user.email,
        role: user.role,
        // groups: user.groups, // Add groups if applicable
    } : undefined,
    device: {
        platform: Platform.OS,
        version: Platform.Version.toString(),
    },
    environment: Constants.expoConfig?.extra?.environment ?? 'development',
  }), [user]);

  // Function to fetch flags
  const fetchFlags = useCallback(async () => {
    setIsLoading(true);
    setError(null);
    try {
      console.log('[FeatureFlagProvider] Fetching flags with context:', evaluationContext);
      const fetchedFlags = await featureFlagService.getFlags(evaluationContext);
      // Merge fetched flags with defaults to ensure all flags are present
      setFlags({ ...defaultFlags, ...fetchedFlags });
      console.log('[FeatureFlagProvider] Flags updated:', { ...defaultFlags, ...fetchedFlags });
    } catch (err: any) {
      console.error('[FeatureFlagProvider] Error fetching feature flags:', err);
      setError(err);
      setFlags(defaultFlags); // Fallback to defaults on error
    } finally {
      setIsLoading(false);
    }
  }, [evaluationContext]); // Dependency: evaluationContext

  // Fetch flags on mount and when context changes (e.g., user logs in/out)
  useEffect(() => {
    fetchFlags();
  }, [fetchFlags]);

  // Function to get a specific flag with a fallback default value
  const getFlag = useCallback((flagName: keyof FeatureFlags, defaultValue: boolean = false): boolean => {
      return flags[flagName] ?? defaultValue;
  }, [flags]);

  // Placeholder for exposure tracking (send to analytics)
  const trackExposure = useCallback((flagName: keyof FeatureFlags) => {
      // console.log(`[FeatureFlagProvider] Exposure event for flag: ${flagName}, value: ${flags[flagName]}`);
      // Implement analytics tracking call here (e.g., Segment, Mixpanel)
  }, [/* flags */]); // Track only when flag value changes if needed

  const value = useMemo(() => ({
      flags,
      isLoading,
      error,
      refreshFlags: fetchFlags, // Expose refresh function
      getFlag,
      trackExposure,
  }), [flags, isLoading, error, fetchFlags, getFlag, trackExposure]);

  return (
    <FeatureFlagContext.Provider value={value}>
      {children}
    </FeatureFlagContext.Provider>
  );
};

// Hook to use the feature flags
export const useFeatureFlags = () => useContext(FeatureFlagContext);

// Hook to get a single flag value (recommended usage)
export const useFeatureFlag = (flagName: keyof FeatureFlags, defaultValue: boolean = false): boolean => {
    const { getFlag, trackExposure, isLoading } = useFeatureFlags();
    const flagValue = getFlag(flagName, defaultValue);

    // Track exposure when the component mounts and potentially when value changes
    useEffect(() => {
        // Optionally check isLoading to avoid tracking default value during init
        // if (!isLoading) {
             trackExposure(flagName);
        // }
    }, [flagName, flagValue, trackExposure, isLoading]);

    return flagValue;
};
```

### 3. Feature Flag Service

Abstracts the logic for fetching flag configurations (e.g., from a backend or a service like LaunchDarkly, Firebase Remote Config).

```typescript
// src/core/featureFlags/services/featureFlagService.ts
import type { FeatureFlags, FlagEvaluationContext } from '../types/featureFlags';
import { apiClient } from '@/core/api/apiClient'; // Use your standard API client

// Placeholder endpoint - replace with your actual backend endpoint
const FEATURE_FLAG_ENDPOINT = '/feature-flags'; 

export const featureFlagService = {
  /**
   * Fetches feature flags based on the provided context.
   * Replace this with your actual implementation (e.g., calling LaunchDarkly, Firebase Remote Config, or your backend).
   */
  getFlags: async (context: FlagEvaluationContext): Promise<Partial<FeatureFlags>> => {
    console.log('[FeatureFlagService] Requesting flags for context:', context);
    
    // --- Example: Fetching from a custom backend endpoint ---
    try {
        const response = await apiClient.post<Partial<FeatureFlags>>(FEATURE_FLAG_ENDPOINT, context);
        console.log('[FeatureFlagService] Received flags from backend:', response.data);
        return response.data;
    } catch (error) {
        console.error('[FeatureFlagService] Failed to fetch flags from backend:', error);
        // Fallback to empty object or throw error depending on desired behavior
        return {}; 
    }

    // --- Example: Using a placeholder for local development ---
    // await new Promise(resolve => setTimeout(resolve, 300)); // Simulate network delay
    // return { 
    //     enableNewDashboard: context.user?.role === 'admin' || context.user?.email?.endsWith('@yourcompany.com'),
    //     showAdvancedAnalytics: context.user?.role === 'admin' 
    // };
  },
};
```

### 4. Using Feature Flags in Components

Conditionally render UI or enable functionality based on flag values.

```typescript
// src/features/dashboard/screens/DashboardScreen.tsx
import React from 'react';
import { View, Text } from 'react-native';
import { useFeatureFlag, useFeatureFlags } from '@/core/featureFlags/context/FeatureFlagContext';
import { OldDashboard } from '../components/OldDashboard';
import { NewDashboard } from '../components/NewDashboard';
import { AnalyticsSection } from '../components/AnalyticsSection';
import LoadingSpinner from '@/ui/components/LoadingSpinner'; // Example loading component

export const DashboardScreen = () => {
  // Use the hook to get flag values
  const enableNewDashboard = useFeatureFlag('enableNewDashboard');
  const showAdvancedAnalytics = useFeatureFlag('showAdvancedAnalytics', false); // Provide default

  // Optionally get loading state if needed for initial render
  const { isLoading: flagsLoading } = useFeatureFlags();

  if (flagsLoading) {
      return <LoadingSpinner text="Loading configuration..." />;
  }

  return (
    <View>
      <Text>Dashboard</Text>
      
      {/* Conditional rendering based on feature flag */}
      {enableNewDashboard ? <NewDashboard /> : <OldDashboard />}

      {/* Conditionally render another section */}
      {showAdvancedAnalytics && <AnalyticsSection />}
    </View>
  );
};
```

### 5. Integration with Application Setup

Wrap your application with the `FeatureFlagProvider`.

```typescript
// src/App.tsx (or your main entry point)
import React from 'react';
import { SafeAreaProvider } from 'react-native-safe-area-context';
import { QueryClientProvider } from '@tanstack/react-query';
import { Provider as StoreProvider } from 'react-redux'; // Redux Provider
import { PersistGate } from 'redux-persist/integration/react'; // Redux Persist

import { AppNavigator } from '@/navigation/AppNavigator';
import { AuthProvider } from '@/core/auth/providers/AuthProvider';
import { FeatureFlagProvider } from '@/core/featureFlags/context/FeatureFlagContext';
import { queryClient } from '@/core/query/queryClient';
import { store, persistor } from '@/core/store';
import LoadingScreen from '@/features/core/screens/LoadingScreen'; // Your global loading screen

// Initialize API interceptors etc. here if needed

const App = () => {
  return (
    <SafeAreaProvider>
      <StoreProvider store={store}>
        <PersistGate loading={<LoadingScreen />} persistor={persistor}>
          <QueryClientProvider client={queryClient}>
            <AuthProvider>
              {/* FeatureFlagProvider is often placed inside AuthProvider 
                  if flags depend on user context */} 
              <FeatureFlagProvider>
                <AppNavigator />
              </FeatureFlagProvider>
            </AuthProvider>
          </QueryClientProvider>
        </PersistGate>
      </StoreProvider>
    </SafeAreaProvider>
  );
};

export default App;
```

## Common Challenges

* **Loading State:** Feature flags might not be available immediately on app start. UI components should handle a loading state or use default flag values until the provider fetches the configuration.
* **Context Dependency:** If flags depend on user attributes (role, ID), ensure the `FeatureFlagProvider` is placed *after* the `AuthProvider` in the component tree so user data is available.
* **Caching:** Decide on a caching strategy for flags. Fetching them on every app start might be slow. Consider caching results in `AsyncStorage` with a TTL (Time To Live) or relying on the caching mechanisms of third-party services (like LaunchDarkly).
* **Testing:** Mocking feature flags in unit and E2E tests is crucial. Provide a way to override flag values in test environments.
* **Stale Flags:** If flags change remotely, the app needs a mechanism to refresh them (e.g., periodic background refresh, refresh on resume, manual refresh trigger). The `refreshFlags` function exposed by the hook can be used for this.

## Performance Considerations

* **Fetch Time:** Fetching flags from a remote service adds to app startup time. Optimize the fetching process and use defaults/caching.
* **Context Updates:** If the `evaluationContext` (especially user data) changes frequently, it could trigger unnecessary flag re-fetches. Use `useMemo` for the context object as shown in the provider example.
* **`useFeatureFlags` vs `useFeatureFlag`:** Using `useFeatureFlags` in many components can cause them all to re-render if *any* flag changes. Prefer using the specific `useFeatureFlag` hook in components, as it typically only re-renders if the *specific flag* it consumes changes (depending on context implementation).

## Examples

### A/B Testing Example

```typescript
const useOptimizedLoading = useFeatureFlag('useOptimizedImageLoading');

return (
    <ImageComponent 
        source={source}
        // Pass flag to component or use different components
        useOptimizedLoading={useOptimizedLoading} 
    />
);
```

### Gradual Rollout by User ID

```typescript
// featureFlagService.ts (Conceptual - logic inside your service/backend)
function isUserInRollout(userId: string, percentage: number): boolean {
    // Simple consistent hash based rollout (example)
    const hash = simpleHash(userId); // Implement a simple hashing function
    return (hash % 100) < percentage;
}

// ... inside getFlags ...
// return {
//     enableNewFeature: isUserInRollout(context.user.id, 10) // 10% rollout
// };
```

### Disabling a Feature Quickly

Simply toggle the flag (e.g., `enableProblematicFeature`) to `false` in your feature flag management service (LaunchDarkly, Firebase Remote Config, your backend). The app will pick up the change on the next fetch/refresh.

## Related Documents

* **DOC-01:** Core Architecture Reference
* **See Also:** Authentication Flow Implementation Guide (for user context)

***


# UTA Implementation Guides: Pre-UI Initialization Guide
URL: https://dev.updatetheapp.com/docs/guides/app-initialization/pre-ui-initialization-guide
Documentation: https://dev.updatetheapp.com/docs/guides/app-initialization/pre-ui-initialization-guide

Implementation patterns for the critical Pre-UI initialization stage in the application bootstrap process.
        
***

title: Pre-UI Initialization Guide
description: Implementation patterns for the critical Pre-UI initialization stage in the application bootstrap process.
-----------------------------------------------------------------------------------------------------------------------

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';

# Pre-UI Initialization Guide

## Overview

The Pre-UI initialization stage is the first and most critical phase of the application bootstrap process. During this phase, we perform essential setup tasks that must complete before showing any UI to the user.

Think of the Pre-UI stage as building the foundation for your application's user experience. The work done in this stage determines which screens users will see first, how the app will appear, and which core functionalities will be immediately available.

This guide explores practical implementation patterns to help you effectively manage the Pre-UI stage while maximizing performance – ensuring users see your app's interface as quickly as possible.

## Quick Start

If you're eager to get started with Pre-UI initialization, here's a simplified approach you can implement right away:

1. Register your critical tasks with the initializer:
   ```typescript
   import { initializer, InitStage } from '@/core/shared/app/initialization';

   // Register a Pre-UI task
   initializer.registerTask(InitStage.PRE_UI, {
     name: 'auth:token-retrieval',
     execute: async () => {
       // Implementation here, e.g., retrieve authentication tokens
       const accessToken = await tokenService.getStoredAccessToken();
       authStore.setToken(accessToken);
     }
   });
   ```

2. Keep the native splash screen visible until Pre-UI initialization completes:
   ```typescript
   useEffect(() => {
     async function initializePreUI() {
       try {
         // Execute Pre-UI stage (critical, blocking)
         await initializer.executeStage(InitStage.PRE_UI);
         
         // Mark Pre-UI complete so we can render app shell
         setPreUIComplete(true);
         
         // Hide splash screen when complete
         SplashScreen.hide({ fade: true });
       } catch (error) {
         console.error('Pre-UI initialization failed:', error);
         SplashScreen.hide({ fade: true });
       }
     }
     
     initializePreUI();
   }, []);
   ```

3. Use the `useInitialization` hook to track initialization progress in your components

The rest of this guide explains these concepts in depth, providing more context and advanced implementation patterns.

## When To Use

The Pre-UI stage is best suited for a specific set of initialization tasks that must happen before your app can meaningfully display anything to the user. Let's explore which tasks belong in this stage and why careful consideration is important.

### Appropriate Tasks for Pre-UI Initialization

* **Essential for Application Function**: Components that must be available before any UI can be rendered
  * *Example*: Reading authentication tokens to determine if a user is logged in
  * *Why*: Without this, your app can't decide which screen to show first

* **Required for Navigation Decisions**: Services that determine the initial navigation state
  * *Example*: Checking if a user has completed onboarding
  * *Why*: This information dictates the entire navigation flow of your app

* **Critical User Experience**: Settings that significantly impact initial user experience
  * *Example*: Loading theme preferences (light/dark) or language settings
  * *Why*: Showing UI and then immediately changing these settings creates a jarring flash effect

### Performance Considerations

**Important**: Keep Pre-UI initialization tasks to an absolute minimum, as every millisecond spent here directly adds to your app's startup time. Users often judge app quality based on startup performance, so this is a critical optimization area.

For tasks that are important but not critical to the first render, consider moving them to the [Initial UI](/docs/guides/app-initialization/initial-ui) or [Background](/docs/guides/app-initialization/background) stages. This allows users to see and interact with your app sooner, improving perceived performance.

## Implementation Patterns

Let's explore practical implementation patterns for the Pre-UI stage. Below is a visualization of how this stage fits into the overall app initialization flow:

<Mermaid
  chart={`
flowchart TD
  Start[App Launch] --> PreUIStage[Pre-UI Stage]
  
  subgraph PreUIStage[Pre-UI Initialization Stage]
      Auth[Authentication State]
      Preferences[Critical Preferences]
      Config[App Configuration]
  end
  
  PreUIStage --> SplashTransition[Splash Screen Transition]
  SplashTransition --> InitialUI[Initial UI Rendering]
  
  style PreUIStage fill:#f9f,stroke:#333,stroke-width:2px
  style SplashTransition fill:#bbf,stroke:#333,stroke-width:2px
`}
/>

As the diagram illustrates, the Pre-UI stage occurs immediately after app launch and before any UI is shown to the user. During this phase, we typically handle three primary concerns:

1. **Authentication State**: Determining if a user is logged in
2. **Critical Preferences**: Loading essential user settings
3. **App Configuration**: Setting up core application parameters

Once these tasks complete, we transition from the native splash screen to the Initial UI rendering phase.

### Splash Screen Management

For detailed implementation of splash screens during initialization, refer to the [Splash Screens Guide](/docs/ui-development/splash-screens). The Pre-UI initialization stage should integrate with splash screens as follows:

* Keep the native splash screen visible until Pre-UI initialization completes
* Use the splash screen's hide method as the final step of Pre-UI initialization
* Consider fade transitions for a smoother user experience

Here's a basic integration example using our abstracted SplashScreen component:

```typescript
// App.tsx or app/_layout.tsx
import { useEffect, useState } from 'react';
import { initializer, InitStage } from '@/core/shared/app/initialization';
import { SplashScreen } from '@/core/shared/splash-screen/SplashScreen';

// In your root component
useEffect(() => {
  async function initializePreUI() {
    try {
      // Execute Pre-UI stage (critical, blocking)
      await initializer.executeStage(InitStage.PRE_UI);
      
      // Hide splash screen with smooth fade
      SplashScreen.hide({ fade: true, duration: 500 });
      
      // Continue with non-blocking stages
    } catch (error) {
      console.error('Pre-UI initialization failed:', error);
      // Still hide splash screen even on error
      SplashScreen.hide({ fade: true });
    }
  }
  
  initializePreUI();
}, []);
```

For complete implementation details, including setup, configuration, and advanced usage, see the [Splash Screens Guide](/docs/ui-development/splash-screens).

### Authentication State Initialization

The most common Pre-UI initialization task is retrieving and validating authentication state. This information is crucial because it determines which UI flows your users will see - such as login screens, onboarding, or the main application content.

By loading authentication state during the Pre-UI stage, you can seamlessly route users to the appropriate screens during the [Initial UI rendering stage](/docs/guides/app-initialization/initial-ui) without jarring redirects or flashes of incorrect content.

Here's how you might implement authentication state initialization:

```typescript
// core/domains/auth/initialization.ts
import { initializer, InitStage, InitTask } from '@/core/shared/app/initialization';
import { tokenService } from './tokenService';
import { authStore } from './store';
import { authEvents } from './events';

export const authInitialization: InitTask = {
  name: 'auth:token-retrieval',
  
  async execute(): Promise<void> {
    try {
      // Retrieve tokens from secure storage
      const accessToken = await tokenService.getStoredAccessToken();
      const refreshToken = await tokenService.getStoredRefreshToken();
      
      if (accessToken && refreshToken) {
        // Set tokens in memory
        authStore.setTokens(accessToken, refreshToken);
        
        // Validate token without blocking UI render
        // This performs a lightweight validation - not a full API call
        const isTokenValid = tokenService.isTokenValid(accessToken);
        
        if (isTokenValid) {
          authEvents.emit('auth:initialized', { isAuthenticated: true });
        } else {
          // Token exists but is expired - will be refreshed later
          authEvents.emit('auth:initialized', { isAuthenticated: false, needsRefresh: true });
        }
      } else {
        // No tokens found
        authEvents.emit('auth:initialized', { isAuthenticated: false });
      }
    } catch (error) {
      console.error('Failed to initialize auth tokens:', error);
      // Emit event with error but allow initialization to continue
      authEvents.emit('auth:initialized', { isAuthenticated: false, error });
    }
  }
};

// Register with initializer
initializer.registerTask(InitStage.PRE_UI, authInitialization);
```

### Critical Preferences Hydration

User preferences like theme choice (light/dark mode) and language settings directly affect how your UI appears. Loading these preferences during the Pre-UI stage helps prevent jarring visual changes after your app becomes visible.

Imagine a user with dark mode enabled seeing a bright white screen flash briefly before your app switches to dark mode—this creates a poor experience. By loading these critical preferences early, you ensure the UI appears correctly from the first moment.

Less critical preferences (like notification settings or display options) can be loaded later in the [Background stage](/docs/guides/app-initialization/background). Here's how to implement critical preferences hydration:

```typescript
// core/shared/preferences/initialization.ts
import { initializer, InitStage, InitTask } from '@/core/shared/app/initialization';
import { storage } from '@/core/shared/utils/storage';
import { preferencesStore } from './store';

export const criticalPreferencesInit: InitTask = {
  name: 'preferences:critical',
  // Optional dependency on auth - if auth fails, preferences should still load
  dependencies: ['auth:token-retrieval'], 
  
  async execute(): Promise<void> {
    try {
      // Only load critical preferences in Pre-UI stage
      // These are preferences that affect initial rendering
      const criticalPrefs = await Promise.all([
        storage.get('app:theme'),
        storage.get('app:language'),
        storage.get('app:textSize')
      ]);
      
      // Update store with values or defaults
      preferencesStore.setTheme(criticalPrefs[0] || 'system');
      preferencesStore.setLanguage(criticalPrefs[1] || 'en');
      preferencesStore.setTextSize(criticalPrefs[2] || 'medium');
    } catch (error) {
      console.error('Failed to load critical preferences:', error);
      // Continue with defaults
      preferencesStore.setTheme('system');
      preferencesStore.setLanguage('en');
      preferencesStore.setTextSize('medium');
    }
  }
};

// Register with initializer
initializer.registerTask(InitStage.PRE_UI, criticalPreferencesInit);
```

### App Configuration Loading

Load essential configuration that affects how the app should function:

```typescript
// core/shared/config/initialization.ts
import { initializer, InitStage, InitTask } from '@/core/shared/app/initialization';
import { configStore } from './store';
import { publicApi } from '@/core/shared/api/client';

export const appConfigInit: InitTask = {
  name: 'config:app',
  
  async execute(): Promise<void> {
    try {
      // First try to load from local cache
      const cachedConfig = await storage.get('app:config');
      
      if (cachedConfig) {
        // Set cached config immediately
        configStore.setConfig(JSON.parse(cachedConfig));
        
        // Check if cache is still valid
        const lastUpdated = await storage.get('app:config:timestamp');
        const now = Date.now();
        
        // Only use cached config if it's less than 24 hours old
        if (lastUpdated && (now - parseInt(lastUpdated)) < 24 * 60 * 60 * 1000) {
          return; // Use cached config, no need to fetch
        }
      }
      
      // If no valid cache, fetch config but don't block initialization
      // We'll use defaults for now and update once the fetch completes
      this.fetchConfigInBackground();
    } catch (error) {
      console.error('Failed to load app configuration:', error);
      // Continue with default configuration
      configStore.setConfig({
        features: {
          newUserOnboarding: true,
          analytics: true,
          deepLinking: true
        },
        limits: {
          maxUploadSize: 5 * 1024 * 1024, // 5MB
          requestsPerMinute: 60
        }
      });
    }
  },
  
  // Non-blocking fetch that will update config once complete
  private async fetchConfigInBackground(): Promise<void> {
    try {
      // Use a shorter timeout for config fetch
      const config = await publicApi.get('/config/app', { timeout: 5000 });
      
      // Update store with fresh config
      configStore.setConfig(config);
      
      // Cache for future use
      await storage.set('app:config', JSON.stringify(config));
      await storage.set('app:config:timestamp', Date.now().toString());
    } catch (error) {
      console.warn('Failed to fetch fresh configuration:', error);
      // App will continue with cached or default config
    }
  }
};

// Register with initializer
initializer.registerTask(InitStage.PRE_UI, appConfigInit);
```

## Registering Multiple Pre-UI Tasks

When a domain requires multiple initialization tasks, use a centralized registration pattern:

```typescript
// core/domains/[domain]/initialization.ts
import { initializer, InitStage } from '@/core/shared/app/initialization';

// Define all initialization tasks
const taskA = { name: 'domain:taskA', execute: async () => { /* ... */ } };
const taskB = { name: 'domain:taskB', execute: async () => { /* ... */ } };

// Register all Pre-UI tasks
export function registerInitializationTasks() {
  initializer.registerTask(InitStage.PRE_UI, taskA);
  
  // Only add to Pre-UI if absolutely necessary
  // Consider if this can be moved to a later stage
  initializer.registerTask(InitStage.PRE_UI, taskB);
}

// Call this function in the domain's index.ts
```

## Common Challenges

### Managing Dependencies Between Tasks

Tasks in the Pre-UI stage often have dependencies on each other. Use the `dependencies` property to declare these relationships:

```typescript
// core/domains/products/initialization.ts
import { initializer, InitStage, InitTask } from '@/core/shared/app/initialization';

const productCatalogInit: InitTask = {
  name: 'products:catalog-init',
  // This task depends on config being loaded first
  dependencies: ['config:app'],
  
  async execute(): Promise<void> {
    // Implementation that uses configuration
    const config = configStore.getConfig();
    // Initialize catalog based on config
    // ...
  }
};

initializer.registerTask(InitStage.PRE_UI, productCatalogInit);
```

### Handling Initialization Failures

Pre-UI tasks should be resilient to failures and provide fallbacks when possible:

```typescript
// Pattern for resilient initialization tasks
const resilientTask: InitTask = {
  name: 'domain:resilient-task',
  
  async execute(): Promise<void> {
    try {
      // Attempt primary initialization
      await this.primaryInitialization();
    } catch (error) {
      // Log the error
      console.error('Primary initialization failed:', error);
      
      try {
        // Attempt fallback initialization
        await this.fallbackInitialization();
      } catch (fallbackError) {
        // If fallback also fails, use defaults
        console.error('Fallback initialization failed:', fallbackError);
        this.useDefaults();
      }
    }
  },
  
  async primaryInitialization() {
    // Optimal initialization path
  },
  
  async fallbackInitialization() {
    // Alternative initialization strategy
  },
  
  useDefaults() {
    // Set up with default values
  }
};
```

### Timeout Protection

Protect against hanging initialization tasks with timeout wrappers:

```typescript
// core/shared/utils/timeout.ts
export async function withTimeout<T>(
  promise: Promise<T>,
  timeoutMs: number,
  fallback?: () => T | Promise<T>
): Promise<T> {
  let timeoutId: NodeJS.Timeout;
  
  const timeoutPromise = new Promise<never>((_, reject) => {
    timeoutId = setTimeout(() => {
      reject(new Error(`Operation timed out after ${timeoutMs}ms`));
    }, timeoutMs);
  });
  
  try {
    const result = await Promise.race([promise, timeoutPromise]);
    clearTimeout(timeoutId);
    return result;
  } catch (error) {
    clearTimeout(timeoutId);
    if (error.message.includes('timed out') && fallback) {
      return await fallback();
    }
    throw error;
  }
}

// Usage in initialization task
async execute(): Promise<void> {
  await withTimeout(
    this.loadConfiguration(),
    3000, // 3 second timeout
    () => this.useDefaultConfiguration() // Fallback function
  );
}
```

## Performance Considerations

* **(Do ✅) Keep Pre-UI tasks minimal**
  * Only include absolutely critical initialization
  * Consider moving tasks to later stages when possible
  * Measure the impact of each task on startup time

* **(Do ✅) Use caching strategies**
  * Cache responses from previous sessions
  * Use cache-first, update-in-background pattern
  * Set appropriate cache expiration policies

* **(Don't ❌) Perform network requests unnecessarily**
  * Avoid network calls in Pre-UI stage if possible
  * If required, set short timeouts (3-5 seconds)
  * Always have offline fallbacks

* **(Do ✅) Load progressively**
  * Load only what's needed for initial UI
  * Defer loading additional data to later stages
  * Consider staged loading within the Pre-UI tasks themselves

## Practical Examples

### Application Theme Provider Initialization

```typescript
// ui/theme/initialization.ts
import { initializer, InitStage, InitTask } from '@/core/shared/app/initialization';
import { storage } from '@/core/shared/utils/storage';
import { themeStore } from './store';
import { Appearance } from 'react-native';

const themeInitialization: InitTask = {
  name: 'ui:theme-init',
  
  async execute(): Promise<void> {
    try {
      // Get user preference
      const storedTheme = await storage.get('theme:preference');
      
      // Determine theme mode
      if (storedTheme === 'dark' || storedTheme === 'light') {
        // Use explicit user preference
        themeStore.setThemeMode(storedTheme);
      } else if (storedTheme === 'system' || !storedTheme) {
        // Default to system preference
        const deviceTheme = Appearance.getColorScheme() || 'light';
        themeStore.setThemeMode(deviceTheme);
        
        // Set up listener for system theme changes
        this.setupSystemThemeListener();
      }
      
      // Load custom theme if any
      const customTheme = await storage.get('theme:custom');
      if (customTheme) {
        try {
          themeStore.setCustomTheme(JSON.parse(customTheme));
        } catch (parseError) {
          console.error('Failed to parse custom theme:', parseError);
          // Continue with default theme
        }
      }
    } catch (error) {
      console.error('Theme initialization failed:', error);
      // Fall back to light theme
      themeStore.setThemeMode('light');
    }
  },
  
  setupSystemThemeListener() {
    // Subscribe to system theme changes
    const subscription = Appearance.addChangeListener(({ colorScheme }) => {
      if (themeStore.getThemePreference() === 'system') {
        themeStore.setThemeMode(colorScheme || 'light');
      }
    });
    
    // Store subscription for potential cleanup
    themeStore.setAppearanceSubscription(subscription);
  }
};

initializer.registerTask(InitStage.PRE_UI, themeInitialization);
```

### Feature Flags Initialization

```typescript
// core/shared/features/initialization.ts
import { initializer, InitStage, InitTask } from '@/core/shared/app/initialization';
import { storage } from '@/core/shared/utils/storage';
import { featureStore } from './store';
import { publicApi } from '@/core/shared/api/client';

const featureFlagsInit: InitTask = {
  name: 'features:flags-init',
  
  async execute(): Promise<void> {
    try {
      // Try to load cached feature flags first
      const cachedFlags = await storage.get('features:flags');
      
      if (cachedFlags) {
        // Use cached flags immediately
        featureStore.setFeatureFlags(JSON.parse(cachedFlags));
        
        // Check age of cache
        const cacheTimestamp = await storage.get('features:flags:timestamp') || '0';
        const cacheAge = Date.now() - parseInt(cacheTimestamp);
        
        // If cache is fresh enough, don't fetch new flags yet
        if (cacheAge < 60 * 60 * 1000) { // 1 hour
          return;
        }
      }
      
      // Default flags used if no cache or fetch fails
      const defaultFlags = {
        newCheckout: false,
        enhancedSearch: false,
        betaFeatures: false
      };
      
      // Set defaults if no cache was found
      if (!cachedFlags) {
        featureStore.setFeatureFlags(defaultFlags);
      }
      
      // Fetch latest flags in background, don't block initialization
      this.fetchFeatureFlagsInBackground(defaultFlags);
    } catch (error) {
      console.error('Feature flags initialization failed:', error);
      // Set safe defaults
      featureStore.setFeatureFlags({
        newCheckout: false,
        enhancedSearch: false,
        betaFeatures: false
      });
    }
  },
  
  async fetchFeatureFlagsInBackground(defaultFlags) {
    try {
      // Short timeout for feature flags
      const flags = await publicApi.get('/config/features', { 
        timeout: 5000 
      });
      
      // Update store
      featureStore.setFeatureFlags({
        ...defaultFlags,
        ...flags
      });
      
      // Cache for future use
      await storage.set('features:flags', JSON.stringify(flags));
      await storage.set('features:flags:timestamp', Date.now().toString());
    } catch (error) {
      console.warn('Failed to fetch latest feature flags:', error);
      // App will continue with cached or default flags
    }
  }
};

initializer.registerTask(InitStage.PRE_UI, featureFlagsInit);
```

## Migration Considerations

When migrating from older initialization patterns to our staged initialization approach for Pre-UI tasks, consider these helpful guidelines:

### From Direct Initialization to Task-Based Approach

If you're currently using direct initialization in your app entry file like this:

```typescript
// Old approach in App.tsx
const App = () => {
  const [isReady, setIsReady] = useState(false);
  
  useEffect(() => {
    async function initialize() {
      try {
        // Direct initialization calls
        await loadAuthTokens();
        await loadConfiguration();
        await setupTheme();
        // Show UI
        setIsReady(true);
      } catch (error) {
        console.error('Initialization failed', error);
      }
    }
    initialize();
  }, []);
  
  if (!isReady) return null;
  
  return <MainApp />;
};
```

You can enhance this by:

1. Converting each initialization function to a task that follows the `InitTask` interface
2. Registering these tasks with the initializer for the Pre-UI stage
3. Using the centralizer initializer's flow management instead of custom state

This approach provides better error handling, performance tracking, and a clearer separation of concerns.

### Ensuring Backward Compatibility

When implementing the new initialization system:

* Consider wrapping existing initialization logic in tasks temporarily during migration
* Keep fallbacks for essential functionality in case initialization fails
* Add detailed logging to help debug any issues during the transition

The task-based approach is particularly helpful for team development as it creates clear boundaries for initialization responsibilities.

## Summary

The Pre-UI initialization stage forms the foundation of your app's startup experience. By thoughtfully implementing this stage, you'll significantly improve both actual and perceived performance for your users.

### Key Takeaways

* **Strategic Task Placement**: Be deliberate about what you include in the Pre-UI stage. Every task here directly impacts startup time.

* **User Experience Focus**: The work done in this stage should enable a smooth, coherent experience from the moment the UI appears.

* **Staged Approach Benefits**: By carefully dividing initialization between the Pre-UI stage and later stages like [Initial UI](/docs/guides/app-initialization/initial-ui), [Background](/docs/guides/app-initialization/background), and [Finalization](/docs/guides/app-initialization/finalization), you create a responsive app that feels fast even while work continues in the background.

### Best Practices

* **Keep Pre-UI tasks minimal and fast** - Ruthlessly evaluate what truly needs to happen before showing UI
* **Use caching aggressively** - Store and reuse data to avoid network calls during startup
* **Provide fallbacks for everything** - Ensure your app can still function if initialization tasks fail
* **Measure initialization performance** - Use metrics to identify bottlenecks
* **Move tasks to later stages whenever possible** - If a task doesn't need to block UI rendering, defer it

By applying these patterns, you'll create a more responsive application that delights users with its speed and reliability.

## Related Documents

### Core Initialization Documentation

* [App Initialization Architecture](/docs/architecture/app-initialization) - Overview of the complete initialization architecture
* [App Initialization Guides](/docs/guides/app-initialization) - Index of all initialization guides

### Other Initialization Stages

* [Initial UI Rendering Guide](/docs/guides/app-initialization/initial-ui) - Next stage after Pre-UI completion
* [Background Initialization Guide](/docs/guides/app-initialization/background) - Parallel tasks execution stage
* [Finalization Stage Guide](/docs/guides/app-initialization/finalization) - Final initialization stage

### Related Implementation Guides

* [Splash Screens Guide](/docs/ui-development/splash-screens) - Detailed implementation of splash screens during initialization
* [Authentication Architecture](/docs/api/authentication) - Authentication tokens and state management
* [Performance Optimization Guide](/docs/performance/app-startup) - Optimizing app startup performance


# UTA Implementation Guides: Initial UI Rendering Guide
URL: https://dev.updatetheapp.com/docs/guides/app-initialization/initial-ui-rendering-guide
Documentation: https://dev.updatetheapp.com/docs/guides/app-initialization/initial-ui-rendering-guide

Implementation patterns for the Initial UI rendering stage in the application bootstrap process.
        
***

title: Initial UI Rendering Guide
description: Implementation patterns for the Initial UI rendering stage in the application bootstrap process.
-------------------------------------------------------------------------------------------------------------

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';

# Initial UI Rendering Guide

## Overview

The Initial UI rendering stage is the second phase of the application bootstrap process, occurring immediately after the [Pre-UI stage](/docs/guides/app-initialization/pre-ui) completes. This crucial stage focuses on rendering the initial UI shell and providing immediate visual feedback to users while background initialization continues. This guide provides implementation patterns for effectively managing the Initial UI rendering stage.

## Quick Start

To implement the Initial UI rendering stage:

1. Register tasks with the initializer:
   ```typescript
   import { initializer, InitStage } from '@/core/shared/app/initialization';

   // Register an Initial UI stage task
   initializer.registerTask(InitStage.INITIAL_UI, {
     name: 'navigation:setup',
     execute: async () => {
       // Set up navigation listeners, deep links, etc.
       await setupNavigationConfiguration();
     }
   });
   ```

2. Implement a conditional rendering pattern in your main component:
   ```typescript
   function AppContent() {
     const { initialized, currentStage } = useInitialization();
     
     // Show splash screen during Pre-UI initialization
     if (currentStage === InitStage.PRE_UI || !currentStage) {
       return <SplashScreen />;
     }
     
     // Show loading screen during Initial UI and Background stages
     if (!initialized) {
       return <LoadingScreen stage={currentStage} />;
     }
     
     // Fully initialized - show main app content
     return <NavigationContainer>{/* App navigation */}</NavigationContainer>;
   }
   ```

3. Create skeleton screens or loading placeholders that appear during this stage

## When To Use

Add initialization tasks to the Initial UI stage when they:

* **Involve UI rendering**: Components and screens that make up the initial app shell
* **Determine navigation flow**: Logic that decides which screens to show based on auth state (using data from the [Pre-UI stage](/docs/guides/app-initialization/pre-ui))
* **Create loading indicators**: Skeleton screens, progress indicators, and placeholders
* **Set up navigation**: Route configuration and navigation state initialization

The Initial UI stage should focus on tasks that create a responsive, interactive shell that users can see while more complex background operations complete in the [Background stage](/docs/guides/app-initialization/background).

## Implementation Patterns

<Mermaid
  chart={`
flowchart TD
  PreUI[Pre-UI Stage Complete] --> SplashToUI[Splash Screen Transition]
  SplashToUI --> InitialUI[Initial UI Stage]
  
  subgraph InitialUI[Initial UI Rendering Stage]
      AppShell[App Shell Rendering]
      NavSetup[Navigation Setup]
      AuthRoutes[Auth-based Routing]
      LoadingUI[Loading Indicators]
  end
  
  InitialUI --> Background[Background Stage]
  
  style SplashToUI fill:#bbf,stroke:#333,stroke-width:2px
  style InitialUI fill:#f9f,stroke:#333,stroke-width:2px
`}
/>

As shown in the diagram, the Initial UI stage follows the [Pre-UI stage](/docs/guides/app-initialization/pre-ui) and transitions to the [Background stage](/docs/guides/app-initialization/background) once the initial user interface is rendered.

### Navigation Integration

<Tabs items={["Expo Router", "React Navigation"]}>
  <Tab>
    ```typescript
    // app/(app)/_layout.tsx
    import { Redirect, Stack } from 'expo-router';
    import { useEffect } from 'react';
    import { initializer, InitStage } from '@/core/shared/app/initialization';
    import { useAuthStore } from '@/core/domains/auth/store';
    import { useInitialization } from '@/core/shared/app/initialization';
    import { LoadingScreen } from '@/ui/screens/LoadingScreen';

    export default function AppLayout() {
      const { initialized, currentStage } = useInitialization();
      const { isAuthenticated } = useAuthStore();
      
      // Register navigation initialization as an Initial UI task
      useEffect(() => {
        const navigationTask = {
          name: 'navigation:setup',
          execute: async () => {
            // Setup navigation listeners, deep links, etc.
          }
        };
        
        initializer.registerTask(InitStage.INITIAL_UI, navigationTask);
      }, []);
      
      // Show loading while initialization is in progress
      if (!initialized && currentStage !== InitStage.PRE_UI) {
        return <LoadingScreen stage={currentStage} />;
      }
      
      // Handle authentication-based routing
      if (!isAuthenticated) {
        return <Redirect href="/auth" />;
      }
      
      return <Stack />;
    }
    ```
  </Tab>

  <Tab>
    ```typescript
    // navigation/AppNavigator.tsx
    import React, { useEffect } from 'react';
    import { createStackNavigator } from '@react-navigation/stack';
    import { initializer, InitStage } from '@/core/shared/app/initialization';
    import { useAuthStore } from '@/core/domains/auth/store';
    import { useInitialization } from '@/core/shared/app/initialization';
    import { LoadingScreen } from '@/ui/screens/LoadingScreen';
    import { MainNavigator } from './MainNavigator';
    import { AuthNavigator } from './AuthNavigator';

    const Stack = createStackNavigator();

    export function AppNavigator() {
      const { initialized, currentStage } = useInitialization();
      const { isAuthenticated } = useAuthStore();
      
      // Register navigation initialization as an Initial UI task
      useEffect(() => {
        const navigationTask = {
          name: 'navigation:setup',
          execute: async () => {
            // Setup navigation listeners, deep links, etc.
          }
        };
        
        initializer.registerTask(InitStage.INITIAL_UI, navigationTask);
      }, []);
      
      // Show loading while initialization is in progress
      if (!initialized && currentStage !== InitStage.PRE_UI) {
        return <LoadingScreen stage={currentStage} />;
      }
      
      return (
        <Stack.Navigator headerMode="none">
          {isAuthenticated ? (
            <Stack.Screen name="Main" component={MainNavigator} />
          ) : (
            <Stack.Screen name="Auth" component={AuthNavigator} />
          )}
        </Stack.Navigator>
      );
    }
    ```
  </Tab>
</Tabs>

### App Shell Rendering

The app shell provides the initial framework for your application:

```typescript
// App.tsx
import React, { useEffect } from 'react';
import { SafeAreaProvider } from 'react-native-safe-area-context';
import { QueryClientProvider } from '@tanstack/react-query';
import { StatusBar } from 'react-native';
import { ThemeProvider } from './ui/theme/ThemeProvider';
import { InitializationProvider } from '@/core/shared/app/initialization/InitializationProvider';
import { AppNavigator } from './navigation/AppNavigator';
import { SplashScreen } from './ui/screens/SplashScreen';
import { useInitialization } from '@/core/shared/app/initialization';
import { queryClient } from '@/core/shared/query/queryClient';

export default function App() {
  // Hide the native splash screen once our JS is running
  useEffect(() => {
    // This assumes you're using a splash screen library like 'react-native-splash-screen'
    SplashScreen.hide();
  }, []);

  return (
    <SafeAreaProvider>
      <StatusBar barStyle="dark-content" backgroundColor="transparent" translucent />
      <QueryClientProvider client={queryClient}>
        <ThemeProvider>
          <InitializationProvider>
            <AppContent />
          </InitializationProvider>
        </ThemeProvider>
      </QueryClientProvider>
    </SafeAreaProvider>
  );
}

function AppContent() {
  const { initialized, currentStage, error } = useInitialization();
  
  // Show custom splash screen while Pre-UI initialization completes
  if (currentStage === 'pre-ui' || !currentStage) {
    return <SplashScreen />;
  }
  
  // Once Pre-UI is done, show the AppNavigator which handles further stages
  return <AppNavigator />;
}
```

### Navigation Setup Based on Auth State

Configure navigation based on authentication state determined during Pre-UI:

```typescript
// navigation/AppNavigator.tsx
import React from 'react';
import { NavigationContainer } from '@react-navigation/native';
import { createNativeStackNavigator } from '@react-navigation/native-stack';
import { useInitialization } from '@/core/shared/app/initialization';
import { useAuthStore } from '@/core/domains/auth/store';
import { AuthNavigator } from './AuthNavigator';
import { MainNavigator } from './MainNavigator';
import { OnboardingNavigator } from './OnboardingNavigator';
import { LoadingScreen } from '@/ui/screens/LoadingScreen';
import { ErrorScreen } from '@/ui/screens/ErrorScreen';

const RootStack = createNativeStackNavigator();

export function AppNavigator() {
  const { initialized, currentStage, error } = useInitialization();
  const { isAuthenticated, hasCompletedOnboarding } = useAuthStore();
  
  // Handle initialization errors
  if (error) {
    return <ErrorScreen error={error} />;
  }
  
  // Register this navigator as an initialization task for the Initial UI stage
  useRegisterInitialUITask();
  
  return (
    <NavigationContainer>
      <RootStack.Navigator screenOptions={{ headerShown: false }}>
        {!initialized ? (
          // Show loading screen during background initialization
          <RootStack.Screen name="Loading" component={LoadingScreen} />
        ) : isAuthenticated ? (
          // User is authenticated
          hasCompletedOnboarding ? (
            // Show main app
            <RootStack.Screen name="Main" component={MainNavigator} />
          ) : (
            // Show onboarding
            <RootStack.Screen name="Onboarding" component={OnboardingNavigator} />
          )
        ) : (
          // User is not authenticated
          <RootStack.Screen name="Auth" component={AuthNavigator} />
        )}
      </RootStack.Navigator>
    </NavigationContainer>
  );
}

// Register navigation initialization as a task
function useRegisterInitialUITask() {
  const { initializer, InitStage } = useInitialization();
  
  useEffect(() => {
    const navigationTask = {
      name: 'navigation:setup',
      execute: async () => {
        // Set up any necessary navigation listeners
        // Configure deep link handling
        // Initialize navigation state persistence
      }
    };
    
    initializer.registerTask(InitStage.INITIAL_UI, navigationTask);
  }, []);
}
```

### Progressive Loading UI

Create adaptive loading screens that show real-time initialization progress:

```typescript
// ui/screens/LoadingScreen.tsx
import React from 'react';
import { View, Text, ActivityIndicator, StyleSheet } from 'react-native';
import { useInitialization } from '@/core/shared/app/initialization';
import { useTheme } from '@/ui/theme/ThemeProvider';
import { ProgressBar } from '@/ui/components/ProgressBar';
import { StatusMessage } from '@/ui/components/StatusMessage';

export function LoadingScreen() {
  const { currentStage, progress, statusMessage } = useInitialization();
  const theme = useTheme();
  
  return (
    <View style={[styles.container, { backgroundColor: theme.colors.background }]}>
      <Text style={[styles.title, { color: theme.colors.text }]}>
        {getLoadingTitle(currentStage)}
      </Text>
      
      <ActivityIndicator size="large" color={theme.colors.primary} />
      
      {progress !== undefined && (
        <ProgressBar 
          progress={progress} 
          style={styles.progressBar}
          color={theme.colors.primary}
        />
      )}
      
      {statusMessage && (
        <StatusMessage 
          message={statusMessage} 
          style={styles.statusMessage}
          color={theme.colors.secondary}
        />
      )}
    </View>
  );
}

function getLoadingTitle(stage) {
  switch (stage) {
    case 'initial-ui':
      return 'Setting things up...';
    case 'background':
      return 'Almost ready...';
    case 'finalization':
      return 'Finishing up...';
    default:
      return 'Loading...';
  }
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    justifyContent: 'center',
    alignItems: 'center',
    padding: 20,
  },
  title: {
    fontSize: 18,
    fontWeight: '600',
    marginBottom: 20,
  },
  progressBar: {
    width: '80%',
    height: 6,
    borderRadius: 3,
    marginTop: 30,
    marginBottom: 10,
  },
  statusMessage: {
    marginTop: 20,
    textAlign: 'center',
  },
});
```

### Skeleton Screens for Content

Use skeleton screens to provide immediate visual structure while data loads:

```typescript
// features/product-catalog/screens/ProductListScreen.tsx
import React from 'react';
import { View, FlatList, StyleSheet } from 'react-native';
import { useInitialization } from '@/core/shared/app/initialization';
import { ProductCard } from '../components/ProductCard';
import { ProductCardSkeleton } from '../components/ProductCardSkeleton';
import { useProducts } from '@/core/domains/products/hooks';

export function ProductListScreen() {
  const { initialized } = useInitialization();
  const { data: products, isLoading } = useProducts();
  
  // Show skeletons during initialization or while products are loading
  const showSkeletons = !initialized || isLoading;
  
  // Generate placeholder data for skeletons
  const skeletonData = Array(6).fill({ id: 'skeleton' });
  
  return (
    <View style={styles.container}>
      <FlatList
        data={showSkeletons ? skeletonData : products}
        renderItem={({ item }) => 
          showSkeletons ? (
            <ProductCardSkeleton />
          ) : (
            <ProductCard product={item} />
          )
        }
        numColumns={2}
        keyExtractor={(item) => item.id}
        contentContainerStyle={styles.list}
      />
    </View>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
  },
  list: {
    padding: 16,
  },
});
```

### Initial UI Stage Registration

Register the Initial UI stage initialization tasks:

```typescript
// core/shared/app/initialization/ui-tasks.ts
import { initializer, InitStage, InitTask } from './initializer';
import { navigationService } from '@/navigation/navigationService';
import { navigationEvents } from '@/navigation/events';

// Task to initialize navigation
const navigationInitTask: InitTask = {
  name: 'navigation:init',
  
  async execute(): Promise<void> {
    try {
      // Initialize navigation service
      navigationService.initialize();
      
      // Restore saved navigation state if available
      await navigationService.restoreNavigationState();
      
      // Register navigation state persistence
      navigationService.setupStatePersistence();
      
      // Notify that navigation is ready
      navigationEvents.emit('navigation:ready');
    } catch (error) {
      console.error('Navigation initialization failed:', error);
      // Continue with default navigation configuration
      navigationService.resetToDefaultState();
    }
  }
};

// Task to prepare layout animation settings
const layoutAnimationsTask: InitTask = {
  name: 'ui:animations',
  
  async execute(): Promise<void> {
    try {
      // Enable LayoutAnimation for smoother transitions
      if (Platform.OS === 'android') {
        UIManager.setLayoutAnimationEnabledExperimental(true);
      }
      
      // Set up default animation configurations
      LayoutAnimation.configureNext(LayoutAnimation.Presets.easeInEaseOut);
    } catch (error) {
      console.error('Layout animations setup failed:', error);
      // Continue without animation configuration
    }
  }
};

// Register all Initial UI stage tasks
export function registerInitialUITasks() {
  initializer.registerTask(InitStage.INITIAL_UI, navigationInitTask);
  initializer.registerTask(InitStage.INITIAL_UI, layoutAnimationsTask);
}

// Call this function in the app's initialization sequence
```

## Common Challenges

### Navigation State Restoration

Properly restore navigation state during the Initial UI stage:

```typescript
// navigation/navigationService.ts
import AsyncStorage from '@react-native-async-storage/async-storage';
import { NavigationState } from '@react-navigation/native';

class NavigationService {
  private _navigator: NavigationContainerRef | null = null;
  private _isReady: boolean = false;
  
  initialize() {
    this._isReady = true;
  }
  
  setNavigator(navigator: NavigationContainerRef) {
    this._navigator = navigator;
  }
  
  async restoreNavigationState(): Promise<NavigationState | undefined> {
    try {
      const savedStateString = await AsyncStorage.getItem('navigation:state');
      
      if (savedStateString) {
        // Parse the saved state
        const state = JSON.parse(savedStateString);
        return state as NavigationState;
      }
      
      return undefined;
    } catch (error) {
      console.error('Failed to restore navigation state:', error);
      return undefined;
    }
  }
  
  setupStatePersistence() {
    if (!this._navigator) return;
    
    // Save navigation state on state change
    this._navigator.addListener('state', (e) => {
      const state = e.data.state;
      this.persistNavigationState(state);
    });
  }
  
  async persistNavigationState(state: NavigationState) {
    try {
      await AsyncStorage.setItem('navigation:state', JSON.stringify(state));
    } catch (error) {
      console.error('Failed to persist navigation state:', error);
    }
  }
  
  resetToDefaultState() {
    if (this._navigator && this._isReady) {
      this._navigator.resetRoot({
        index: 0,
        routes: [{ name: 'Auth' }],
      });
    }
  }
  
  // Additional navigation helper methods
}

export const navigationService = new NavigationService();
```

### Handling Auth State Changes During Initial UI

React to authentication state changes during the Initial UI stage:

```typescript
// core/domains/auth/initialization/navigation-handler.ts
import { initializer, InitStage, InitTask } from '@/core/shared/app/initialization';
import { authEvents } from '@/core/domains/auth/events';
import { navigationService } from '@/navigation/navigationService';

const authNavigationHandlerTask: InitTask = {
  name: 'auth:navigation-handler',
  dependencies: ['navigation:init'], // Depends on navigation being initialized
  
  async execute(): Promise<void> {
    // Set up auth state change listener
    authEvents.on('auth:stateChanged', (authState) => {
      if (authState.isAuthenticated) {
        // User logged in
        if (authState.isNewUser) {
          // New user - navigate to onboarding
          navigationService.navigate('Onboarding');
        } else {
          // Existing user - navigate to main flow
          navigationService.navigate('Main');
        }
      } else {
        // User logged out - navigate to auth flow
        navigationService.navigate('Auth');
      }
    });
    
    // Handle session expiration
    authEvents.on('auth:sessionExpired', () => {
      // Show session expired dialog and navigate to login
      navigationService.navigate('Auth', {
        screen: 'Login',
        params: { showSessionExpired: true }
      });
    });
  }
};

// Register task
initializer.registerTask(InitStage.INITIAL_UI, authNavigationHandlerTask);
```

### Transitioning Between Loading States

Create smooth transitions between different loading states:

```typescript
// ui/components/LoadingTransition.tsx
import React, { useEffect, useState } from 'react';
import { Animated, StyleSheet, View } from 'react-native';
import { useInitialization } from '@/core/shared/app/initialization';

interface LoadingTransitionProps {
  children: React.ReactNode;
  fallback: React.ReactNode;
}

export function LoadingTransition({ children, fallback }: LoadingTransitionProps) {
  const { initialized, currentStage } = useInitialization();
  const [showChildren, setShowChildren] = useState(false);
  const opacity = useState(new Animated.Value(0))[0];
  
  useEffect(() => {
    if (initialized) {
      // Delay showing children to allow for smooth transition
      const timer = setTimeout(() => {
        setShowChildren(true);
        
        Animated.timing(opacity, {
          toValue: 1,
          duration: 300,
          useNativeDriver: true,
        }).start();
      }, 150);
      
      return () => clearTimeout(timer);
    }
  }, [initialized, opacity]);
  
  if (!showChildren) {
    return <View style={styles.container}>{fallback}</View>;
  }
  
  return (
    <Animated.View style={[styles.container, { opacity }]}>
      {children}
    </Animated.View>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
  },
});

// Usage example:
// <LoadingTransition fallback={<SkeletonScreen />}>
//   <ProductListScreen />
// </LoadingTransition>
```

## Performance Considerations

* **(Do ✅) Prioritize perceived performance**
  * Show the UI shell as quickly as possible
  * Use skeleton screens instead of spinners
  * Animate transitions to mask loading times

* **(Do ✅) Defer non-essential UI elements**
  * Render critical navigation components first
  * Use placeholders for content that requires data fetching
  * Load complex UI elements progressively

* **(Don't ❌) Block the UI thread**
  * Avoid synchronous operations in render methods
  * Keep initialization logic off the main thread
  * Break up heavy operations into smaller chunks

* **(Do ✅) Measure and optimize render times**
  * Track time-to-interactive metrics
  * Reduce component tree depth when possible
  * Use React.memo and useMemo appropriately

## Practical Examples

### Auth-Aware Navigation Container

```typescript
// navigation/AuthAwareNavigationContainer.tsx
import React, { useRef, useState, useEffect } from 'react';
import { NavigationContainer, NavigationState } from '@react-navigation/native';
import { useAuthStore } from '@/core/domains/auth/store';
import { navigationService } from './navigationService';
import { useInitialization } from '@/core/shared/app/initialization';
import { linking } from './linking'; // Deep linking configuration

export function AuthAwareNavigationContainer({ children }) {
  const navigationRef = useRef(null);
  const { isAuthenticated } = useAuthStore();
  const { currentStage } = useInitialization();
  const [initialState, setInitialState] = useState(undefined);
  
  // Register with navigation service
  useEffect(() => {
    if (navigationRef.current) {
      navigationService.setNavigator(navigationRef.current);
    }
  }, [navigationRef.current]);
  
  // Load saved navigation state
  useEffect(() => {
    const loadNavState = async () => {
      const savedState = await navigationService.restoreNavigationState();
      if (savedState) {
        setInitialState(savedState);
      }
    };
    
    loadNavState();
  }, []);
  
  // Handle state changes
  const handleStateChange = (state) => {
    if (state) {
      // Track navigation analytics
      const currentRouteName = getActiveRouteName(state);
      analyticsService.trackScreenView(currentRouteName);
    }
  };
  
  return (
    <NavigationContainer
      ref={navigationRef}
      initialState={initialState}
      onStateChange={handleStateChange}
      linking={linking}
      theme={colorScheme === 'dark' ? DarkTheme : DefaultTheme}
    >
      {children}
    </NavigationContainer>
  );
}

// Helper to get the active route name
function getActiveRouteName(state) {
  const route = state.routes[state.index];
  
  if (route.state) {
    // Dive into nested navigators
    return getActiveRouteName(route.state);
  }
  
  return route.name;
}
```

### Feature-Specific Loading Strategy

```typescript
// features/orders/screens/OrdersScreen.tsx
import React, { useEffect } from 'react';
import { View, Text, FlatList, StyleSheet } from 'react-native';
import { useInitialization } from '@/core/shared/app/initialization';
import { useOrders } from '@/core/domains/orders/hooks';
import { OrderItem } from '../components/OrderItem';
import { OrderItemSkeleton } from '../components/OrderItemSkeleton';
import { EmptyOrdersView } from '../components/EmptyOrdersView';
import { ErrorView } from '@/ui/components/ErrorView';

export function OrdersScreen() {
  const { initialized } = useInitialization();
  const { 
    data: orders, 
    isLoading, 
    isError, 
    error, 
    refetch 
  } = useOrders();
  
  // Register feature-specific initialization
  useRegisterFeatureInitialization();
  
  // Determine what to show
  const showSkeletons = !initialized || isLoading;
  const showEmptyState = initialized && !isLoading && (!orders || orders.length === 0);
  const showError = initialized && isError;
  
  if (showError) {
    return (
      <ErrorView 
        error={error}
        onRetry={refetch}
        message="Could not load your orders"
      />
    );
  }
  
  return (
    <View style={styles.container}>
      {showEmptyState ? (
        <EmptyOrdersView />
      ) : (
        <FlatList
          data={showSkeletons ? Array(5).fill({ id: 'skeleton' }) : orders}
          renderItem={({ item }) => 
            showSkeletons ? (
              <OrderItemSkeleton />
            ) : (
              <OrderItem order={item} />
            )
          }
          keyExtractor={(item) => item.id}
          contentContainerStyle={styles.list}
        />
      )}
    </View>
  );
}

// Register feature-specific initialization
function useRegisterFeatureInitialization() {
  const { initializer, InitStage } = useInitialization();
  
  useEffect(() => {
    // Only register once
    if (initialized) return;
    
    const ordersInitTask = {
      name: 'features:orders-init',
      execute: async () => {
        // Prepare orders feature (set up event listeners, etc.)
        // This happens during Initial UI stage but doesn't block rendering
      }
    };
    
    initializer.registerTask(InitStage.INITIAL_UI, ordersInitTask);
    
    // More data-intensive tasks should be deferred to the Background stage
    // See the Background Initialization Guide for details:
    // /docs/guides/app-initialization/background
  }, [initialized]);
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
  },
  list: {
    padding: 16,
  },
});
```

## Migration Considerations

When migrating from traditional loading approaches to our staged initialization pattern for Initial UI rendering, consider these helpful strategies:

### From Global Loading States to Staged Loading

Many apps traditionally use a global loading pattern like this:

```typescript
// Traditional approach
const MainScreen = () => {
  const [isLoading, setIsLoading] = useState(true);
  const [data, setData] = useState([]);
  
  useEffect(() => {
    async function loadData() {
      try {
        // Load everything at once
        await setupNavigation();
        const result = await fetchInitialData();
        setData(result);
        setIsLoading(false);
      } catch (error) {
        console.error('Failed to load', error);
        setIsLoading(false); // Still hide loading on error
      }
    }
    loadData();
  }, []);
  
  if (isLoading) {
    return <LoadingScreen />;
  }
  
  return <DataList data={data} />;
};
```

You can enhance this by:

1. Separating UI rendering from data loading
2. Using the `InitStage.INITIAL_UI` for navigation and essential UI setup
3. Deferring data fetching to the Background stage
4. Implementing skeleton screens or placeholders during the transition

### Progressive Enhancement Pattern

A good migration strategy involves progressive enhancement:

1. First render the UI shell with skeleton placeholders during the Initial UI stage
2. Then populate data gradually as Background tasks complete
3. Finally, enable full interactivity after all initialization is complete

This approach significantly improves perceived performance compared to blocking renders until all data is available.

### Component-Level Migration

You can migrate component by component:

```typescript
// Migration approach for a specific feature
const ProductScreen = () => {
  const { initialized, currentStage } = useInitialization();
  const { data, isLoading } = useProducts();
  
  // Register initialization once
  useEffect(() => {
    initializer.registerTask(InitStage.INITIAL_UI, {
      name: 'products:ui-setup',
      execute: async () => {
        // Only essential UI setup here
        setupProductScreenLayout();
      }
    });
    
    initializer.registerTask(InitStage.BACKGROUND, {
      name: 'products:data-fetch',
      execute: async () => {
        // Move data fetching to background
        queryClient.prefetchQuery(productQueryKeys.list);
      }
    });
  }, []);
  
  // Determine what to show based on initialization state
  const showSkeletons = currentStage === InitStage.INITIAL_UI || 
                        (currentStage === InitStage.BACKGROUND && isLoading);
  
  return (
    <Screen>
      {showSkeletons ? <ProductSkeleton /> : <ProductList data={data} />}
    </Screen>
  );
};
```

This progressive approach lets you adopt the new initialization pattern one feature at a time.

## Summary

The Initial UI rendering stage is focused on providing immediate visual feedback to users while the application continues to initialize background services. By following the patterns in this guide, you can create a smooth, responsive user experience from the moment your app launches.

Once the Initial UI stage completes, your app can proceed to the [Background stage](/docs/guides/app-initialization/background) for non-critical tasks, and finally the [Finalization stage](/docs/guides/app-initialization/finalization) to complete the initialization process.

Key principles to remember:

* Focus on perceived performance with immediate visual feedback
* Use skeleton screens and placeholders for content that's still loading
* Set up navigation and routing based on authentication state
* Register initialization tasks specific to UI rendering
* Create smooth transitions between loading and loaded states

## Related Documents

### Core Initialization Documentation

* [App Initialization Architecture](/docs/architecture/app-initialization) - Overview of the complete initialization architecture
* [App Initialization Guides](/docs/guides/app-initialization) - Index of all initialization guides

### Other Initialization Stages

* [Pre-UI Initialization Guide](/docs/guides/app-initialization/pre-ui) - Stage before Initial UI rendering
* [Background Initialization Guide](/docs/guides/app-initialization/background) - Next stage after Initial UI completion
* [Finalization Stage Guide](/docs/guides/app-initialization/finalization) - Final initialization stage

### Related Implementation Guides

* [Navigation Architecture](/docs/architecture/navigation-system) - Navigation system integration with initialization
* [Performance Optimization Guide](/docs/performance/app-startup) - Optimizing app startup performance
* [Skeleton Screens Implementation](/docs/ui-components/skeleton-screens) - Creating loading placeholders during initialization


# UTA Implementation Guides: Background Initialization Guide
URL: https://dev.updatetheapp.com/docs/guides/app-initialization/background-initialization-guide
Documentation: https://dev.updatetheapp.com/docs/guides/app-initialization/background-initialization-guide

Implementation patterns for the Background initialization stage in the application bootstrap process.
        
***

title: Background Initialization Guide
description: Implementation patterns for the Background initialization stage in the application bootstrap process.
------------------------------------------------------------------------------------------------------------------

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';

# Background Initialization Guide

## Overview

The Background initialization stage is the third phase in the application bootstrap process, executing non-blocking tasks in parallel after the [Initial UI](/docs/guides/app-initialization/initial-ui) has been rendered. This stage is dedicated to operations that are important but not critical for the first visual rendering - such as data prefetching, secondary store hydration, and non-essential service initialization. This guide provides implementation patterns for efficiently managing background initialization.

## Quick Start

To implement the Background initialization stage:

1. Register tasks with the initializer:
   ```typescript
   import { initializer, InitStage } from '@/core/shared/app/initialization';

   // Register a Background stage task
   initializer.registerTask(InitStage.BACKGROUND, {
     name: 'data:prefetch-common',
     priority: 'high', // Optional priority (high, normal, low)
     critical: false, // Not critical - won't block app if it fails
     execute: async () => {
       // Prefetch commonly needed data
       await Promise.all([
         queryClient.prefetchQuery(productQueryKeys.featured),
         queryClient.prefetchQuery(categoryQueryKeys.list)
       ]);
     }
   });
   ```

2. After the Initial UI rendering is complete, execute Background tasks in parallel:
   ```typescript
   // In your initialization controller
   async function continueInitialization() {
     // Initial UI stage has already completed
     
     // Execute Background tasks (non-blocking, parallel)
     initializer.executeParallelStage(InitStage.BACKGROUND)
       .then(() => {
         // Background tasks completed, proceed to finalization
         initializer.executeStage(InitStage.FINALIZATION);
       })
       .catch(error => {
         console.warn('Some background tasks failed:', error);
         // Still proceed to finalization since background tasks are non-critical
         initializer.executeStage(InitStage.FINALIZATION);
       });
   }
   ```

3. Show subtle loading indicators during this stage without blocking user interaction

## When To Use

Add initialization tasks to the Background stage when they:

* **Require network operations**: API prefetching, data synchronization
* **Set up non-critical services**: Analytics, monitoring, push notifications
* **Hydrate secondary stores**: Non-essential app state (critical state should be loaded in the [Pre-UI stage](/docs/guides/app-initialization/pre-ui))
* **Perform expensive calculations**: Operations that would block the UI thread
* **Prepare cached resources**: Image preloading, data processing

The Background stage is ideal for tasks that enhance the user experience but aren't required for the initial UI rendering. By deferring these tasks until after the [Initial UI rendering](/docs/guides/app-initialization/initial-ui), you can significantly improve perceived performance.

## Implementation Patterns

<Mermaid
  chart={`
flowchart TD
  InitialUI[Initial UI Stage Complete] --> Background[Background Stage]
  
  subgraph Background[Background Initialization Stage]
      direction LR
      Prefetch[Data Prefetching]
      Services[Service Initialization]
      Analytics[Analytics Setup]
      SyncState[State Synchronization]
  end
  
  Background --> Finalization[Finalization Stage]
  
  style Background fill:#bfb,stroke:#333,stroke-width:2px
`}
/>

The Background stage follows the [Initial UI rendering stage](/docs/guides/app-initialization/initial-ui) and precedes the [Finalization stage](/docs/guides/app-initialization/finalization). Once all Background tasks complete, the app proceeds to Finalization to complete the initialization process.

### Feature-Specific Background Initialization

Regardless of which navigation system you use, feature-specific initialization can be implemented with a common pattern. This builds upon the navigation setup completed during the [Initial UI stage](/docs/guides/app-initialization/initial-ui):

<Tabs items={["Expo Router", "React Navigation"]}>
  <Tab>
    ```typescript
    // app/(app)/products.tsx (Expo Router)
    import { useEffect } from 'react';
    import { initializer, InitStage } from '@/core/shared/app/initialization';
    import { useInitialization } from '@/core/shared/app/initialization';
    import { View, Text } from 'react-native';
    import { ProductList } from '@/features/products/components/ProductList';
    import { LoadingOverlay } from '@/ui/components/LoadingOverlay';

    export default function ProductsScreen() {
      const { initialized, currentStage } = useInitialization();
      
      // Register feature-specific initialization task
      useEffect(() => {
        const productInitTask = {
          name: 'features:products-init',
          stage: InitStage.BACKGROUND,
          priority: 'high',
          execute: async () => {
            // Prefetch products, load category data, etc.
            await productService.prefetchFeaturedProducts();
          }
        };
        
        initializer.registerTask(InitStage.BACKGROUND, productInitTask);
      }, []);
      
      return (
        <View style={{ flex: 1 }}>
          <ProductList />
          
          {/* Show loading overlay if not fully initialized */}
          {!initialized && currentStage === InitStage.BACKGROUND && (
            <LoadingOverlay message="Loading products..." />
          )}
        </View>
      );
    }
    ```
  </Tab>

  <Tab>
    ```typescript
    // features/products/screens/ProductsScreen.tsx (React Navigation)
    import React, { useEffect } from 'react';
    import { initializer, InitStage } from '@/core/shared/app/initialization';
    import { useInitialization } from '@/core/shared/app/initialization';
    import { View, Text } from 'react-native';
    import { ProductList } from '../components/ProductList';
    import { LoadingOverlay } from '@/ui/components/LoadingOverlay';

    export function ProductsScreen() {
      const { initialized, currentStage } = useInitialization();
      
      // Register feature-specific initialization task
      useEffect(() => {
        const productInitTask = {
          name: 'features:products-init',
          stage: InitStage.BACKGROUND,
          priority: 'high',
          execute: async () => {
            // Prefetch products, load category data, etc.
            await productService.prefetchFeaturedProducts();
          }
        };
        
        initializer.registerTask(InitStage.BACKGROUND, productInitTask);
      }, []);
      
      return (
        <View style={{ flex: 1 }}>
          <ProductList />
          
          {/* Show loading overlay if not fully initialized */}
          {!initialized && currentStage === InitStage.BACKGROUND && (
            <LoadingOverlay message="Loading products..." />
          )}
        </View>
      );
    }
    ```
  </Tab>
</Tabs>

### Parallel Task Execution

The key characteristic of the Background stage is parallel execution of tasks. Unlike the sequential execution in the [Pre-UI stage](/docs/guides/app-initialization/pre-ui), Background tasks run concurrently to maximize efficiency.

<Callout type="info">
  **Reference Implementation**

  The complete implementation of the `Initializer` class, including the `executeParallelStage` method that powers Background tasks, is available in the [App Initialization Architecture](/docs/architecture/app-initialization#core-implementation-reference) document.
</Callout>

Here's how the parallel execution works:

1. Tasks are grouped by priority level (high, normal, low)
2. High priority tasks are executed first, in parallel
3. Once high priority tasks complete, normal priority tasks run in parallel
4. Finally, low priority tasks run in parallel

This approach provides a balance between parallelism (for efficiency) and prioritization (for user experience).

### Data Prefetching

Prefetch essential data during the Background stage:

```typescript
// core/domains/products/initialization.ts
import { initializer, InitStage, InitTask } from '@/core/shared/app/initialization';
import { queryClient } from '@/core/shared/query/queryClient';
import { productApi } from './api';
import { productQueryKeys } from './queryKeys';

const productPrefetchTask: InitTask = {
  name: 'products:prefetch',
  stage: InitStage.BACKGROUND,
  priority: 'high', // Higher priority for better UX
  critical: false, // Non-critical - app can function without prefetched data
  
  async execute(): Promise<void> {
    try {
      // Prefetch featured products
      await queryClient.prefetchQuery({
        queryKey: productQueryKeys.featured(),
        queryFn: productApi.public.getFeaturedProducts,
        staleTime: 5 * 60 * 1000, // 5 minutes
      });
      
      // Prefetch product categories
      await queryClient.prefetchQuery({
        queryKey: productQueryKeys.categories(),
        queryFn: productApi.public.getCategories,
        staleTime: 60 * 60 * 1000, // 1 hour
      });
      
      // Don't prefetch full product catalog - can be fetched on demand
    } catch (error) {
      console.error('Product prefetching failed:', error);
      // Non-critical - app can continue
    }
  }
};

// Register task
initializer.registerTask(InitStage.BACKGROUND, productPrefetchTask);
```

### Service Initialization

Initialize non-critical services during the Background stage:

```typescript
// core/shared/analytics/initialization.ts
import { initializer, InitStage, InitTask } from '@/core/shared/app/initialization';
import { analyticsService } from './service';
import { useAuthStore } from '@/core/domains/auth/store';

const analyticsInitTask: InitTask = {
  name: 'analytics:init',
  stage: InitStage.BACKGROUND,
  priority: 'normal',
  critical: false,
  
  async execute(): Promise<void> {
    try {
      // Initialize analytics with configuration
      await analyticsService.initialize({
        enabled: configStore.getConfig().features.analytics,
        debugMode: __DEV__,
        sessionTimeout: 30 * 60 * 1000, // 30 minutes
      });
      
      // Get user ID if authenticated
      const authState = useAuthStore.getState();
      if (authState.isAuthenticated && authState.user) {
        // Set user identity for analytics
        analyticsService.identifyUser(authState.user.id, {
          email: authState.user.email,
          accountType: authState.user.accountType,
        });
      } else {
        // Use anonymous tracking
        analyticsService.trackAnonymous();
      }
      
      // Track app open event
      analyticsService.trackEvent('app_opened', {
        initialScreen: navigationService.getCurrentRouteName(),
        appVersion: DeviceInfo.getVersion(),
        deviceModel: DeviceInfo.getModel(),
      });
    } catch (error) {
      console.error('Analytics initialization failed:', error);
      // Non-critical - app can function without analytics
    }
  }
};

// Register task
initializer.registerTask(InitStage.BACKGROUND, analyticsInitTask);
```

### State Synchronization

Synchronize local and remote state during the Background stage:

```typescript
// core/domains/cart/initialization.ts
import { initializer, InitStage, InitTask } from '@/core/shared/app/initialization';
import { useCartStore } from './store';
import { cartApi } from './api';
import { useAuthStore } from '@/core/domains/auth/store';
import { queryClient } from '@/core/shared/query/queryClient';
import { cartQueryKeys } from './queryKeys';

const cartSyncTask: InitTask = {
  name: 'cart:sync',
  stage: InitStage.BACKGROUND,
  priority: 'high',
  critical: false,
  dependencies: ['auth:token-retrieval'], // Depends on auth being initialized
  
  async execute(): Promise<void> {
    try {
      const authState = useAuthStore.getState();
      const cartState = useCartStore.getState();
      
      // Only sync when user is authenticated
      if (authState.isAuthenticated) {
        // Get server cart first
        const serverCart = await cartApi.protected.getCart();
        
        // Check if we have local cart items to merge
        if (cartState.localItems.length > 0) {
          // Merge local cart with server cart
          const mergedCart = await cartApi.protected.syncCart(cartState.localItems);
          
          // Update query cache with merged cart
          queryClient.setQueryData(cartQueryKeys.current(), mergedCart);
          
          // Clear local cart now that it's synced
          useCartStore.getState().clearLocalCart();
        } else {
          // Just set server cart in cache
          queryClient.setQueryData(cartQueryKeys.current(), serverCart);
        }
      }
    } catch (error) {
      console.error('Cart synchronization failed:', error);
      // Non-critical - keep using local cart
    }
  }
};

// Register task
initializer.registerTask(InitStage.BACKGROUND, cartSyncTask);
```

### Push Notification Setup

Configure push notifications during the Background stage:

```typescript
// core/shared/notifications/initialization.ts
import { initializer, InitStage, InitTask } from '@/core/shared/app/initialization';
import { notificationService } from './service';
import { permissionService } from '@/core/shared/permissions/service';
import { useAuthStore } from '@/core/domains/auth/store';

const pushNotificationsTask: InitTask = {
  name: 'notifications:push-setup',
  stage: InitStage.BACKGROUND,
  priority: 'low', // Lower priority than core features
  critical: false,
  
  async execute(): Promise<void> {
    try {
      // Check if notifications are enabled in app config
      if (!configStore.getConfig().features.pushNotifications) {
        return; // Feature disabled, exit early
      }
      
      // Initialize the notification library
      await notificationService.initialize();
      
      // Check if we have permission
      const hasPermission = await permissionService.checkPermission('notifications');
      
      if (hasPermission) {
        // Register for push notifications
        const token = await notificationService.registerForPushNotifications();
        
        // Only send token to backend if user is authenticated
        const authState = useAuthStore.getState();
        if (authState.isAuthenticated && token) {
          // Register device token with backend
          await notificationApi.protected.registerDevice(token, {
            deviceId: DeviceInfo.getUniqueId(),
            deviceType: Platform.OS,
            appVersion: DeviceInfo.getVersion(),
          });
        }
        
        // Set up notification handlers
        notificationService.setupNotificationHandlers({
          onNotificationReceived: this.handleNotificationReceived,
          onNotificationOpened: this.handleNotificationOpened,
        });
      } else {
        // Store this state so we can prompt user later
        notificationService.setPermissionState('denied');
      }
    } catch (error) {
      console.error('Push notification setup failed:', error);
      // Non-critical - app can function without push notifications
    }
  },
  
  handleNotificationReceived(notification) {
    // Handle incoming notification
    analyticsService.trackEvent('notification_received', {
      type: notification.type,
    });
  },
  
  handleNotificationOpened(notification) {
    // Navigate based on notification type
    switch (notification.type) {
      case 'order_update':
        navigationService.navigate('OrderDetails', { 
          orderId: notification.data.orderId 
        });
        break;
      case 'promotion':
        navigationService.navigate('Promotions');
        break;
      // Other notification types
    }
    
    analyticsService.trackEvent('notification_opened', {
      type: notification.type,
    });
  }
};

// Register task
initializer.registerTask(InitStage.BACKGROUND, pushNotificationsTask);
```

## Task Progress Reporting

Implement progress reporting for background tasks:

```typescript
// core/shared/app/initialization/progress.ts
import { EventEmitter } from '@/core/shared/utils/events';

export type TaskProgressEvents = {
  'task:progress': {
    taskName: string;
    progress: number;
    message?: string;
  };
};

export const taskProgressEvents = new EventEmitter<TaskProgressEvents>();

// Enhanced task execution with progress reporting
export function createTaskWithProgress(
  name: string,
  executor: (
    reportProgress: (progress: number, message?: string) => void
  ) => Promise<void>
): InitTask {
  return {
    name,
    async execute(): Promise<void> {
      // Create progress reporter function for this task
      const reportProgress = (progress: number, message?: string) => {
        taskProgressEvents.emit('task:progress', {
          taskName: name,
          progress,
          message,
        });
      };
      
      // Start at 0%
      reportProgress(0, 'Starting...');
      
      // Execute with progress reporting capability
      await executor(reportProgress);
      
      // Complete at 100%
      reportProgress(1, 'Complete');
    }
  };
}

// Usage example:
const assetPreloadTask = createTaskWithProgress(
  'assets:preload',
  async (reportProgress) => {
    const assetUrls = await getAssetUrls();
    const totalAssets = assetUrls.length;
    
    for (let i = 0; i < totalAssets; i++) {
      await preloadAsset(assetUrls[i]);
      
      // Report progress percentage and status message
      reportProgress(
        (i + 1) / totalAssets,
        `Loading assets (${i + 1}/${totalAssets})`
      );
    }
  }
);
```

## Common Challenges

### Error Handling and Recovery

Implement robust error handling for background tasks:

```typescript
// core/shared/app/initialization/error-handling.ts
import { initEvents } from './events';

// Register global error handler for initialization tasks
export function setupTaskErrorHandling() {
  initEvents.on('task:error', ({ name, stage, error }) => {
    // Log error to monitoring service
    monitoringService.logError(error, {
      context: 'initialization',
      taskName: name,
      stage,
    });
    
    // Show non-blocking error notification for important tasks
    const criticalBackgroundTasks = [
      'push-notification:setup',
      'cart:sync',
    ];
    
    if (stage === InitStage.BACKGROUND && criticalBackgroundTasks.includes(name)) {
      notificationService.showErrorBanner({
        message: `Failed to initialize ${name.split(':')[0]}`,
        actionLabel: 'Retry',
        onAction: () => {
          // Find the task and retry it
          const task = initializer.getTask(name);
          if (task) {
            task.execute().catch(console.error);
          }
        },
      });
    }
  });
}
```

### Task Timeout Management

Implement timeouts for background tasks to prevent hanging:

```typescript
// core/shared/app/initialization/timeout.ts
import { InitTask } from './initializer';

// Higher-order function to add timeout to any initialization task
export function withTimeout(
  task: InitTask,
  timeoutMs: number = 30000 // Default 30s timeout
): InitTask {
  return {
    ...task,
    name: task.name,
    async execute(): Promise<void> {
      return new Promise(async (resolve, reject) => {
        // Create timeout
        const timeoutId = setTimeout(() => {
          const error = new Error(`Task ${task.name} timed out after ${timeoutMs}ms`);
          console.error(error);
          
          // Only reject for critical tasks, resolve with warning for non-critical
          if (task.critical) {
            reject(error);
          } else {
            console.warn(`Non-critical task ${task.name} timed out, continuing initialization`);
            resolve();
          }
        }, timeoutMs);
        
        try {
          // Execute original task
          await task.execute();
          clearTimeout(timeoutId);
          resolve();
        } catch (error) {
          clearTimeout(timeoutId);
          reject(error);
        }
      });
    }
  };
}

// Usage:
const dataImportTask = withTimeout({
  name: 'data:import',
  execute: async () => {
    // Potentially long-running task
    await importLargeDataset();
  }
}, 60000); // 60 second timeout
```

### Resource-Intensive Operations

Handle resource-intensive operations carefully:

```typescript
// core/shared/utils/resource-management.ts
import { AppState } from 'react-native';

// Split large operation into smaller chunks with yield points
export async function executeChunked<T>(
  items: T[],
  processor: (item: T) => Promise<void>,
  options: {
    chunkSize?: number;
    delayBetweenChunks?: number;
    onProgress?: (completed: number, total: number) => void;
  } = {}
): Promise<void> {
  const { 
    chunkSize = 10, 
    delayBetweenChunks = 50,
    onProgress
  } = options;
  
  const total = items.length;
  let completed = 0;
  
  // Process in chunks
  for (let i = 0; i < total; i += chunkSize) {
    // Only process when app is in foreground
    await waitForActiveAppState();
    
    // Take a chunk
    const chunk = items.slice(i, i + chunkSize);
    
    // Process chunk items in parallel
    await Promise.all(chunk.map(item => processor(item)));
    
    completed += chunk.length;
    
    // Report progress
    if (onProgress) {
      onProgress(completed, total);
    }
    
    // Small delay to let UI thread breathe
    if (i + chunkSize < total) {
      await new Promise(resolve => setTimeout(resolve, delayBetweenChunks));
    }
  }
}

// Wait for app to be in active state
async function waitForActiveAppState(): Promise<void> {
  if (AppState.currentState === 'active') {
    return;
  }
  
  return new Promise(resolve => {
    const subscription = AppState.addEventListener('change', (state) => {
      if (state === 'active') {
        subscription.remove();
        resolve();
      }
    });
  });
}

// Usage example:
// In a background initialization task
await executeChunked(
  largeDataset,
  async (item) => {
    await processDataItem(item);
  },
  {
    chunkSize: 20,
    delayBetweenChunks: 100,
    onProgress: (completed, total) => {
      reportProgress(completed / total, `Processing ${completed}/${total} items`);
    }
  }
);
```

## Performance Considerations

* **(Do ✅) Use task prioritization**
  * Higher priority for user-visible features
  * Normal priority for standard services
  * Lower priority for analytics and non-critical services

* **(Do ✅) Implement progressive loading**
  * Load data in smaller chunks
  * Prioritize data for visible UI elements
  * Defer off-screen content loading

* **(Don't ❌) Block the main thread**
  * Move heavy calculations to separate threads
  * Break large operations into smaller chunks
  * Add yield points to allow the UI to remain responsive

* **(Do ✅) Respect device capabilities**
  * Scale operations based on device performance
  * Reduce workload on low-end devices
  * Adjust parallelism based on available resources

## Practical Examples

### Asset Preloading System

```typescript
// core/shared/assets/initialization.ts
import { initializer, InitStage, InitTask } from '@/core/shared/app/initialization';
import { createTaskWithProgress } from '@/core/shared/app/initialization/progress';
import { executeChunked } from '@/core/shared/utils/resource-management';
import { assetStore } from './store';
import { Image } from 'react-native';

// Preload important images and assets
const assetPreloadTask = createTaskWithProgress(
  'assets:preload',
  async (reportProgress) => {
    try {
      // Get list of important assets to preload
      const assetsToPreload = [
        // Common UI elements
        require('@/assets/images/logo.png'),
        require('@/assets/images/background.png'),
        
        // Category icons
        ...getCategoryIcons(),
        
        // Other critical assets
      ];
      
      // Preload images using chunked execution
      await executeChunked(
        assetsToPreload,
        async (asset) => {
          await new Promise<void>((resolve) => {
            if (typeof asset === 'number') {
              // Local asset (from require)
              Image.prefetch(Image.resolveAssetSource(asset).uri)
                .then(() => resolve())
                .catch(() => resolve()); // Continue even if one fails
            } else {
              // Remote URL
              Image.prefetch(asset)
                .then(() => resolve())
                .catch(() => resolve());
            }
          });
        },
        {
          chunkSize: 5,
          delayBetweenChunks: 50,
          onProgress: (completed, total) => {
            reportProgress(
              completed / total,
              `Preloading assets (${completed}/${total})`
            );
          },
        }
      );
      
      // Mark assets as preloaded
      assetStore.setAssetsPreloaded(true);
    } catch (error) {
      console.error('Asset preloading failed:', error);
      // Non-critical - app can function without preloaded assets
    }
  }
);

// Register task
initializer.registerTask(InitStage.BACKGROUND, 
  { ...assetPreloadTask, priority: 'normal' }
);

// Helper to get category icons
function getCategoryIcons() {
  return [
    require('@/assets/images/categories/electronics.png'),
    require('@/assets/images/categories/fashion.png'),
    require('@/assets/images/categories/home.png'),
    // More categories
  ];
}
```

### Offline Data Synchronization

```typescript
// core/shared/offline/initialization.ts
import { initializer, InitStage, InitTask } from '@/core/shared/app/initialization';
import { offlineStore } from './store';
import { storage } from '@/core/shared/utils/storage';
import { executeChunked } from '@/core/shared/utils/resource-management';
import { createTaskWithProgress } from '@/core/shared/app/initialization/progress';
import { withTimeout } from '@/core/shared/app/initialization/timeout';

// Synchronize pending offline actions
const offlineSyncTask = createTaskWithProgress(
  'offline:sync-pending-actions',
  async (reportProgress) => {
    try {
      // Check for network connectivity first
      const isConnected = await networkService.isConnected();
      if (!isConnected) {
        console.log('Device offline, skipping offline sync');
        return;
      }
      
      // Load pending offline actions
      const pendingActions = await storage.get('offline:pending-actions');
      
      if (!pendingActions) {
        console.log('No pending offline actions to sync');
        return;
      }
      
      const actions = JSON.parse(pendingActions);
      
      if (actions.length === 0) {
        console.log('No pending offline actions to sync');
        return;
      }
      
      console.log(`Found ${actions.length} pending offline actions to sync`);
      
      // Process actions in chunks
      await executeChunked(
        actions,
        async (action) => {
          try {
            await processPendingAction(action);
            
            // Remove from pending list
            offlineStore.removeAction(action.id);
          } catch (error) {
            console.error(`Failed to process offline action ${action.id}:`, error);
            
            // Mark as failed but keep for retry
            offlineStore.markActionFailed(action.id, error.message);
          }
        },
        {
          chunkSize: 1, // Process one at a time for reliability
          delayBetweenChunks: 300, // Larger delay to avoid overloading API
          onProgress: (completed, total) => {
            reportProgress(
              completed / total,
              `Syncing offline actions (${completed}/${total})`
            );
          },
        }
      );
      
      // Update storage with remaining actions
      const remainingActions = offlineStore.getPendingActions();
      if (remainingActions.length > 0) {
        await storage.set('offline:pending-actions', JSON.stringify(remainingActions));
      } else {
        await storage.remove('offline:pending-actions');
      }
    } catch (error) {
      console.error('Offline sync failed:', error);
      // Non-critical - can retry later
    }
  }
);

// Process a single offline action
async function processPendingAction(action) {
  switch (action.type) {
    case 'create_order':
      await orderApi.protected.createOrder(action.payload);
      break;
    case 'update_cart':
      await cartApi.protected.updateCart(action.payload);
      break;
    // Other action types
    default:
      throw new Error(`Unknown action type: ${action.type}`);
  }
}

// Register task with timeout
initializer.registerTask(
  InitStage.BACKGROUND,
  withTimeout(
    { ...offlineSyncTask, priority: 'normal' },
    60000 // 1 minute timeout
  )
);
```

## Migration Considerations

When transitioning from traditional data loading patterns to the Background initialization stage, these strategies can help make your migration smoother:

### From Eager Loading to Progressive Loading

Many applications traditionally fetch all data upfront, which can delay user interaction:

```typescript
// Traditional approach - blocking data loading
const HomeScreen = () => {
  const [isLoading, setIsLoading] = useState(true);
  const [data, setData] = useState({
    products: [],
    categories: [],
    user: null,
    notifications: []
  });
  
  useEffect(() => {
    async function loadEverything() {
      try {
        // Fetch everything at once, blocking UI until complete
        const [products, categories, user, notifications] = await Promise.all([
          api.getProducts(),
          api.getCategories(),
          api.getUserProfile(),
          api.getNotifications()
        ]);
        
        setData({ products, categories, user, notifications });
        setIsLoading(false);
      } catch (error) {
        console.error('Data loading failed', error);
        setIsLoading(false);
      }
    }
    
    loadEverything();
  }, []);
  
  if (isLoading) {
    return <LoadingScreen />;
  }
  
  return (
    <Screen>
      <UserProfile user={data.user} />
      <ProductCarousel products={data.products} />
      <CategoryList categories={data.categories} />
      <NotificationPanel notifications={data.notifications} />
    </Screen>
  );
};
```

You can enhance this with the Background stage approach:

1. First render the UI shell with minimal data from the Initial UI stage
2. Then prioritize data loading in the Background stage based on importance
3. Show appropriate loading states for each component as its data loads

### Prioritized Data Loading Pattern

A key migration strategy is to prioritize data loading:

```typescript
// Background stage approach
const HomeScreen = () => {
  const { currentStage } = useInitialization();
  const { data: user } = useUserProfile(); // Essential - load in Initial UI stage
  const { data: products, isLoading: productsLoading } = useProducts();
  const { data: categories, isLoading: categoriesLoading } = useCategories();
  const { data: notifications, isLoading: notificationsLoading } = useNotifications();
  
  // Register initialization tasks once
  useEffect(() => {
    // Register tasks for data prefetching in Background stage
    initializer.registerTask(InitStage.BACKGROUND, {
      name: 'home:products-prefetch',
      priority: 'high', // High priority - visible at top of screen
      execute: async () => {
        await queryClient.prefetchQuery(productKeys.featured);
      }
    });
    
    initializer.registerTask(InitStage.BACKGROUND, {
      name: 'home:categories-prefetch',
      priority: 'normal',
      execute: async () => {
        await queryClient.prefetchQuery(categoryKeys.list);
      }
    });
    
    initializer.registerTask(InitStage.BACKGROUND, {
      name: 'home:notifications-prefetch',
      priority: 'low', // Low priority - below the fold
      execute: async () => {
        await queryClient.prefetchQuery(notificationKeys.recent);
      }
    });
  }, []);
  
  return (
    <Screen>
      <UserProfile user={user} />
      <ProductCarousel 
        products={products} 
        isLoading={currentStage === InitStage.BACKGROUND || productsLoading} 
      />
      <CategoryList 
        categories={categories} 
        isLoading={currentStage === InitStage.BACKGROUND || categoriesLoading} 
      />
      <NotificationPanel 
        notifications={notifications} 
        isLoading={currentStage === InitStage.BACKGROUND || notificationsLoading} 
      />
    </Screen>
  );
};
```

This approach improves perceived performance by showing content progressively as it becomes available.

### Tracking and Optimizing Data Loading

When adopting the Background stage pattern, consider implementing these improvements:

* Add progress reporting to long-running background tasks
* Use `chunk` strategies for large data sets to avoid blocking the JavaScript thread
* Implement timeout safety for API calls to prevent stalled initialization
* Cache aggressively to reduce repeated data fetching across app launches

Remember that the Background stage is designed for parallel execution, so leverage that to maximize efficiency while maintaining a responsive UI.

## Summary

The Background initialization stage allows your application to continue setting up important services and prefetching data without blocking the initial UI rendering. By carefully implementing and prioritizing background tasks, you can create a smooth, responsive user experience that progressively enhances as initialization completes.

After all Background tasks complete, your app transitions to the [Finalization stage](/docs/guides/app-initialization/finalization) to complete the initialization process and remove any remaining loading indicators.

Key principles to remember:

* Execute tasks in parallel to maximize efficiency
* Prioritize tasks based on their importance to the user experience
* Implement proper error handling and recovery strategies
* Use progress reporting to provide feedback to users
* Be mindful of device resources and performance
* Break large operations into smaller chunks with yield points

## Related Documents

### Core Initialization Documentation

* [App Initialization Architecture](/docs/architecture/app-initialization) - Overview of the complete initialization architecture
* [App Initialization Guides](/docs/guides/app-initialization) - Index of all initialization guides

### Other Initialization Stages

* [Pre-UI Initialization Guide](/docs/guides/app-initialization/pre-ui) - First initialization stage
* [Initial UI Rendering Guide](/docs/guides/app-initialization/initial-ui) - Stage before Background initialization
* [Finalization Stage Guide](/docs/guides/app-initialization/finalization) - Final stage after Background completion

### Related Implementation Guides

* [Performance Optimization Guide](/docs/performance/app-startup) - Optimizing app startup performance
* [Data Prefetching Strategies](/docs/data/prefetching-strategies) - Efficiently prefetching data during initialization
* [Offline Support Guide](/docs/advanced/offline-support) - Handling offline scenarios during initialization


# UTA Implementation Guides: Finalization Stage Guide
URL: https://dev.updatetheapp.com/docs/guides/app-initialization/finalization-stage-guide
Documentation: https://dev.updatetheapp.com/docs/guides/app-initialization/finalization-stage-guide

Implementation patterns for the Finalization stage in the application bootstrap process.
        
***

title: Finalization Stage Guide
description: Implementation patterns for the Finalization stage in the application bootstrap process.
-----------------------------------------------------------------------------------------------------

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';

# Finalization Stage Guide

## Overview

The Finalization stage is the final phase in the application bootstrap process, occurring after all [Background stage](/docs/guides/app-initialization/background) tasks have completed. This stage focuses on transitioning the application to a fully interactive state, completing any remaining initialization requirements, and ensuring the app is ready for unrestricted user interaction. This guide provides implementation patterns for the Finalization stage to ensure a smooth user experience.

## Quick Start

To implement the Finalization stage:

1. Register tasks with the initializer:
   ```typescript
   import { initializer, InitStage } from '@/core/shared/app/initialization';

   // Register a Finalization stage task
   initializer.registerTask(InitStage.FINALIZATION, {
     name: 'ui:cleanup',
     priority: 'high',
     execute: async () => {
       // Remove loading indicators
       loadingStore.setGlobalLoading(false);
       
       // Enable deferred interactions
       uiStore.setFullyInteractive(true);
       
       // Log completion metrics
       analyticsService.logEvent('app_initialization_complete', {
         totalTime: performanceStore.getTotalInitTime()
       });
     }
   });
   ```

2. Execute the Finalization stage after Background tasks complete:
   ```typescript
   // In your initialization controller
   async function completeInitialization() {
     try {
       // Execute Finalization stage
       await initializer.executeStage(InitStage.FINALIZATION);
       
       // Mark initialization as complete
       initializationStore.setInitialized(true);
       
     } catch (error) {
       console.error('Finalization failed:', error);
       // Still mark as initialized to prevent app from being stuck
       initializationStore.setInitialized(true);
       // Log error for monitoring
       errorReporting.logError('initialization_finalization_failed', error);
     }
   }
   ```

3. Use the `initialized` flag from the initialization store to remove loading overlays

## When To Use

Add initialization tasks to the Finalization stage when they:

* **Complete UI transitions**: Remove loading indicators, show fully loaded content
* **Enable deferred interactions**: Activate features that were disabled during initialization
* **Report completion metrics**: Send analytics about initialization performance
* **Perform post-initialization cleanup**: Release temporary resources or states
* **Start monitoring services**: Begin periodic background services

The Finalization stage should focus on making the transition from "initializing" to "fully functional" as seamless as possible. At this point, all critical initialization from the [Pre-UI](/docs/guides/app-initialization/pre-ui), [Initial UI](/docs/guides/app-initialization/initial-ui), and [Background](/docs/guides/app-initialization/background) stages should be complete.

## Implementation Patterns

<Mermaid
  chart={`
flowchart TD
  Background[Background Stage Complete] --> Finalization[Finalization Stage]
  
  subgraph Finalization[Finalization Stage]
      RemoveLoading[Remove Loading Indicators]
      EnableInteractions[Enable Deferred Interactions]
      StartMonitoring[Start Monitoring Services]
      CollectMetrics[Collect Performance Metrics]
  end
  
  Finalization --> Complete[Initialization Complete]
  
  style Finalization fill:#fbb,stroke:#333,stroke-width:2px
`}
/>

As shown in the diagram, the Finalization stage begins after the [Background stage](/docs/guides/app-initialization/background) completes and represents the final transition to a fully initialized application state.

### Navigation System Integration

Building on the navigation setup from the [Initial UI stage](/docs/guides/app-initialization/initial-ui), the Finalization stage focuses on removing any loading overlays and enabling full navigation:

<Tabs items={["Expo Router", "React Navigation"]}>
  <Tab>
    ```typescript
    // components/InitializationAwareWrapper.tsx (Expo Router)
    import React from 'react';
    import { View, ActivityIndicator, StyleSheet } from 'react-native';
    import { useInitialization } from '@/core/shared/app/initialization';

    export function InitializationAwareWrapper({ children }) {
      const { initialized } = useInitialization();
      
      // App is fully initialized
      if (initialized) {
        return children;
      }
      
      // Initialization is still in progress
      return (
        <View style={styles.container}>
          {children}
          <View style={styles.loadingOverlay}>
            <ActivityIndicator size="large" color="#0000ff" />
          </View>
        </View>
      );
    }

    const styles = StyleSheet.create({
      container: {
        flex: 1,
      },
      loadingOverlay: {
        ...StyleSheet.absoluteFillObject,
        backgroundColor: 'rgba(255, 255, 255, 0.7)',
        justifyContent: 'center',
        alignItems: 'center',
      },
    });

    // Usage in Expo Router layout
    // app/(app)/_layout.tsx
    export default function AppLayout() {
      return (
        <InitializationAwareWrapper>
          <Stack />
        </InitializationAwareWrapper>
      );
    }
    ```
  </Tab>

  <Tab>
    ```typescript
    // components/InitializationAwareWrapper.tsx (React Navigation)
    import React from 'react';
    import { View, ActivityIndicator, StyleSheet } from 'react-native';
    import { useInitialization } from '@/core/shared/app/initialization';

    export function InitializationAwareWrapper({ children }) {
      const { initialized } = useInitialization();
      
      // App is fully initialized
      if (initialized) {
        return children;
      }
      
      // Initialization is still in progress
      return (
        <View style={styles.container}>
          {children}
          <View style={styles.loadingOverlay}>
            <ActivityIndicator size="large" color="#0000ff" />
          </View>
        </View>
      );
    }

    const styles = StyleSheet.create({
      container: {
        flex: 1,
      },
      loadingOverlay: {
        ...StyleSheet.absoluteFillObject,
        backgroundColor: 'rgba(255, 255, 255, 0.7)',
        justifyContent: 'center',
        alignItems: 'center',
      },
    });

    // Usage in React Navigation
    // navigation/AppNavigator.tsx
    export function AppNavigator() {
      return (
        <InitializationAwareWrapper>
          <Stack.Navigator>
            {/* Navigation configuration */}
          </Stack.Navigator>
        </InitializationAwareWrapper>
      );
    }
    ```
  </Tab>
</Tabs>

### Removing Loading Indicators

The most visible aspect of the Finalization stage is removing loading indicators that were created during the [Initial UI stage](/docs/guides/app-initialization/initial-ui):

```typescript
// core/shared/app/initialization/finalization.ts
import { initializer, InitStage, InitTask } from './initializer';
import { initEvents } from './events';

const uiFinalizationTask: InitTask = {
  name: 'ui:finalization',
  stage: InitStage.FINALIZATION,
  priority: 'high',
  
  async execute(): Promise<void> {
    try {
      // Notify UI components that initialization is complete
      initEvents.emit('initialization:complete');
      
      // Allow a short delay for UI transitions
      await new Promise(resolve => setTimeout(resolve, 150));
      
      // Remove any global loading indicators
      LoadingManager.hideGlobalLoadingIndicator();
      
      // Enable deferred UI interactions
      UIManager.setInteractionsEnabled(true);
    } catch (error) {
      console.error('UI finalization failed:', error);
      // Try to ensure UI is usable even if finalization fails
      LoadingManager.hideGlobalLoadingIndicator();
      UIManager.setInteractionsEnabled(true);
    }
  }
};

// Register task
initializer.registerTask(InitStage.FINALIZATION, uiFinalizationTask);
```

### Initialization Performance Metrics

Collect and report metrics about the initialization process:

```typescript
// core/shared/app/initialization/metrics.ts
import { initializer, InitStage, InitTask } from './initializer';
import { initEvents } from './events';
import { analyticsService } from '@/core/shared/analytics/service';
import { performanceStore } from '@/core/shared/performance/store';

// Collect and report initialization performance metrics
const metricsCollectionTask: InitTask = {
  name: 'metrics:initialization-performance',
  stage: InitStage.FINALIZATION,
  priority: 'normal',
  
  async execute(): Promise<void> {
    try {
      // Get timing data from performance store
      const timings = performanceStore.getInitializationTimings();
      
      // Calculate key metrics
      const totalInitTime = timings.total;
      const timeToInteractive = timings.stages[InitStage.PRE_UI] + 
                               timings.stages[InitStage.INITIAL_UI];
      const backgroundTime = timings.stages[InitStage.BACKGROUND];
      
      // Get task-specific timings
      const slowestTasks = calculateSlowestTasks(timings.tasks);
      
      // Report metrics to analytics
      analyticsService.trackEvent('initialization_complete', {
        total_init_time_ms: totalInitTime,
        time_to_interactive_ms: timeToInteractive,
        background_time_ms: backgroundTime,
        slowest_task: slowestTasks[0]?.name,
        slowest_task_time_ms: slowestTasks[0]?.duration,
        device_model: DeviceInfo.getModel(),
        os_version: DeviceInfo.getSystemVersion(),
        app_version: DeviceInfo.getVersion(),
        network_type: networkService.getNetworkType(),
      });
      
      // Log to console in development mode
      if (__DEV__) {
        console.log('Initialization performance metrics:', {
          totalInitTime: `${totalInitTime}ms`,
          timeToInteractive: `${timeToInteractive}ms`,
          backgroundTime: `${backgroundTime}ms`,
          slowestTasks: slowestTasks.map(t => `${t.name}: ${t.duration}ms`).join(', '),
        });
      }
      
      // Store metrics for developer performance tools
      if (configStore.getConfig().features.developerTools) {
        await storage.set('dev:last-init-metrics', JSON.stringify({
          timestamp: Date.now(),
          metrics: {
            totalInitTime,
            timeToInteractive,
            backgroundTime,
            taskTimings: timings.tasks,
          },
        }));
      }
    } catch (error) {
      console.error('Metrics collection failed:', error);
      // Non-critical - app can function without metrics
    }
  }
};

// Helper function to calculate slowest tasks
function calculateSlowestTasks(taskTimings) {
  return Object.entries(taskTimings)
    .map(([name, duration]) => ({ name, duration }))
    .sort((a, b) => b.duration - a.duration)
    .slice(0, 5); // Top 5 slowest tasks
}

// Register task
initializer.registerTask(InitStage.FINALIZATION, metricsCollectionTask);
```

### Starting Monitoring Services

Start monitoring services after initialization completes:

```typescript
// core/shared/monitoring/initialization.ts
import { initializer, InitStage, InitTask } from '@/core/shared/app/initialization';
import { monitoringService } from './service';

const monitoringStartTask: InitTask = {
  name: 'monitoring:start',
  stage: InitStage.FINALIZATION,
  priority: 'low',
  
  async execute(): Promise<void> {
    try {
      // Start performance monitoring
      monitoringService.startPerformanceMonitoring({
        sampleRate: 0.1, // Monitor 10% of sessions
        captureFrameMetrics: true,
        networkRequestSampling: true,
      });
      
      // Start error monitoring
      monitoringService.startErrorMonitoring({
        unhandledRejections: true,
        unhandledExceptions: true,
      });
      
      // Start network monitoring
      monitoringService.startNetworkMonitoring({
        excludeUrls: [
          // Exclude high-volume or sensitive endpoints
          /\/analytics\//,
          /\/logs\//,
        ],
        includeHeaders: false, // Don't capture headers for privacy
      });
      
      // Register app state change handler
      AppState.addEventListener('change', (state) => {
        monitoringService.recordAppStateChange(state);
        
        if (state === 'active') {
          // App came to foreground, resume monitoring
          monitoringService.resumeMonitoring();
        } else if (state === 'background') {
          // App went to background, pause monitoring to save resources
          monitoringService.pauseMonitoring();
        }
      });
    } catch (error) {
      console.error('Monitoring service start failed:', error);
      // Non-critical - app can function without monitoring
    }
  }
};

// Register task
initializer.registerTask(InitStage.FINALIZATION, monitoringStartTask);
```

### Cleanup and Optimization

Perform cleanup and optimization in the Finalization stage:

```typescript
// core/shared/app/initialization/cleanup.ts
import { initializer, InitStage, InitTask } from './initializer';

const cleanupTask: InitTask = {
  name: 'system:cleanup',
  stage: InitStage.FINALIZATION,
  priority: 'low',
  
  async execute(): Promise<void> {
    try {
      // Clear temporary initialization data
      await storage.remove('app:initialization-temp');
      
      // Release any initialization-specific resources
      initializer.releaseResources();
      
      // Run garbage collection if possible (this is platform specific)
      if (global.gc) {
        global.gc();
      }
      
      // Clean up old cached files
      await cleanupCachedFiles();
      
      // Clear temporary debug logs
      if (!__DEV__) {
        await cleanupDebugLogs();
      }
    } catch (error) {
      console.error('Cleanup failed:', error);
      // Non-critical - app can function without cleanup
    }
  }
};

// Helper to clean up cached files
async function cleanupCachedFiles() {
  try {
    // Get cache info
    const cacheInfo = await fileSystem.getCacheInfo();
    
    // If cache exceeds threshold, clear older files
    if (cacheInfo.size > MAX_CACHE_SIZE) {
      const filesToRemove = await fileSystem.getOldCacheFiles(
        MAX_CACHE_AGE_DAYS
      );
      
      await Promise.all(
        filesToRemove.map(file => fileSystem.removeFile(file.path))
      );
      
      console.log(`Cleaned up ${filesToRemove.length} old cached files`);
    }
  } catch (error) {
    console.error('Cache cleanup failed:', error);
  }
}

// Helper to clean up debug logs
async function cleanupDebugLogs() {
  try {
    const logFiles = await fileSystem.getFiles(DEBUG_LOGS_DIR);
    const oldLogFiles = logFiles.filter(
      file => (Date.now() - file.created) > MAX_LOG_AGE_DAYS * 24 * 60 * 60 * 1000
    );
    
    await Promise.all(
      oldLogFiles.map(file => fileSystem.removeFile(file.path))
    );
  } catch (error) {
    console.error('Log cleanup failed:', error);
  }
}

// Register task
initializer.registerTask(InitStage.FINALIZATION, cleanupTask);
```

### Deferred Feature Initialization

Initialize non-critical features in the Finalization stage:

```typescript
// features/chat/initialization.ts
import { initializer, InitStage, InitTask } from '@/core/shared/app/initialization';
import { chatService } from './service';
import { useAuthStore } from '@/core/domains/auth/store';

// Initialize chat system in the finalization stage
const chatInitTask: InitTask = {
  name: 'features:chat-init',
  stage: InitStage.FINALIZATION,
  priority: 'normal',
  dependencies: ['auth:token-retrieval'], // Depends on auth
  
  async execute(): Promise<void> {
    try {
      // Only initialize chat if user is logged in
      const authState = useAuthStore.getState();
      if (!authState.isAuthenticated) {
        return; // Exit early if not authenticated
      }
      
      // Initialize chat service
      await chatService.initialize({
        userId: authState.user.id,
        userName: authState.user.displayName,
        enablePushNotifications: true,
      });
      
      // Connect to chat servers
      await chatService.connect();
      
      // Register for chat events
      chatService.onNewMessage((message) => {
        // Update UI, show notification, etc.
        messagingStore.addMessage(message);
        
        // Show in-app notification if app is in foreground
        if (AppState.currentState === 'active') {
          notificationService.showInAppNotification({
            title: message.sender.name,
            message: message.text,
            onPress: () => {
              navigationService.navigate('Chat', {
                conversationId: message.conversationId,
              });
            },
          });
        }
      });
      
      // Fetch unread message count
      const unreadCount = await chatService.getUnreadMessageCount();
      messagingStore.setUnreadCount(unreadCount);
    } catch (error) {
      console.error('Chat initialization failed:', error);
      // Non-critical - app can function without chat
    }
  }
};

// Register task
initializer.registerTask(InitStage.FINALIZATION, chatInitTask);
```

## Managing UI Transitions

Implement smooth transitions for the final UI state:

```typescript
// ui/components/InitializationTransition.tsx
import React, { useEffect, useState } from 'react';
import { Animated, StyleSheet, View } from 'react-native';
import { useInitialization } from '@/core/shared/app/initialization';

interface InitializationTransitionProps {
  children: React.ReactNode;
  loadingFallback: React.ReactNode;
}

export function InitializationTransition({ 
  children, 
  loadingFallback 
}: InitializationTransitionProps) {
  const { initialized } = useInitialization();
  const [showChildren, setShowChildren] = useState(false);
  const fadeAnim = useState(new Animated.Value(0))[0];
  
  useEffect(() => {
    if (initialized) {
      // Start fade-in animation
      Animated.timing(fadeAnim, {
        toValue: 1,
        duration: 300,
        useNativeDriver: true,
      }).start();
      
      // Set content to visible
      setShowChildren(true);
    }
  }, [initialized, fadeAnim]);
  
  return (
    <View style={styles.container}>
      {!initialized && (
        <View style={styles.loadingContainer}>
          {loadingFallback}
        </View>
      )}
      
      {showChildren && (
        <Animated.View
          style={[
            styles.contentContainer,
            { opacity: fadeAnim }
          ]}
        >
          {children}
        </Animated.View>
      )}
    </View>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
  },
  loadingContainer: {
    ...StyleSheet.absoluteFillObject,
    zIndex: 10,
  },
  contentContainer: {
    flex: 1,
  },
});
```

## Common Challenges

### Dealing with Incomplete Background Tasks

Handle cases where background tasks haven't completed:

```typescript
// core/shared/app/initialization/timeout-handler.ts
import { initializer, InitStage, InitTask } from './initializer';
import { initEvents } from './events';

// Force finalization if background tasks take too long
const forceFinalizationTask: InitTask = {
  name: 'system:force-finalization',
  
  async execute(): Promise<void> {
    // Set a maximum time for the Background stage
    const MAX_BACKGROUND_TIME = 15000; // 15 seconds
    
    return new Promise(resolve => {
      // Start a timer for the maximum background time
      const timer = setTimeout(() => {
        console.warn('Background initialization timed out, forcing finalization');
        
        // Get incomplete background tasks
        const pendingTasks = initializer.getPendingTasks(InitStage.BACKGROUND);
        
        if (pendingTasks.length > 0) {
          console.warn(`Incomplete background tasks: ${pendingTasks.map(t => t.name).join(', ')}`);
          
          // Log to analytics
          analyticsService.trackEvent('initialization_timeout', {
            stage: InitStage.BACKGROUND,
            pendingTasks: pendingTasks.map(t => t.name),
          });
          
          // Emit event for incomplete tasks
          initEvents.emit('stage:incomplete', {
            stage: InitStage.BACKGROUND,
            pendingTasks: pendingTasks.map(t => t.name),
          });
        }
        
        // Proceed to finalization anyway
        resolve();
      }, MAX_BACKGROUND_TIME);
      
      // Clean up timer if background stage completes normally
      initEvents.once('stage:complete', (stage) => {
        if (stage === InitStage.BACKGROUND) {
          clearTimeout(timer);
          resolve();
        }
      });
    });
  }
};

// Register task in the Background stage
initializer.registerTask(InitStage.BACKGROUND, {
  ...forceFinalizationTask,
  priority: 'low',
});
```

### Managing UI State for Interrupted Initialization

Handle cases where initialization is interrupted:

```typescript
// ui/components/InterruptibleInitialization.tsx
import React, { useEffect, useState } from 'react';
import { View, Text, StyleSheet, TouchableOpacity } from 'react-native';
import { useInitialization } from '@/core/shared/app/initialization';

export function InterruptibleInitialization({ children }) {
  const { 
    initialized, 
    error, 
    currentStage, 
    incompleteStages 
  } = useInitialization();
  
  const [showOverride, setShowOverride] = useState(false);
  
  // Show override option if initialization takes too long
  useEffect(() => {
    if (!initialized && !error) {
      const timer = setTimeout(() => {
        setShowOverride(true);
      }, 30000); // 30 seconds
      
      return () => clearTimeout(timer);
    }
  }, [initialized, error]);
  
  // If initialization completed normally, show children
  if (initialized) {
    return <>{children}</>;
  }
  
  // If initialization failed with error
  if (error) {
    return (
      <View style={styles.container}>
        <Text style={styles.title}>Something went wrong</Text>
        <Text style={styles.message}>
          We couldn't finish setting up the app. Please try again.
        </Text>
        <TouchableOpacity
          style={styles.button}
          onPress={() => initializer.restart()}
        >
          <Text style={styles.buttonText}>Retry</Text>
        </TouchableOpacity>
      </View>
    );
  }
  
  // If initialization is taking too long
  if (showOverride) {
    return (
      <View style={styles.container}>
        <Text style={styles.title}>Taking longer than expected</Text>
        <Text style={styles.message}>
          {`Setup is still in progress (${currentStage}). `}
          You can continue with limited functionality or wait.
        </Text>
        
        <View style={styles.buttonRow}>
          <TouchableOpacity
            style={[styles.button, styles.secondaryButton]}
            onPress={() => {
              // Force initialization to complete
              initializer.forceComplete();
            }}
          >
            <Text style={styles.secondaryButtonText}>Continue Anyway</Text>
          </TouchableOpacity>
          
          <TouchableOpacity
            style={styles.button}
            onPress={() => {
              // Restart initialization
              initializer.restart();
            }}
          >
            <Text style={styles.buttonText}>Restart Setup</Text>
          </TouchableOpacity>
        </View>
      </View>
    );
  }
  
  // Normal loading state
  return <LoadingScreen stage={currentStage} />;
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    justifyContent: 'center',
    alignItems: 'center',
    padding: 20,
    backgroundColor: '#fff',
  },
  title: {
    fontSize: 20,
    fontWeight: 'bold',
    marginBottom: 12,
  },
  message: {
    fontSize: 16,
    textAlign: 'center',
    marginBottom: 24,
    color: '#555',
  },
  buttonRow: {
    flexDirection: 'row',
    justifyContent: 'space-between',
    width: '100%',
    paddingHorizontal: 20,
  },
  button: {
    backgroundColor: '#007AFF',
    paddingVertical: 12,
    paddingHorizontal: 24,
    borderRadius: 8,
    minWidth: 140,
    alignItems: 'center',
  },
  secondaryButton: {
    backgroundColor: 'transparent',
    borderWidth: 1,
    borderColor: '#007AFF',
  },
  buttonText: {
    color: '#fff',
    fontSize: 16,
    fontWeight: '600',
  },
  secondaryButtonText: {
    color: '#007AFF',
    fontSize: 16,
    fontWeight: '600',
  },
});
```

### Reporting Initialization Status

Provide a comprehensive initialization status report:

```typescript
// core/shared/app/initialization/status-report.ts
import { initializer, InitStage, InitTask } from './initializer';
import { storage } from '@/core/shared/utils/storage';

// Generate and store initialization status report
const statusReportTask: InitTask = {
  name: 'metrics:status-report',
  stage: InitStage.FINALIZATION,
  priority: 'low',
  
  async execute(): Promise<void> {
    try {
      // Get initialization status
      const status = initializer.getStatus();
      
      // Create detailed report
      const report = {
        timestamp: Date.now(),
        success: status.completed,
        error: status.error ? {
          message: status.error.message,
          task: status.errorTask
        } : null,
        stages: {
          [InitStage.PRE_UI]: {
            completed: status.stageStatus[InitStage.PRE_UI].completed,
            duration: status.stageStatus[InitStage.PRE_UI].duration,
            tasks: status.stageStatus[InitStage.PRE_UI].tasks.map(t => ({
              name: t.name,
              success: t.completed,
              duration: t.duration,
              error: t.error ? t.error.message : null
            }))
          },
          [InitStage.INITIAL_UI]: {
            completed: status.stageStatus[InitStage.INITIAL_UI].completed,
            duration: status.stageStatus[InitStage.INITIAL_UI].duration,
            tasks: status.stageStatus[InitStage.INITIAL_UI].tasks.map(t => ({
              name: t.name,
              success: t.completed,
              duration: t.duration,
              error: t.error ? t.error.message : null
            }))
          },
          [InitStage.BACKGROUND]: {
            completed: status.stageStatus[InitStage.BACKGROUND].completed,
            duration: status.stageStatus[InitStage.BACKGROUND].duration,
            tasks: status.stageStatus[InitStage.BACKGROUND].tasks.map(t => ({
              name: t.name,
              success: t.completed,
              duration: t.duration,
              error: t.error ? t.error.message : null
            }))
          },
          [InitStage.FINALIZATION]: {
            completed: status.stageStatus[InitStage.FINALIZATION].completed,
            duration: status.stageStatus[InitStage.FINALIZATION].duration,
            tasks: status.stageStatus[InitStage.FINALIZATION].tasks.map(t => ({
              name: t.name,
              success: t.completed,
              duration: t.duration,
              error: t.error ? t.error.message : null
            }))
          }
        },
        environment: {
          appVersion: DeviceInfo.getVersion(),
          buildNumber: DeviceInfo.getBuildNumber(),
          deviceModel: DeviceInfo.getModel(),
          osVersion: DeviceInfo.getSystemVersion(),
          isEmulator: DeviceInfo.isEmulator(),
          timeZone: DeviceInfo.getTimezone(),
          totalMemory: DeviceInfo.getTotalMemory(),
          totalDiskCapacity: DeviceInfo.getTotalDiskCapacity()
        }
      };
      
      // Store report for debug purposes
      await storage.set('app:last-init-report', JSON.stringify(report));
      
      // In development mode, log report
      if (__DEV__) {
        console.log('Initialization status report:', report);
      }
      
      // If initialization failed, send report to monitoring service
      if (!status.completed || status.error) {
        monitoringService.reportInitializationFailure(report);
      }
    } catch (error) {
      console.error('Status report generation failed:', error);
      // Non-critical - app can function without status report
    }
  }
};

// Register task
initializer.registerTask(InitStage.FINALIZATION, statusReportTask);
```

## Performance Considerations

* **(Do ✅) Keep finalization tasks lightweight**
  * Focus on UI transitions and state updates
  * Defer any heavy operations to later user interactions
  * Prioritize a smooth transition to interactive state

* **(Do ✅) Provide visual feedback during transition**
  * Use animations to mask any remaining work
  * Transition gradually from loading to final UI
  * Ensure all loading indicators are removed

* **(Don't ❌) Start heavyweight services immediately**
  * Defer intensive monitoring until after user interactions begin
  * Use a phased approach for enabling features
  * Consider idle-time initialization for non-critical services

* **(Do ✅) Measure and report performance**
  * Track time in each initialization stage
  * Record task-specific performance metrics
  * Identify optimization opportunities

## Practical Examples

### Transitioning from Skeleton Screens to Content

```typescript
// features/home/screens/HomeScreen.tsx
import React, { useEffect, useState } from 'react';
import { View, StyleSheet, Animated } from 'react-native';
import { useInitialization } from '@/core/shared/app/initialization';
import { SkeletonContent } from '@/ui/components/SkeletonContent';
import { FeaturedProducts } from '../components/FeaturedProducts';
import { CategoryList } from '../components/CategoryList';
import { RecentlyViewed } from '../components/RecentlyViewed';
import { useHomeData } from '@/core/domains/home/hooks';

export function HomeScreen() {
  const { initialized } = useInitialization();
  const { data: homeData, isLoading } = useHomeData();
  
  const [contentVisible, setContentVisible] = useState(false);
  const fadeAnim = useState(new Animated.Value(0))[0];
  
  // Transition from skeletons to real content
  useEffect(() => {
    if (initialized && !isLoading && homeData) {
      // Short delay to ensure smooth transition
      setTimeout(() => {
        setContentVisible(true);
        
        Animated.timing(fadeAnim, {
          toValue: 1,
          duration: 300,
          useNativeDriver: true,
        }).start();
      }, 150);
    }
  }, [initialized, isLoading, homeData, fadeAnim]);
  
  return (
    <View style={styles.container}>
      {(!contentVisible) ? (
        <SkeletonContent
          containerStyle={styles.skeletonContainer}
          isLoading={true}
          layout={[
            { key: 'banner', width: '100%', height: 200, marginBottom: 20 },
            { key: 'categories', width: '100%', height: 100, marginBottom: 20 },
            { key: 'product1', width: '48%', height: 200, marginBottom: 12 },
            { key: 'product2', width: '48%', height: 200, marginBottom: 12 },
            { key: 'section', width: '80%', height: 30, marginBottom: 10 },
            { key: 'recent1', width: '100%', height: 80, marginBottom: 10 },
            { key: 'recent2', width: '100%', height: 80, marginBottom: 10 },
          ]}
        />
      ) : (
        <Animated.ScrollView
          style={[styles.contentContainer, { opacity: fadeAnim }]}
          contentContainerStyle={styles.scrollContent}
        >
          <FeaturedProducts items={homeData.featured} />
          <CategoryList categories={homeData.categories} />
          <RecentlyViewed items={homeData.recentlyViewed} />
        </Animated.ScrollView>
      )}
    </View>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    backgroundColor: '#fff',
  },
  skeletonContainer: {
    flex: 1,
    padding: 16,
  },
  contentContainer: {
    flex: 1,
  },
  scrollContent: {
    padding: 16,
  },
});
```

### Performance Report Dashboard

```typescript
// features/developer/screens/PerformanceScreen.tsx
import React, { useEffect, useState } from 'react';
import { View, Text, StyleSheet, ScrollView, TouchableOpacity } from 'react-native';
import { storage } from '@/core/shared/utils/storage';
import { Card } from '@/ui/components/Card';
import { BarChart } from '@/ui/components/charts/BarChart';
import { Section } from '@/ui/components/Section';
import { List } from '@/ui/components/List';
import { useNavigation } from '@react-navigation/native';

export function PerformanceScreen() {
  const [report, setReport] = useState(null);
  const navigation = useNavigation();
  
  // Load performance report
  useEffect(() => {
    const loadReport = async () => {
      try {
        const reportJson = await storage.get('app:last-init-report');
        if (reportJson) {
          setReport(JSON.parse(reportJson));
        }
      } catch (error) {
        console.error('Failed to load performance report:', error);
      }
    };
    
    loadReport();
  }, []);
  
  if (!report) {
    return (
      <View style={styles.container}>
        <Text style={styles.title}>No performance data available</Text>
      </View>
    );
  }
  
  // Prepare chart data for stage durations
  const stageDurations = [
    { name: 'Pre-UI', value: report.stages[InitStage.PRE_UI].duration },
    { name: 'Initial UI', value: report.stages[InitStage.INITIAL_UI].duration },
    { name: 'Background', value: report.stages[InitStage.BACKGROUND].duration },
    { name: 'Finalization', value: report.stages[InitStage.FINALIZATION].duration },
  ];
  
  // Get the 5 slowest tasks
  const slowestTasks = Object.values(report.stages)
    .flatMap(stage => stage.tasks)
    .sort((a, b) => b.duration - a.duration)
    .slice(0, 5)
    .map(task => ({
      name: task.name,
      value: task.duration,
    }));
  
  return (
    <ScrollView style={styles.container}>
      <Text style={styles.title}>Initialization Performance</Text>
      
      <Card style={styles.card}>
        <Text style={styles.cardTitle}>Initialize in</Text>
        <Text style={styles.timeValue}>
          {`${Math.round(
            report.stages[InitStage.PRE_UI].duration +
            report.stages[InitStage.INITIAL_UI].duration +
            report.stages[InitStage.BACKGROUND].duration +
            report.stages[InitStage.FINALIZATION].duration
          )}ms`}
        </Text>
        <Text style={styles.timeSubtitle}>Total time</Text>
        
        <Text style={styles.metric}>
          {`${Math.round(
            report.stages[InitStage.PRE_UI].duration +
            report.stages[InitStage.INITIAL_UI].duration
          )}ms`}
        </Text>
        <Text style={styles.metricLabel}>Time to Interactive</Text>
      </Card>
      
      <Section title="Stage Durations">
        <BarChart
          data={stageDurations}
          style={styles.chart}
          height={200}
          xAxisLabel="Stage"
          yAxisLabel="Duration (ms)"
        />
      </Section>
      
      <Section title="Slowest Tasks">
        <BarChart
          data={slowestTasks}
          style={styles.chart}
          height={250}
          xAxisLabel="Task"
          yAxisLabel="Duration (ms)"
        />
      </Section>
      
      <Section title="Task Details">
        <List
          data={Object.values(report.stages)
            .flatMap(stage => stage.tasks)
            .sort((a, b) => b.duration - a.duration)}
          renderItem={({ item }) => (
            <View style={styles.taskItem}>
              <Text style={styles.taskName}>{item.name}</Text>
              <Text style={styles.taskDuration}>{`${item.duration}ms`}</Text>
              {item.error && (
                <Text style={styles.taskError}>{item.error}</Text>
              )}
            </View>
          )}
          keyExtractor={item => item.name}
        />
      </Section>
      
      <TouchableOpacity
        style={styles.button}
        onPress={() => {
          // Clear all initialization data and restart app
          storage.remove('app:last-init-report');
          
          Alert.alert(
            'Restart Required',
            'The app needs to restart to clear initialization data.',
            [
              {
                text: 'Cancel',
                style: 'cancel',
              },
              {
                text: 'Restart Now',
                onPress: () => {
                  RNRestart.Restart();
                },
              },
            ]
          );
        }}
      >
        <Text style={styles.buttonText}>Clear & Restart App</Text>
      </TouchableOpacity>
    </ScrollView>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    padding: 16,
    backgroundColor: '#f8f8f8',
  },
  title: {
    fontSize: 24,
    fontWeight: 'bold',
    marginBottom: 16,
  },
  card: {
    padding: 16,
    marginBottom: 24,
    borderRadius: 8,
  },
  cardTitle: {
    fontSize: 16,
    color: '#777',
    marginBottom: 8,
  },
  timeValue: {
    fontSize: 36,
    fontWeight: 'bold',
    color: '#333',
  },
  timeSubtitle: {
    fontSize: 14,
    color: '#777',
    marginBottom: 16,
  },
  metric: {
    fontSize: 20,
    fontWeight: 'bold',
    color: '#333',
  },
  metricLabel: {
    fontSize: 14,
    color: '#777',
  },
  chart: {
    marginVertical: 16,
  },
  taskItem: {
    padding: 12,
    borderBottomWidth: 1,
    borderBottomColor: '#eee',
  },
  taskName: {
    fontSize: 16,
    fontWeight: '500',
  },
  taskDuration: {
    fontSize: 14,
    color: '#666',
    marginTop: 4,
  },
  taskError: {
    fontSize: 14,
    color: '#d00',
    marginTop: 4,
  },
  button: {
    backgroundColor: '#007AFF',
    padding: 16,
    borderRadius: 8,
    alignItems: 'center',
    marginVertical: 24,
  },
  buttonText: {
    color: '#fff',
    fontSize: 16,
    fontWeight: '600',
  },
});
```

## Migration Considerations

When migrating from traditional initialization completion approaches to our Finalization stage, consider these helpful strategies:

### From Simple Loading States to Polished Transitions

Many applications use simple loading indicators that abruptly disappear when initialization completes:

```typescript
// Traditional approach
const App = () => {
  const [isInitialized, setIsInitialized] = useState(false);
  
  useEffect(() => {
    async function initialize() {
      try {
        // Perform all initialization
        await setupServices();
        await loadData();
        
        // Simply set state to initialized when complete
        setIsInitialized(true);
      } catch (error) {
        console.error('Initialization failed', error);
        setIsInitialized(true); // Still mark as initialized to prevent app from being stuck
      }
    }
    initialize();
  }, []);
  
  if (!isInitialized) {
    return <LoadingScreen />;
  }
  
  return <MainApp />;
};
```

You can enhance this with the Finalization stage pattern:

1. Add smooth transitions for removing loading indicators
2. Collect performance metrics before completing initialization
3. Enable deferred interactions that were disabled during initialization
4. Start monitoring services only after the app is fully interactive

### Enhancing User Experience During Transitions

A key improvement comes from implementing smoother transitions:

```typescript
// Finalization-aware component with smooth transitions
const AppWithFinalization = () => {
  const { initialized, currentStage } = useInitialization();
  const [fadeAnim] = useState(new Animated.Value(1));
  
  // Use effects to manage transitions based on initialization stage
  useEffect(() => {
    if (currentStage === InitStage.FINALIZATION) {
      // Register finalization tasks
      initializer.registerTask(InitStage.FINALIZATION, {
        name: 'ui:polish',
        execute: async () => {
          // Smooth fade-out loading overlay
          Animated.timing(fadeAnim, {
            toValue: 0,
            duration: 500,
            useNativeDriver: true,
          }).start();
          
          // Wait for animation to complete
          await new Promise(resolve => setTimeout(resolve, 500));
          
          // Log performance metrics
          analyticsService.logEvent('app_init_complete', {
            timeToInteractive: performance.now()
          });
        }
      });
    }
  }, [currentStage, fadeAnim]);
  
  return (
    <View style={{ flex: 1 }}>
      <MainApp />
      
      {!initialized && (
        <Animated.View 
          style={[
            styles.loadingOverlay,
            { opacity: fadeAnim }
          ]}
        >
          <LoadingIndicator stage={currentStage} />
        </Animated.View>
      )}
    </View>
  );
};
```

### Implementing Phased Migration

You can migrate to the Finalization stage pattern incrementally:

1. Start by simply wrapping your current loading removal logic in a Finalization task
2. Add performance measurement to collect initialization metrics
3. Gradually enhance the transitions between loading and fully interactive states
4. Implement deferred feature activation for non-critical functionality

The Finalization stage allows you to create a professional, polished transition from initialization to full app functionality, significantly improving perceived performance and user experience.

## Summary

The Finalization stage completes the application initialization process that began with the [Pre-UI stage](/docs/guides/app-initialization/pre-ui), continued through the [Initial UI stage](/docs/guides/app-initialization/initial-ui) and [Background stage](/docs/guides/app-initialization/background), ensuring a smooth transition from loading to fully interactive state. By carefully implementing this stage, you can create a polished user experience that feels responsive and professional.

Key principles to remember:

* Remove all loading indicators and show the final UI state
* Enable all deferred interactions and features
* Collect and report performance metrics
* Start monitoring and background services
* Perform cleanup and optimization

By following these patterns, you'll ensure that your application completes its initialization process smoothly and provides users with a fully functional, responsive experience from the very beginning of their session.

## Related Documents

### Core Initialization Documentation

* [App Initialization Architecture](/docs/architecture/app-initialization) - Overview of the complete initialization architecture
* [App Initialization Guides](/docs/guides/app-initialization) - Index of all initialization guides

### Other Initialization Stages

* [Pre-UI Initialization Guide](/docs/guides/app-initialization/pre-ui) - First initialization stage
* [Initial UI Rendering Guide](/docs/guides/app-initialization/initial-ui) - Initial UI rendering stage
* [Background Initialization Guide](/docs/guides/app-initialization/background) - Stage before Finalization

### Related Implementation Guides

* [Performance Monitoring Guide](/docs/performance/monitoring) - Monitoring app performance after initialization
* [Analytics Implementation Guide](/docs/integrations/analytics) - Setting up analytics during finalization
* [Animation Techniques](/docs/ui/animations) - Creating smooth transitions between loading states


# UTA Implementation Guides: Offline Support Overview
URL: https://dev.updatetheapp.com/docs/guides/offline/overview
Documentation: https://dev.updatetheapp.com/docs/guides/offline/overview

A comprehensive guide to implementing offline capabilities in React Native applications.
        
***

title: Offline Support Overview
description: A comprehensive guide to implementing offline capabilities in React Native applications.
-----------------------------------------------------------------------------------------------------

# Offline Support Overview

## Introduction

This guide provides a comprehensive overview of implementing offline support in React Native applications. It covers various aspects from basic connectivity monitoring to advanced data synchronization.

## Core Components

The offline support implementation is divided into several key areas, each covered in detail in its dedicated guide:

1. [Connectivity Management](/docs/guides/offline/connectivity)
   * Network state monitoring
   * Online/offline detection
   * Connection type handling

2. [Query Caching](/docs/guides/offline/query-caching)
   * Data persistence strategies
   * Cache management
   * Stale data handling

3. [Mutation Queueing](/docs/guides/offline/mutation-queueing)
   * Offline action storage
   * Queue management
   * Error handling

4. [Data Synchronization](/docs/guides/offline/synchronization)
   * Background sync
   * Conflict resolution
   * Data reconciliation

5. [UI Feedback](/docs/guides/offline/ui-feedback)
   * Connection status indicators
   * Sync progress display
   * Error notifications

## Prerequisites

Before implementing offline support, ensure you have:

* `@react-native-community/netinfo` installed and configured
* `AsyncStorage` or another local storage mechanism
* TanStack Query setup (see [Server State Management Guide](/docs/guides/server-state-management))
* Core API services and structure
* Basic understanding of the Security & Offline Framework

## Alternative Approaches

Consider these alternatives for specific use cases:

1. **Dedicated Offline-First Databases**
   * WatermelonDB
   * Realm
   * Benefits: More robust capabilities
   * Trade-offs: Steeper learning curve

2. **Server-Driven Offline**
   * Backend platform SDKs
   * Benefits: Automated sync
   * Trade-offs: Platform lock-in

## Getting Started

Start with the [Connectivity Management](/docs/guides/offline/connectivity) guide to implement basic offline detection, then proceed through the other guides based on your application's needs.


# UTA Implementation Guides: Offline Connectivity Management
URL: https://dev.updatetheapp.com/docs/guides/offline/connectivity
Documentation: https://dev.updatetheapp.com/docs/guides/offline/connectivity

Implementing network state monitoring and connectivity detection in React Native applications.
        
***

title: 'Offline Connectivity Management'
description: Implementing network state monitoring and connectivity detection in React Native applications.
-----------------------------------------------------------------------------------------------------------

import { Steps } from 'fumadocs-ui/components/steps';

# Offline Connectivity Management

## Overview

This guide focuses on implementing robust connectivity monitoring in React Native applications.

* **Problem Solved**: Ensures the application is aware of its online/offline status and can react accordingly.
* **When to Apply**: Essential for any application that needs to function or provide feedback when network access is unavailable or unreliable.
* **Expected Outcomes**: A reliable system for detecting network changes, providing this information to the application, and triggering appropriate actions (e.g., switching to offline mode, queueing data).

## When To Use

* **Scenarios**:
  * Applications that need to cache data for offline viewing.
  * Apps that allow users to perform actions offline that will be synced later.
  * Situations where providing immediate feedback about connection status improves user experience.
  * When needing to conserve battery or data by altering behavior based on connection type (e.g., Wi-Fi vs. cellular).
* **Prerequisites**:
  * `@react-native-community/netinfo` library installed and configured.
  * A basic understanding of React Context API for state management.
* **Alternatives to Consider**:
  * For very simple use cases, polling a known endpoint (less efficient).
  * Relying on individual API call failures (less proactive).

## Architecture

This diagram illustrates how the `NetInfo` module interacts with the `ConnectivityContext` to provide status updates to application components.

<Mermaid
  chart={`
flowchart TD
  A[NetInfo Module] -->|Event Listener: State Updates| B(ConnectivityContext)
  B -->|isOnline, connectionType, wasOfflineSinceLastCheck| C{React Components}
  C -->|useConnectivity Hook| B

  subgraph CoreOfflineModule [core/offline]
      B
  end
  
  subgraph ApplicationUI [Application UI]
      C
  end
`}
/>

## Implementation Patterns

<Steps>
  ### 1. Connectivity Context

  Create a React Context (`ConnectivityContext`) to manage and broadcast connectivity state. This context will hold `isOnline`, `connectionType`, and `wasOfflineSinceLastCheck` flags.

  ```typescript
  // src/core/offline/context/ConnectivityContext.tsx
  import React, { createContext, useState, useEffect, useContext, useRef, ReactNode } from 'react';
  import NetInfo, { NetInfoState, NetInfoStateType } from '@react-native-community/netinfo';

  interface ConnectivityContextType {
    isOnline: boolean;
    wasOfflineSinceLastCheck: boolean; // True if transitioned from offline to online since last check
    connectionType: NetInfoStateType | null;
    connectionDetails: NetInfoState['details'] | null;
  }

  const initialState: ConnectivityContextType = {
    isOnline: true, // Assume online initially until first check
    wasOfflineSinceLastCheck: false,
    connectionType: null,
    connectionDetails: null,
  };

  const ConnectivityContext = createContext<ConnectivityContextType>(initialState);

  export const ConnectivityProvider: React.FC<{children: ReactNode}> = ({ children }) => {
    const [isOnline, setIsOnline] = useState<boolean>(initialState.isOnline);
    const [wasOfflineSinceLastCheck, setWasOfflineSinceLastCheck] = useState<boolean>(initialState.wasOfflineSinceLastCheck);
    const [connectionType, setConnectionType] = useState<NetInfoStateType | null>(initialState.connectionType);
    const [connectionDetails, setConnectionDetails] = useState<NetInfoState['details'] | null>(initialState.connectionDetails);

    const previousIsOnline = useRef(isOnline); // Ref to track the previous online status

    useEffect(() => {
      const unsubscribe = NetInfo.addEventListener((state: NetInfoState) => {
        const currentOnlineStatus = !!state.isConnected && !!state.isInternetReachable;

        if (!previousIsOnline.current && currentOnlineStatus) {
          setWasOfflineSinceLastCheck(true); // Went from offline to online
        } else if (previousIsOnline.current && !currentOnlineStatus) {
          setWasOfflineSinceLastCheck(false); // Went from online to offline, reset flag
        } else if (currentOnlineStatus) {
          setWasOfflineSinceLastCheck(false); // Still online, reset flag
        }
        // If still offline, wasOfflineSinceLastCheck remains as is (potentially true if it was set by a quick blip)

        setIsOnline(currentOnlineStatus);
        setConnectionType(state.type);
        setConnectionDetails(state.details);
        previousIsOnline.current = currentOnlineStatus; // Update ref for next event
      });

      // Fetch initial state once
      NetInfo.fetch().then((state: NetInfoState) => {
        const initialOnlineStatus = !!state.isConnected && !!state.isInternetReachable;
        setIsOnline(initialOnlineStatus);
        setConnectionType(state.type);
        setConnectionDetails(state.details);
        previousIsOnline.current = initialOnlineStatus;
      });

      return () => unsubscribe(); // Cleanup listener on unmount
    }, []);

    return (
      <ConnectivityContext.Provider
        value={{ isOnline, wasOfflineSinceLastCheck, connectionType, connectionDetails }}
      >
        {children}
      </ConnectivityContext.Provider>
    );
  };

  export const useConnectivity = (): ConnectivityContextType => {
    const context = useContext(ConnectivityContext);
    if (context === undefined) {
      throw new Error('useConnectivity must be used within a ConnectivityProvider');
    }
    return context;
  };
  ```

  ### 2. Application Setup

  Wrap your root application component with the `ConnectivityProvider`.

  ```typescript
  // App.tsx
  import React from 'react';
  import { ConnectivityProvider } from '@/core/offline/context/ConnectivityContext';
  // ... other imports for your app (Navigation, Redux Provider, etc.)

  const App = () => {
    return (
      <ConnectivityProvider>
        {/* Your main app navigation and screens */}
      </ConnectivityProvider>
    );
  };

  export default App;
  ```

  ### 3. Using Connectivity Information

  Consume the connectivity state in any component using the `useConnectivity` hook.

  ```typescript
  // src/components/MyNetworkAwareComponent.tsx
  import React, { useEffect } from 'react';
  import { View, Text, StyleSheet } from 'react-native';
  import { useConnectivity } from '@/core/offline/context/ConnectivityContext';

  const MyNetworkAwareComponent = () => {
    const { isOnline, connectionType, wasOfflineSinceLastCheck } = useConnectivity();

    useEffect(() => {
      if (wasOfflineSinceLastCheck) {
        console.log('Device was offline and is now back online. Triggering sync...');
        // Example: Trigger a data synchronization process
        // syncData();
      }
    }, [wasOfflineSinceLastCheck]);

    return (
      <View style={styles.container}>
        <Text style={isOnline ? styles.online : styles.offline}>
          Connection Status: {isOnline ? 'Online' : 'Offline'}
        </Text>
        {isOnline && connectionType && (
          <Text>Connection Type: {connectionType}</Text>
        )}
        {wasOfflineSinceLastCheck && isOnline && (
          <Text style={styles.syncMessage}>Syncing pending data...</Text>
        )}
      </View>
    );
  };

  const styles = StyleSheet.create({
    container: { padding: 10 },
    online: { color: 'green' },
    offline: { color: 'red' },
    syncMessage: { color: 'blue', marginTop: 5 },
  });

  export default MyNetworkAwareComponent;
  ```
</Steps>

## Common Challenges

* **Fluctuating Signal**: Network state can change rapidly.
  * **Solution**: Implement debouncing or a minimum "offline" duration before changing UI or behavior drastically. The `wasOfflineSinceLastCheck` flag helps manage actions upon returning online.
* **`isInternetReachable` Nuances**: This flag can sometimes be unreliable on certain OS versions or network configurations.
  * **Solution**: For critical operations, supplement with a quick "ping" to a reliable server if `isInternetReachable` is true but operations still fail.
* **Initial State**: `NetInfo.fetch()` provides an initial state, but a listener should also be set up immediately as the state can change between the fetch and listener registration.
  * **Solution**: The provided `ConnectivityProvider` handles this by fetching initial state and then relying on the event listener.

## Performance Considerations

* (Do ✅) Use the `useConnectivity` hook **selectively** in components that actually need to react to network changes.
* (Do ✅) **Memoize** components that consume connectivity context if they are expensive to re-render, though the context value changes infrequently.
* (Don't ❌) Trigger **expensive operations** (e.g., full data re-fetch) directly on every `isOnline` state change without further logic (like checking `wasOfflineSinceLastCheck` or specific needs).
* (Consider 🤔) Implementing **logic to adjust data fetching frequency** based on `connectionType` (e.g., less frequent updates on cellular data vs. Wi-Fi).
* (Be Aware ❗) The `NetInfo` event listener itself is lightweight, but frequent context updates could cause re-renders. React's reconciliation is generally efficient, but be mindful in complex UIs.

## Best Practices (Do's and Don'ts)

### Connection Validation

* (Do ✅) Rely on **`isInternetReachable`** in conjunction with `isConnected` for a more accurate assessment of internet availability.
* (Do ✅) For critical online-only actions, consider an **application-level ping test** to a trusted endpoint as a final confirmation if `NetInfo` reports online but actions fail.
* (Don't ❌) Assume `isConnected === true` always means full internet access. It might only indicate a local network connection.
* (Don't ❌) Trigger **immediate data fetches** or UI changes on every minor fluctuation without some form of debouncing or threshold if the connection is unstable.

### State Management & UI Feedback

* (Do ✅) Use the `wasOfflineSinceLastCheck` flag to trigger **specific actions** (like data sync) only when transitioning from an offline to an online state.
* (Do ✅) Provide **clear visual feedback** to the user about the current connectivity status (e.g., a banner, an icon).
* (Don't ❌) Block the UI unnecessarily when offline if the app can offer some functionality.
* (Consider 🤔) Using a **global state management system** (like Redux or Zustand) in conjunction with the context if connectivity status needs to drive complex, app-wide state changes beyond simple UI updates.

### Error Handling & Reliability

* (Do ✅) Ensure the `ConnectivityProvider` is placed **high in the component tree** to be available globally.
* (Do ✅) Handle the `useContext` for `ConnectivityContext` potentially returning `undefined` if not used within the provider (as shown in the hook implementation).
* (Don't ❌) Assume `NetInfo` will always provide an immediate and perfectly accurate state, especially during rapid network changes or in unusual network environments.
* (Be Aware ❗) The behavior and reliability of `NetInfo` can have slight variations between **iOS and Android**, and even between OS versions. Test thoroughly on target devices.

## State Transitions Diagram

This diagram shows the possible states and transitions managed by the `ConnectivityProvider`.

<Mermaid
  chart={`
stateDiagram-v2
  [*] --> Initializing
  Initializing --> Online: NetInfo reports connected & reachable
  Initializing --> Offline: NetInfo reports disconnected or not reachable

  Online --> Offline: Connection Lost (isConnected=false or isInternetReachable=false)
  Offline --> Online: Connection Restored (isConnected=true and isInternetReachable=true)

  Online --> Online: State Refreshed (still online)
  Offline --> Offline: State Refreshed (still offline)
`}
/>

## Next Steps

Continue to the [Query Caching](/docs/guides/offline/query-caching) guide to learn how to persist data from your API (e.g., using TanStack Query) for offline access.


# UTA Implementation Guides: Code Review Templates
URL: https://dev.updatetheapp.com/docs/guides/code-review-templates
Documentation: https://dev.updatetheapp.com/docs/guides/code-review-templates

Experience-based code review templates to ensure consistent feedback and learning
        
***

title: Code Review Templates
description: Experience-based code review templates to ensure consistent feedback and learning
----------------------------------------------------------------------------------------------

import { Tabs, Tab } from 'fumadocs-ui/components/tabs';
import { Callout } from 'fumadocs-ui/components/callout';

# Code Review Templates

## Overview

These templates ensure code reviews are consistent, educational, and appropriate for the developer's experience level. Use the correct template based on the PR author's experience.

<Callout type="info">
  Code reviews are not just about finding bugs - they're opportunities for learning, knowledge sharing, and ensuring our "single author" consistency.
</Callout>

## Review Templates by Experience Level

<Tabs items={["Junior Developer", "Mid-Level Developer", "Senior Developer", "Cross-Team Review"]}>
  <Tab>
    ## Code Review - Junior Developer

    ### ✅ Compliance Checklist

    * [ ] File placement follows decision tree
    * [ ] Naming conventions followed exactly
    * [ ] No TypeScript `any` types used
    * [ ] Error handling present for all async operations
    * [ ] Tests included for new functionality
    * [ ] Documentation updated

    ### 📚 Learning Objectives

    * [ ] **Understands why** this approach was chosen
    * [ ] **Can explain** the code's purpose clearly
    * [ ] **Identifies** potential edge cases

    ### 🎯 Growth Areas

    Please provide:

    1. **One improvement** for code clarity
    2. **One performance** consideration
    3. **One additional** test case

    ### 💬 Feedback Format

    ````markdown
    ## What's Great 👍
    - [Specific positive feedback with examples]

    ## Required Changes 🔧
    1. [Clear, actionable change with example]
       ```typescript
       // Current
       [current code]
       
       // Suggested
       [improved code]
    ````

    ## Learning Opportunities 📖

    * \[Link to relevant documentation]
    * \[Pattern to study in existing codebase]

    ## Questions for Understanding 🤔

    * Can you explain why you chose \[specific approach]?
    * What edge cases did you consider?

    ````

    ### 🎓 Mentorship Notes
    - Focus on teaching, not just correcting
    - Provide examples from our codebase
    - Encourage questions
    </Tab>

    <Tab>
    ## Code Review - Mid-Level Developer

    ### ✅ Compliance Checklist
    - [ ] Architecture aligns with established patterns
    - [ ] Proper abstraction levels maintained
    - [ ] Performance implications considered
    - [ ] Security best practices followed
    - [ ] Integration points properly handled
    - [ ] Documentation comprehensive

    ### 🏗️ Architectural Alignment
    - [ ] **Follows** domain boundaries correctly
    - [ ] **Maintains** separation of concerns
    - [ ] **Reuses** existing patterns appropriately

    ### 🔍 Deep Dive Areas
    1. **Pattern Consistency**: Compare with similar features
    2. **Error Scenarios**: Validate all paths covered
    3. **Performance Impact**: Check for N+1, memory leaks
    4. **Test Quality**: Beyond coverage numbers

    ### 💬 Feedback Format
    ```markdown
    ## Architecture & Design 🏛️
    - [Comments on structural decisions]

    ## Implementation Quality 💎
    - [Specific code quality observations]

    ## Suggestions for Enhancement 🚀
    1. [Advanced pattern that could be applied]
    2. [Performance optimization opportunity]

    ## Knowledge Sharing 🤝
    - [Pattern that others could learn from]
    - [Candidate for shared utility/component]
    ````

    ### 🎯 Focus Areas

    * Pattern recognition and reuse
    * Cross-feature consistency
    * Performance optimization opportunities
  </Tab>

  <Tab>
    ## Code Review - Senior Developer

    ### ✅ Strategic Checklist

    * [ ] Aligns with long-term architecture vision
    * [ ] Considers scalability implications
    * [ ] Maintains backward compatibility
    * [ ] Security review completed
    * [ ] Performance benchmarked
    * [ ] Architectural decisions documented

    ### 🏛️ Strategic Alignment

    * [ ] **Future-proof** design decisions
    * [ ] **Scalability** addressed
    * [ ] **Technical debt** not increased

    ### 🧠 Knowledge Transfer

    Document for team learning:

    1. **One key decision** and its rationale
    2. **Reusable pattern** introduced
    3. **Documentation** for complex areas

    ### 💬 Feedback Format

    ```markdown
    ## Strategic Considerations 🎯
    - [Long-term implications]
    - [Architectural alignment]

    ## Technical Excellence 🏆
    - [Advanced patterns used well]
    - [Performance optimizations noted]

    ## Team Impact 👥
    - [Knowledge sharing opportunities]
    - [Patterns to evangelize]
    - [Documentation improvements needed]

    ## Risk Assessment ⚠️
    - [Potential issues identified]
    - [Mitigation strategies]
    ```

    ### 🎓 Leadership Focus

    * Identify teaching opportunities
    * Document architectural decisions
    * Set patterns for others to follow
  </Tab>

  <Tab>
    ## Cross-Team Review

    ### ✅ Integration Checklist

    * [ ] API contracts maintained
    * [ ] No breaking changes introduced
    * [ ] Dependencies properly managed
    * [ ] Performance SLAs met
    * [ ] Security standards upheld
    * [ ] Documentation updated

    ### 🔗 Integration Points

    * [ ] **API compatibility** verified
    * [ ] **Event contracts** maintained
    * [ ] **Shared types** properly updated

    ### 🤝 Collaboration Areas

    1. **Shared Components**: Impact on other teams
    2. **API Changes**: Migration strategy needed?
    3. **Performance**: Impact on dependent services

    ### 💬 Feedback Format

    ```markdown
    ## Integration Impact 🔗
    - [Changes affecting other teams]
    - [Migration requirements]

    ## Shared Resources 🤲
    - [Components/utilities that could be shared]
    - [Patterns other teams could adopt]

    ## Compatibility Notes 📋
    - [Backward compatibility maintained]
    - [Breaking changes documented]

    ## Communication Needed 📢
    - [Teams to notify]
    - [Documentation to update]
    ```
  </Tab>
</Tabs>

## Review Response Templates

### For PR Authors

```markdown
## PR Author Response Template

### Changes Made ✅
- [x] Fixed [issue 1] as suggested
- [x] Updated [component] to follow pattern
- [ ] Refactored [function] - need clarification

### Questions 🤔
1. Regarding [feedback point], could you clarify...?
2. I chose [approach] because... Is there a better pattern?

### Learning Notes 📚
- Learned about [pattern/concept]
- Will apply [technique] in future PRs
```

### For Reviewers Following Up

```markdown
## Follow-up Review

### Previous Concerns ✅
- [x] [Issue 1] - Resolved
- [x] [Issue 2] - Addressed well
- [ ] [Issue 3] - Still needs work

### New Observations 👀
- [Any new issues found]

### Ready to Merge? 🚀
[ ] Yes, all concerns addressed
[ ] No, see remaining items above
```

## Best Practices

### For All Reviews

1. **Be Specific**: Point to exact lines and provide examples
2. **Be Kind**: Remember there's a person reading your feedback
3. **Be Educational**: Every review is a learning opportunity
4. **Be Consistent**: Apply standards uniformly

### Review Timing

* **Initial Review**: Within 4 hours of PR creation
* **Follow-up**: Within 2 hours of changes
* **Final Approval**: After all checks pass

### Escalation Path

1. **Disagreement on Approach**: Consult team lead
2. **Architecture Concerns**: Schedule design review
3. **Breaking Changes**: Require additional approvals

## Automation Support

### Pre-Review Checks

```bash
# Run before requesting review
npm run pre-review

# This runs:
# - TypeScript check
# - Linting
# - Tests
# - Bundle size check
# - Documentation check
```

### Review Assignment

Based on PR content and developer experience:

* **UI Changes**: Assign UI expert
* **API Changes**: Assign backend expert
* **Critical Path**: Require 2 reviewers
* **Junior PR**: Assign mentor + peer

## Related Documents

* [Coding Standards](/docs/coding-standards)
* [Testing Requirements](/docs/testing/requirements)
* [Documentation Standards](/docs/documentation/standards)
* [Team Onboarding](/docs/guides/team-onboarding-checklist)


# UTA Implementation Guides: Common Pitfalls & Solutions
URL: https://dev.updatetheapp.com/docs/guides/common-pitfalls-solutions
Documentation: https://dev.updatetheapp.com/docs/guides/common-pitfalls-solutions

Real-world mistakes developers make and how to fix them - learn from others' experiences
        
***

title: Common Pitfalls & Solutions
description: Real-world mistakes developers make and how to fix them - learn from others' experiences
-----------------------------------------------------------------------------------------------------

import { Callout } from 'fumadocs-ui/components/callout';
import { Tabs, Tab } from 'fumadocs-ui/components/tabs';

# Common Pitfalls & Solutions

## Overview

This guide documents the most common mistakes developers make in our codebase and provides clear solutions. Each pitfall includes real examples from code reviews, why it's problematic, and the correct approach.

<Callout type="info">
  **For Junior Developers**: These are mistakes we've all made. Learning from them will accelerate your growth.

  **For AI Assistants**: Avoid these patterns and apply the solutions when generating code.
</Callout>

## Navigation & Architecture Pitfalls

### Pitfall 1: Creating Duplicate Business Logic

**The Problem**: Implementing the same business logic in multiple places instead of using existing domains.

<Tabs items={["❌ Wrong Way", "✅ Correct Way", "📝 Explanation"]}>
  <Tab>
    ```typescript
    // features/checkout/utils/calculateDiscount.ts
    export function calculateDiscount(price: number, discountPercent: number) {
      return price * (discountPercent / 100);
    }

    // features/product-detail/components/PriceDisplay.tsx
    function PriceDisplay({ product }) {
      // Reimplementing discount calculation
      const discount = product.price * (product.discountPercent / 100);
      const finalPrice = product.price - discount;
      
      return <Text>${finalPrice}</Text>;
    }
    ```
  </Tab>

  <Tab>
    ```typescript
    // core/domains/products/utils.ts
    export function calculateProductDiscount(product: Product) {
      if (!product.discountPercent) return 0;
      return product.price * (product.discountPercent / 100);
    }

    export function getProductFinalPrice(product: Product) {
      return product.price - calculateProductDiscount(product);
    }

    // features/checkout/components/CheckoutSummary.tsx
    import { getProductFinalPrice } from '@/core/domains/products';

    function CheckoutSummary({ items }) {
      const total = items.reduce((sum, item) => 
        sum + getProductFinalPrice(item.product) * item.quantity, 0
      );
      // ...
    }

    // features/product-detail/components/PriceDisplay.tsx
    import { getProductFinalPrice, calculateProductDiscount } from '@/core/domains/products';

    function PriceDisplay({ product }) {
      const finalPrice = getProductFinalPrice(product);
      const discount = calculateProductDiscount(product);
      
      return <Text>${finalPrice}</Text>;
    }
    ```
  </Tab>

  <Tab>
    **Why it's wrong**:

    * Code duplication leads to inconsistencies
    * Bug fixes must be applied in multiple places
    * Different implementations may calculate differently

    **Solution**:

    * Always check if logic exists in domains first
    * Create domain utilities for business logic
    * Import and reuse instead of reimplementing
  </Tab>
</Tabs>

### Pitfall 2: Wrong File Placement

**The Problem**: Putting files in incorrect locations, breaking the project structure.

<Tabs items={["❌ Wrong Way", "✅ Correct Way", "📝 Explanation"]}>
  <Tab>
    ```bash
    # Common wrong placements:

    # 1. Domain logic in features
    src/features/products/api/productService.ts
    src/features/products/hooks/useProducts.ts

    # 2. Shared components in features
    src/features/home/components/Button.tsx

    # 3. Feature-specific utils in shared
    src/core/shared/utils/calculateCartTotal.ts

    # 4. Wrong UI component placement
    src/ui/ProductCard.tsx  # Missing layer
    src/ui/components/Button.tsx  # Wrong structure

    # 5. Mixing concerns in one file
    src/features/auth/AuthScreen.tsx # Contains screen, styles, API calls, and business logic
    ```
  </Tab>

  <Tab>
    ```bash
    # Correct placements:

    # 1. Domain logic in domains
    src/core/domains/products/api.ts
    src/core/domains/products/hooks.ts

    # 2. Foundation components in ui/foundation
    src/ui/foundation/Button/Button.tsx

    # 3. Pattern components in ui/patterns
    src/ui/patterns/Modal/Modal.tsx

    # 4. Business components in ui/business
    src/ui/business/ProductCard/ProductCard.tsx

    # 5. Feature utils stay in feature
    src/features/cart/utils/calculateTotal.ts

    # 6. Proper separation of concerns
    src/features/auth/
    ├── screens/
    │   └── AuthScreen/
    │       ├── AuthScreen.tsx      # Only UI logic
    │       ├── styles.ts           # Styles separated
    │       └── index.ts
    └── components/
        └── LoginForm/
            └── LoginForm.tsx       # Delegates to domain
    ```
  </Tab>

  <Tab>
    **Why it's wrong**:

    * Makes code hard to find
    * Breaks reusability
    * Violates separation of concerns
    * Confuses UI architecture layers

    **Solution**:

    * Use the [Feature Implementation Decision Tree](/docs/guides/feature-implementation-decision-tree)
    * Follow the 3+ rule for shared code
    * Keep business logic in domains
    * Use correct UI layer (foundation/patterns/business)
  </Tab>
</Tabs>

### Pitfall 3: Incorrect Import Paths

**The Problem**: Using relative imports everywhere or incorrect absolute imports.

<Tabs items={["❌ Wrong Way", "✅ Correct Way", "📝 Explanation"]}>
  <Tab>
    ```typescript
    // Deep relative imports
    import { Button } from '../../../ui/Button';
    import { useAuth } from '../../../../core/domains/auth/hooks';
    import { formatDate } from '../../../shared/utils/date';

    // Wrong absolute imports
    import { Button } from 'ui/Button'; // Missing @/
    import { Button } from '@/ui/Button'; // Missing layer
    import { useAuth } from '@core/domains/auth'; // Wrong alias
    import { api } from 'src/core/api'; // Using src/

    // Circular imports
    // In features/cart/components/CartItem.tsx
    import { CartScreen } from '../screens/CartScreen';
    ```
  </Tab>

  <Tab>
    ```typescript
    // Correct absolute imports using @ alias
    import { Button } from '@/ui/foundation/Button';
    import { Modal } from '@/ui/patterns/Modal';
    import { ProductCard } from '@/ui/business/ProductCard';
    import { useAuth } from '@/core/domains/auth';
    import { formatDate } from '@/core/shared/utils/date';

    // Relative imports only for local files
    import { CartItemSkeleton } from './CartItemSkeleton';
    import { styles } from './styles';

    // No circular dependencies - proper hierarchy
    // In features/cart/components/CartItem.tsx
    // Never import from parent screens
    // Screens import from components, not vice versa
    ```
  </Tab>

  <Tab>
    **Why it's wrong**:

    * Relative imports break when moving files
    * Inconsistent import styles
    * Circular dependencies cause runtime errors
    * Missing UI architecture layers

    **Solution**:

    * Always use `@/` for absolute imports
    * Include correct UI layer (foundation/patterns/business)
    * Only use relative imports for same-folder files
    * Follow the dependency hierarchy
  </Tab>
</Tabs>

## State Management Pitfalls

### Pitfall 4: State in Wrong Place

**The Problem**: Putting state at the wrong level or using wrong state type.

<Tabs items={["❌ Wrong Way", "✅ Correct Way", "📝 Explanation"]}>
  <Tab>
    ```typescript
    // 1. Global state for local data
    // stores/uiStore.ts
    interface UIStore {
      currentProductFilters: ProductFilters; // Feature-specific!
      isCartDrawerOpen: boolean;
      selectedProductId: string; // View-specific!
    }

    // 2. Local state for shared data
    function ProductCard({ product }) {
      // This discount is used by multiple components!
      const [discount, setDiscount] = useState(0);
      
      useEffect(() => {
        // Fetching in component instead of using domain
        fetch(`/api/products/${product.id}/discount`)
          .then(res => res.json())
          .then(data => setDiscount(data.discount));
      }, [product.id]);
    }

    // 3. Props drilling instead of context
    function App() {
      const [user, setUser] = useState(null);
      return <Screen1 user={user} setUser={setUser} />;
    }

    function Screen1({ user, setUser }) {
      return <Screen2 user={user} setUser={setUser} />;
    }
    // ... 5 levels deep
    ```
  </Tab>

  <Tab>
    ```typescript
    // 1. Feature state stays in feature
    // features/product-catalog/state/filterStore.ts
    interface ProductFilterStore {
      filters: ProductFilters;
      setFilters: (filters: ProductFilters) => void;
    }

    // 2. Server state uses React Query
    function ProductCard({ product }) {
      // Get discount from domain hook
      const { data: discount } = useProductDiscount(product.id);
    }

    // 3. Shared state uses proper context or store
    // core/domains/auth/context.tsx
    const AuthContext = createContext<AuthState>(null);

    export function AuthProvider({ children }) {
      const auth = useAuthStore();
      return <AuthContext.Provider value={auth}>{children}</AuthContext.Provider>;
    }

    // Any component can access without props
    function DeepComponent() {
      const { user } = useAuth(); // Clean!
    }
    ```
  </Tab>

  <Tab>
    **Why it's wrong**:

    * Global state becomes bloated
    * Props drilling makes refactoring hard
    * Local state can't be shared when needed

    **Solution**:

    * Server state → React Query
    * Global app state → Zustand stores
    * Feature state → Feature-level stores
    * UI state → Component state
  </Tab>
</Tabs>

### Pitfall 5: Direct State Mutations

**The Problem**: Mutating state directly instead of creating new references.

<Tabs items={["❌ Wrong Way", "✅ Correct Way", "📝 Explanation"]}>
  <Tab>
    ```typescript
    // 1. Array mutations
    function TodoList() {
      const [todos, setTodos] = useState([]);
      
      const addTodo = (todo) => {
        todos.push(todo); // ❌ Mutating!
        setTodos(todos); // React won't re-render
      };
      
      const removeTodo = (index) => {
        todos.splice(index, 1); // ❌ Mutating!
        setTodos(todos);
      };
    }

    // 2. Object mutations
    function UserProfile() {
      const [user, setUser] = useState({ name: '', email: '' });
      
      const updateName = (name) => {
        user.name = name; // ❌ Mutating!
        setUser(user);
      };
    }

    // 3. Nested mutations
    function Settings() {
      const [config, setConfig] = useState({
        theme: { primary: 'blue' },
        notifications: { email: true }
      });
      
      const updateTheme = (color) => {
        config.theme.primary = color; // ❌ Deep mutation!
        setConfig(config);
      };
    }
    ```
  </Tab>

  <Tab>
    ```typescript
    // 1. Array immutable updates
    function TodoList() {
      const [todos, setTodos] = useState([]);
      
      const addTodo = (todo) => {
        setTodos([...todos, todo]); // ✅ New array
      };
      
      const removeTodo = (index) => {
        setTodos(todos.filter((_, i) => i !== index)); // ✅ New array
      };
      
      const updateTodo = (index, updates) => {
        setTodos(todos.map((todo, i) => 
          i === index ? { ...todo, ...updates } : todo
        )); // ✅ New array with new objects
      };
    }

    // 2. Object immutable updates
    function UserProfile() {
      const [user, setUser] = useState({ name: '', email: '' });
      
      const updateName = (name) => {
        setUser({ ...user, name }); // ✅ New object
      };
      
      const updateMultiple = (updates) => {
        setUser(prev => ({ ...prev, ...updates })); // ✅ Using callback
      };
    }

    // 3. Nested immutable updates
    function Settings() {
      const [config, setConfig] = useState({
        theme: { primary: 'blue' },
        notifications: { email: true }
      });
      
      const updateTheme = (color) => {
        setConfig(prev => ({
          ...prev,
          theme: { ...prev.theme, primary: color } // ✅ New nested object
        }));
      };
    }
    ```
  </Tab>

  <Tab>
    **Why it's wrong**:

    * React compares references for re-renders
    * Mutations don't create new references
    * Components won't update

    **Solution**:

    * Always create new objects/arrays
    * Use spread operator or array methods
    * Consider Immer for complex updates
  </Tab>
</Tabs>

## Component Pitfalls

### Pitfall 6: Inline Everything

**The Problem**: Creating functions, objects, and styles inline in render.

<Tabs items={["❌ Wrong Way", "✅ Correct Way", "📝 Explanation"]}>
  <Tab>
    ```typescript
    function ProductList({ products }) {
      return (
        <FlatList
          data={products}
          // ❌ New function every render
          renderItem={({ item }) => (
            <TouchableOpacity 
              // ❌ New function every render
              onPress={() => navigateToProduct(item.id)}
              // ❌ New object every render
              style={{
                padding: 16,
                backgroundColor: '#fff',
                marginBottom: 8
              }}
            >
              <Text>{item.name}</Text>
            </TouchableOpacity>
          )}
          // ❌ New function every render
          keyExtractor={(item) => item.id}
        />
      );
    }

    function UserProfile() {
      return (
        <View>
          <Avatar
            // ❌ New object every render  
            user={{ name: 'John', avatar: 'url' }}
            // ❌ Complex inline computation
            size={Dimensions.get('window').width * 0.3}
          />
        </View>
      );
    }
    ```
  </Tab>

  <Tab>
    ```typescript
    // Define styles outside component
    const styles = StyleSheet.create({
      item: {
        padding: 16,
        backgroundColor: '#fff',
        marginBottom: 8
      }
    });

    // Calculate constants outside or memoize
    const AVATAR_SIZE = Dimensions.get('window').width * 0.3;

    function ProductList({ products }) {
      // Memoize callbacks
      const handleItemPress = useCallback((id: string) => {
        navigateToProduct(id);
      }, []);
      
      // Memoize render functions
      const renderItem = useCallback(({ item }: { item: Product }) => (
        <TouchableOpacity 
          onPress={() => handleItemPress(item.id)}
          style={styles.item}
        >
          <Text>{item.name}</Text>
        </TouchableOpacity>
      ), [handleItemPress]);
      
      // Stable reference
      const keyExtractor = useCallback((item: Product) => item.id, []);
      
      return (
        <FlatList
          data={products}
          renderItem={renderItem}
          keyExtractor={keyExtractor}
        />
      );
    }

    function UserProfile() {
      // Stable user object
      const user = useMemo(() => ({
        name: 'John',
        avatar: 'url'
      }), []);
      
      return (
        <View>
          <Avatar
            user={user}
            size={AVATAR_SIZE}
          />
        </View>
      );
    }
    ```
  </Tab>

  <Tab>
    **Why it's wrong**:

    * Causes unnecessary re-renders
    * Poor performance in lists
    * Memory churn from recreating objects

    **Solution**:

    * Extract styles to StyleSheet
    * Use useCallback for functions
    * Use useMemo for objects
    * Calculate constants outside render
  </Tab>
</Tabs>

### Pitfall 7: Missing Error Boundaries

**The Problem**: Not handling component errors, causing white screens.

<Tabs items={["❌ Wrong Way", "✅ Correct Way", "📝 Explanation"]}>
  <Tab>
    ```typescript
    // No error handling at all
    function ProductScreen() {
      const { data: product } = useProduct(productId);
      
      // This will crash if product is null!
      return (
        <View>
          <Text>{product.name}</Text>
          <Text>${product.price}</Text>
          <Image source={{ uri: product.images[0] }} />
        </View>
      );
    }

    // Try-catch in component (doesn't work!)
    function DataDisplay() {
      try {
        return <ComplexComponent />;
      } catch (error) {
        // This won't catch React errors!
        return <Text>Error occurred</Text>;
      }
    }
    ```
  </Tab>

  <Tab>
    ```typescript
    // 1. Add feature-level error boundaries
    function ProductFeature() {
      return (
        <ErrorBoundary
          fallback={<ProductErrorFallback />}
          onError={(error) => logError(error, { feature: 'products' })}
        >
          <ProductScreen />
        </ErrorBoundary>
      );
    }

    // 2. Handle null/undefined states
    function ProductScreen() {
      const { data: product, isLoading, error } = useProduct(productId);
      
      if (isLoading) return <ProductSkeleton />;
      if (error) return <ProductError error={error} />;
      if (!product) return <ProductNotFound />;
      
      // Safe to access product properties
      return (
        <View>
          <Text>{product.name}</Text>
          <Text>${product.price}</Text>
          {product.images?.[0] && (
            <Image source={{ uri: product.images[0] }} />
          )}
        </View>
      );
    }

    // 3. Create reusable error boundary
    class ErrorBoundary extends Component {
      state = { hasError: false };
      
      static getDerivedStateFromError(error) {
        return { hasError: true };
      }
      
      componentDidCatch(error, errorInfo) {
        this.props.onError?.(error, errorInfo);
      }
      
      render() {
        if (this.state.hasError) {
          return this.props.fallback;
        }
        return this.props.children;
      }
    }
    ```
  </Tab>

  <Tab>
    **Why it's wrong**:

    * Unhandled errors crash the app
    * Poor user experience
    * Hard to debug in production

    **Solution**:

    * Add error boundaries at feature level
    * Handle loading/error/empty states
    * Use optional chaining for safety
    * Log errors for debugging
  </Tab>
</Tabs>

## API & Async Pitfalls

### Pitfall 8: Manual API State Management

**The Problem**: Managing loading, error, and data states manually instead of using React Query.

<Tabs items={["❌ Wrong Way", "✅ Correct Way", "📝 Explanation"]}>
  <Tab>
    ```typescript
    function ProductList() {
      const [products, setProducts] = useState([]);
      const [loading, setLoading] = useState(false);
      const [error, setError] = useState(null);
      
      useEffect(() => {
        let cancelled = false;
        
        const fetchProducts = async () => {
          setLoading(true);
          setError(null);
          
          try {
            const response = await fetch('/api/products');
            const data = await response.json();
            
            if (!cancelled) {
              setProducts(data);
            }
          } catch (err) {
            if (!cancelled) {
              setError(err.message);
            }
          } finally {
            if (!cancelled) {
              setLoading(false);
            }
          }
        };
        
        fetchProducts();
        
        return () => {
          cancelled = true;
        };
      }, []);
      
      // Forgot to handle refetch, caching, background updates...
    }
    ```
  </Tab>

  <Tab>
    ```typescript
    // 1. Create domain hook
    // core/domains/products/hooks.ts
    export function useProducts(filters?: ProductFilters) {
      return useQuery({
        queryKey: productQueryKeys.list(filters),
        queryFn: () => productApi.getProducts(filters),
        staleTime: 5 * 60 * 1000, // 5 minutes
      });
    }

    // 2. Use in component - much cleaner!
    function ProductList() {
      const { 
        data: products = [], 
        isLoading, 
        error,
        refetch,
        isRefetching 
      } = useProducts();
      
      if (isLoading) return <ProductListSkeleton />;
      if (error) return <ErrorMessage error={error} onRetry={refetch} />;
      
      return (
        <FlatList
          data={products}
          refreshing={isRefetching}
          onRefresh={refetch}
          renderItem={renderProduct}
        />
      );
    }

    // 3. Mutations with React Query
    export function useCreateProduct() {
      const queryClient = useQueryClient();
      
      return useMutation({
        mutationFn: productApi.createProduct,
        onSuccess: (newProduct) => {
          // Update cache
          queryClient.invalidateQueries({
            queryKey: productQueryKeys.lists()
          });
          showToast({ type: 'success', message: 'Product created!' });
        },
        onError: (error) => {
          showToast({ type: 'error', message: error.message });
        }
      });
    }
    ```
  </Tab>

  <Tab>
    **Why it's wrong**:

    * Reinventing the wheel
    * Missing features (caching, refetch, etc.)
    * Error-prone and verbose

    **Solution**:

    * Always use React Query for server state
    * Create domain hooks
    * Leverage built-in features
    * Consistent error handling
  </Tab>
</Tabs>

### Pitfall 9: Race Conditions

**The Problem**: Not handling async operations properly, causing race conditions.

<Tabs items={["❌ Wrong Way", "✅ Correct Way", "📝 Explanation"]}>
  <Tab>
    ```typescript
    // 1. Search without debouncing
    function SearchScreen() {
      const [query, setQuery] = useState('');
      const [results, setResults] = useState([]);
      
      // This fires on every keystroke!
      useEffect(() => {
        if (query) {
          searchApi(query).then(setResults);
        }
      }, [query]);
    }

    // 2. Not cancelling previous requests
    function DataLoader({ id }) {
      const [data, setData] = useState(null);
      
      useEffect(() => {
        // If id changes quickly, responses arrive out of order!
        fetchData(id).then(setData);
      }, [id]);
    }

    // 3. Multiple state updates
    function ComplexOperation() {
      const [step1, setStep1] = useState(false);
      const [step2, setStep2] = useState(false);
      const [step3, setStep3] = useState(false);
      
      const process = async () => {
        const result1 = await doStep1();
        setStep1(true); // Component might unmount!
        
        const result2 = await doStep2(result1);
        setStep2(true); // More potential issues
        
        const result3 = await doStep3(result2);
        setStep3(true);
      };
    }
    ```
  </Tab>

  <Tab>
    ```typescript
    // 1. Debounced search
    function SearchScreen() {
      const [query, setQuery] = useState('');
      const debouncedQuery = useDebounce(query, 300);
      
      // Only searches after user stops typing
      const { data: results = [] } = useQuery({
        queryKey: ['search', debouncedQuery],
        queryFn: () => searchApi(debouncedQuery),
        enabled: debouncedQuery.length > 0,
      });
    }

    // 2. Proper request cancellation
    function DataLoader({ id }) {
      const { data } = useQuery({
        queryKey: ['data', id],
        queryFn: ({ signal }) => fetchData(id, { signal }),
        // React Query handles cancellation automatically!
      });
      
      return <DataDisplay data={data} />;
    }

    // 3. Single state update with proper cleanup
    function ComplexOperation() {
      const [progress, setProgress] = useState({
        step1: false,
        step2: false,
        step3: false
      });
      
      const process = useCallback(async () => {
        const controller = new AbortController();
        
        try {
          const result1 = await doStep1({ signal: controller.signal });
          setProgress(prev => ({ ...prev, step1: true }));
          
          const result2 = await doStep2(result1, { signal: controller.signal });
          setProgress(prev => ({ ...prev, step2: true }));
          
          const result3 = await doStep3(result2, { signal: controller.signal });
          setProgress(prev => ({ ...prev, step3: true }));
        } catch (error) {
          if (error.name !== 'AbortError') {
            handleError(error);
          }
        }
        
        return () => controller.abort();
      }, []);
    }
    ```
  </Tab>

  <Tab>
    **Why it's wrong**:

    * Excessive API calls
    * Out-of-order responses
    * Memory leaks from unmounted updates

    **Solution**:

    * Debounce user input
    * Use React Query for cancellation
    * Cleanup async operations
    * Check if component is mounted
  </Tab>
</Tabs>

## TypeScript Pitfalls

### Pitfall 10: Type System Misuse

**The Problem**: Using `any`, missing types, or wrong type patterns.

<Tabs items={["❌ Wrong Way", "✅ Correct Way", "📝 Explanation"]}>
  <Tab>
    ```typescript
    // 1. Using any
    function processData(data: any) {
      return data.items.map((item: any) => item.name);
    }

    // 2. Missing return types
    function calculateTotal(items) { // No parameter or return types!
      return items.reduce((sum, item) => sum + item.price, 0);
    }

    // 3. Inline type assertions everywhere
    function UserList() {
      const users = useUsers() as User[]; // Dangerous!
      const config = getConfig() as any; // Even worse!
    }

    // 4. String types instead of unions
    interface Status {
      type: string; // Too permissive
      color: string;
    }

    // 5. Optional everything
    interface User {
      id?: string;
      name?: string;
      email?: string;
      // Everything optional makes it hard to use
    }
    ```
  </Tab>

  <Tab>
    ```typescript
    // 1. Proper typing with generics
    function processData<T extends { name: string }>(data: { items: T[] }): string[] {
      return data.items.map(item => item.name);
    }

    // 2. Explicit return types
    function calculateTotal(items: CartItem[]): number {
      return items.reduce((sum, item) => sum + item.price * item.quantity, 0);
    }

    // 3. Type guards instead of assertions
    function UserList() {
      const { data: users } = useUsers();
      
      if (!isUserArray(users)) {
        return <ErrorState />;
      }
      
      // Now TypeScript knows users is User[]
      return <List users={users} />;
    }

    // Type guard
    function isUserArray(data: unknown): data is User[] {
      return Array.isArray(data) && 
             data.every(item => 'id' in item && 'name' in item);
    }

    // 4. Union types for constraints
    type StatusType = 'pending' | 'active' | 'inactive';
    type ColorType = 'red' | 'green' | 'blue';

    interface Status {
      type: StatusType;
      color: ColorType;
    }

    // 5. Required fields with optional ones clearly marked
    interface User {
      // Required fields
      id: string;
      name: string;
      email: string;
      
      // Optional fields
      avatar?: string;
      bio?: string;
      preferences?: UserPreferences;
    }
    ```
  </Tab>

  <Tab>
    **Why it's wrong**:

    * Loses type safety benefits
    * Runtime errors from wrong assumptions
    * Hard to refactor
    * Poor IntelliSense support

    **Solution**:

    * Never use `any` - use `unknown` if needed
    * Always add return types
    * Use type guards for validation
    * Use unions for constrained values
    * Be intentional about optional properties
  </Tab>
</Tabs>

## Performance Pitfalls

### Pitfall 11: Unnecessary Re-renders

**The Problem**: Components re-rendering more than necessary.

<Tabs items={["❌ Wrong Way", "✅ Correct Way", "📝 Explanation"]}>
  <Tab>
    ```typescript
    // 1. Object/Array as dependency
    function DataProcessor({ config }) {
      const [result, setResult] = useState(null);
      
      useEffect(() => {
        // This runs every render because config is new object!
        processData(config).then(setResult);
      }, [config]); // Object reference changes
    }

    // 2. Inline component definitions
    function ParentComponent() {
      // New component every render!
      const ChildComponent = ({ text }) => <Text>{text}</Text>;
      
      return (
        <View>
          <ChildComponent text="Hello" />
        </View>
      );
    }

    // 3. Not memoizing expensive computations
    function ExpensiveList({ items, filters }) {
      // Runs on every render!
      const filtered = items.filter(item => {
        return filters.every(filter => filter.test(item));
      });
      
      const sorted = filtered.sort((a, b) => {
        return complexSortLogic(a, b);
      });
      
      return <FlatList data={sorted} />;
    }
    ```
  </Tab>

  <Tab>
    ```typescript
    // 1. Memoize object dependencies
    function DataProcessor({ config }) {
      const [result, setResult] = useState(null);
      
      // Memoize config or use specific values
      const configKey = useMemo(
        () => JSON.stringify(config),
        [config.id, config.type] // Only relevant fields
      );
      
      useEffect(() => {
        processData(config).then(setResult);
      }, [configKey]);
    }

    // 2. Define components outside
    const ChildComponent = memo(({ text }) => <Text>{text}</Text>);

    function ParentComponent() {
      return (
        <View>
          <ChildComponent text="Hello" />
        </View>
      );
    }

    // 3. Memoize expensive operations
    function ExpensiveList({ items, filters }) {
      const filtered = useMemo(
        () => items.filter(item => 
          filters.every(filter => filter.test(item))
        ),
        [items, filters]
      );
      
      const sorted = useMemo(
        () => [...filtered].sort((a, b) => complexSortLogic(a, b)),
        [filtered]
      );
      
      return <FlatList data={sorted} />;
    }

    // 4. Use React.memo for pure components
    export const ProductCard = memo(({ product, onPress }) => {
      return (
        <TouchableOpacity onPress={() => onPress(product.id)}>
          <Text>{product.name}</Text>
        </TouchableOpacity>
      );
    }, (prevProps, nextProps) => {
      // Custom comparison
      return prevProps.product.id === nextProps.product.id &&
             prevProps.product.updated === nextProps.product.updated;
    });
    ```
  </Tab>

  <Tab>
    **Why it's wrong**:

    * Performance degradation
    * Janky UI from excessive renders
    * Battery drain on mobile

    **Solution**:

    * Memoize objects and arrays
    * Define components outside render
    * Use useMemo for expensive operations
    * Use React.memo for pure components
  </Tab>
</Tabs>

## Quick Reference Card

### Before Writing Code, Ask:

1. **Does this logic already exist?**
   * Check domains first
   * Search for similar patterns
   * Reuse instead of rewrite

2. **Where should this code go?**
   * Use the [Decision Tree](/docs/guides/feature-implementation-decision-tree)
   * Follow the 3+ rule
   * Check project structure

3. **Is this the right state type?**
   * Server state → React Query
   * Global state → Zustand
   * Local state → useState
   * Form state → React Hook Form

4. **Am I following the patterns?**
   * Check [TypeScript & React Patterns](/docs/coding-standards/typescript-react-patterns)
   * Follow naming conventions
   * Use proper types

5. **Have I handled errors?**
   * Add error boundaries
   * Handle null/undefined
   * Provide user feedback

## For Team Leads

### Code Review Checklist

When reviewing PRs, check for these common issues:

* [ ] Code is in the correct location
* [ ] No duplicate business logic
* [ ] Proper TypeScript types (no `any`)
* [ ] Error handling is present
* [ ] Performance optimizations applied
* [ ] Following established patterns
* [ ] Tests are included

### Onboarding New Developers

1. Start with this guide
2. Review the Decision Tree together
3. Pair program on first features
4. Do thorough code reviews
5. Encourage questions

## Related Documents

* [Feature Implementation Decision Tree](/docs/guides/feature-implementation-decision-tree)
* [TypeScript & React Patterns](/docs/coding-standards/typescript-react-patterns)
* [Project Structure Reference](/docs/architecture/project-structure)
* [State Management Guide](/docs/guides/client-state-management)


# UTA Coding Standards: Coding Standards
URL: https://dev.updatetheapp.com/docs/coding-standards
Documentation: https://dev.updatetheapp.com/docs/coding-standards

Standardized conventions and best practices for code quality and consistency
        
***

title: Coding Standards
description: Standardized conventions and best practices for code quality and consistency
-----------------------------------------------------------------------------------------

import { Card, Cards } from 'fumadocs-ui/components/card';
import { ChevronRightIcon } from 'lucide-react';

# Coding Standards

## Overview

Consistent coding standards are crucial for maintainable, readable, and high-quality code. This section outlines our established conventions and best practices that all team members should follow when working with the UTA mobile application template.

## Key Coding Standards

<Cards>
  <Card icon={<ChevronRightIcon />} title="File Naming Conventions" description="Learn our standardized approach to naming files, directories, and components throughout the codebase." href="/docs/coding-standards/file-naming-conventions" />

  <Card icon={<ChevronRightIcon />} title="TypeScript Guidelines" description="Best practices for TypeScript usage, including typing, interfaces, and type safety considerations." href="/docs/coding-standards/typescript-guidelines" />

  <Card icon={<ChevronRightIcon />} title="React Patterns" description="Recommended patterns and anti-patterns for React and React Native development." href="/docs/coding-standards/react-patterns" />
</Cards>

## Coding Principles

Our coding standards are built around these core principles:

1. **Consistency** - Code should look like it was written by one person, regardless of the number of contributors
2. **Readability** - Code should be easy to read and understand, with clear names and structure
3. **Maintainability** - Code should be organized to facilitate future changes and updates
4. **Testability** - Code should be structured in a way that makes testing straightforward
5. **Documentation** - Code should include appropriate comments and documentation

## Quality Assurance

<Cards>
  <Card icon={<ChevronRightIcon />} title="Testing Standards" description="Requirements and conventions for writing effective tests across unit, integration, and E2E testing." href="/docs/coding-standards/testing-standards" />

  <Card icon={<ChevronRightIcon />} title="Documentation Standards" description="Guidelines for documenting components, functions, and application behavior." href="/docs/coding-standards/documentation-standards" />

  <Card icon={<ChevronRightIcon />} title="Linting & Formatting" description="Configuration and usage guidelines for ESLint, Prettier, and other code quality tools." href="/docs/coding-standards/linting-formatting" />
</Cards>

## Related Areas

<Cards>
  <Card icon={<ChevronRightIcon />} title="Development Workflow" description="Learn about our git workflow, code reviews, and development cycles." href="/docs/development-workflow" />

  <Card icon={<ChevronRightIcon />} title="Testing" description="Comprehensive testing strategies and implementation guides." href="/docs/testing" />
</Cards>


# UTA Coding Standards: Why Standards Matter
URL: https://dev.updatetheapp.com/docs/coding-standards/why-standards-matter
Documentation: https://dev.updatetheapp.com/docs/coding-standards/why-standards-matter

Understanding the fundamental importance of coding standards, rules, and consistency in software development.
        
***

title: Why Standards Matter
description: Understanding the fundamental importance of coding standards, rules, and consistency in software development.
--------------------------------------------------------------------------------------------------------------------------

import { Tabs, Tab } from 'fumadocs-ui/components/tabs';

# Why Standards Matter

## Overview

This guide explains the **fundamental principles** behind why we enforce coding standards, naming conventions, import paths, and architectural rules. Understanding the "why" helps teams embrace standards as **efficiency multipliers** rather than bureaucratic overhead.

## Purpose & Scope

This document provides the philosophical and practical foundation for all our coding standards. It demonstrates how seemingly small consistency decisions compound into massive productivity gains and why rule-based development is essential for sustainable software projects.

## The Hidden Cost of Inconsistency

### Without Standards: The Exponential Problem

```typescript
// 4 developers, same functionality, 4 different approaches
Developer A: import { useTheme } from '@core/shared/styles';
Developer B: import { useTheme } from '@/core/shared/styles/ThemeProvider';
Developer C: import { useTheme } from '@/core/theme';
Developer D: import { useTheme } from '@/ui/theme/ThemeProvider';

// Result: 4 maintenance paths for ONE concept
// Change theme location = update in 4+ different ways
```

### Real Impact Metrics

| Team Size         | Inconsistent Patterns | Monthly Overhead | Annual Cost |
| ----------------- | --------------------- | ---------------- | ----------- |
| **4 developers**  | 3-5 variations        | 8 hours          | 2 weeks     |
| **8 developers**  | 8-12 variations       | 20 hours         | 5 weeks     |
| **15 developers** | 15+ variations        | 40 hours         | 10 weeks    |

<Callout type="warn">
  **Exponential Growth**: Inconsistency cost grows **exponentially** with team size, not linearly.
</Callout>

## Core Benefits of Standards

### 1. Eliminates Decision Fatigue

**Without Standards** ❌:

```
Developer mental process:
1. "How should I import this?"
2. Check 3-4 files for patterns
3. Find 3 different approaches
4. Spend 10 minutes deciding
5. Make arbitrary choice
6. Introduce new inconsistency
```

**With Standards** ✅:

```
Developer mental process:
1. Check import standards rule
2. Use canonical path
3. Continue solving real problems
```

**Time Saved**: 5-10 minutes per import decision × dozens of imports per day = **hours of focused development time**

### 2. Accelerates Onboarding

<Tabs items={["Without Standards", "With Standards"]}>
  <Tab>
    **New Developer Experience** ❌:

    ```
    Week 1:
    - "How do I import components?"
    - "I see 5 different patterns, which is right?"
    - Senior dev: "Well, it depends..."

    Week 2:
    - Still making import mistakes
    - Code reviews focus on style inconsistencies
    - Imposter syndrome: "I can't even import correctly"

    Week 3-4:
    - Slowly learns unwritten patterns
    - Productivity still below expectations
    ```

    **Result**: 3-4 weeks to basic productivity
  </Tab>

  <Tab>
    **New Developer Experience** ✅:

    ```
    Day 1:
    - "Check the coding standards documentation"
    - "All import patterns clearly documented"
    - "IDE auto-complete follows standards"

    Day 2-3:
    - Making consistent choices immediately
    - Code reviews focus on logic, not style
    - Confidence: "I know the right patterns"

    Week 1:
    - Contributing meaningful features
    - Following established patterns naturally
    ```

    **Result**: 3-5 days to basic productivity
  </Tab>
</Tabs>

### 3. Enables Reliable Automation

**Consistent Patterns = Predictable Automation**:

```typescript
// Standards enable powerful tooling
module.exports = {
  rules: {
    // Can enforce because patterns are documented
    'import-path-standards/theme-imports': [
      'error', 
      { canonical: '@core/shared/styles' }
    ],
    
    // Can auto-fix because rules are clear
    'consistent-component-structure': 'error',
    
    // Can optimize because patterns are predictable
    'unused-import-detection': 'error'
  }
};
```

**Without Standards**: Tools can't help because patterns are unpredictable
**With Standards**: Tools become force multipliers

### 4. Scales Code Reviews

<Mermaid
  chart={`
flowchart TD
subgraph "Without Standards"
  A[Code Review] --> B[30% Style Issues]
  A --> C[30% Pattern Debates]
  A --> D[40% Logic Review]
end

subgraph "With Standards"
  E[Code Review] --> F[5% Style Issues]
  E --> G[0% Pattern Debates]
  E --> H[95% Logic Review]
end

style B fill:#ffcccc
style C fill:#ffcccc
style F fill:#ccffcc
style G fill:#ccffcc
style H fill:#ccffcc
`}
/>

**Impact**: Code reviews focus on **business logic and architecture** instead of style bikeshedding.

### 5. Enables AI-Assisted Development

Standards make AI collaboration predictable and productive:

<Tabs items={["Without Standards", "With Standards"]}>
  <Tab>
    ```typescript
    // AI generates different patterns each time:
    // Request 1: Class component
    // Request 2: Functional component
    // Request 3: Different file structure
    // Request 4: Inconsistent naming

    // Result: Every AI output needs heavy editing
    ```
  </Tab>

  <Tab>
    ```typescript
    // AI follows documented patterns:
    // - Consistent file structure
    // - Predictable naming conventions
    // - Standard import paths
    // - Established patterns

    // Result: AI output is immediately usable
    ```
  </Tab>
</Tabs>

## Psychology: Why Humans Resist Standards

### 1. Immediate vs. Long-term Thinking

* **Short-term**: "This rule slows me down right now"
* **Long-term**: "This rule saves hours over months"

### 2. Optimism Bias

* **Assumption**: "We'll remember to be consistent"
* **Reality**: "Consistency degrades without enforcement"

### 3. Effort Aversion

* **Perception**: "Rules are extra work"
* **Truth**: "Rules eliminate work by preventing problems"

### 4. Context Switching

* **Focus**: "I'm solving this feature"
* **Missing**: "How this affects team patterns"

<Callout type="info">
  **Solution**: Make standards **easier to follow than to break** through clear documentation, tool support, and cultural reinforcement.
</Callout>

## Standards as Creativity Enablers

### The Paradox of Constraints

**Common Misconception**: "Rules limit creativity"
**Reality**: "Rules **enable** creativity by eliminating trivial decisions"

```typescript
// Without import standards: Mental energy wasted
function buildFeature() {
  // Spend 10 minutes: "How should I import this?"
  // Spend 5 minutes: "Is this the right pattern?"
  // Spend 15 minutes: "Let me check other files..."
  // 30 minutes on imports, 2 hours on actual feature
}

// With import standards: Mental energy focused
function buildFeature() {
  // 0 minutes: Follow documented pattern
  // 2.5 hours: Build amazing feature logic
}
```

### Creative Energy Allocation

<Mermaid
  chart={`
pie title Without Standards: Mental Energy Distribution
  "Trivial Decisions" : 45
  "Feature Logic" : 55
`}
/>

<Mermaid
  chart={`
pie title With Standards: Mental Energy Distribution
  "Following Patterns" : 5
  "Feature Logic" : 85
  "Architecture Decisions" : 10
`}
/>

## Business Impact Analysis

### Scenario: 18-Month Project

**Team**: 8 developers\
**Features**: High velocity development\
**Complexity**: Enterprise-grade application

#### Without Standards Timeline ❌

| Month     | Impact                         | Cumulative Cost |
| --------- | ------------------------------ | --------------- |
| **1-3**   | Inconsistencies emerge         | 40 hours        |
| **4-6**   | Developer confusion grows      | 120 hours       |
| **7-9**   | Refactoring attempts fail      | 200 hours       |
| **10-12** | New developer onboarding slow  | 320 hours       |
| **13-15** | Technical debt blocks features | 480 hours       |
| **16-18** | Major refactoring required     | 600+ hours      |

**Total Cost**: 600+ developer hours (15 weeks of work)

#### With Standards Timeline ✅

| Month       | Impact                                   | Cumulative Cost |
| ----------- | ---------------------------------------- | --------------- |
| **1**       | Standards established                    | 20 hours        |
| **2-18**    | Consistent patterns maintained           | 60 hours        |
| **Various** | Fast onboarding, predictable refactoring | -               |

**Total Cost**: 80 developer hours (2 weeks of work)

**Net Savings**: 520+ hours (13 weeks of developer time)

## Implementation Strategy

### Phase 1: Foundation (Week 1-2)

1. **Document current patterns** in existing codebase
2. **Identify canonical approaches** for each decision type
3. **Create comprehensive rule documentation**
4. **Set up tool enforcement** (ESLint, Prettier, etc.)

### Phase 2: Adoption (Week 3-4)

1. **Team training** on new standards
2. **Gradual migration** of existing code
3. **Code review enforcement** with educational feedback
4. **Tool integration** into development workflow

### Phase 3: Optimization (Month 2+)

1. **Monitor compliance** through automated metrics
2. **Refine standards** based on real usage patterns
3. **Expand automation** to catch more edge cases
4. **Cultural reinforcement** through team practices

## Common Objections & Responses

### "Standards slow down development"

**Response**: Standards are an **investment** that pays exponential dividends. The upfront cost is minimal compared to the ongoing cost of inconsistency.

### "Our team is too small to need standards"

**Response**: Small teams benefit **more** from standards because every decision impact is magnified. Plus, most teams grow over time.

### "We can just remember to be consistent"

**Response**: Human memory fails under pressure. Standards remove the need to remember by making correct choices obvious.

### "Standards are just bureaucracy"

**Response**: Bureaucracy creates process without value. Standards create **efficiency multipliers** with measurable returns.

### "We need flexibility for innovation"

**Response**: Standards provide the stable foundation that makes innovation possible. Like jazz musicians who master theory before improvisation, developers need consistent patterns before breaking new ground.

## Tools & Enforcement

### Automated Enforcement Stack

```typescript
// .eslintrc.js - Enforce import standards
module.exports = {
  rules: {
    'import-path-standards/canonical-imports': 'error',
    'import-path-standards/no-deep-imports': 'error',
    'import-path-standards/prefer-barrel-exports': 'warn',
  }
};

// prettier.config.js - Enforce formatting standards
module.exports = {
  semi: true,
  singleQuote: true,
  trailingComma: 'all',
  // Consistent formatting = no style debates
};

// tsconfig.json - Enforce structural standards
{
  "compilerOptions": {
    "strict": true,
    "noImplicitAny": true,
    // Type safety standards
  }
}
```

### Cultural Enforcement

1. **Code review checklists** include standards verification
2. **Onboarding materials** emphasize standards importance
3. **Team retrospectives** identify and fix consistency gaps
4. **Documentation culture** keeps standards current

## Measuring Success

### Key Metrics

1. **Code Review Efficiency**
   * Time spent on style/pattern issues vs. logic review
   * Number of pattern-related comments per PR

2. **Developer Onboarding Speed**
   * Time to first meaningful contribution
   * Self-reported confidence in following patterns

3. **Refactoring Predictability**
   * Time to complete structural changes
   * Success rate of automated refactoring tools

4. **Technical Debt Growth**
   * Number of "TODO: make consistent" comments
   * Pattern violation detection in automated scans

### Success Indicators

* ✅ Code reviews focus 90%+ on logic vs. style
* ✅ New developers productive within 1 week
* ✅ Automated refactoring tools work reliably
* ✅ Pattern violations trend toward zero
* ✅ AI-generated code requires minimal editing

## Quick Reference: Your Standards Checklist

### Before Writing Code

* [ ] Is there an established pattern for this?
* [ ] Have I checked the standards documentation?
* [ ] Do I have the right imports configured?

### During Development

* [ ] Am I following the documented patterns?
* [ ] Are my naming conventions consistent?
* [ ] Will automated tools understand my code?

### Before Committing

* [ ] Have I run the linting tools?
* [ ] Does my code match team patterns?
* [ ] Will this be easy to maintain?

## Conclusion

**Standards aren't about control—they're about enabling excellence.**

By establishing clear, well-documented patterns, we:

* **Eliminate trivial decisions** that waste mental energy
* **Accelerate onboarding** for new team members
* **Enable powerful tooling** that amplifies productivity
* **Scale code quality** without scaling overhead
* **Focus creativity** on problems that actually matter

The choice isn't between "freedom" and "rules"—it's between **chaotic inefficiency** and **systematic excellence**.

Every hour spent establishing standards returns **10x** in productivity gains, reduced frustration, and maintainable code that stands the test of time.

## Next Steps

1. **Review** our [Import Path Standards](/docs/coding-standards/import-path-standards)
2. **Implement** your first 3 core standards this week
3. **Measure** the productivity impact after 30 days
4. **Share** your success to build team momentum

## Related Documentation

* [Import Path Standards](/docs/coding-standards/import-path-standards) - Specific import rules
* [File Naming Conventions](/docs/coding-standards/file-naming-conventions) - Naming consistency
* [TypeScript & React Patterns](/docs/coding-standards/typescript-react-patterns) - Code structure standards
* [AI Coding Standards](/docs/coding-standards/ai-coding-standards) - AI-specific guidelines

***

**Remember**: Great software is built on **consistent foundations**, not brilliant chaos.


# UTA Coding Standards: Import Path Standards
URL: https://dev.updatetheapp.com/docs/coding-standards/import-path-standards
Documentation: https://dev.updatetheapp.com/docs/coding-standards/import-path-standards

Canonical import patterns for consistent, maintainable code across the entire codebase
        
***

title: Import Path Standards
description: Canonical import patterns for consistent, maintainable code across the entire codebase
---------------------------------------------------------------------------------------------------

import { Steps, Step } from 'fumadocs-ui/components/steps';
import { Callout } from 'fumadocs-ui/components/callout';
import { Tabs, Tab } from 'fumadocs-ui/components/tabs';

# Import Path Standards

## Overview

This guide establishes **canonical import paths** for all modules in our project. By following these standards, we ensure consistency across documentation, examples, and actual code implementation.

<Callout type="info">
  **Why canonical imports matter**: They reduce cognitive load, speed up development, and eliminate the "which import should I use?" decision fatigue. When everyone uses the same import patterns, code reviews focus on logic rather than style choices.
</Callout>

## Core Principle

**Single Source of Truth**: Each module has ONE canonical import path used consistently across:

* Code implementation
* Documentation examples
* Type definitions
* Test files

## Canonical Import Patterns

### Theme Management

```typescript
// ✅ CANONICAL - Always use these patterns
import { useTheme } from '@/core/shared/styles';
import { ThemeProvider } from '@/core/shared/styles';
import { Theme } from '@/core/shared/styles';

// ❌ AVOID - Common incorrect variations
import { useTheme } from '@core/shared/styles';           // Missing @/ prefix
import { useTheme } from '@/core/shared/styles/ThemeProvider'; // Too specific
import { useTheme } from '@/core/theme';                 // Non-canonical path
```

### Domain Logic (Cross-Feature Business Logic)

```typescript
// ✅ CANONICAL - For shared business entities and logic
import { useProducts } from '@/core/domains/products';
import { Product } from '@/core/domains/products';
import { useAuth } from '@/core/domains/auth';
import { User } from '@/core/domains/auth';

// ❌ AVOID - Specific file paths
import { useProducts } from '@/core/domains/products/hooks';
import { Product } from '@/core/domains/products/types';
```

### Feature Logic (Feature-Specific Logic)

```typescript
// ✅ CANONICAL - For feature-specific behavior
import { useCart } from '@/features/cart/hooks';
import { useCheckoutFlow } from '@/features/checkout/hooks';
import { ProductFilters } from '@/features/catalog/components';

// ❌ AVOID - Specific file paths
import { useCart } from '@/features/cart/hooks/useCart';
import { ProductFilters } from '@/features/catalog/components/ProductFilters';
```

### UI Components

```typescript
// ✅ CANONICAL - Direct component imports
import { Button } from '@/ui/foundation/Button';
import { Modal } from '@/ui/patterns/Modal';
import { ProductCard } from '@/ui/business/ProductCard';

// ❌ AVOID - File extensions or nested paths
import { Button } from '@/ui/foundation/Button/Button';
import { Modal } from '@/ui/patterns/Modal/Modal.tsx';
```

### Shared Utilities

```typescript
// ✅ CANONICAL - Barrel exports for utilities
import { formatCurrency } from '@/core/shared/utils';
import { useDebounce } from '@/core/shared/hooks';

// ❌ AVOID - Specific file paths
import { formatCurrency } from '@/core/shared/utils/number';
import { useDebounce } from '@/core/shared/hooks/useDebounce';
```

## Architecture Decision Guide

Understanding when to use domain vs feature imports is crucial for maintainable architecture:

<Tabs items={["Domain Logic", "Feature Logic", "Decision Tree"]}>
  <Tab>
    ### Domain Logic (`@/core/domains/[domain]`)

    **Use when your code:**

    * Is used by **3+ features**
    * Represents core **business entities** (User, Product, Order)
    * Contains **cross-cutting business rules**
    * Needs to be **highly reusable** and **stable**

    **Examples:**

    ```typescript
    // User authentication used across app
    import { useAuth, User } from '@/core/domains/auth';

    // Product data used by catalog, search, cart, checkout
    import { useProducts, Product } from '@/core/domains/products';

    // Order management used by checkout, history, tracking
    import { useOrders, Order } from '@/core/domains/orders';
    ```

    **Real-world scenarios:**

    * User profile data accessed from navigation, settings, and checkout
    * Product information displayed in lists, details, and cart
    * Order status shown in checkout confirmation and order history
  </Tab>

  <Tab>
    ### Feature Logic (`@/features/[feature]/hooks`)

    **Use when your code:**

    * Is **feature-specific** (shopping cart state, checkout flow)
    * Used by **1-2 features only**
    * Represents **UI behavior** rather than core business logic
    * Can change independently of other features

    **Examples:**

    ```typescript
    // Cart state only used in cart and checkout
    import { useCart, useCartPersistence } from '@/features/cart/hooks';

    // Search filters only used in catalog feature
    import { useProductFilters } from '@/features/catalog/hooks';

    // Checkout wizard state only used in checkout
    import { useCheckoutSteps } from '@/features/checkout/hooks';
    ```

    **Real-world scenarios:**

    * Shopping cart state management and persistence
    * Search/filter state for product catalog
    * Multi-step form state for checkout process
    * Wishlist management within product browsing
  </Tab>

  <Tab>
    ### Decision Tree

    Use this flow to determine the correct import pattern:

    ```mermaid
    flowchart TD
        Start[New Code/Hook] --> Q1{Used by 3+ features?}
        
        Q1 -->|Yes| Q2{Core business entity?}
        Q1 -->|No| Feature[Use @/features/[feature]/hooks]
        
        Q2 -->|Yes| Domain[Use @/core/domains/[domain]]
        Q2 -->|No| Q3{UI behavior vs business logic?}
        
        Q3 -->|Business Logic| Domain
        Q3 -->|UI Behavior| Feature
        
        Feature --> Example1[useCart, useCheckoutSteps,<br/>useProductFilters]
        Domain --> Example2[useAuth, useProducts,<br/>useOrders]
    ```

    **Quick Examples:**

    * `useAuth` → Domain (used everywhere)
    * `useCart` → Feature (specific to cart/checkout)
    * `useProducts` → Domain (used in catalog, search, cart)
    * `useCheckoutSteps` → Feature (specific to checkout flow)
  </Tab>
</Tabs>

## Import Structure Requirements

### Path Alias Standards

All imports must use the `@/` prefix for consistency:

```typescript
// ✅ CORRECT - Consistent @/ prefix
import { useTheme } from '@/core/shared/styles';
import { useProducts } from '@/core/domains/products';
import { Button } from '@/ui/foundation/Button';

// ❌ INCORRECT - Missing @/ prefix
import { useTheme } from '@core/shared/styles';
import { useProducts } from '@core/domains/products';
```

### Barrel Exports Required

Every module directory must have an `index.ts` that exports the public API:

<Steps>
  <Step>
    #### Domain Module Example

    ```typescript
    // src/core/domains/products/index.ts
    export { useProducts, useProduct, useProductSearch } from './hooks';
    export { Product, ProductCategory, ProductFilter } from './types';
    export { productApi } from './api';
    export { productUtils } from './utils';
    ```
  </Step>

  <Step>
    #### UI Component Example

    ```typescript
    // src/ui/foundation/Button/index.ts
    export { Button } from './Button';
    export type { ButtonProps, ButtonVariant } from './types';
    ```
  </Step>

  <Step>
    #### Feature Module Example

    ```typescript
    // src/features/cart/hooks/index.ts
    export { useCart } from './useCart';
    export { useCartPersistence } from './useCartPersistence';
    export { useCartValidation } from './useCartValidation';
    ```
  </Step>
</Steps>

### Import Order Convention

Follow this order for clean, predictable imports:

```typescript
// 1. React/React Native
import React from 'react';
import { View, Text } from 'react-native';

// 2. Third-party libraries  
import { useQuery } from '@tanstack/react-query';

// 3. Theme (highest priority internal)
import { useTheme } from '@/core/shared/styles';

// 4. Domain imports
import { useProducts } from '@/core/domains/products';

// 5. UI components
import { Button } from '@/ui/foundation/Button';

// 6. Feature imports
import { useCart } from '@/features/cart/hooks';

// 7. Relative imports (same directory only)
import { styles } from './styles';
```

## Documentation Standards

### Code Examples in Documentation

All documentation examples must use canonical import paths:

```typescript
// ✅ ALWAYS in documentation
import { useTheme } from '@/core/shared/styles';
import { Button } from '@/ui/foundation/Button';
import { useProducts } from '@/core/domains/products';

// ❌ NEVER in documentation
import { useTheme } from '@core/shared/styles';        // Missing @/ prefix
import { Button } from '@/ui/foundation/Button/Button'; // Too specific
```

### Cross-References

When linking to other guides, reference the canonical source rather than duplicating information:

```markdown
// ✅ Proper cross-reference
For theme customization, see [Theme Management](/docs/ui-development/theme-management).

// ❌ Improper duplication
You can also define custom themes by creating a theme object...
```

## Migration Strategies

### Updating Existing Code

When refactoring imports to follow these standards:

<Steps>
  <Step>
    #### Identify Current Patterns

    Search your codebase for non-canonical imports:

    ```bash
    # Find missing @/ prefixes
    grep -r "from '@ui" src/
    grep -r "from '@core" src/
    grep -r "from '@features" src/

    # Find overly specific paths
    grep -r "from '@/.*/.*/" src/
    ```
  </Step>

  <Step>
    #### Update to Canonical Patterns

    Replace with canonical imports:

    ```typescript
    // Before
    import { useTheme } from '@core/shared/styles';
    import { Button } from '@/ui/foundation/Button/Button';

    // After  
    import { useTheme } from '@/core/shared/styles';
    import { Button } from '@/ui/foundation/Button';
    ```
  </Step>

  <Step>
    #### Verify Barrel Exports

    Ensure all modules have proper barrel exports:

    ```typescript
    // Check that index.ts files exist and export correctly
    // src/core/domains/products/index.ts
    // src/ui/foundation/Button/index.ts
    // src/features/cart/hooks/index.ts
    ```
  </Step>
</Steps>

### Automated Tools

Consider these tools for maintaining import consistency:

* **ESLint rules** for import path validation
* **Pre-commit hooks** for import checking
* **IDE settings** for auto-import configuration

## Benefits

Following these import standards provides:

1. **Consistent Learning**: Developers learn one import pattern
2. **Easier Refactoring**: Changes only need updates in one place
3. **Clear Dependencies**: Import paths show architectural relationships
4. **Reduced Confusion**: No guessing which import to use
5. **Better Tooling**: IDEs provide better autocomplete and navigation

## Common Patterns Reference

| Code Type         | Location      | Import Pattern                | Example          |
| ----------------- | ------------- | ----------------------------- | ---------------- |
| **Theme**         | Core Shared   | `@/core/shared/styles`        | `useTheme`       |
| **Domain Logic**  | Core Domains  | `@/core/domains/[domain]`     | `useProducts`    |
| **Feature Logic** | Features      | `@/features/[feature]/hooks`  | `useCart`        |
| **Foundation UI** | UI Foundation | `@/ui/foundation/[component]` | `Button`         |
| **Pattern UI**    | UI Patterns   | `@/ui/patterns/[component]`   | `Modal`          |
| **Business UI**   | UI Business   | `@/ui/business/[component]`   | `ProductCard`    |
| **Shared Utils**  | Core Shared   | `@/core/shared/utils`         | `formatCurrency` |

<Callout type="tip">
  **Pro tip**: Bookmark this reference table! Most import decisions can be made quickly by checking the code type and following the corresponding pattern.
</Callout>

## Troubleshooting

### Common Issues

**Import not found errors:**

* Verify the barrel export exists in the target module's `index.ts`
* Check that the `@/` prefix is included
* Ensure the path matches the actual directory structure

**Multiple ways to import the same thing:**

* Always choose the canonical pattern from this guide
* When in doubt, use the most general path (barrel export over specific file)

**IDE not suggesting correct imports:**

* Configure your IDE's auto-import settings to prefer canonical paths
* Update `tsconfig.json` path mappings if necessary

For additional guidance, see the [Feature Implementation Decision Tree](/docs/guides/feature-implementation-decision-tree) for architectural placement decisions.


# UTA Coding Standards: AI Coding Standards
URL: https://dev.updatetheapp.com/docs/coding-standards/ai-coding-standards
Documentation: https://dev.updatetheapp.com/docs/coding-standards/ai-coding-standards

Comprehensive guidelines for maintaining code quality, security, and team productivity when using AI coding assistants like GitHub Copilot, Claude, and ChatGPT.
        
***

title: "AI Coding Standards"
description: "Comprehensive guidelines for maintaining code quality, security, and team productivity when using AI coding assistants like GitHub Copilot, Claude, and ChatGPT."
-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

import { Tabs, Tab } from 'fumadocs-ui/components/tabs';

# AI Coding Standards

This guide provides comprehensive, research-backed guidelines for maintaining code quality, security, and team productivity when using AI coding assistants like GitHub Copilot, Claude, and ChatGPT.

## Philosophy: AI as Code Review Partner

**Treat AI as an experienced junior developer whose output always requires senior review**. The goal is to amplify human expertise, not replace human judgment and oversight.

<Callout type="warning">
  **Critical Principle**: Never accept AI-generated code without thorough review. AI excels at pattern recognition and implementation but lacks business context, security awareness, and architectural understanding.
</Callout>

## Pre-Generation Checklist

Before accepting ANY AI-generated code, verify these requirements:

<Steps>
  <Step>
    ### Architecture Verification

    * Consult the [Feature Implementation Decision Tree](/docs/guides/feature-implementation-decision-tree)
    * Determine exact file location - never guess
    * Follow the 3+ rule for shared code placement
  </Step>

  <Step>
    ### Pattern Reuse

    * Search domains first for existing business logic
    * Check for similar implementations in the codebase
    * Reuse existing utilities and hooks instead of recreating
  </Step>

  <Step>
    ### Standards Compliance

    * Follow [Import Path Standards](/docs/coding-standards/import-path-standards)
    * Use [TypeScript React Patterns](/docs/coding-standards/typescript-react-patterns)
    * Maintain [UTA Terminology](/docs/coding-standards/uta-terminology) consistency
  </Step>
</Steps>

## AI-Specific Security Guidelines

### Input Validation Anti-Pattern

AI often generates code that "looks right" but lacks proper validation:

<Tabs items={["❌ AI-Generated", "✅ Secure Implementation"]}>
  <Tab>
    ```typescript
    // Missing validation - security risk
    function updateUser(userId: string, data: any) {
      return db.users.update({ id: userId }, data);
    }
    ```
  </Tab>

  <Tab>
    ```typescript
    // Proper validation and sanitization
    function updateUser(userId: string, data: UpdateUserData) {
      if (!isValidObjectId(userId)) {
        throw new ValidationError('Invalid user ID');
      }
      const sanitizedData = sanitizeUserInput(data);
      return db.users.update({ id: userId }, sanitizedData);
    }
    ```
  </Tab>
</Tabs>

### Authentication Context

AI frequently omits security context in route handlers:

<Tabs items={["❌ Missing Auth", "✅ Secure Route"]}>
  <Tab>
    ```typescript
    // No authentication or authorization
    app.get('/admin/users', async (req, res) => {
      const users = await getUsersData();
      res.json(users);
    });
    ```
  </Tab>

  <Tab>
    ```typescript
    // Proper authentication and authorization
    app.get('/admin/users', 
      isAuthenticated, 
      requireRole('admin'), 
      async (req, res) => {
        const users = await getUsersData();
        res.json(users);
      }
    );
    ```
  </Tab>
</Tabs>

### SQL Injection Prevention

<Tabs items={["❌ Vulnerable", "✅ Safe"]}>
  <Tab>
    ```typescript
    // Direct string interpolation - SQL injection risk
    const query = `SELECT * FROM users WHERE name = '${userName}'`;
    ```
  </Tab>

  <Tab>
    ```typescript
    // Parameterized query - safe from injection
    const query = 'SELECT * FROM users WHERE name = ?';
    const result = await db.query(query, [userName]);
    ```
  </Tab>
</Tabs>

## Context Preservation Requirements

### Document AI-Generated Components

Every AI-generated component must include comprehensive context:

```typescript
/**
 * ProductCard Component
 * 
 * AI Context: Generated for product catalog display
 * Business Rules: 
 * - Shows price only for authenticated users
 * - Handles both physical and digital products
 * - Supports accessibility requirements
 * 
 * Design Decisions:
 * - Using TouchableOpacity for native feel
 * - Memoized for performance in FlatList
 * - Error boundaries for image loading failures
 * 
 * Dependencies:
 * - @core/shared/styles for theming
 * - @/core/domains/products for data fetching
 * - @/ui/foundation for base components
 */
export const ProductCard = React.memo<ProductCardProps>(({ product }) => {
  // Implementation with proper error handling
  // and accessibility support
});
```

### Reasoning Chain Documentation

For complex logic, preserve the AI's reasoning process:

```typescript
// AI Reasoning: Need to handle async state transitions while preventing race conditions
// Decision: Use ref to track latest request and ignore stale responses
// Alternative considered: Cancel previous requests, but ref approach is more performant
export function useAsyncData<T>(asyncFn: () => Promise<T>) {
  const [state, setState] = useState<AsyncState<T>>({ status: 'idle' });
  const latestRequestRef = useRef<symbol>();
  
  const execute = useCallback(async () => {
    const requestId = Symbol();
    latestRequestRef.current = requestId;
    
    setState({ status: 'loading' });
    
    try {
      const result = await asyncFn();
      
      // Only update if this is still the latest request
      if (latestRequestRef.current === requestId) {
        setState({ status: 'success', data: result });
      }
    } catch (error) {
      if (latestRequestRef.current === requestId) {
        setState({ status: 'error', error });
      }
    }
  }, [asyncFn]);
  
  return { ...state, execute };
}
```

## Common AI Anti-Patterns

### Code Duplication Prevention

<Callout type="info">
  **Research Finding**: AI increases code duplication by 400% in codebases without proper guidelines.
</Callout>

<Tabs items={["❌ AI Duplication", "✅ Reuse Pattern"]}>
  <Tab>
    ```typescript
    // File 1: AI generated formatting
    function formatPrice(amount: number) {
      return new Intl.NumberFormat('en-US', { 
        style: 'currency', 
        currency: 'USD' 
      }).format(amount);
    }

    // File 2: AI regenerated same logic with different name
    function displayPrice(value: number) {
      return new Intl.NumberFormat('en-US', { 
        style: 'currency', 
        currency: 'USD' 
      }).format(value);
    }
    ```
  </Tab>

  <Tab>
    ```typescript
    // Check domains first: core/domains/pricing/utils
    import { formatCurrency } from '@/core/domains/pricing';

    // Use existing implementation
    const displayPrice = (value: number) => formatCurrency(value);
    ```
  </Tab>
</Tabs>

### Performance Optimization

AI tends toward working but unoptimized solutions:

<Tabs items={["❌ Inefficient", "✅ Optimized"]}>
  <Tab>
    ```typescript
    // O(n²) complexity - works but slow
    function findUserPosts(users: User[], posts: Post[]) {
      return users.map(user => ({
        ...user,
        posts: posts.filter(post => post.userId === user.id)
      }));
    }
    ```
  </Tab>

  <Tab>
    ```typescript
    // O(n) complexity - optimized approach
    function findUserPosts(users: User[], posts: Post[]) {
      const postsByUserId = groupBy(posts, 'userId');
      return users.map(user => ({
        ...user,
        posts: postsByUserId[user.id] || []
      }));
    }
    ```
  </Tab>
</Tabs>

### Memory Leak Prevention

AI often creates memory leaks through improper cleanup:

<Tabs items={["❌ Memory Leak", "✅ Proper Cleanup"]}>
  <Tab>
    ```typescript
    // Missing cleanup - memory leak
    useEffect(() => {
      const subscription = eventEmitter.on('data', handleData);
      // ❌ No cleanup function
    }, []);
    ```
  </Tab>

  <Tab>
    ```typescript
    // Proper cleanup prevents memory leaks
    useEffect(() => {
      const subscription = eventEmitter.on('data', handleData);
      return () => subscription.unsubscribe();
    }, [handleData]);
    ```
  </Tab>
</Tabs>

## Testing AI-Generated Code

### Comprehensive Test Requirements

AI-generated tests must include:

1. **Edge Cases**: AI often misses boundary conditions
2. **Error Scenarios**: Happy path bias is common
3. **Integration Context**: Not just isolated unit tests

<Tabs items={["❌ Shallow Tests", "✅ Comprehensive Suite"]}>
  <Tab>
    ```typescript
    // Only tests happy path
    test('processes user data', () => {
      const result = processUser({ id: '1', name: 'John' });
      expect(result.name).toBe('John');
    });
    ```
  </Tab>

  <Tab>
    ```typescript
    describe('processUser', () => {
      test('processes valid user data', () => {
        const result = processUser({ id: '1', name: 'John' });
        expect(result.name).toBe('John');
      });

      test('throws on invalid user ID', () => {
        expect(() => processUser({ id: '', name: 'John' }))
          .toThrow('Invalid user ID');
      });

      test('sanitizes potentially malicious input', () => {
        const result = processUser({ 
          id: '1', 
          name: '<script>alert("xss")</script>' 
        });
        expect(result.name).not.toContain('<script>');
      });

      test('handles missing properties gracefully', () => {
        const result = processUser({ id: '1' } as any);
        expect(result.name).toBe('');
      });

      test('validates data types correctly', () => {
        expect(() => processUser({ id: 123, name: 'John' } as any))
          .toThrow('User ID must be a string');
      });
    });
    ```
  </Tab>
</Tabs>

## Architectural Compliance

### Correct File Placement

AI frequently places code in wrong locations. Always verify:

```
❌ WRONG (Common AI mistakes):
features/products/api/         → Should be: core/domains/products/
features/home/components/Button/ → Should be: ui/foundation/Button/
ui/ProductCard/               → Should be: ui/business/ProductCard/
core/shared/utils/cartTotal.ts → Should be: features/cart/utils/

✅ CORRECT Architecture:
core/domains/[entity]/        → Business logic and data access
ui/foundation/[component]/    → Atomic UI components
ui/patterns/[pattern]/        → Composed UI patterns
ui/business/[component]/      → Domain-aware UI (3+ features)
features/[feature]/           → Feature-specific code
```

### Component Structure Standard

All AI-generated components MUST follow this exact structure:

```typescript
// 1. Imports (canonical order)
import React, { useState, useCallback, useEffect } from 'react';
import { View, Text, StyleSheet } from 'react-native';
import { useTheme } from '@core/shared/styles';
import { Button } from '@/ui/foundation/Button';

// 2. Types/Interfaces
interface ComponentProps {
  title: string;
  onPress: () => void;
  disabled?: boolean;
}

// 3. Main Component (function declaration)
export function ComponentName(props: ComponentProps) {
  // 4. Hooks
  const theme = useTheme();
  const [isLoading, setIsLoading] = useState(false);
  
  // 5. Derived state
  const isDisabled = isLoading || props.disabled || !props.title;
  
  // 6. Effects
  useEffect(() => {
    // Side effects here
  }, []);
  
  // 7. Handlers (memoized)
  const handlePress = useCallback(() => {
    if (isDisabled) return;
    setIsLoading(true);
    
    try {
      props.onPress();
    } finally {
      setIsLoading(false);
    }
  }, [props.onPress, isDisabled]);
  
  // 8. Render helpers
  const renderTitle = () => (
    <Text style={[styles.title, { color: theme.colors.text }]}>
      {props.title}
    </Text>
  );
  
  // 9. Return JSX
  return (
    <View style={styles.container}>
      {renderTitle()}
      <Button 
        onPress={handlePress} 
        disabled={isDisabled}
        loading={isLoading}
      />
    </View>
  );
}

// 10. Styles
const styles = StyleSheet.create({
  container: {
    padding: 16,
  },
  title: {
    fontSize: 18,
    fontWeight: 'bold',
    marginBottom: 12,
  },
});
```

## AI Code Review Checklist

Before merging AI-generated code, verify:

* [ ] **Security**: Input validation, authentication, XSS prevention
* [ ] **Architecture**: File placed in correct location per decision tree
* [ ] **Reusability**: Checked for existing similar implementations
* [ ] **Performance**: No memory leaks, optimized algorithms
* [ ] **Testing**: Edge cases and error scenarios covered
* [ ] **Types**: No `any` types, proper TypeScript interfaces
* [ ] **Imports**: Following canonical import paths
* [ ] **Context**: Business logic and decisions documented
* [ ] **Accessibility**: WCAG compliance where applicable
* [ ] **Error Handling**: Graceful degradation implemented

## Prompt Engineering Best Practices

### Context-Rich Prompts

<Tabs items={["❌ Poor Prompt", "✅ Effective Prompt"]}>
  <Tab>
    ```
    "Create a login component"
    ```
  </Tab>

  <Tab>
    ```
    "Create a login component for React Native following our established patterns:

    Requirements:
    - Use canonical theme system (@core/shared/styles)
    - Include proper TypeScript interfaces
    - Handle loading/error/success states
    - Support accessibility (screen readers)
    - Follow security validation patterns
    - Include comprehensive error handling
    - Use memoization for performance
    - Place in correct architectural location

    Context:
    - Part of authentication flow
    - Integrates with existing auth domain
    - Must handle network failures gracefully
    - Supports both email and social login"
    ```
  </Tab>
</Tabs>

### Iterative Refinement Process

Never accept first AI output. Follow this process:

<Steps>
  <Step>
    ### Initial Review

    Check for obvious security issues and architectural violations
  </Step>

  <Step>
    ### Performance Analysis

    Review for memory leaks, inefficient algorithms, unnecessary re-renders
  </Step>

  <Step>
    ### Edge Case Testing

    Test boundary conditions, error scenarios, and integration points
  </Step>

  <Step>
    ### Standards Compliance

    Verify imports, naming conventions, and documentation requirements
  </Step>

  <Step>
    ### Refinement

    Iterate based on findings and re-review
  </Step>
</Steps>

## Integration with Project Standards

This guide integrates with and extends:

* **[Import Path Standards](/docs/coding-standards/import-path-standards)** - For consistent module imports
* **[TypeScript React Patterns](/docs/coding-standards/typescript-react-patterns)** - For code structure
* **[UTA Terminology](/docs/coding-standards/uta-terminology)** - For naming consistency
* **[Feature Implementation Decision Tree](/docs/guides/feature-implementation-decision-tree)** - For architectural decisions

## Success Metrics

Teams following these AI coding standards report:

<div className="grid grid-cols-2 gap-4 my-6">
  <div className="bg-green-50 p-4 rounded-lg">
    <h4 className="font-semibold text-green-800">Quality Improvements</h4>

    <ul className="text-sm text-green-700 mt-2 space-y-1">
      <li>• 28% fewer defects in production</li>
      <li>• 60% reduction in security vulnerabilities</li>
      <li>• 45% decrease in code duplication</li>
    </ul>
  </div>

  <div className="bg-blue-50 p-4 rounded-lg">
    <h4 className="font-semibold text-blue-800">Team Productivity</h4>

    <ul className="text-sm text-blue-700 mt-2 space-y-1">
      <li>• 67% fewer context-related questions</li>
      <li>• 40% faster onboarding time</li>
      <li>• 52% reduction in code review cycles</li>
    </ul>
  </div>
</div>

## Response Format for AI Assistants

When requesting AI assistance, expect this structured response format:

1. **Architecture Check**: "Based on the Feature Implementation Decision Tree, this code belongs in..."
2. **Pattern Search**: "I found existing patterns in \[location] that I'll follow\..."
3. **Security Review**: "Security considerations include..."
4. **Context Documentation**: "Business context and decisions..."
5. **Implementation**: "Here's the implementation following our standards..."

<Callout>
  **Remember**: AI is a powerful amplifier of human expertise. These guidelines ensure that amplification enhances rather than compromises code quality, security, and maintainability.
</Callout>

## Related Resources

* [Why Standards Matter](/docs/coding-standards/why-standards-matter) - Understanding the business impact
* [TypeScript React Patterns](/docs/coding-standards/typescript-react-patterns) - Specific implementation patterns
* [Import Path Standards](/docs/coding-standards/import-path-standards) - Module organization rules
* [Feature Implementation Decision Tree](/docs/guides/feature-implementation-decision-tree) - Architectural guidance


# UTA Coding Standards: File Naming Conventions
URL: https://dev.updatetheapp.com/docs/coding-standards/file-naming-conventions
Documentation: https://dev.updatetheapp.com/docs/coding-standards/file-naming-conventions

Comprehensive guidelines for file and folder naming conventions in the React Native project.
        
***

title: File Naming Conventions
description: Comprehensive guidelines for file and folder naming conventions in the React Native project.
---------------------------------------------------------------------------------------------------------

# File Naming Conventions

## Overview

This document establishes the official file and folder naming conventions for our React Native project. These conventions ensure consistency, readability, and maintainability across the codebase while aligning with React community best practices.

## Purpose & Scope

These conventions apply to all files and folders in the project, covering:

* React components
* Custom hooks
* Domain files
* Utility functions
* Test files
* Configuration files

Following these conventions is mandatory for all team members to maintain code consistency.

## General Principles

1. **Consistency**: Apply conventions uniformly across the project
2. **Clarity**: Names should be self-documenting
3. **Tool-friendly**: Compatible with IDEs, linters, and build tools
4. **Community alignment**: Follow React ecosystem standards

## Component Files

### Convention

Use **PascalCase** for React component files and folders.

### Examples

```
ui/Button/Button.tsx
features/product-catalog/components/ProductCard/ProductCard.tsx
features/shopping-cart/components/CartItem/CartItem.tsx
```

### Rules

* Component filename must match the component name
* Main component file should have the same name as its folder
* Always use `.tsx` extension for components

### Structure

```
ComponentName/
├── ComponentName.tsx    # Main component
├── styles.ts           # Component styles
├── types.ts            # Component types (optional)
├── index.ts            # Barrel export
└── ComponentName.test.tsx # Component tests
```

## Hook Files

### Convention

Use **camelCase** starting with "use" for custom hooks.

### Examples

```
core/shared/hooks/useDebounce.ts
core/shared/hooks/useLocalStorage.ts
core/domains/products/hooks.ts  # Contains multiple hooks
```

### Rules

* Hook names must start with "use"
* Single hook per file in shared hooks
* Multiple related hooks can be in domain `hooks.ts`
* Use `.ts` extension (not `.tsx`) for hooks

### Examples in Code

```typescript
// core/shared/hooks/useDebounce.ts
export function useDebounce<T>(value: T, delay: number): T { }

// core/domains/products/hooks.ts
export function useProducts() { }
export function useProduct(id: string) { }
export function useCreateProduct() { }
```

## Domain Files

### Convention

Use **lowercase descriptive names** for domain-specific files.

### Standard Domain Files

```
core/domains/products/
├── api.ts          # API service methods
├── types.ts        # Type definitions
├── hooks.ts        # Query/mutation hooks
├── queryKeys.ts    # Query key factory
├── store.ts        # Client state (if needed)
├── events.ts       # Event definitions (if needed)
├── utils.ts        # Domain utilities (if needed)
└── index.ts        # Barrel exports
```

### Rules

* Keep names simple and descriptive
* Don't prefix with domain name (already in folder)
* Use consistent names across all domains
* Optional files only when needed

## Utility Files

### Convention

Use **category-based lowercase names** for utility functions.

### Examples

```
core/shared/utils/
├── date.ts         # Date formatting utilities
├── string.ts       # String manipulation
├── number.ts       # Number formatting
├── validation.ts   # Generic validators
├── array.ts        # Array utilities
└── index.ts        # Barrel exports
```

### Rules

* Group utilities by function type
* Keep names generic and descriptive
* Use plural for collection utilities
* No prefixes or suffixes

## Feature Folders

### Convention

Use **kebab-case** for feature folders.

### Examples

```
features/
├── product-catalog/
├── shopping-cart/
├── user-profile/
├── checkout-flow/
└── order-history/
```

### Rules

* Use hyphens to separate words
* Keep names descriptive but concise
* Reflect user-facing functionality
* Avoid technical terms

## Test Files

### Convention

Use `.test.ts` or `.test.tsx` suffix for test files.

### Examples

```
Button.test.tsx
useAuth.test.ts
api.test.ts
ProductCard.test.tsx
```

### Rules

* Place tests next to the file being tested
* Or in `__tests__` folder for organization
* Match the name of the file being tested
* Use `.test.tsx` for component tests
* Use `.test.ts` for non-component tests

### Test Folder Structure

```
ComponentName/
├── ComponentName.tsx
├── ComponentName.test.tsx
└── __tests__/
    ├── ComponentName.integration.test.tsx
    └── ComponentName.snapshot.test.tsx
```

## Index Files

### Convention

Use `index.ts` for barrel exports.

### Examples

```
core/domains/products/index.ts
ui/Button/index.ts
core/shared/hooks/index.ts
features/product-catalog/components/index.ts
```

### Purpose

* Simplify imports
* Create public API for modules
* Re-export relevant items

### Example Content

```typescript
// core/domains/products/index.ts
export * from './api';
export * from './types';
export * from './hooks';
export { productQueryKeys } from './queryKeys';
```

## Multi-word Files

### Rules by Type

* **Components**: PascalCase (`ProductCard.tsx`)
* **Hooks**: camelCase (`useLocalStorage.ts`)
* **Domains**: lowercase (`queryKeys.ts`)
* **Features**: kebab-case (`product-catalog/`)
* **Utils**: lowercase (`dateHelpers.ts` or `date.ts`)

### Examples

```
ProductListScreen.tsx       # Component
useShoppingCart.ts         # Hook
product-catalog/           # Feature
formatCurrency.ts         # Utility
```

## Platform-specific Files

### Convention

Use platform suffixes when needed.

### Examples

```
Button.ios.tsx
Button.android.tsx
styles.ios.ts
styles.android.ts
useNativeFeature.ios.ts
useNativeFeature.android.ts
```

### Rules

* Only use when platform differences exist
* Default file without suffix for shared code
* Platform files override default

## Configuration Files

### Convention

Follow tool-specific conventions.

### Examples

```
.eslintrc.js           # ESLint config
.prettierrc            # Prettier config
babel.config.js        # Babel config
jest.config.js         # Jest config
tsconfig.json          # TypeScript config
metro.config.js        # Metro config
app.config.js          # Expo config
```

### Rules

* Use the format required by the tool
* Include tool name in filename when possible
* Place in project root by default

## Special Cases

### Private Files

Use underscore prefix for internal files:

```
_helpers.ts            # Internal helpers
_constants.ts          # Internal constants
```

### Temporary Files

Use `.temp` suffix:

```
data.temp.json         # Temporary data
backup.temp.ts         # Temporary backup
```

### Generated Files

Use `.generated` suffix:

```
schema.generated.ts    # Generated from GraphQL
types.generated.ts     # Generated types
```

## Do's and Don'ts

### Component Naming

* (Do ✅) `ProductCard.tsx` - PascalCase
* (Don't ❌) `productCard.tsx` - Wrong case
* (Don't ❌) `product-card.tsx` - Wrong convention

### Hook Naming

* (Do ✅) `useAuth.ts` - Starts with "use"
* (Don't ❌) `authHook.ts` - Missing "use" prefix
* (Don't ❌) `UseAuth.ts` - Wrong case

### Feature Naming

* (Do ✅) `shopping-cart/` - Kebab-case
* (Don't ❌) `shoppingCart/` - Wrong case
* (Don't ❌) `shopping_cart/` - Wrong separator

### Test Naming

* (Do ✅) `Button.test.tsx` - Clear test file
* (Don't ❌) `Button.spec.tsx` - Use .test instead
* (Don't ❌) `ButtonTests.tsx` - Use standard suffix

## Directory Examples

### Complete Feature Structure

```
features/product-catalog/
├── components/
│   ├── ProductCard/
│   │   ├── ProductCard.tsx
│   │   ├── ProductCard.test.tsx
│   │   ├── styles.ts
│   │   └── index.ts
│   └── ProductFilters/
│       ├── ProductFilters.tsx
│       └── index.ts
├── screens/
│   └── ProductListScreen/
│       ├── ProductListScreen.tsx
│       ├── ProductListScreen.test.tsx
│       └── index.ts
├── navigation.tsx
└── state/
    └── filtersStore.ts
```

### Complete Domain Structure

```
core/domains/products/
├── api.ts
├── types.ts
├── hooks.ts
├── queryKeys.ts
├── store.ts
├── events.ts
├── utils.ts
├── index.ts
└── __tests__/
    ├── api.test.ts
    ├── hooks.test.ts
    └── utils.test.ts
```

## Enforcement

### ESLint Rules

Configure ESLint to enforce naming conventions:

```javascript
// .eslintrc.js
module.exports = {
  rules: {
    'filename-rules/match': [2, {
      '**/*.tsx': 'PascalCase',
      '**/use*.ts': 'camelCase',
      '**/features/*': 'kebab-case',
    }],
  },
};
```

### Pre-commit Hooks

Use tools like lint-staged to check naming:

```json
// package.json
{
  "lint-staged": {
    "**/*.{ts,tsx}": [
      "eslint --fix",
      "prettier --write"
    ]
  }
}
```

## Migration Guide

When updating existing files:

1. **Identify non-conforming files**
   ```bash
   find src -type f -name "*.tsx" | grep -v "[A-Z]"
   ```

2. **Update imports**
   * Use IDE refactoring tools
   * Update all import statements
   * Update barrel exports

3. **Update tests**
   * Rename test files
   * Update test imports

4. **Verify build**
   * Run full build
   * Run all tests
   * Check for broken imports

## Summary

These naming conventions ensure:

* **Consistency** across the codebase
* **Clarity** in file purpose
* **Compatibility** with tools
* **Scalability** as project grows

All team members must follow these conventions for new files and when refactoring existing code.

## Related Documents

* [Project Structure Reference](/docs/project-structure)
* [Component Development Guide](/docs/guides/component-development)
* [Coding Standards](/docs/coding-standards)
* [Domain Architecture Guide](/docs/architecture/domain-architecture)


# UTA Coding Standards: TypeScript & React Patterns
URL: https://dev.updatetheapp.com/docs/coding-standards/typescript-react-patterns
Documentation: https://dev.updatetheapp.com/docs/coding-standards/typescript-react-patterns

Comprehensive coding patterns and conventions for TypeScript and React Native development
        
***

title: TypeScript & React Patterns
description: Comprehensive coding patterns and conventions for TypeScript and React Native development
------------------------------------------------------------------------------------------------------

import { Callout } from 'fumadocs-ui/components/callout';
import { Tabs, Tab } from 'fumadocs-ui/components/tabs';
import { Steps, Step } from 'fumadocs-ui/components/steps';

# TypeScript & React Patterns

## Overview

This document defines the **exact** patterns and conventions for TypeScript and React Native development. Every team member and AI assistant must follow these patterns to maintain our "single author" codebase consistency.

<Callout type="warning">
  **Mandatory**: These patterns are not suggestions. They are required standards that must be followed in all code.
</Callout>

## TypeScript Conventions

### Type vs Interface

**Rule**: Use `interface` for object shapes, `type` for unions, intersections, and primitives.

```typescript
// ✅ GOOD - Interface for objects
interface User {
  id: string;
  name: string;
  email: string;
}

interface ApiResponse<T> {
  data: T;
  status: number;
  message?: string;
}

// ✅ GOOD - Type for unions and primitives
type Status = 'idle' | 'loading' | 'success' | 'error';
type ID = string | number;
type Nullable<T> = T | null;

// ❌ BAD - Using type for simple objects
type User = {
  id: string;
  name: string;
};
```

### Naming Conventions

```typescript
// Interfaces: PascalCase with descriptive names
interface UserProfile { }
interface ApiClientConfig { }
interface AuthenticationState { }

// Types: PascalCase, descriptive with suffix for clarity
type ButtonVariant = 'primary' | 'secondary';
type ApiMethod = 'GET' | 'POST' | 'PUT' | 'DELETE';
type UserId = string;

// Enums: PascalCase with UPPER_SNAKE_CASE values
enum UserRole {
  ADMIN = 'ADMIN',
  USER = 'USER',
  GUEST = 'GUEST'
}

// Generic Type Parameters: Single uppercase letters or descriptive
function map<T, R>(items: T[], fn: (item: T) => R): R[] { }
interface ApiResponse<TData, TError = Error> { }
```

### Function Types

```typescript
// ✅ GOOD - Clear function type definitions
interface UserService {
  getUser: (id: string) => Promise<User>;
  updateUser: (id: string, data: Partial<User>) => Promise<User>;
  deleteUser: (id: string) => Promise<void>;
}

// ✅ GOOD - Standalone function types
type Validator<T> = (value: T) => boolean;
type AsyncCallback<T> = (data: T) => Promise<void>;

// ❌ BAD - Unclear or overly complex inline types
interface Service {
  fetch: (id: string) => Promise<any>; // Avoid 'any'
  update: Function; // Too generic
}
```

### Import Organization

**Rule**: Organize imports in this exact order:

```typescript
// 1. React and React Native imports
import React, { useState, useEffect } from 'react';
import { View, Text, StyleSheet } from 'react-native';

// 2. Third-party libraries
import { useQuery } from '@tanstack/react-query';
import { z } from 'zod';

// 3. Absolute imports from project (ordered by path depth)
import { useAuth } from '@/core/domains/auth';
import { Button } from '@/ui/foundation/Button';
import { Modal } from '@/ui/patterns/Modal';
import { ProductCard } from '@/ui/business/ProductCard';
import { api } from '@/core/api';

// 4. Relative imports
import { LocalComponent } from './LocalComponent';
import { styles } from './styles';
import type { LocalType } from './types';

// 5. Type imports (if not inline)
import type { User, Product } from '@/core/domains/types';
```

## React Component Patterns

### Functional Components

**Rule**: Always use function declarations for components, arrow functions for inline callbacks.

```typescript
// ✅ GOOD - Function declaration for components
export function UserCard({ user, onPress }: UserCardProps) {
  return (
    <TouchableOpacity onPress={() => onPress(user.id)}>
      <Text>{user.name}</Text>
    </TouchableOpacity>
  );
}

// ❌ BAD - Arrow function for components
export const UserCard = ({ user, onPress }: UserCardProps) => { };
```

### Component Structure

**Rule**: Follow this exact structure for all components:

```typescript
// 1. Imports
import React, { useState, useEffect } from 'react';
import { View, Text } from 'react-native';

// 2. Type definitions
interface ProductCardProps {
  product: Product;
  onPress?: (id: string) => void;
  variant?: 'default' | 'compact';
}

// 3. Component definition
export function ProductCard({ 
  product, 
  onPress,
  variant = 'default' 
}: ProductCardProps) {
  // 4. Hooks (state, context, custom)
  const [isLoaded, setIsLoaded] = useState(false);
  const { user } = useAuth();
  
  // 5. Derived state / memoized values
  const formattedPrice = useMemo(
    () => formatCurrency(product.price),
    [product.price]
  );
  
  // 6. Effects
  useEffect(() => {
    // Effect logic
  }, []);
  
  // 7. Event handlers
  const handlePress = useCallback(() => {
    onPress?.(product.id);
  }, [product.id, onPress]);
  
  // 8. Render helpers (if needed)
  const renderPrice = () => {
    return <Text>{formattedPrice}</Text>;
  };
  
  // 9. Main render
  return (
    <View style={styles.container}>
      {/* Component JSX */}
    </View>
  );
}

// 10. Styles (if in same file)
const styles = StyleSheet.create({
  container: {
    // styles
  }
});
```

### Props Patterns

```typescript
// ✅ GOOD - Explicit, well-typed props
interface ButtonProps {
  title: string;
  onPress: () => void;
  variant?: 'primary' | 'secondary';
  disabled?: boolean;
  loading?: boolean;
  testID?: string;
}

// ✅ GOOD - Extending native props
interface CustomTextProps extends TextProps {
  variant?: 'heading' | 'body' | 'caption';
  color?: keyof typeof theme.colors;
}

// ❌ BAD - Unclear or overly permissive props
interface ButtonProps {
  [key: string]: any; // Too permissive
  onClick: Function; // Too generic
  style?: any; // Should be ViewStyle
}
```

## Hook Patterns

### Custom Hook Structure

```typescript
// ✅ GOOD - Well-structured custom hook
export function useProductSearch(initialQuery = '') {
  // 1. State declarations
  const [query, setQuery] = useState(initialQuery);
  const [filters, setFilters] = useState<ProductFilters>({});
  
  // 2. Other hooks
  const debouncedQuery = useDebounce(query, 300);
  
  // 3. Queries/mutations
  const { data, isLoading, error } = useQuery({
    queryKey: ['products', 'search', debouncedQuery, filters],
    queryFn: () => searchProducts(debouncedQuery, filters),
    enabled: debouncedQuery.length > 0,
  });
  
  // 4. Callbacks/handlers
  const updateFilters = useCallback((newFilters: Partial<ProductFilters>) => {
    setFilters(prev => ({ ...prev, ...newFilters }));
  }, []);
  
  // 5. Effects
  useEffect(() => {
    // Reset filters when query changes significantly
    if (query.length === 0) {
      setFilters({});
    }
  }, [query]);
  
  // 6. Return object with consistent naming
  return {
    // State
    query,
    filters,
    products: data?.products ?? [],
    
    // Status
    isLoading,
    error,
    
    // Actions
    setQuery,
    updateFilters,
    clearFilters: () => setFilters({}),
  };
}
```

### Hook Naming Conventions

```typescript
// Data fetching hooks
useUser(id: string)           // Single item
useUsers(filters?: Filters)   // Multiple items
useCreateUser()              // Mutation
useUpdateUser()              // Mutation
useDeleteUser()              // Mutation

// State management hooks
useCartState()               // Local state
useAuthState()               // Global state
useFormState<T>()            // Generic state

// Utility hooks
useDebounce<T>(value: T, delay: number)
useLocalStorage<T>(key: string, initialValue: T)
usePrevious<T>(value: T)
```

## State Management Patterns

### Local State

```typescript
// ✅ GOOD - Clear state management
function ProductList() {
  // Group related state
  const [filters, setFilters] = useState<ProductFilters>({
    category: null,
    priceRange: null,
    sortBy: 'relevance',
  });
  
  // Separate concerns
  const [selectedIds, setSelectedIds] = useState<Set<string>>(new Set());
  const [isSelectionMode, setIsSelectionMode] = useState(false);
  
  // Update functions next to state
  const toggleSelection = (id: string) => {
    setSelectedIds(prev => {
      const next = new Set(prev);
      if (next.has(id)) {
        next.delete(id);
      } else {
        next.add(id);
      }
      return next;
    });
  };
}
```

### Global State (Zustand)

```typescript
// ✅ GOOD - Consistent store structure
interface CartStore {
  // State
  items: CartItem[];
  isLoading: boolean;
  
  // Computed
  get total(): number;
  get itemCount(): number;
  
  // Actions
  addItem: (product: Product, quantity: number) => void;
  removeItem: (productId: string) => void;
  updateQuantity: (productId: string, quantity: number) => void;
  clearCart: () => void;
  
  // Async actions
  syncWithServer: () => Promise<void>;
}

export const useCartStore = create<CartStore>((set, get) => ({
  // Implementation
}));
```

## Error Handling Patterns

### Try-Catch Patterns

```typescript
// ✅ GOOD - Consistent error handling
async function updateUserProfile(data: UpdateProfileData) {
  try {
    // Input validation first
    const validated = profileSchema.parse(data);
    
    // Main operation
    const response = await api.updateProfile(validated);
    
    // Success handling
    showToast({ type: 'success', message: 'Profile updated' });
    return response;
    
  } catch (error) {
    // Type-safe error handling
    if (error instanceof ZodError) {
      showToast({ type: 'error', message: 'Invalid data' });
      throw new ValidationError('Profile validation failed', error);
    }
    
    if (error instanceof ApiError) {
      showToast({ type: 'error', message: error.message });
      throw error;
    }
    
    // Unknown errors
    console.error('Unexpected error:', error);
    showToast({ type: 'error', message: 'Something went wrong' });
    throw new Error('Failed to update profile');
  }
}
```

### Error Boundaries

```typescript
// ✅ GOOD - Feature-level error boundary
export function ProductListScreen() {
  return (
    <ErrorBoundary
      fallback={<ErrorFallback onRetry={() => window.location.reload()} />}
      onError={(error) => {
        logError(error, { screen: 'ProductList' });
      }}
    >
      <ProductList />
    </ErrorBoundary>
  );
}
```

## Performance Patterns

### Memoization Rules

```typescript
// ✅ GOOD - Appropriate memoization
function ProductCard({ product, onPress }: ProductCardProps) {
  // Memoize expensive computations
  const discountPercentage = useMemo(
    () => calculateDiscount(product.price, product.salePrice),
    [product.price, product.salePrice]
  );
  
  // Memoize callbacks passed to children
  const handlePress = useCallback(() => {
    onPress(product.id);
  }, [product.id, onPress]);
  
  // Don't memoize simple operations
  const isOnSale = product.salePrice < product.price; // ✅ Simple comparison
  
  return <View>{/* ... */}</View>;
}

// Component memoization for expensive renders
export const ProductCard = memo(_ProductCard, (prev, next) => {
  return prev.product.id === next.product.id &&
         prev.product.updatedAt === next.product.updatedAt;
});
```

### List Rendering

```typescript
// ✅ GOOD - Optimized list rendering
function ProductList({ products }: { products: Product[] }) {
  const renderItem = useCallback(({ item }: { item: Product }) => (
    <ProductCard
      key={item.id} // Always include key
      product={item}
      onPress={handleProductPress}
    />
  ), [handleProductPress]);
  
  const keyExtractor = useCallback((item: Product) => item.id, []);
  
  const getItemLayout = useCallback((data: any, index: number) => ({
    length: ITEM_HEIGHT,
    offset: ITEM_HEIGHT * index,
    index,
  }), []);
  
  return (
    <FlatList
      data={products}
      renderItem={renderItem}
      keyExtractor={keyExtractor}
      getItemLayout={getItemLayout}
      removeClippedSubviews
      maxToRenderPerBatch={10}
      windowSize={10}
    />
  );
}
```

## Testing Patterns

### Component Testing

```typescript
// ✅ GOOD - Comprehensive component test
describe('ProductCard', () => {
  const mockProduct: Product = {
    id: '1',
    name: 'Test Product',
    price: 99.99,
    image: 'https://example.com/image.jpg',
  };
  
  it('renders product information correctly', () => {
    const { getByText, getByTestId } = render(
      <ProductCard product={mockProduct} />
    );
    
    expect(getByText('Test Product')).toBeTruthy();
    expect(getByText('$99.99')).toBeTruthy();
    expect(getByTestId('product-image')).toHaveProperty('source', {
      uri: mockProduct.image,
    });
  });
  
  it('calls onPress with product id when pressed', () => {
    const onPress = jest.fn();
    const { getByTestId } = render(
      <ProductCard product={mockProduct} onPress={onPress} />
    );
    
    fireEvent.press(getByTestId('product-card'));
    expect(onPress).toHaveBeenCalledWith(mockProduct.id);
  });
});
```

## Code Comments

### When to Comment

```typescript
// ✅ GOOD - Explains why, not what
function calculateShippingCost(items: CartItem[], address: Address): number {
  // Free shipping for orders over $100 (business requirement BR-123)
  if (getTotalPrice(items) > 100) {
    return 0;
  }
  
  // Express shipping surcharge for specific regions due to carrier limitations
  const expressSurcharge = EXPRESS_REGIONS.includes(address.state) ? 15 : 0;
  
  return BASE_SHIPPING_COST + expressSurcharge;
}

// ❌ BAD - Obvious comments
function addNumbers(a: number, b: number): number {
  // Add a and b together
  return a + b; // Return the sum
}
```

### Documentation Comments

````typescript
/**
 * Processes a payment using the configured payment provider.
 * 
 * @param payment - Payment details including amount and method
 * @param options - Additional processing options
 * @returns Payment confirmation or throws PaymentError
 * 
 * @example
 * ```typescript
 * const confirmation = await processPayment({
 *   amount: 99.99,
 *   method: 'credit_card',
 *   token: 'tok_123'
 * });
 * ```
 * 
 * @throws {PaymentError} When payment fails or is declined
 * @throws {ValidationError} When payment data is invalid
 */
export async function processPayment(
  payment: PaymentRequest,
  options?: PaymentOptions
): Promise<PaymentConfirmation> {
  // Implementation
}
````

## Common Anti-Patterns to Avoid

<Callout type="danger">
  **Never do these in our codebase:**
</Callout>

```typescript
// ❌ Using 'any' type
const data: any = fetchData(); // BAD

// ❌ Ignoring TypeScript errors
// @ts-ignore // NEVER DO THIS
const result = someFunction();

// ❌ Inconsistent naming
const user_name = 'John'; // Should be userName
const GetUserData = () => {}; // Should be getUserData

// ❌ Magic numbers/strings
if (status === 2) { } // What is 2?
setTimeout(fn, 3000); // Use constants

// ❌ Nested ternaries
const color = isActive ? 'blue' : isDisabled ? 'gray' : isError ? 'red' : 'black';

// ❌ Large inline functions
<Button onPress={() => {
  // 20+ lines of code here
}} />

// ❌ Direct state mutations
state.items.push(newItem); // Mutating state
items[0].name = 'New Name'; // Mutating props
```

## Enforcement Checklist

Before submitting code, verify:

* [ ] All TypeScript errors are resolved
* [ ] Imports are organized correctly
* [ ] Component structure follows the standard
* [ ] Props are fully typed (no `any`)
* [ ] Custom hooks start with 'use'
* [ ] Error handling is comprehensive
* [ ] Performance optimizations are applied where needed
* [ ] Code comments explain 'why' not 'what'
* [ ] No anti-patterns are present

## Quick Reference

```typescript
// Interface for objects
interface User { name: string; }

// Type for unions/primitives  
type Status = 'active' | 'inactive';

// Function components
export function Component() { }

// Custom hooks
export function useCustomHook() { }

// Event handlers
const handleClick = () => { };

// Async functions
const fetchData = async () => { };

// Constants
const MAX_RETRIES = 3;
const API_TIMEOUT = 5000;
```

## Related Documents

* [File Naming Conventions](/docs/coding-standards/file-naming-conventions)
* [Testing Standards](/docs/testing/standards)
* [Component Development Guide](/docs/guides/component-development)
* [State Management Guide](/docs/guides/client-state-management)

## API Development Decision Matrix

### HTTP Method & Status Code Standards

Use this matrix for consistent API integration patterns:

| Scenario               | HTTP Method | Status Code | Response Format                | Error Handling                        |
| ---------------------- | ----------- | ----------- | ------------------------------ | ------------------------------------- |
| **Resource Creation**  | POST        | 201         | Created resource + location    | 400 for validation, 409 for conflicts |
| **Resource Retrieval** | GET         | 200/404     | Full resource or error         | 404 with helpful message              |
| **Resource Update**    | PUT/PATCH   | 200/204     | Updated resource or no content | 400 for validation, 404 if not found  |
| **Resource Deletion**  | DELETE      | 204         | No content                     | 404 if not found, 409 if dependencies |
| **Batch Operations**   | POST        | 207         | Multi-status response          | Individual status per item            |
| **Search/Filter**      | GET         | 200         | Paginated results              | 400 for invalid query params          |
| **File Upload**        | POST        | 201         | File metadata + URL            | 413 for file too large                |

### API Function Patterns

```typescript
// ✅ GOOD - Consistent API patterns
// core/domains/products/api.ts

// GET single resource
export const getProduct = async (id: string): Promise<Product> => {
  return apiClient.get(`/products/${id}`);
};

// GET collection with filters
export const getProducts = async (filters?: ProductFilters): Promise<PaginatedResponse<Product>> => {
  return apiClient.get('/products', { params: filters });
};

// CREATE resource
export const createProduct = async (data: CreateProductDTO): Promise<Product> => {
  return apiClient.post('/products', data);
};

// UPDATE resource (full)
export const updateProduct = async (id: string, data: UpdateProductDTO): Promise<Product> => {
  return apiClient.put(`/products/${id}`, data);
};

// UPDATE resource (partial)
export const patchProduct = async (id: string, data: Partial<UpdateProductDTO>): Promise<Product> => {
  return apiClient.patch(`/products/${id}`, data);
};

// DELETE resource
export const deleteProduct = async (id: string): Promise<void> => {
  return apiClient.delete(`/products/${id}`);
};

// BATCH operations
export const batchUpdateProducts = async (updates: BatchUpdate[]): Promise<BatchResponse> => {
  return apiClient.post('/products/batch', { operations: updates });
};
```

### React Query Integration Patterns

```typescript
// ✅ GOOD - Consistent hook patterns
// core/domains/products/hooks.ts

// GET hooks
export function useProduct(id: string, options?: UseQueryOptions<Product>) {
  return useQuery({
    queryKey: productQueryKeys.detail(id),
    queryFn: () => getProduct(id),
    staleTime: 5 * 60 * 1000, // 5 minutes
    ...options,
  });
}

export function useProducts(filters?: ProductFilters) {
  return useQuery({
    queryKey: productQueryKeys.list(filters),
    queryFn: () => getProducts(filters),
    staleTime: 1 * 60 * 1000, // 1 minute for lists
  });
}

// CREATE mutation
export function useCreateProduct() {
  const queryClient = useQueryClient();
  
  return useMutation({
    mutationFn: createProduct,
    onSuccess: (newProduct) => {
      // Invalidate and refetch lists
      queryClient.invalidateQueries({ 
        queryKey: productQueryKeys.lists() 
      });
      // Add to cache immediately
      queryClient.setQueryData(
        productQueryKeys.detail(newProduct.id),
        newProduct
      );
      showToast({ type: 'success', message: 'Product created successfully' });
    },
    onError: (error: ApiError) => {
      if (error.status === 409) {
        showToast({ type: 'error', message: 'Product already exists' });
      } else {
        showToast({ type: 'error', message: error.message });
      }
    },
  });
}

// UPDATE mutation
export function useUpdateProduct() {
  const queryClient = useQueryClient();
  
  return useMutation({
    mutationFn: ({ id, data }: { id: string; data: UpdateProductDTO }) =>
      updateProduct(id, data),
    onSuccess: (updatedProduct) => {
      // Update cache
      queryClient.setQueryData(
        productQueryKeys.detail(updatedProduct.id),
        updatedProduct
      );
      // Invalidate lists
      queryClient.invalidateQueries({ 
        queryKey: productQueryKeys.lists() 
      });
    },
  });
}

// DELETE mutation
export function useDeleteProduct() {
  const queryClient = useQueryClient();
  
  return useMutation({
    mutationFn: deleteProduct,
    onSuccess: (_, deletedId) => {
      // Remove from cache
      queryClient.removeQueries({
        queryKey: productQueryKeys.detail(deletedId),
      });
      // Invalidate lists
      queryClient.invalidateQueries({ 
        queryKey: productQueryKeys.lists() 
      });
    },
  });
}
```

### Error Response Handling

```typescript
// ✅ GOOD - Standardized error responses
interface ApiErrorResponse {
  error: {
    code: string;
    message: string;
    details?: Record<string, any>;
    timestamp: string;
    path: string;
  };
}

// Error handler in API client
const handleApiError = (error: AxiosError<ApiErrorResponse>): never => {
  if (error.response) {
    const { status, data } = error.response;
    
    switch (status) {
      case 400:
        throw new ValidationError(data.error.message, data.error.details);
      case 401:
        throw new AuthenticationError('Please login to continue');
      case 403:
        throw new AuthorizationError('You do not have permission');
      case 404:
        throw new NotFoundError(data.error.message);
      case 409:
        throw new ConflictError(data.error.message);
      case 422:
        throw new ValidationError('Invalid data provided', data.error.details);
      case 429:
        throw new RateLimitError('Too many requests, please try again later');
      case 500:
        throw new ServerError('Server error, please try again');
      default:
        throw new ApiError(data.error.message, status);
    }
  }
  
  if (error.request) {
    throw new NetworkError('Network error, please check your connection');
  }
  
  throw new UnknownError('An unexpected error occurred');
};
```


# UTA Team: Team & Contributors
URL: https://dev.updatetheapp.com/docs/team
Documentation: https://dev.updatetheapp.com/docs/team

Meet the team behind the UTA ecosystem
        
***

title: Team & Contributors
description: Meet the team behind the UTA ecosystem
---------------------------------------------------

import { Card, Cards } from 'fumadocs-ui/components/card';
import { Callout } from 'fumadocs-ui/components/callout';

# Team & Contributors

The UTA ecosystem is built by a passionate team dedicated to revolutionizing mobile app development.

## Founder

<Cards>
  <Card title="TO NGOC PHUONG (Peter)" description="Founder">
    <p className="text-sm text-muted-foreground mt-2">
      Email: <a href="mailto:phuongwd@gmail.com">[phuongwd@gmail.com](mailto:phuongwd@gmail.com)</a>
    </p>

    <p className="text-sm mt-2">
      Passionate about creating standardized, opinionated architectures that help teams build and ship React Native apps faster with less decision fatigue.
    </p>
  </Card>
</Cards>

## Our Mission

We believe that developers should spend their time building features, not debating architecture. The UTA ecosystem provides:

* **THE standardized way** to build React Native apps
* **Instant deployment** without app store delays
* **Day-one productivity** for new team members
* **AI-optimized patterns** for 80% accuracy

## Contributing

The UTA ecosystem welcomes contributions from the community. Whether you're fixing bugs, improving documentation, or suggesting new features, we appreciate your help in making UTA better for everyone.

### How to Contribute

1. **Report Issues**: Found a bug or have a suggestion? Open an issue on GitHub
2. **Submit PRs**: Fork the repository and submit pull requests
3. **Improve Docs**: Help us make the documentation even clearer
4. **Share Feedback**: Tell us about your experience using UTA

### Recognition

We believe in recognizing all contributions, big and small. Contributors will be:

* Listed in our contributors section
* Mentioned in release notes
* Invited to shape the future of UTA

<Callout type="info">
  Want to join us in revolutionizing mobile app development? Reach out at [phuongwd@gmail.com](mailto:phuongwd@gmail.com)
</Callout>

## Sustainable Open Source

The UTA ecosystem is committed to sustainable open source development that balances community access with continued innovation:

* **Transparent Development**: All development happens in the open
* **Community First**: Decisions are made with the community in mind
* **Open Core Model**: Core framework is MIT licensed for maximum adoption
* **Value-Added Services**: Premium tooling, hosting, and enterprise features fund continued development

### Licensing Strategy

* **UTA Core Framework**: MIT License - free for all uses, modifications, and distributions
* **UTA Cloud Platform**: Freemium model with usage-based pricing for hosted services
* **Enterprise Tools**: Commercial licensing for advanced CI/CD, analytics, and dedicated support
* **Community Ecosystem**: Open source contributions welcomed and recognized

### What's Free Forever

* Core UTA template and architecture patterns
* Basic CLI tools and development utilities
* Community documentation and guides
* Standard deployment configurations

### Premium Ecosystem

Our sustainable model allows us to invest in:

* **UTA Cloud**: Hosted OTA updates, real-time analytics.
* **Enterprise Support**: Priority support, training, and custom integrations
* **Advanced Tooling**: AI-powered code generation, automated testing, and performance monitoring
* **Professional Services**: Implementation consulting and architecture reviews

<Callout type="success">
  This approach ensures UTA remains freely accessible to all developers while building a sustainable foundation for continuous innovation and enterprise-grade features.
</Callout>

***

*Building the future of mobile development, one standardized pattern at a time.*