mixpanel-react-native/claude/codebase-map.md

Official React Native Tracking Library for Mixpanel Analytics

# Codebase Map: mixpanel-react-native

## Executive Summary

This is a React Native library implementing Mixpanel analytics with a **dual architecture strategy**: native iOS/Android modules for performance plus pure JavaScript fallback for Expo/Web compatibility. The codebase demonstrates sophisticated cross-platform patterns with token-based multi-instance support.

## 🎯 Entry Points

### Primary Library Interface
- `index.js` - Main export exposing Mixpanel, People, and MixpanelGroup classes
- `index.d.ts` - TypeScript definitions with comprehensive type coverage
- `package.json` - Library metadata, dependencies (AsyncStorage, uuid, expo-crypto)

### Configuration
- `react-native.config.js` - React Native autolinking configuration for native modules
- `MixpanelReactNative.podspec` - iOS CocoaPods specification

## 🏗️ Core Architecture Components

### Native Implementation (Performance Path)
```
ios/
├── MixpanelReactNative.swift          # iOS bridge using Mixpanel Swift SDK
├── MixpanelReactNative.m              # Objective-C bridge file
├── AutomaticProperties.swift          # Device property collection
├── MixpanelTypeHandler.swift          # Type conversion utilities
└── Constants.swift                    # iOS-specific constants

android/src/main/java/com/mixpanel/reactnative/
├── MixpanelReactNativeModule.java     # Android bridge using Mixpanel Android SDK
├── MixpanelReactNativePackage.java    # React Native package registration
├── AutomaticProperties.java          # Device property collection
└── ReactNativeHelper.java            # Utility functions
```

### JavaScript Implementation (Compatibility Path)
```
javascript/
├── mixpanel-main.js                   # JS mode entry point - full API implementation
├── mixpanel-core.js                   # Core tracking logic shared between modes
├── mixpanel-queue.js                  # Event queue management with auto-flush
├── mixpanel-network.js                # HTTP client with retry logic
├── mixpanel-storage.js                # AsyncStorage abstraction layer
├── mixpanel-persistent.js             # State persistence management
├── mixpanel-config.js                 # Configuration management
├── mixpanel-logger.js                 # Centralized logging system
├── mixpanel-constants.js              # Shared constants and enums
└── mixpanel-utils.js                  # Utility functions
```

## 🧪 Testing Infrastructure

### Test Organization
```
__tests__/
├── jest_setup.js                      # Test environment configuration
├── core.test.js                       # Core functionality tests
├── index.test.js                      # Main API tests
├── main.test.js                       # JavaScript implementation tests
├── network.test.js                    # HTTP client tests
└── queue.test.js                      # Queue management tests

__mocks__/
└── @react-native-async-storage/       # AsyncStorage mock for testing
    └── async-storage.js
```

### Test Patterns
- **Comprehensive mocking**: All external dependencies (AsyncStorage, React Native modules)
- **Jest configuration**: Custom setup with React Native preset
- **Module isolation**: Each core component tested independently

## 📱 Sample Applications

### Development/Testing Apps
```
Samples/
├── SimpleMixpanel/                     # Basic integration example (TypeScript)
├── MixpanelDemo/                      # Full-featured demo app
├── ContextAPIMixpanel/                # React Context API integration
└── MixpanelExpo/                      # Expo-compatible example
```

Each sample includes complete React Native app structure with platform-specific builds.

## 📚 Documentation

### Generated Documentation
```
docs/                                   # JSDoc-generated API documentation
├── index.html                         # Main documentation entry
├── Mixpanel.html                      # Mixpanel class documentation
├── People.html                        # People Analytics documentation
└── MixpanelGroup.html                 # Group Analytics documentation
```

### Maintenance Scripts
- `generate_docs.sh` - JSDoc documentation generation script
- `release.py` - Release automation script

## 🔍 Key Architectural Insights

### Multi-Instance Design
- **Token-based isolation**: Each Mixpanel project gets separate instance
- **Shared infrastructure**: Common queue, network, and storage layers
- **State persistence**: User IDs, super properties survive app restarts

### Cross-Platform Strategy
- **Automatic fallback**: Native → JavaScript mode based on availability
- **Platform detection**: iOS/Android-specific behavior handling
- **Unified API**: Same interface regardless of implementation mode

### Performance Considerations
- **Batched flushing**: Events sent in configurable batches (default 50)
- **Background flushing**: Automatic data transmission on app state changes
- **Memory management**: In-memory queues with persistent backup

### Error Handling Philosophy
- **Graceful degradation**: JavaScript mode as native fallback
- **Input validation**: Comprehensive parameter checking with helpful errors
- **Logging strategy**: Centralized, configurable logging system

## 🔧 Configuration Patterns

### React Native Integration
- **Autolinking**: Automatic native module discovery
- **Manual linking support**: Fallback for older RN versions
- **Metro bundler**: Standard React Native build pipeline

### Dependencies Strategy [Updated: 2025-05-30]
- **Minimal external deps**: Only essential libraries (AsyncStorage, uuid, expo-crypto)
- **Platform compatibility**: Enhanced Expo support with expo-crypto for UUID generation
- **Version constraints**: Conservative dependency versioning
- **Graceful fallbacks**: expo-crypto optional, falls back to uuid package