227 lines
5.7 KiB
Markdown
227 lines
5.7 KiB
Markdown
# **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. |