WhspBrd/docs/FS.md

# **WhspBrd — Functional Requirements**

## I. **Core Functional Requirements**

### 1. **Terminal-Based User Interface (TUI)**

* **Framework**: Use `gocui` for building a rich, responsive text-based UI.
* **Components**:

  * Chat window (scrollable history).
  * Contact list / chat list panel.
  * Input field for typing messages.
  * Status bar with connection/server/user status.

* **Image Rendering**:

  * Render `.png`, `.jpg`, and `.gif` images in terminal using our own implementation of [Kitty graphics protocol](https://sw.kovidgoyal.net/kitty/graphics-protocol/).
  * Display avatars inline next to usernames.
  * Display inline images within messages (resizable).

### 2. **Secure Messaging**

* **PGP Encryption**:

  * All messages are encrypted locally using the recipient's PGP public key.
  * Messages are decrypted only on the receiving client.
* **Message Routing**:

  * Messages are routed through a central server only for delivery.
  * Server does **not store** any message content.
* **Offline Message Storage**:

  * Server temporarily caches messages for **offline users** for a configurable TTL (e.g., 12–48 hours).
  * If the user does not connect in that window, the message is deleted, and the sender is notified.

### 3. **Client Data Management**

* **Local Storage**:

  * All messages are stored client-side in `.json` files per conversation.
  * Embedded images are stored as:

    * RGBA raw data in JSON (Base64-encoded).
    * A PNG copy in a parallel `media/` folder.
* **PGP Keys**:

  * Each user maintains a local PGP key pair.
  * Ability to import/export keys.
  * Server can validate keys via a **Web of Trust** model.

### 4. **Systray & Notifications**

* **Systray Integration**:

  * Use `getlantern/systray` for showing status icon.
  * Show connection status, current server, unread message badge.
* **System Notifications**:

  * Use `beeep` to show toast notifications (cross-platform).
  * Trigger on:

    * New message.
    * User mentions.
    * Connection status changes.

### 5. **Server Communication**

* **Server Role**:

  * Acts as a message relay and presence manager.
  * Handles identity validation through a Web of Trust.
  * Temporary offline message cache (with expiry).
* **Multiple Server Support**:

  * User can connect to multiple servers at once.
  * Prioritize closest/fastest server for message delivery.
* **Server Authentication**:

  * Server identifies users via PGP signature.
  * No traditional password-based auth.

### 6. **CLI Messaging Tool (Non-TUI)**

* Quick command-line utility to send messages:

  ```sh
  whspbrd --to user123 --message "hey!"
  ```

* Designed for shell scripting, automation, cronjobs.
* Uses same encryption and delivery mechanism as TUI.

---

## II. Optional / Extended Functionality

### 1. **Peer-to-Peer Messaging (Local Network)**

* **Automatic LAN Discovery**:

  * Bonjour/mDNS or UDP broadcast for peer discovery.
* **Direct LAN Messaging**:

  * If users are in same network, bypass server and send messages directly.
  * Messages still encrypted with PGP.
* **Fallback**: If P2P fails, fallback to server-based delivery.

### 2. **Plugin System (C Modules)**

* Optional C plugin support.
* Users can write extensions for:

  * UI customization.
  * Automation hooks.
  * Custom message processors.
* Plugin sandboxing required to maintain app security.

### 3. **Music Sharing Integration (Linux Only)**

* Use `playerctl` and `MPRIS` to:

  * Detect current track on Spotify/VLC/etc.
  * Optionally share what you're listening to in status.
  * Enable `/nowplaying` command to post track in chat.

---

## III. 🔧 Non-Functional Requirements

### 1. **Cross-Platform Support**

* Full support for:

  * Linux (primary support)
  * Windows (via WSL or native terminal)
  * macOS (should work same as on linux hopefully)

* All features should work identically or degrade gracefully.

### 2. **Performance & Responsiveness**

* TUI should remain responsive even with long message histories.
* Image rendering must be optimized to avoid lag.

### 3. **Security**

* End-to-end encryption by default (no toggle).
* No unencrypted message is ever sent or stored.
* All key exchange and server handshake must be encrypted.

### 4. **Portability**

* App should be easy to compile with `go build` on all platforms.
* Minimal external dependencies.

### 5. **Configurability**

* Config file in JSON format.
* User can configure:

  * Servers
  * Avatar/image size
  * Notification preferences
  * Logging level

### 6. **Logging & Debugging**

* Optional encrypted log file support (for debugging).
* CLI flags like `--verbose`, `--log`, `--debug`.

---

## IV. 📦 Directory and File Structure Example

```shell
~/.config/whspbrd/
├──  config.json
├──  icon.png
└──  servers
    ├──  default
    │   ├──  server.json
    │   └──  users
    │       ├──  alice
    │       │   ├── 󰷖 alice.pub
    │       │   ├──  icon.png
    │       │   └──  messages.json
    │       └──  bob
    │           ├── 󰷖 bob.pub
    │           └──  messages.json
    └──  secondary
```

---

## V. 📌 Example Use Cases

### 1. TUI Chat

* Open app from terminal:

  ```sh
  whspbrd
  ```

* Chat using keyboard-driven TUI interface.

### 2. CLI Send

* Send message directly from terminal:

  ```sh
  whspbrd --to alice --message "Meeting at 5?"
  ```

### 3. Tray & Notifications

* App minimized to tray.
* Incoming message triggers `beeep` notification.

### 4. Local Network P2P

* Two devices on same Wi-Fi detect each other.
* Chat without routing via server.

### 5. Plugin Example

* Load plugin that sends an auto-reply or updates presence from external data.