Project Title: GhostWire

A Distributed CLI-Based Communication System with Hybrid Protocol Architecture

1. Executive Summary

GhostWire is a 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 (React/Angular), GhostWire operates entirely in the terminal, utilizing raw TCP streams for low-latency messaging and a parallel HTTP pipeline for binary file transfer. It is designed to be installed globally via NPM and uses tunneling (Ngrok) 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.
• Instant Setup: No account creation or database required.
• Network Agnostic: Works across different Wi-Fi networks using tunneling.

---

3. System Architecture

The application utilizes a Hybrid Dual-Port Architecture:

1. The Control Plane (Port 3000 - TCP):
   • Powered by Node.js net module.
   • Maintains persistent, stateful connections for real-time text exchange.
   • Handles command parsing (e.g., /nick, /kick) and user session management.
2. The Data Plane (Port 3001 - HTTP):
   • Powered by Node.js http/express module.
   • Handles stateless binary file transfers (PUT requests).
   • Utilizes Node.js Streams (fs.createReadStream) to pipe data directly from disk to network, ensuring low memory usage even for 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.
  • https: For secure file uploads via Ngrok.
• CLI Tools: npm (for global distribution), chalk (for terminal UI styling).
• Networking: Ngrok (for tunneling 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.
• Mechanism: When User A sends data, the server iterates through the array and writes the data to all sockets except User A’s socket.
• Handling Disconnects: Event listeners (socket.on('end')) automatically filter the array to remove "ghost" connections, preventing server crashes.

B. Stream-Based File Sharing

• Challenge: Sending binary data (images/zips) over a raw text-based TCP connection corrupts the stream.
• Solution: Out-of-band data transfer.
  1. Client intercepts /share filename command.
  2. Client initiates an HTTP PUT request to the File Server.
  3. Server saves the file and broadcasts a "Signal Message" (FILE_UPLOAD|User|File.jpg) to the TCP Chat.
  4. Clients receive the signal and reconstruct the secure download URL.

C. The "Smart Client" Wrapper

• Instead of using a generic tool like telnet, a custom Node.js client was built to intercept user keystrokes.
• This allows for client-side logic (checking if a file exists on disk) before sending data to the server, reducing unnecessary network traffic.

---

6. User Workflow (Step-by-Step)

Step 1: Installation
User installs the tool globally on their machine.

Bash

npm install -g ghostwire

Step 2: Hosting a Room
User A (Host) starts the server and exposes it via Ngrok.

Bash

ghostwire host
# Output: Server running on localhost:3000

Step 3: Joining a Room
User B (Remote) joins using the Host's unique Ngrok addresses.

Bash

ghostwire join 0.tcp.ngrok.io:15234 https://ghostwire-files.ngrok-free.app

Step 4: Interaction

• Chat: Users type normally.
• File Share: User types /share screenshot.png. The system automatically handles the upload and notifies the room.

---