React Native App (happy-app)
Relevant source files
The following files were used as context for generating this wiki page:
The happy-app is a cross-platform mobile and web client built using React Native and the Expo SDK. It serves as a remote control and session-sharing interface for Claude Code and Codex, enabling users to interact with remote terminal sessions from their devices. The application emphasizes real-time synchronization, end-to-end encryption, and a responsive design that supports iOS, Android, and Web platforms.
Sources: apps/web/react/CLAUDE.md:1-5, CLAUDE.md:8-12, knowledge.md:5-9
Core Architecture and Technology Stack
The application is built on Expo SDK 53 and utilizes a monorepo structure for shared logic. It leverages TypeScript in strict mode to ensure type safety across the codebase.
Primary Technology Stack
| Category | Technology |
|---|---|
| Framework | React Native with Expo SDK 53 |
| Routing | Expo Router v5 (File-based) |
| Styling | Unistyles (cross-platform with themes/breakpoints) |
| Real-time | Socket.io for WebSocket communication |
| Encryption | Tweetnacl for end-to-end encryption (E2EE) |
| State Management | React Context (Auth) and Custom Reducer (Sync) |
Sources: apps/web/react/CLAUDE.md:46-52, apps/web/react/package.json:80-140
System Data Flow
The following diagram illustrates how the React Native app interacts with the backend server and the CLI to provide a synchronized view of terminal sessions.
The server acts as a zero-knowledge relay, facilitating the transfer of encrypted data between the CLI and the mobile app without being able to decrypt user content.
Sources: CLAUDE.md:188-197, knowledge.md:31-36
Authentication and Synchronization
The application implements a specialized authentication flow designed for secure remote connection without traditional passwords.
Authentication Flow
Authentication is performed via a QR code challenge-response mechanism. The CLI generates a keypair and displays a QR code, which the mobile app scans to establish an encrypted link.
Data Sync Engine
Synchronization is managed by the SyncSocket and SyncSession classes. Data is transferred using the @magic-agent/protocol shared Zod schemas. The sync engine handles automatic reconnection and state management through a custom reducer.
Sources: apps/web/react/CLAUDE.md:60-61, 75, knowledge.md:21-25
UI Components and Layout
The app follows a strict UI pattern using ItemList and Item components for standard interfaces, while implementing custom views for complex data like chat or code artifacts.
Responsive Design with Unistyles
Styling is handled via react-native-unistyles, which allows for theme-aware and breakpoint-driven layouts. The app enforces layout width constraints on full-screen containers to ensure readability on tablets and web browsers.
import { StyleSheet } from 'react-native-unistyles'
const styles = StyleSheet.create((theme, runtime) => ({
container: {
flex: 1,
backgroundColor: theme.colors.background,
paddingTop: runtime.insets.top,
paddingHorizontal: theme.margins.md,
}
}))
Sources: apps/web/react/CLAUDE.md:139-150, 221-224
Specialized Renderers
The app includes high-performance components for rendering technical content:
- MermaidRenderer: A secure renderer that uses a sandboxed WebView (native) or iframe (web) to display Mermaid diagrams. It utilizes
postMessagefor secure communication andDOMPurifyfor SVG sanitization. - Artifacts Viewer: Supports syntax-highlighted code and markdown rendering.
Sources: apps/web/react/sources/components/markdown/MermaidRenderer.tsx:13-35, apps/web/react/sources/app/(app)/artifacts/new.tsx:15-30
Internationalization (i18n)
The application mandates the use of a t() function for all user-visible strings, supporting languages including English (en), Russian (ru), Spanish (es), and Polish (pl).
i18n Implementation
- Centralized Metadata: Languages are defined in
sources/text/_all.ts. - Dynamic Translation: Supports typed parameters for variables (e.g.,
{ name: 'Steve' }). - Strict Rules: JSX files must never contain hardcoded strings; development/debug pages are the only exception.
Sources: apps/web/react/CLAUDE.md:88-105, 115-125
Development and Deployment
Key Commands
| Command | Description |
|---|---|
yarn start | Start the Expo development server |
yarn ios / android | Run the app on a simulator or emulator |
yarn prebuild | Generate native project directories (ios/, android/) |
yarn ota | Deploy Over-the-Air updates via EAS Update |
yarn typecheck | Run TypeScript validation |
Sources: apps/web/react/CLAUDE.md:12-25, apps/web/react/package.json:15-35
Development Rules
- Alerts: Never use the standard React Native
Alertmodule; always use the custom@sources/modal/index.ts. - Hooks: Async operations should use the
useHappyActionhook for unified error handling. - Navigation: Use Expo Router API exclusively rather than the base React Navigation API.
- Formatting: Use 4 spaces for indentation as per project guidelines.
Sources: apps/web/react/CLAUDE.md:71, 78, 225-231
The happy-app is a robust React Native implementation designed to handle high-frequency data updates from remote CLI sessions. By combining E2EE security with a flexible layout engine and strictly typed shared protocols, it provides a seamless and secure developer experience across mobile and web platforms.