MeshLink

A Cross-Platform Offline P2P Mesh Communication Desktop Application

---

📖 Overview

MeshLink is a fully decentralized, off-the-grid peer-to-peer (P2P) desktop communication tool. It functions entirely autonomously without an internet connection or any centralized server infrastructure. By leveraging UDP multicasting for local device discovery and establishing a robust raw TCP mesh network, MeshLink enables seamless, symmetric-encrypted messaging between Windows, macOS, and Linux devices physically connected to the same LAN or Wi-Fi network.

✨ Core Features

• Serverless P2P Discovery: Employs background UDP (dgram) multicast mechanisms to dynamically scan and identify adjacent MeshLink nodes on the local network footprint.

• Flooding Mesh Routing Engine: Intelligent multi-hop packet proxying effectively routes traffic across devices. Utilizes strict TTL (Time-to-Live) tracking and algorithmic LRU memory caching to permanently mitigate infinite packet loop floods.

• Advanced Cryptography Layer: Secures all cross-network communication symmetrically using zero-dependency natively accelerated AES-256-GCM encryption buffers.

• High-Performance Architecture: Uses raw TCP framing (net) for reliable data transports rather than WebSockets, reducing socket overhead overhead by preventing HTTP handshakes limits during massive broadcast storms.

• Premium UX/UI: An exquisitely engineered frontend rendering layer structured using React and Tailwind CSS 4 featuring strict typing, glassmorphism abstractions, and interactive peer visual identities.

🛠️ Technology Stack

Architecture Layer	File / Component	Technology	Description
GUI Framework	Electron Main/Renderer	Electron.js	Desktop application container
Frontend UI	React Components	React 19, Tailwind CSS v4	User interface and styling
Networking Layer	src/main/network/lan.ts	Node.js dgram & net	Local network UDP discovery and TCP connections
Mesh Controller	src/main/mesh/router.ts	Node.js Event Emitter	Multi-hop packet routing and deduplication
Cryptography	Node native crypto	AES-256-GCM	Symmetric zero-dependency payload encryption
IPC Bridge	src/preload/index.ts	contextBridge	Secure UI-to-Backend communication
Build / Tooling	electron-builder.yml	Vite, electron-builder	Cross-platform packaging (EXE, DMG, AppImage)

🚀 Getting Started

1. Local Development

Ensure you have Node.js installed (v18+ recommended).

# Clone the repository
git clone https://github.com/your-org/meshlink.git
cd meshlink

# Install all sub-dependencies
npm install

# Start the Vite + Electron development environment
npm run dev

Note on Testing: Due to standard OS loopback boundaries on UDP multicast sockets, testing peer discovery behaves best when run across two entirely separate physical computers communicating under the same router. Alternatively, use isolated Docker containers (instructions below).

2. Docker Deployment

Because MeshLink directly binds to hardware network adapters to emit local broadcast pulses, containerizing requires passing through your host's X11 Display context and utilizing host networking bindings.

# Open X11 socket (For Linux Hosts)
xhost +local:docker

# Build & Boot the container
docker compose up --build

Note: Ensure network_mode: "host" is kept in the docker-compose.yml to allow the UDP pulses to break out of the docker bridge into the physical LAN.

📦 Production Builds & Distribution

MeshLink leverages electron-builder to automatically generate cross-platform binaries directly out of your workspace.

# Windows binary (.exe inside /dist)
npm run build:win

# macOS mountable image (.dmg inside /dist)
npm run build:mac

# Linux standalone portable package (.AppImage inside /dist)
npm run build:linux

We highly recommend using the .AppImage (Linux) or .exe (Windows) formats for true "plug-and-play" secure thumb-drive distribution to offline zones.

🏗️ Architectural Topology

MeshLink adheres rigorously to Electron's security boundaries (Context Isolation enabled).

1. Network Process: (src/main/network/lan.ts): Binds UDP on 49152 communicating over multcast 224.0.0.114. Automatically negotiates reverse TCP binds to dynamically randomized server sockets (ports 49153-59153).
2. Mesh Controller: (src/main/mesh/router.ts): Serves as the central Event Emitter traffic cop. Validates parsed incoming JSON from TCP byte streams, strips dead TTL hops, executes LRU duplicate cache invalidations, and retransmits broadcast sequences to adjacent local TCP nodes.
3. IPC Bridge: (src/preload/index.ts): Highly constrained contextBridge.exposeInMainWorld interface passing deterministic UI instructions to Electron's sandbox.

🗺️ Roadmap & Limitations

1. Bluetooth Low Energy (BLE) Fallback: Currently deferred. Implementations relying on @abandonware/noble impose extreme cross-compilation strictness on C++ headers per-device (Windows vs MacOS). LAN operates as the dominant active transport constraint in Prototype 1.
2. Dynamic Key Exchange: Current infrastructure shares symmetric mesh keys (crypto.scryptSync()). Phase 2 will implement independent peer-to-peer Diffie-Hellman handshakes per socket negotiation resolving pure Zero-Knowledge protocols (E2EE) natively.
3. Advanced Payloads: Expanding the payload JSON formats beyond text to serialize raw binary chunks for localized file-sharing without internet bandwidth costs.

📝 License

Distributed under the MIT License. See LICENSE for more information.