Sail JADA — Engineering Log

Technical work on sailjada.com and the JADA booking systems

```html

Building a Local SMS Sync Bridge: Bridging Samsung Devices and macOS Messages Without Cloud Dependencies

Overview

Over the past development session, we built out a local SMS synchronization system that bridges Samsung Android devices with macOS Messages.app, eliminating the need for Twilio credentials or cloud-based SMS infrastructure. This approach leverages Android Debug Bridge (ADB) to directly query device databases and native macOS AppleScript integration to deliver messages through the system's built-in SMS capabilities.

What Was Built

The core deliverable consists of two Python modules:

  • /Users/cb/Documents/repos/tools/samsung_sms_sync.py — Main synchronization engine
  • /Users/cb/Documents/repos/tools/samsung_sms_auth.py — Authentication and ADB device management
  • /Users/cb/Library/LaunchAgents/com.cb.samsung-sms-sync.plist — macOS daemon configuration for continuous sync

Technical Architecture

Data Ingestion Layer

The synchronization pipeline reads directly from Android's SMS storage without any cloud intermediary:

  • ADB Connection: Establishes USB or TCP connection to Samsung device running Android
  • Database Query: Directly queries /data/data/com.android.providers.telephony/databases/mmssms.db — the standard Android message storage database
  • Query Method: Uses ADB shell commands to execute SQLite queries against the device's SMS/MMS provider

The auth module handles device discovery and credential exchange:

adb devices  # List connected devices
adb -s <device-id> shell  # Connect to specific device
adb shell content query --uri content://sms  # Query SMS provider directly

Message Transformation Pipeline

Raw Android message data is normalized before delivery to macOS:

  • Extract sender/recipient phone numbers and normalize to E.164 format
  • Parse UNIX timestamp (milliseconds) from Android provider into human-readable format
  • Filter message type (SMS vs. MMS) and read status
  • Handle multi-part messages and character encoding edge cases

macOS Integration Layer

Rather than relying on third-party SMS services, we leverage the native Messages.app SMS bridge:

  • Service Discovery: Uses osascript to query available Messages services and identify SMS-capable services
  • Message Delivery: Invokes AppleScript to send messages through Messages.app, which handles SMS routing through the system's native cellular/iMessage infrastructure
  • Chat Tracking: Maintains local database of synced conversations to prevent duplicates and enable bidirectional sync

AppleScript integration for message sending:

osascript -e 'tell application "Messages" to send "message text" to buddy "phone-number" of service "SMS"'

Infrastructure & Setup

macOS Launch Agent Configuration

The plist file at /Users/cb/Library/LaunchAgents/com.cb.samsung-sms-sync.plist configures continuous synchronization:

  • Label: com.cb.samsung-sms-sync — Unique daemon identifier
  • Program: Points to Python 3 interpreter running the sync script
  • Interval: Configured for periodic sync (e.g., every 5 minutes)
  • StartOnLoad: Set to true for automatic daemon startup on login
  • StandardOutPath / StandardErrorPath: Logs to user library directory for debugging

Loading the daemon:

launchctl load ~/Library/LaunchAgents/com.cb.samsung-sms-sync.plist
launchctl list | grep samsung-sms-sync  # Verify it's running

Android Device Prerequisites

ADB communication requires specific device configuration:

  • Enable Developer Mode: Settings → About → Build Number (tap 7 times)
  • Enable USB Debugging: Developer Options → USB Debugging
  • For wireless debugging: Developer Options → Wireless Debugging (Android 11+)
  • Grant persistent USB debugging permission on the device when prompted

Homebrew Dependency Installation

ADB requires Android platform tools, installed via Homebrew:

brew install android-platform-tools
which adb  # Verify installation at /opt/homebrew/bin/adb (Apple Silicon)

Key Design Decisions

Why Not Twilio?

The original architecture referenced Twilio credentials for SMS handling. We pivoted to direct device integration because:

  • Eliminates dependency on cloud service uptime and API quota limits
  • Removes credential management overhead (Twilio SID/auth tokens)
  • Leverages existing device connectivity already established on the network
  • Reduces per-message costs for high-volume operations
  • Maintains message history locally for audit and reference

Local Database Over Cloud Sync

We maintain a local SQLite database of synced conversations rather than streaming to cloud storage:

  • Prevents vendor lock-in (no S3 bucket, no CloudFront distribution required)
  • Enables offline access to message history
  • Reduces network I/O and associated latency

AppleScript vs. Custom SMS Service

Using native Messages.app integration instead of raw SMS service queries:

  • Automatically handles iMessage vs. SMS routing logic
  • Respects system-level SMS service configuration
  • Integrates with existing Messages.app UI (user sees messages in standard app)
  • Leverages native cellular/WiFi calling infrastructure already configured

Operational Workflow

Sync Cycle

  1. LaunchAgent triggers sync script every N minutes
  2. Script checks for connected ADB devices
  3. For each connected device, queries mmssms.db for messages newer than last sync timestamp
  4. Normalizes phone numbers and timestamps
  5. Checks local database to avoid duplicate ingestion
  6. For new messages with configured send rule, delivers via Messages.app AppleScript bridge
  7. Updates local sync timestamp for next interval

Error Handling

The system includes resilience for common failure modes:

  • Device Disconnection: Gracefully waits for device to reconnect; doesn't crash daemon
  • ADB Permission Denied: Logs error with instruction to re-authorize USB debugging on device
  • AppleScript Timeout: Retries message send with exponential backoff
  • Database Lock: