Real-time Synchronization
Relevant source files
The following files were used as context for generating this wiki page:
Real-time Synchronization in the Happy ecosystem is a multi-platform architecture designed to provide seamless, end-to-end encrypted (E2EE) session sharing and remote control. The system facilitates instantaneous data flow between the CLI (which wraps Claude Code), a central relay server (Fastify or Cloudflare Workers), and mobile/web clients.
The architecture relies on a "zero-knowledge" principle where the server acts as an encrypted relay, facilitating communication without having the ability to decrypt user data. This is achieved through TweetNaCl for server-side encryption and AES-256-GCM for client-side E2EE.
Sources: CLAUDE.md:173-181, apps/server/workers/README.md:103-107
System Architecture
The synchronization engine follows a hub-and-spoke model where the server serves as the central hub for distributed clients. Clients connect via WebSockets to receive persistent updates (state changes) and ephemeral events (transient UI indicators).
Core Components
| Component | Responsibility |
|---|---|
| Happy CLI | Captures Claude Code session state, encrypts updates, and pushes to server. |
| Server (Docker/Workers) | Relays encrypted messages using Socket.io or Durable Objects. |
| Happy App (React) | Decrypts and displays session state, sends user input back to CLI. |
| Sync Engine | Manages WebSocket lifecycles, retries, and state reconciliation. |
Sources: CLAUDE.md:184-192, apps/web/react/sources/sync/sync.ts:167-185
Data Flow Overview
The following diagram illustrates the path of an encrypted update from the CLI to the Mobile UI.
Explanation: The CLI initiates updates which the server relays to connected apps. Apps can send commands back via RPC calls.
Sources: CLAUDE.md:195-204, apps/web/react/sources/sync/sync.ts:403-445
Synchronization Mechanisms
Persistent Updates vs. Ephemeral Events
The protocol distinguishes between data that must be persisted and transient events that only exist in the current session context.
- Persistent Updates (
tdiscriminator): Includes session creation, new messages, machine registration, and artifact updates. These are tracked via sequence numbers (seq). - Ephemeral Events (
typediscriminator): Includes typing indicators, activity status, and usage metrics. These are not stored in the database.
Sources: packages/schema/protocol/CLAUDE.md:150-160, knowledge.md:46-52
Delta Sync and Sequence Tracking
To minimize bandwidth and recover from disconnections, the system employs Delta Synchronization. Clients track a lastKnownSeq for different entity types. Upon reconnection, the client requests only updates that occurred after its last known sequence number.
Explanation: The Delta Sync process allows the client to catch up on missed messages without performing a full state refetch.
Sources: apps/web/react/sources/sync/sync.ts:742-763, apps/web/react/sources/sync/sync.ts:44-53
Client Implementation
The React Native application manages synchronization through the Sync class, which handles multiple concurrent sync processes including sessions, profiles, and settings.
Synchronization Priority Tiers
To prevent network congestion on app resume, sync operations are staggered into four priority waves:
- Tier 1 (Immediate): Core UX data (Sessions, Profile, Settings).
- Tier 2 (100ms): Important non-blocking data (Machines, Purchases).
- Tier 3 (200ms): Secondary features (Artifacts, Push Tokens).
- Tier 4 (300ms): Background/Social features (Friends, Feed, Todos).
Sources: apps/web/react/sources/sync/sync.ts:203-225
WebSocket Connection Management
The application uses a ConnectionManager (in Workers) or apiSocket (in React) to maintain the real-time link.
| Feature | Implementation Detail |
|---|---|
| Authentication | Ed25519 cryptographic signatures; no passwords stored. |
| Scoping | Connections can be user-scoped, session-scoped, or machine-scoped. |
| Heartbeat | Periodic ping/pong to verify connection stability. |
| Recovery | Exponential backoff for reconnection attempts. |
Sources: apps/server/workers/README.md:109-115, apps/server/workers/load-tests/scenarios/websocket-performance.js:203-215
Security and Encryption
Real-time synchronization is secondary to the security of the data being synchronized. The system uses a dual-encryption strategy.
Encryption Protocol
- Client-to-Client (E2EE): Sensitive data (messages, artifacts) is encrypted using AES-256-GCM with a 12-byte nonce. The relay server never possesses the keys required to decrypt this data.
- Server-Side: Server-managed secrets (like AI vendor tokens) are encrypted using TweetNaCl secretbox.
- Key Rotation: Version bytes (e.g.,
0x01) in the encrypted bundle allow for seamless key rotation without breaking historical data access.
Sources: apps/cli/CLAUDE.md:154-170, CLAUDE.md:173-181
Performance Baselines
The system is designed to handle high concurrency, specifically validated for:
- Concurrent Connections: 100+ clients per Durable Object.
- Broadcast Latency: Messages delivered to all participants in < 500ms.
- Sync Recovery: Reconnection and state reconciliation under 2 seconds.
Sources: apps/server/workers/load-tests/scenarios/websocket-performance.js:14-25
Conclusion
Real-time Synchronization in Magic-Agent provides a high-performance, secure bridge between local AI execution (CLI) and remote interfaces. By combining staggered priority syncing, Delta Sync reconciliation, and mandatory E2EE, the system maintains a responsive and private user experience across diverse network conditions.