Architecture Overview

Technical architecture, design patterns, and system design of the Peregrine mobile application.

Architecture Overview

This document provides a comprehensive overview of the Peregrine application’s technical architecture, design patterns, and structural organization.

Architecture Principles

The Peregrine application follows several core architectural principles:

Separation of Concerns - Clear boundaries between UI, business logic, and data layers
Pluggable Architecture - API adapters allow swapping backend implementations
Strict TypeScript - Type safety enforced throughout the codebase
Reusable Components - Custom components encapsulate Phenom-specific functionality
Centralized Theming - Design tokens managed in a single location

Directory Structure

PhenomApp/
├── app/
│   ├── components/
│   │   ├── phenom/                 # Custom Phenom-specific components
│   │   │   ├── EndlessMediaFeed.tsx
│   │   │   └── map/                # Map visualization components
│   │   │       ├── HexGlobeWireframe.tsx
│   │   │       ├── HexSelectionOverlay.tsx
│   │   │       └── PhenomMapStyle.ts
│   │   └── [Ignite boilerplate components: Button, Card, Header, etc.]
│   │
│   ├── screens/
│   │   ├── PhenomScreens/          # Core application screens
│   │   │   ├── HomeScreen.tsx      # Media feed browsing
│   │   │   ├── MapScreen.tsx       # H3 hexagonal map
│   │   │   ├── RecordScreen.tsx    # Media recording
│   │   │   ├── ChatScreen.tsx      # Communication
│   │   │   └── PhenomScreen.tsx    # Base screen wrapper
│   │   ├── DemoDebugScreen.tsx     # Debug/profile utilities
│   │   ├── WelcomeScreen.tsx       # Onboarding
│   │   ├── LoginScreen.tsx         # Authentication
│   │   └── [Other screens]
│   │
│   ├── navigators/
│   │   ├── AppNavigator.tsx        # Root navigator (Auth flow)
│   │   ├── PhenomNavigator.tsx     # Bottom tab navigator
│   │   ├── DemoNavigator.tsx       # Demo screens navigator
│   │   └── navigationTypes.ts
│   │
│   ├── services/
│   │   └── api/
│   │       └── phenom/
│   │           ├── base/
│   │           │   ├── PhenomAPI.ts       # Adapter pattern holder
│   │           │   ├── APIConnector.ts
│   │           │   └── APIConfig.ts
│   │           ├── adapters/
│   │           │   ├── IAPIAdapter.ts     # Interface definition
│   │           │   ├── MockDataAdapter.ts # Mock implementation
│   │           │   └── test/              # Test utilities
│   │           └── types/                 # TypeScript definitions
│   │
│   ├── context/
│   │   ├── AuthContext.tsx         # Authentication state
│   │   ├── EpisodeContext.tsx      # Episode/content management
│   │   └── [Other contexts]
│   │
│   ├── theme/
│   │   ├── context.tsx             # Theme provider (light/dark)
│   │   ├── colors.ts, colorsDark.ts
│   │   ├── spacing.ts, spacingDark.ts
│   │   ├── typography.ts
│   │   └── [Design tokens]
│   │
│   ├── i18n/
│   │   ├── index.ts                # i18next initialization
│   │   ├── en.ts, es.ts, ar.ts     # Language files
│   │   ├── fr.ts, ja.ts, ko.ts, hi.ts
│   │   └── translate.ts
│   │
│   ├── utils/
│   │   ├── storage/                # MMKV storage utilities
│   │   ├── useCustomFonts.ts
│   │   ├── useAppTheme.tsx
│   │   └── [Other utilities]
│   │
│   ├── config/
│   │   ├── index.ts                # Config loader
│   │   ├── config.base.ts
│   │   ├── config.dev.ts
│   │   └── config.prod.ts
│   │
│   ├── app.tsx                     # Root app component
│   └── index.tsx                   # Entry point
│
├── assets/                          # Static resources
│   ├── images/
│   ├── icons/                       # 54+ icon files
│   ├── fonts/
│   └── metadata/
│
├── .maestro/                        # E2E test flows
├── test/                            # Test configurations
├── app.json                         # Expo configuration
├── eas.json                         # EAS build configuration
└── [Configuration files]

Layer Architecture

1. Presentation Layer (UI/Components)

Purpose: Render user interface and handle user interactions

Components:

Phenom Components (app/components/phenom/)
- EndlessMediaFeed.tsx - Infinite scroll media browser
- map/HexGlobeWireframe.tsx - H3 hexagonal map renderer
- map/HexSelectionOverlay.tsx - Interactive hex selection
- Custom UI elements specific to Peregrine
Screens (app/screens/PhenomScreens/)
- HomeScreen.tsx - Main feed interface
- MapScreen.tsx - Spatial data visualization
- RecordScreen.tsx - Video capture interface
- ChatScreen.tsx - Communication interface

Technology: React Native with TypeScript

2. Business Logic Layer

Purpose: Handle application state, business rules, and data orchestration

Components:

Context Providers (app/context/)
- AuthContext - Authentication and user session
- EpisodeContext - Phenomena/episodes state management
- Theme context - Theme and styling state
Custom Hooks
- Reusable stateful logic for phenomena operations
- Map data management
- Authentication helpers

Technology: React Context API with TypeScript

3. Data Access Layer

Purpose: Abstract backend communication and data persistence

Components:

API Services (app/services/api/phenom/)
- API Adapter Pattern (Strategy Pattern implementation)
- MockDataAdapter.ts - Current in-memory implementation
- Future: REST/GraphQL adapters for real backend
Storage
- MMKV for encrypted local storage
- Cache management

4. Domain Model Layer

Purpose: Define core data structures and domain concepts

Models:

PhenomCoords - Geographical coordinate system with H3 indexing
PhenomCategory - Phenomenon classification (UAP, Cryptids, Paranormal, Electromagnetic, Infrasound)
PhenomItem - Core phenomenon data structure
PhenomProfile - User profiles
PhenomUser - Full user object

Design Patterns

1. Strategy Pattern (API Adapters)

Usage: Pluggable backend implementations

Current Implementation:

app/services/api/phenom/adapters/
├── IAPIAdapter.ts         # Interface definition
└── MockDataAdapter.ts     # In-memory implementation

Future Adapters:

REST API Adapter
GraphQL Adapter
Firebase Adapter

Benefit: Switch backends without changing application code

2. Context Provider Pattern

Usage: Global state management (authentication, themes, data)

Implementation:

AuthContext - User authentication state (authToken, authEmail)
EpisodeContext - Phenomena state (episodes, favorites)
Theme context - UI theme configuration (light/dark)

Benefit: Avoid prop drilling, centralized state access

3. Hook-Based Utilities

Usage: Encapsulate reusable stateful logic

Examples:

useAuth() - Authentication operations
useEpisodes() - Episode/content management
useAppTheme() - Theme access and manipulation
useCustomFonts() - Font loading

Benefit: Composable, testable logic units

4. Component Composition

Usage: Build complex UIs from reusable components

Example:

HomeScreen
├── Header
├── EndlessMediaFeed
│   ├── PhenomCard
│   ├── PhenomCard
│   └── ...
└── Footer

Data Flow Architecture

Unidirectional Data Flow

User Input (UI)
      ↓
Event Handler (Component)
      ↓
Hook/Context Update
      ↓
API Service Call (Optional)
      ↓
State Update
      ↓
Re-render Component

Example: Loading a Phenomenon

MapScreen User Taps Cell
      ↓
Map interaction handler
      ↓
PhenomAPI.current.getPhenoms()
      ↓
MockDataAdapter.getPhenoms()
      ↓
Generate/fetch phenomenon data
      ↓
Update Context/State
      ↓
Re-render with New Data

Navigation Hierarchy:

RootNavigator (AppNavigator)
├── AuthStack (if not authenticated)
│   ├── LoginScreen
│   └── WelcomeScreen
└── PhenomNavigator (BottomTabNavigator)
    ├── PhenomHome (HomeScreen - Feed)
    ├── PhenomRecord (RecordScreen - Capture)
    ├── PhenomChat (ChatScreen - Communication)
    ├── PhenomMap (MapScreen - H3 Map)
    └── DemoDebug (Debug/Profile)

Technology: React Navigation 7.x with TypeScript

Geospatial Architecture

H3 Hexagonal Grid System

The application uses H3 (Uber’s geospatial indexing system) for organizing global phenomena data:

Global Coverage - Hexagonal tessellation of Earth’s surface
Hierarchical Resolution - 16 resolution levels (0 = continents, 15 = individual buildings)
Efficient Queries - Find phenomena in specific regions without scanning entire dataset
Visualization - Overlay hexagonal grid on Mapbox map

Integration:

Mapbox GL 10.2.10 for rendering
H3-JS 4.4.0 & H3 2.0.1-rc.8 for geospatial calculations
HexGlobeWireframe.tsx - Renders global hex tessellation
HexSelectionOverlay.tsx - Interactive hex cell selection
Automatic polar fade with smoothstep function

Map Component Architecture:

MapScreen
├── Mapbox GL Map Component
│   ├── Base map rendering
│   ├── User location marker
│   └── Phenomenon markers
├── HexGlobeWireframe (Overlay)
│   ├── Hex cell rendering
│   ├── Polar fade effect
│   └── Resolution-based visibility
└── HexSelectionOverlay
    ├── Tap detection
    ├── Coordinate to H3 conversion
    └── Selected cell highlighting

Internationalization (i18n)

Multi-Language Support

Languages Supported: English, Spanish, Arabic, French, Japanese, Korean, Hindi (7 languages)

Implementation: i18next library

Structure:

Language files in app/i18n/ (en.ts, es.ts, ar.ts, fr.ts, ja.ts, ko.ts, hi.ts)
Key-based translation strings
Runtime language switching
Dynamic content translation
RTL support for Arabic (I18nManager.allowRTL())

Usage in Components:

import { useTranslation } from 'react-i18next';

const MyComponent = () => {
  const { t, i18n } = useTranslation();
  return <Text>{t('key.translationKey')}</Text>;
};

Storage Architecture

Local Data Persistence

MMKV (Memory-Mapped Key-Value Store)

Encrypted local storage
Fast, efficient key-value operations
Secure credential storage
Cache management

Use Cases:

User authentication tokens (authToken, authEmail)
Theme preferences (themeScheme: “light” | “dark”)
Cached phenomena data
User preferences
Offline data availability

Note: Navigation state can optionally be persisted based on configuration (persistNavigation: "dev")

Build & Configuration

Expo Configuration

Entry Point: app.tsx (Root component) Expo Registration: index.tsx (registerRootComponent)

Key Configuration:

App name, icon, splash screen
Platform-specific settings (iOS, Android)
Plugin configuration
Environment variables
New Architecture enabled (React Native TurboModules)

TypeScript Configuration

Strict Mode Enabled:

Strict null checks
No implicit any types
Strict function types
Path aliases (@/* -> app/*)
Ensures type safety throughout

External Dependencies

Core Dependencies

react-native: 0.81.5
react: 19.1.0
expo: 54.0.31
@react-navigation/native: 7.x
react-native-mapbox-gl: 10.2.10
h3-js: 4.4.0 & h3: 2.0.1-rc.8
i18next: 23.14.0
react-i18next: 15.0.1
react-native-mmkv: 3.3.3
apisauce: 3.1.1

Development Tools

ESLint 8.57
Prettier 3.3.3
Jest 29.7
Reactotron (debugging)
Maestro (E2E testing)
Dependency-Cruiser 17.0.2

Testing Architecture

The application is designed with testability in mind:

Hooks are pure functions, easily testable
API Adapters can be mocked for unit tests
Context Providers can be wrapped in tests
Components receive props, support snapshot testing
E2E Tests with Maestro in .maestro/flows/

Goal: >80% unit test coverage by Q4 2025

Performance Considerations

Optimization Strategies

Lazy Loading - Screens loaded on demand
Infinite Scroll - EndlessMediaFeed loads data incrementally with virtualization
Memoization - Components avoid unnecessary re-renders
Asset Optimization - Images compressed, icons optimized
Storage Efficiency - MMKV for fast local access
Map Optimization - Polar fade reduces rendering complexity at poles

Monitoring

React DevTools integration (development)
Performance profiling hooks
Error boundary implementations
Hermes JavaScript Engine for improved performance

Security Considerations

Encrypted Storage - MMKV for sensitive data (tokens, credentials)
API Credentials - Environment variables, not hardcoded
Type Safety - TypeScript strict mode prevents injection attacks
Domain Model Validation - Data validation at boundaries
HTTPS Only - All network communication encrypted (future backend)

Future Architecture Improvements

Real Backend Integration - Replace MockDataAdapter with REST/GraphQL adapter
Advanced State Management - Redux/Zustand if Context API becomes insufficient
Offline-First - Enhanced offline capabilities with sync strategies
Real-time Sync - WebSocket integration for live updates
Advanced Caching - Sophisticated cache invalidation strategies
Observability - Logging, analytics, error tracking (Sentry, etc.)
C2PA Integration - Content authenticity verification (per PRD requirements)
AR Object Identification - Real-time object recognition (per user research)

Feedback

Was this page helpful?

Glad to hear it! Please tell us how we can improve.

Sorry to hear that. Please tell us how we can improve.

Architecture Overview

Categories:

Architecture Overview

Architecture Principles

Directory Structure

Layer Architecture

1. Presentation Layer (UI/Components)

2. Business Logic Layer

3. Data Access Layer

4. Domain Model Layer

Design Patterns

1. Strategy Pattern (API Adapters)

2. Context Provider Pattern

3. Hook-Based Utilities

4. Component Composition

Data Flow Architecture

Unidirectional Data Flow

Example: Loading a Phenomenon

Navigation Architecture

React Navigation Stack

Geospatial Architecture

H3 Hexagonal Grid System

Internationalization (i18n)

Multi-Language Support

Storage Architecture

Local Data Persistence

Build & Configuration

Expo Configuration

TypeScript Configuration

External Dependencies

Core Dependencies

Development Tools

Testing Architecture

Performance Considerations

Optimization Strategies

Monitoring

Security Considerations

Future Architecture Improvements

Feedback