MacMirror - Android to macOS Notification Mirroring

Executive Summary

MacMirror is an open-source dual-application ecosystem (Android mobile client and macOS menu bar receiver) engineered to stream phone notifications to the desktop workspace in real time. It eliminates third-party cloud infrastructure entirely, ensuring notification data never leaves the local Wi-Fi network and remains cryptographically secured end-to-end.

The Architectural Challenge

• Strict Privacy with Zero Cloud Dependency: Most notification mirroring tools route data through remote relays or push services. MacMirror required designing a discovery and transport layer operating strictly on the local area network (LAN) while protecting sensitive notification payloads on shared Wi-Fi.
• Background Execution & Aggressive OEM Battery Policies: Maintaining a resilient socket connection across Android Doze Mode and vendor process killers (One UI, MIUI/HyperOS, ColorOS) without draining battery resources.
• Cross-Platform Cryptographic Interoperability: Establishing session keys deterministically between Android’s Java Cryptography Architecture (JCA) and macOS’s native CryptoKit framework.
• Delivery Verification & Traceability: Ensuring streamed notification frames arrive reliably with an explicit acknowledgment (ACK) cycle that survives transient Wi-Fi drops.

Engineering Solutions & Strategy

1. Zero-Conf Discovery & E2EE Handshake: Local discovery powered by Bonjour/mDNS (_macmirror._tcp). Device pairing uses a one-time 6-digit PIN and ephemeral Elliptic-Curve Diffie-Hellman (ECDH Curve P-256) key agreement. Session keys are derived using HKDF-SHA256, encrypting every notification payload with authenticated AES-256-GCM.
2. Persistent Foreground Service & Notification Listener: On Android, a NotificationListenerService captures incoming system alerts, piped into a typed FOREGROUND_SERVICE_CONNECTED_DEVICE service with a low-priority silent notification. This keeps the WebSocket connection alive 24/7 and bypasses aggressive task termination.
3. Native macOS Menu Bar Receiver: Lightweight desktop receiver written in Swift and SwiftUI residing in the macOS Menu Bar. It decrypts incoming notification frames in-memory and triggers system alerts via UNUserNotificationCenter, complete with original Android app icons and sounds.
4. Selective Per-App Filtering: Reactive Jetpack Compose settings interface allowing granular toggles for which applications are permitted to mirror alerts, backed by asynchronous icon caching and real-time search.
5. Bidirectional Diagnostic & ACK Protocol: Real-time WebSocket delivery confirmation emitting explicit ACK payloads upon packet receipt, complemented by an interactive diagnostic flow for end-to-end verification.
6. Automated Homebrew Cask Distribution: Packaged with an official Homebrew tap (brew install --cask angelvelasquezdev/tap/macmirror) supporting stable and beta release channels, backed by CI automation building .dmg and .apk GitHub releases.

Key Architectural Metrics

• 0 ms Cloud Latency: Peer-to-peer Wi-Fi transmission via WebSockets with zero server hosting costs or external dependencies.
• Authenticated End-to-End Encryption: Notification payloads encrypted with AES-256-GCM and ephemeral ECDH key pairs.
• CLI-First Distribution: One-line macOS installation via Homebrew Cask and reproducible open-source releases under the MIT license.