Monorepo Structure
Relevant source files
The following files were used as context for generating this wiki page:
The Happy project is organized as a TypeScript/Swift monorepo containing multiple applications and shared packages designed to enable remote control and session sharing for Claude Code. The architecture follows a "zero-knowledge" principle where sensitive data is end-to-end encrypted (E2E) using AES-256-GCM and TweetNaCl, ensuring the server acts only as an encrypted relay.
Sources: CLAUDE.md:8-10, knowledge.md:7-11, apps/server/workers/README.md:105-108
Core Directory Organization
The repository is structured into distinct areas for applications, shared logic, development tools, and documentation. While the codebase exists within a monorepo structure, it uses multiple Git repositories where individual projects may have their own .git/ directories but are linked via Yarn workspaces.
Sources: CLAUDE.md:73-104, CLAUDE.md:154-165
Major Path Definitions
| Directory | Contents | Description |
|---|---|---|
/apps/ | Applications | End-user products (CLI, Web, Mobile, Admin, macOS). |
/packages/ | Shared Packages | Core logic, schemas, and error handling used across apps. |
/dev/ | Development Tools | Custom lint rules and developer experience configurations. |
/docs/ | Documentation | Cross-project specifications like E2E encryption and API versioning. |
Sources: CLAUDE.md:74-100, knowledge.md:20-24
Workspace Management
The monorepo utilizes Yarn 4 with Yarn Workspaces and Turborepo to manage dependencies and build pipelines. Dependencies are hoisted to the root node_modules/ to ensure consistency, while shared internal packages are linked using the workspace:* protocol.
Sources: CLAUDE.md:112-117, package.json:4-15, package.json:48-52
Dependency Flow Diagram
This diagram shows how different applications consume shared internal packages within the monorepo.
Sources: CLAUDE.md:144-150, package.json:9-14
Shared Packages (@magic-agent)
Internal packages are housed under the packages/ directory and serve as the single source of truth for protocol schemas and error definitions.
@magic-agent/protocol
Located at packages/schema/protocol/, this package provides Zod schemas for API updates and ephemeral events. It is critical for maintaining consistency across the Node.js CLI, React Native app, and Fastify/Worker backends. It also includes a Swift generation script to synchronize types with the native macOS client.
Sources: CLAUDE.md:121-131, packages/schema/protocol/CLAUDE.md:10-14, packages/schema/protocol/CLAUDE.md:28-35
@magic-agent/errors
Located at packages/schema/errors/, this package implements unified error handling via the AppError class and centralized error code constants.
Sources: CLAUDE.md:133-138, knowledge.md:22
Application Subsystems
The apps/ directory contains various clients and servers, each following its own module system and directory conventions.
Subsystem Technical Overview
| Project | Module System | Source Dir | Technology Stack |
|---|---|---|---|
apps/cli | ESM | src/ | Node.js, Claude Code Wrapper |
apps/web/react | ESM | sources/ | Expo, React Native |
apps/server/docker | CommonJS | sources/ | Fastify, Prisma, PostgreSQL |
apps/server/workers | ESM | src/ | Hono, Cloudflare Workers, D1 |
apps/macos | Swift | Happy/ | SwiftUI, Combine |
Sources: CLAUDE.md:226-235, apps/server/workers/README.md:113-125
Data Flow Architecture
The following sequence diagram illustrates the communication flow between the CLI (Daemon), the Server (Relay), and the Mobile Client.
Build and Development Lifecycle
The monorepo uses Turbo to orchestrate tasks like building, linting, and testing across the workspace.
Key Lifecycle Commands
- Install:
yarn install(hoists dependencies and runs post-install builds for protocol/errors). - Build All:
turbo run build - Typecheck:
turbo run typecheck - Local Dev Stack: Run
yarn devin the root or specific projects (e.g.,apps/server/dockerfor the backend).
Sources: CLAUDE.md:112-117, package.json:17-38
Summary
The monorepo structure is designed to enforce a "Single Source of Truth" via shared Zod packages (@magic-agent/protocol) while allowing diverse technology stacks (Swift, Kotlin, React Native, Node.js) to coexist. By centralizing core logic and documentation in the root and packages/ directories, the architecture minimizes schema drift and ensures that E2E encryption standards are applied consistently across all client-server interactions.
Sources: packages/schema/protocol/CLAUDE.md:13-17, knowledge.md:7-14