Localink — Modern LAN Chat Application

Private conversations. Local network. Zero cloud.

Localink is a desktop-first, production-quality LAN chat application that allows users on the same local network (Wi-Fi or Ethernet) to communicate, react, and share files up to 500 MB in real-time — without requiring the internet or any third-party cloud service.

---

📌 Features

• Zero Cloud & Zero Setup: No registration, no databases, no server deployment. Plug-and-play local network sockets.
• Auto-Discovery (UDP): Hosts periodically announce server availability. Clients instantly detect active servers on the LAN and join with a single click.
• Real-Time Messaging (TCP): Dynamic thread-safe chat sockets with instant delivery, emoji support, Unicode text, and typing indicators.
• Robust File Transfers:
  • Drag-and-drop or file explorer attachments (up to 500 MB).
  • Isolated chunked TCP sockets to ensure files transfer fast without blocking the chat thread.
  • Active progress indicators: speed rate (MB/s), transfer percentage, and estimated time remaining (ETA).
  • Automatic download and save functionality via settings config.
  • In-chat image thumbnails with double-click modal image viewer.
• Aesthetic Dark Interface: Sleek Discord-inspired styling, soft shadows, rounded corners, active status badges, and custom context menus.
• Local History Persistence: Conversations are saved as local JSON configurations by server IP/Port and reloaded automatically.
• Frictionless Keyboard Shortcuts: Navigate quickly using natural keystrokes.

---

🛠️ Architecture Overview

Localink is designed around the Model-View-ViewModel (MVVM) architectural pattern:

graph TD
    subgraph Views [View Layer FXML / CSS]
        MainView[main.fxml]
        StartupView[startup.fxml]
        CustomComponents[MessageBubble / UserCard]
    end

    subgraph ViewModels [ViewModel Layer]
        MainVM[MainViewModel]
        StartupVM[StartupViewModel]
    end

    subgraph Services [Service Layer]
        SettingsSvc[SettingsService]
        HistorySvc[HistoryService]
        FileTransfer[FileTransferManager]
    end

    subgraph Sockets [Networking Sockets]
        TCPClient[ChatClient]
        TCPServer[ChatServer]
        UDPBroadcast[DiscoveryServer / Client]
    end

    MainView -->|Bindings/Events| MainVM
    StartupView -->|Bindings/Events| StartupVM
    
    MainVM --> Services
    MainVM --> Sockets
    StartupVM --> Services
    StartupVM --> Sockets

Loading

• Models: Standard Java POJOs (User, Message, Settings) serialized dynamically using Gson.
• ViewModels: Expose reactive JavaFX properties, manage connectivity states, dispatch messages asynchronously, and decouple business logic from UI threads.
• Controllers (Views): FXML-backed classes mapping bindings, managing drag-and-drop interactions, and drawing custom canvas elements like avatars and reaction badges.
• Networking Layer: Thread-per-client model using TCP socket buffers for messages, and UDP multicast groups for node advertising.

---

📂 Folder Structure

localink/
├── config/                  # Local application configurations (settings.json)
├── history/                 # Local chat message histories partitioned by IP/Port
├── logs/                    # Daily rotating application log files
├── src/
│   └── main/
│       ├── java/com/localink/
│       │   ├── controllers/ # FXML Controllers
│       │   ├── models/      # Data models
│       │   ├── network/     # TCP/UDP Socket layer
│       │   ├── services/    # File transfer & data persistence
│       │   ├── viewmodels/  # MVVM ViewModels
│       │   ├── utils/       # Icon Factories, Avatar Generator, Logging setups
│       │   ├── App.java     # JavaFX main Application entry
│       │   └── Launcher.java# Wrapper to launch modular JavaFX without module-info
│       └── resources/
│           ├── styles/      # Global CSS themes (main.css)
│           └── views/       # FXML layout structures (main/startup/settings/about)
└── pom.xml                  # Maven Configuration

---

🚀 Installation & Run

Prerequisites

• Java Development Kit (JDK) 21
• Apache Maven 3.8+

Steps

1. Clone the project locally:

   git clone https://github.com/google/localink.git
   cd localink

2. Compile and package the application:

   mvn clean package

3. Run the application:

   • Using Maven:

     mvn javafx:run

   • Using target JAR:

     java -jar target/localink-1.0-SNAPSHOT-jar-with-dependencies.jar

📦 CI/CD & Native Executable Packaging

This project is configured with an automated GitHub Actions CI/CD workflow (.github/workflows/build.yml).

Upon code push or pull request to the main branch, the workflow will trigger native builds across Windows, macOS, and Linux using jpackage:

• Windows: Produces a native .msi setup installer.
• macOS: Produces a native .dmg disk image.
• Linux: Produces a native .deb Debian package.

You can download the packaged installers directly from the Artifacts tab of the GitHub Actions build run.

---

⌨️ Keyboard Shortcuts

Shortcut	Action	Description
Ctrl + Enter	Send Message	Dispatches the contents of the text field to all users
Ctrl + F	Search Panel	Toggles the message search overlay
Ctrl + O	Attach File	Launches the file chooser to select a file up to 500 MB
Esc	Close Dialogs	Closes search overlay, image viewers, and modal popups

---

🛰️ Networking Protocol Details

1. Auto Discovery (UDP Broadcast):

   • When a user hosts a chat, DiscoveryServer binds to a UDP socket and broadcasts server metadata (IP, Port, Server Name, Online Count, Uptime) to the local subnetwork address (255.255.255.255:50006) every 3 seconds.
   • When users open the app, DiscoveryClient listens on 50006, parses JSON packets, and renders active servers dynamically.

2. Chat Connection (TCP):

   • Sockets connect directly using java.net.Socket.
   • Incoming/Outgoing messages are wrapped as NetworkMessage packets serialized to single-line JSON text followed by a newline delimiter \n.
   • Dedicated client threads block on BufferedReader.readLine() to process incoming payloads asynchronously without freezing the UI.

3. Heartbeat Protocol:

   • Every 8 seconds, ChatClient sends a ping packet.
   • The server handler acknowledges it. If no packet is received for 25 seconds, the server marks the client as dead, initiates a graceful cleanup, and announces a disconnect to the channel.

---

🛣️ Roadmap

• End-to-End Encryption: Optional local peer-to-peer DH/AES encryption.
• Direct Messages: Double-click users on the sidebar to launch isolated private query tabs.
• System Notifications: Native desktop taskbar toast alerts.
• Dark & Light Mode: Selectable themes from settings.

---

📄 License

Distributed under the MIT License. See LICENSE for details.