System Architecture

Under the hood

For the technically curious - here's how the three components connect and the tech that powers each one.

System Diagram

Three components, one encrypted channel

Your phone and desktop both connect outbound to the relay. The relay routes messages but cannot read them.

beachviber-architecture.md
## BeachViber System Architecture Phone (PWA) Cloud Relay Desktop Agent ┌──────────────┐ ┌──────────────────┐ ┌──────────────────┐ │ React 19 │ │ AWS Lambda │ │ Node.js Agent │ │ Zustand │ │ API Gateway │ │ Claude Code SDK │ │ TweetNaCl │ │ DynamoDB │ │ TweetNaCl │ │ Tailwind │ │ WebSocket GW │ │ Unix Socket IPC │ └──────┬───────┘ └────────┬─────────┘ └────────┬─────────┘ │ │ │ │ encrypted msg │ encrypted msg │ │──────────────────► │ ──────────────────► │ │ │ │ │ ┌────────────────┴────────────────┐ │ │ │ RELAY CANNOT READ MESSAGES │ │ │ │ Routes opaque encrypted blobs │ │ │ │ No plaintext ever touches relay │ │ │ └────────────────┬────────────────┘ │ │ │ │ │ Tool Approval Flow │ │ ◄────────────────────────────────────────────── │ approval_request │ ──────────────────────────────────────────────► │ approval_response │ │ │ ┌──────┴───────┐ ┌────────┴─────────┐ ┌───────┴──────────┐ │ Auto-Approve │ │ Auth Layer │ │ Approval Server │ │ Read, Glob │ │ JWT + Refresh │ │ Unix Socket │ │ Grep, Search │ │ GitHub OAuth │ │ 5 min timeout │ │ │ │ bcrypt + zod │ │ Fail = DENY │ │ Phone-Approve │ │ Device Tokens │ │ umask 0077 │ │ Bash, Write │ │ timingSafeEq │ │ │ │ Edit, Notebook│ │ │ │ Hook Lifecycle │ │ │ │ │ │ Install on start │ │ │ │ │ │ Remove on exit │ └──────────────┘ └──────────────────┘ └──────────────────┘
Tech Stack

Built with modern, audited tools

📱

Mobile PWA

React 19, Vite 7, Tailwind CSS 4, Zustand 5, TweetNaCl, Web Speech API

☁

Cloud Relay

AWS Lambda, API Gateway, DynamoDB, WebSocket GW, SES, bcrypt, zod

💻

Desktop Agent

Node.js 20+, Claude Code SDK, TweetNaCl, Unix Socket IPC, PreToolUse Hooks

Protocol

Message protocol

26 message types handle everything from pairing to streaming responses.

🔗 Pairing & Registration

  • register / registered — device registration
  • verify_code / verify_code_ack — pairing verification
  • desktop_status / desktops_list — multi-desktop management

💬 Sessions & Prompts

  • session_create / session_end — session lifecycle
  • prompt — send prompt to Claude
  • stream_start / stream_delta / stream_end — response streaming

✅ Tool Approval

  • tool_approval_request — desktop asks phone for permission
  • tool_approval_response — phone approves or denies
  • Auto-approved tools skip the phone entirely

📁 Projects & History

  • projects_request / projects_response — list projects
  • sessions_request / sessions_response — list sessions
  • session_history_request / session_history_response — transcripts