System Architecture Overview
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The Happy ecosystem is a multi-platform solution designed to provide remote control and session sharing for Claude Code and Codex. It enables users to interact with AI agents through a terminal interface while synchronizing real-time state to mobile and web clients. The system is built on a "zero-knowledge" principle, utilizing end-to-end encryption (E2EE) so that the relaying server never has access to plaintext user data.
The architecture is structured as a TypeScript/Swift monorepo containing specialized applications for CLI, mobile (React Native/Android), desktop (macOS), and edge-native backend services. Central to this architecture is a shared protocol package that enforces type safety across all components through Zod schemas.
Sources: CLAUDE.md:8-12, apps/server/workers/README.md:3-8, knowledge.md:7-10
High-Level Component Architecture
The system consists of three primary tiers: the Producers (CLI/Daemon), the Relay (Server), and the Consumers (Mobile/Web/macOS apps).
System Component Diagram
The following diagram illustrates the relationship between the various applications in the monorepo and their communication paths.
The server acts as an encrypted relay, facilitating communication between the CLI and various client applications.
Sources: CLAUDE.md:144-155, apps/server/workers/README.md:147-160, knowledge.md:36-41
Data Flow and Synchronization
End-to-End Encryption (E2EE)
All user data, including sessions, messages, and artifacts, is encrypted client-side before transmission. The backend acts as a "zero-knowledge" relay.
| Component | Encryption Technology | Purpose |
|---|---|---|
| CLI / Apps | AES-256-GCM / TweetNaCl | Client-side E2EE of user data |
| Server | TweetNaCl secretbox | Encryption of server-managed secrets (AI tokens) |
| Protocol | X25519 ECDH / HKDF | Key derivation and secure handshake |
Sources: apps/cli/CLAUDE.md:188-198, apps/server/workers/README.md:175-179, apps/macos/CLAUDE.md:80-92
Session Synchronization Logic
Synchronization occurs via WebSockets (Socket.IO or native WebSockets via Cloudflare Durable Objects). The process follows a specific lifecycle:
- Capture: The CLI wraps Claude Code and captures session state changes or terminal output.
- Encrypt: Data is encrypted using a shared secret derived during the pairing process.
- Relay: The encrypted payload is sent to the server, which identifies connected consumers for that user.
- Distribute: The server pushes the update to mobile or web clients.
- Decrypt: Clients decrypt the message and update their local state reducers.
Sources: CLAUDE.md:144-155, apps/web/react/CLAUDE.md:104-110
Connection Sequence
The following sequence diagram represents the authentication and pairing flow between a new CLI instance and a mobile device.
Core Modules and Shared Packages
The architecture relies heavily on shared packages located in the packages/ directory to ensure consistency across the monorepo.
@magic-agent/protocol
The single source of truth for all API types. It defines Zod schemas for both persistent updates and ephemeral events.
- Persistent Updates (
tdiscriminator): Session creation, new messages, artifact updates. - Ephemeral Events (
typediscriminator): Typing indicators, cost updates, machine status.
Sources: packages/schema/protocol/CLAUDE.md:7-15, knowledge.md:51-54
ID Naming Inconsistencies (Legacy Support)
The architecture preserves certain historical inconsistencies for backward compatibility, which are enforced in the protocol schemas:
| Entity | Persistent Field | Ephemeral Field |
|---|---|---|
| Session ID | id or sid | id |
| Machine ID | machineId | machineId or id |
Sources: packages/schema/protocol/CLAUDE.md:120-135, knowledge.md:65-70
Platform Specific Architectures
Edge-Native Backend (Cloudflare Workers)
The modern server implementation (apps/server/workers) utilizes Cloudflare's edge infrastructure:
- Hono: Web framework for routing and OpenAPI documentation.
- Durable Objects: Manages WebSocket state and connection consistency using the Hibernation API.
- D1 (SQLite): Relational storage for user accounts and metadata.
- R2: S3-compatible object storage for artifacts and file uploads.
Sources: apps/server/workers/README.md:12-25, apps/server/workers/README.md:147-160
Native macOS / Android
The native clients implement platform-specific patterns while adhering to the global encryption standards:
- macOS: Uses Swift/SwiftUI with the MVVM pattern. It leverages
CryptoKitfor AES-256-GCM operations. - Android: Uses Kotlin/Jetpack Compose with Clean Architecture. It utilizes the
Tinklibrary for cryptographic operations.
Sources: apps/macos/CLAUDE.md:11-20, apps/mobile/android/CLAUDE.md:11-30
Conclusion
The Happy System Architecture is a robust, security-first framework designed for high-performance AI agent interaction. By decoupling the AI execution (CLI) from the user interface (Mobile/Web) through a zero-knowledge relay, it provides a seamless and private experience across devices. The use of a shared protocol package ensures that despite the diversity of platforms (Node.js, React Native, Swift, Kotlin), the data remains consistent and type-safe.
Sources: CLAUDE.md:138-155, knowledge.md:36-41