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.
  • 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:

  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

~/.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:

  whspbrd
  

• Chat using keyboard-driven TUI interface.

2. CLI Send

• Send message directly from terminal:

  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.