Architecture Overview
Technical architecture, design patterns, and system design of the Peregrine mobile application.
Peregrine
Documentation specific to Project Peregrine (Internal Only).
Categories:
This section contains documentation for Project Peregrine. Access is restricted.
Overview
Project Peregrine is the internal development of The Phenom App - a React Native mobile application for phenomenon documentation and verification. Built with modern web technologies and cross-platform mobile development practices, the project focuses on creating an intuitive platform that captures, authenticates, and analyzes real-world phenomena through advanced geospatial mapping and sensor integration.
Technology Stack
Core Framework
- Framework: React Native 0.81.5 with React 19.1.0
- Runtime/Platform: Expo 54.0.31
- Language: TypeScript 5.9.2 (strict mode)
- Navigation: React Navigation 7.x
Specialized Libraries
- Camera: Phenom-earth fork of react-native-vision-camera (pinned at e226a617, v5.0.11); read Camera Recording Fix before touching the camera stack
- Crash Reporting: GlitchTip via @sentry/react-native, JS-only mode; see Crash Reporting
- Geospatial Mapping: Mapbox GL (10.2.10) with H3 hexagonal geospatial indexing
- Storage: MMKV for encrypted local storage
- Internationalization: i18next (7 languages)
- Boilerplate Foundation: Ignite framework
Cross-Platform Development
This approach enables unified development targeting both iOS and Android from a single codebase. TypeScript strict mode ensures type safety across the entire application.
Key Features
Project-Specific (Custom) Features
These features are unique to Peregrine and distinguish it from standard boilerplate applications:
- H3 Hexagonal Map System - Global map with hexagonal tessellation overlay for spatial data organization
- EndlessMediaFeed Component - Custom infinite scroll component for browsing phenomena media
- Domain Models - Specialized data structures (PhenomCoords, PhenomCategory, PhenomItem, PhenomProfile)
- API Adapter Pattern - Pluggable backend architecture for future integrations
- Multi-Language Support - 7 language translations via i18next
Phenomenon Categories
The app organizes content into specialized categories:
- Electromagnetic phenomena
- Infrasound events
- Unidentified Aerial Phenomena (UAP)
- Paranormal activity
- Cryptid sightings
See Features Overview for detailed feature documentation.
Project Architecture
The application is built on a modular architecture with clear separation of concerns:
- Components Layer - Reusable UI components with custom Phenom-specific components
- Screens Layer - Application screens organized by feature
- Services Layer - API adapters and data services
- Theme Layer - Centralized design tokens and styling
- Internationalization - Language and localization management
See Architecture Deep Dive for comprehensive technical architecture documentation.
Development Resources
Code Repositories
- Phenom-earth/PhenomApp - Main React Native application
- Phenom-earth/Jonathancodearchive
- Phenom-earth/PhenomRxn
Technical Documentation
- Architecture Overview - Detailed technical architecture and design patterns
- Features Guide - Custom Peregrine features and implementations
- Product Requirements Document - High-level product requirements and feature set
- Sensor Integration - Device sensors utilized via Expo APIs
- Research & Strategy - User research findings and strategy validation
Project Objectives
Development Goals
- Fully automated CI/CD pipeline for iOS and Android builds via EAS and GitHub Actions
- Deployment time from code merge to TestFlight/Google Play under 45 minutes
- Unit test coverage target: >80% for core application logic
- State management, API interactions, and utility testing covered by automated CI pipeline
Navigation
Development Areas
Explore specific development aspects in the subsections below:
- Architecture - Technical architecture, design patterns, and data flow
- Features - Custom Peregrine features and capabilities
- Product Requirements - Feature set and business requirements
- Product Roadmap - Sprint planning, timeline, and GitHub issue tracking (Q1-Q4 2026)
- Sensors - Device sensor integration
- Research & Strategy - User research and validation
- Backend Integration - Infrastructure, database schema, and deployment architecture
- External Resources - C2PA content authenticity and Matrix/Synapse messaging references
Deployment & Release
- EAS Deployment Pipeline - Comprehensive guide to mobile deployment with Expo Application Services (iOS and Android)
- TestFlight Guide - iOS testing with TestFlight
- EAS Feature Builds - Building and distributing feature branches
- Device UDIDs - Managing test device identifiers
Team & Process
- Testing Roles - Team member testing responsibilities
- Meetings - Team meeting notes and decisions
Product Requirements Document (PRD)
High-level product requirements for the Peregrine version of the Phenom app.
Feature Set & Deployment Architecture
Complete feature set for PhenomApp (Peregrine) production release and deployment architecture via Expo Application Services.
Features Overview
Custom Peregrine features, capabilities, and implementations.
Backend Integration & Infrastructure
Backend API, database, infrastructure, and integration points for Peregrine mobile app.
External Resources & References
External documentation and resources for C2PA content authenticity and Matrix/Synapse messaging integration.
Sensor Usage
Overview of device sensors utilized via Expo APIs.
IMU-Based Infrasound Capture
Why the smartphone microphone cannot capture infrasound, why the IMU is the correct sensor on both iOS and Android, and how to wire it into Peregrine’s Expo + React Native telemetry pipeline.
EAS Deployment Pipeline
Comprehensive guide to the Expo Application Services (EAS) mobile deployment pipeline for iOS and Android production builds and submission.
Camera Recording Fix (iOS Release Builds)
Postmortem and reference for the iOS release-build camera recording failure (issue #91), fixed 2026-06-04 via the Phenom-earth vision-camera fork.
Crash Reporting with GlitchTip
How PhenomApp crash and error reporting works: @sentry/react-native in JS-only mode shipping events to GlitchTip.
iOS TestFlight Testing (EAS)
Using TestFlight and EAS for testing iOS feature branches.
iOS Launch Crash Fixes
Reference for the three iOS release-build launch crashes fixed in builds 32 through 35 and the patches that must be preserved.
App CI/CD: GitHub Actions Quality Gates
The PhenomApp GitHub Actions pipeline: lint, typecheck, tests and secret scanning on every PR, plus husky pre-commit hooks, CODEOWNERS and Dependabot.
Research Analysis & Strategy Validation
Summary of research findings from user interviews and surveys, validating the core design strategy and identifying critical gaps for the Phenom App.
Team Meeting Notes
Agendas, notes, and action items from Peregrine project team meetings.
Finding Device UDIDs
Instructions for finding iOS and Android device UDIDs for internal testing builds.
EAS Feature Branch Builds
How to create and distribute internal test builds for feature branches using EAS Build.
Testing Roles & Responsibilities
Assignment of testing responsibilities for Project Peregrine and Project Buzzard features.
Telemetry Publishing Brief (June 2026)
Plain-language summary for stakeholders: why GPS and sensor data stopped appearing on published phenoms, the two competing fixes, the decision taken, and the path back to full data. All diagrams carry C2PA Content Credentials.
ADR-001: Published Telemetry Is Dual-Source (Sidecar + Embedded Tracks)
Architecture Decision Record: every published phenom carries telemetry both as embedded SRT tracks inside the signed MP4 and as an uploaded sidecar JSON. SRT-only is deferred behind three hard gates. Adopted 2026-06-11.
MOV to MP4 Transition: Status and Completion Plan
Engineering status of the recording-pipeline container switch (build 75 onward): what is fixed, what remains, the publish-boundary definition, and the C2PA ordering constraints that govern the remaining work.
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.