🚀 1. Executive Summary

GhostWire is a lightning-fast, lightweight, command-line interface (CLI) application that establishes a real-time, encrypted communication channel between remote users.

Unlike traditional chat applications that rely on heavy frontend frameworks, GhostWire operates entirely in the terminal, utilizing raw TCP streams for low-latency messaging and a unique "Sidecar Socket" pattern for parallel binary file transfers.

It is designed to be installed globally via NPM and uses tunneling (such as Pinggy) to bypass NAT/Firewalls without requiring complex port forwarding configurations. 🛡️

💡 2. Problem Statement

Most modern communication tools are resource-heavy and over-engineered for simple tasks. Developers and system administrators often need a quick, distraction-free way to communicate and transfer files securely across different networks without leaving their terminal environment.

GhostWire solves this by providing:

• 🎯 Zero UI Overhead: Runs purely in the shell. Leave the browser behind.
• ⚡ Instant Setup: No account creation, no logins, no database required.
• 🌍 Network Agnostic: Works across different Wi-Fi networks using simple tunneling.

🏛️ 3. System Architecture

The application utilizes a Single-Port Multipurpose Architecture over TCP:

1. 💬 The Chat Connection:
   • Powered by the Node.js net module on Port 3000.
   • Maintains persistent, stateful connections for real-time text exchange.
   • Handles command parsing (e.g., /nick, /share, /download) and user session management.
2. 📦 The Sidecar Socket Pattern for Files:
   • Uses the same port (3000) but opens temporary, secondary TCP connections to handle file transfers without clogging the main chat stream.
   • Utilizes Node.js Streams (fs.createReadStream / fs.createWriteStream) to pipe data directly between the disk and the network socket, ensuring low memory usage even for very large files.

🛠️ 4. Technical Stack

• 🟢 Runtime: Node.js (Asynchronous I/O).
• 📦 Core Modules:
  • net: For raw TCP socket creation.
  • fs (FileSystem): For streaming file read/write operations.
• 🎨 CLI Tools: npm (for global distribution), chalk (for stunning terminal UI styling).
• 📡 Networking: Pinggy (for blazing-fast tunneling of localhost to the public internet).

🧠 5. Key Features & Implementation Logic

📡 A. Real-Time Chat (The "Broadcast" Pattern)

• Logic: The server maintains an in-memory array of active socket connections (state.sockets).
• Mechanism: When User A sends a message, the server iterates through the array and writes the data to all registered sockets except User A's socket.

🚀 B. Stream-Based File Sharing via "Sidecar Sockets"

• The Challenge: Sending bulky binary data (images/zips) over a raw text-based TCP connection corrupts the main chat stream and blocks messages.
• The Solution (The Sidecar Pattern): Separate the control plane from the data plane dynamically.
  1. The server examines the first packet of every incoming socket connection.
  2. If the client types /share file.txt, the client software opens a new socket and sends a handshake string: SIDECAR_UPLOAD|file.txt\n.
  3. The server intercepts this prefix, detaches the socket from the chat pool, and pipes the rest of the incoming raw binary stream directly into the local server_storage/ folder.
  4. Once uploaded, the server broadcasts an availability message.
  5. If another client types /download file.txt, their client opens a new socket sending the handshake SIDECAR_DOWNLOAD|file.txt\n. The server then securely streams the file back through this dedicated sidecar channel.

🤖 C. The "Smart Client" Wrapper

• Instead of using a generic tool like telnet, a custom Node.js client was built to beautifully intercept user keystrokes.
• This allows for smart client-side logic—like verifying if a file actually exists on the user's hard drive before opening a Sidecar socket to the server—reducing unnecessary network traffic and handling UI seamlessly.

🎮 6. User Workflow (Step-by-Step)

Step 1: Installation 📥

Get Ghostwire directly from NPM.

npm i -g ghostwire

Step 2: Hosting a Room 🏠

User A (Host) starts the server locally.

ghostwire start
# Output: ✅ TCP Server (Chat + Files) running on Port 3000

Then, User A quickly exposes the local port to the internet using Pinggy. Follow these steps:

1. Get your unique command

   • Log in to your Pinggy Dashboard.
   • Select TCP Tunnel from the left sidebar.
   • Ensure the Local address is set to localhost:3000 (or whichever port your app uses).
   • Copy the command displayed in the blue box. It will look like this:

     ssh -p 443 -R0:127.0.0.1:3000 -o StrictHostKeyChecking=no -o ServerAliveInterval=30 [email protected]

2. Run the command in Terminal
   Open PowerShell or Command Prompt and paste the command.

   # Pinggy will provide a public TCP address (e.g., tcp://xyz.pinggy.io:12345)

Step 3: Joining a Room 🤝

User B (Remote) joins using the Host's Pinggy TCP address.

ghostwire join tcp://xyz.pinggy.io:12345

Step 4: Interaction 💬

• Chat: Simply type your message and hit Enter.
• Commands:
  • 🏷️ /nick <name> : Change your username.
  • 📤 /share <file> : Upload a file to the grid via a sidecar socket.
  • 📥 /download <file> : Download an available file from the grid via a sidecar socket.