docs: update documentation for path management, add contact, theme, sidebar

- README: add multi-path routing, add contact via URI/QR, dark/light theme, desktop sidebar, device share tab, pubkey-based DB naming - User Guide: add sections for Adding Contacts (URI/QR/manual), DM Path Management (multi-path, repeater picker, map picker, keep path toggle), Device Share tab, theme setting, desktop sidebar notes - Architecture: add path management API endpoints (CRUD, reorder, reset, no_auto_flood), manual-add, push-to-device, move-to-cache endpoints, update DB naming to pubkey prefix Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-28 17:42:45 +01:00 · 2026-03-26 18:08:58 +01:00
parent 54be1796f8
commit 054b80926d
3 changed files with 116 additions and 16 deletions
--- a/README.md
+++ b/README.md
@@ -13,25 +13,26 @@ A lightweight web interface providing browser-based access to MeshCore mesh netw

 ## Key Features

- **Mobile-first design** - Responsive UI optimized for small screens
+- **Mobile-first design** - Responsive UI optimized for small screens, with desktop sidebar for wide screens
 - **Channel management** - Create, join, share (QR code), and switch between encrypted channels
- **Direct Messages (DM)** - Private messaging with searchable contact selector, delivery tracking, and configurable retry strategy
+- **Direct Messages (DM)** - Private messaging with searchable contact selector, delivery tracking, configurable retry strategy, and multi-path routing
 - **Smart notifications** - Unread message counters per channel with cross-device sync
- **Contact management** - Manual approval mode, filtering, protection, ignoring, blocking, batch operations, and cleanup tools
+- **Contact management** - Manual approval, add via URI/QR, filtering, protection, ignoring, blocking, batch operations, and cleanup tools
 - **Global search** - Full-text search across all messages (channels and DMs) with FTS5 backend
 - **Database** - Fast and reliable SQLite storage for messages, contacts, and configurations
 - **Contact map** - View contacts and own device on OpenStreetMap (Leaflet) with last seen info
 - **Message archives** - Automatic daily archiving with browse-by-date selector
 - **Interactive Console** - Full MeshCore command suite via WebSocket — repeater, contact, device, and channel management
- **Device dashboard** - Device info and statistics with firmware details
- **Settings** - Configurable DM retry parameters, message retention, and quote length
+- **Device dashboard** - Device info, statistics, and contact sharing (QR code / URI)
+- **Dark/Light theme** - Toggle between dark and light UI themes
+- **Settings** - Configurable DM retry parameters, message retention, quote length, and theme
 - **System Log** - Real-time log viewer with streaming
 - **Database backup** - Create, list, and download database backups from the UI
 - **@Mentions autocomplete** - Type @ to see contact suggestions with fuzzy search
 - **Echo tracking** - "Heard X repeats" with repeater IDs for sent messages, all route paths for incoming messages with deterministic payload matching (persisted across restarts)
 - **MeshCore Analyzer** - View packet details on analyzer.letsmesh.net directly from channel messages
 - **DM delivery tracking** - ACK-based delivery confirmation with SNR and route info
- **Multi-device support** - Database file named after device for easy multi-device setups
+- **Multi-device support** - Database file named after device public key for easy multi-device setups
 - **PWA support** - Browser notifications and installable app (experimental)
 - **Full offline support** - Works without internet (local Bootstrap, icons, emoji picker)

@@ -311,12 +312,12 @@ sudo ~/mc-webui/scripts/updater/install.sh --uninstall
 - [x] Frontend Chat View (Bootstrap UI, message display, quote/reply)
 - [x] Message Sending (Send form, reply, quote with configurable length)
 - [x] Intelligent Auto-refresh (10s checks, UI updates only when needed)
- [x] Contact Management (Approval, filtering, protection, ignore/block, batch operations, cleanup)
+- [x] Contact Management (Approval, add via URI/QR, filtering, protection, ignore/block, batch operations, cleanup)
 - [x] Channel Management (Create, join, share via QR, delete with auto-cleanup)
 - [x] Public Channels (# prefix support, auto-key generation)
 - [x] Message Archiving (Daily archiving with browse-by-date selector)
 - [x] Smart Notifications (Unread counters per channel and total)
- [x] Direct Messages (DM) - Searchable contact selector, delivery tracking, configurable retry
+- [x] Direct Messages (DM) - Searchable contact selector, delivery tracking, configurable retry, multi-path routing
 - [x] Global Message Search - Full-text search across channels and DMs (FTS5)
 - [x] Message Content Enhancements - Mention badges, clickable URLs, image previews
 - [x] @Mentions Autocomplete - Type @ to get contact suggestions with fuzzy search
@@ -327,11 +328,13 @@ sudo ~/mc-webui/scripts/updater/install.sh --uninstall
 - [x] Echo Tracking - "Heard X repeats" badge for sent channel messages
 - [x] MeshCore Analyzer - Packet analysis links on channel messages (analyzer.letsmesh.net)
 - [x] DM Delivery Tracking - ACK-based delivery checkmarks with SNR/route details
- [x] Device Dashboard - Device info and statistics with firmware details
- [x] Settings Modal - Configurable DM retry parameters and message retention
+- [x] Device Dashboard - Device info, statistics, and contact sharing (QR/URI)
+- [x] Settings Modal - DM retry parameters, message retention, and dark/light theme
 - [x] System Log - Real-time log viewer with streaming
 - [x] Database Backup - Create, list, and download backups from the UI
- [x] Multi-device Support - Database file named after device name
+- [x] Desktop Sidebar - Channel/contact sidebar for wide screens (tablet/desktop)
+- [x] Dark/Light Theme - Toggle between dark and light UI themes
+- [x] Multi-device Support - Database file named after device public key

 ### Next Steps

@@ -365,7 +368,7 @@ This is an open-source project. Contributions are welcome!
 ## References

 - [MeshCore Documentation](https://meshcore.org)
- [meshcore-cli GitHub](https://github.com/meshcore-dev/meshcore-cli)
+- [meshcore Python library](https://pypi.org/project/meshcore/)

 ---

--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -21,7 +21,7 @@ Technical documentation for mc-webui, covering system architecture, project stru
 - **Frontend:** HTML5, Bootstrap 5, vanilla JavaScript, Socket.IO client
 - **Deployment:** Docker / Docker Compose (Single-container architecture)
 - **Communication:** Direct hardware access (USB, BLE, or TCP) via `meshcore` library
- **Data source:** SQLite Database (`./data/meshcore/<device_name>.db`)
+- **Data source:** SQLite Database (`./data/meshcore/<pubkey_prefix>.db`)

 ---

@@ -80,8 +80,8 @@ mc-webui/
 │   ├── config.py                   # Configuration from env vars
 │   ├── database.py                 # SQLite database models and CRUD operations
 │   ├── device_manager.py           # Core logic for meshcore communication
-│   ├── contacts_cache.py           # Persistent contacts cache
-│   ├── read_status.py              # Server-side read status manager
+│   ├── contacts_cache.py           # Persistent contacts cache (DB-backed)
+│   ├── read_status.py              # Server-side read status manager (DB-backed)
 │   ├── version.py                  # Git-based version management
 │   ├── migrate_v1.py               # Migration script from v1 flat files to v2 SQLite
 │   ├── meshcore/
@@ -107,7 +107,7 @@ mc-webui/

 mc-webui v2 uses a robust **SQLite Database** with WAL (Write-Ahead Logging) enabled.

-Location: `./data/meshcore/<device_name>.db`
+Location: `./data/meshcore/<pubkey_prefix>.db`

 Key tables:
 - `messages` - All channel and direct messages (with FTS5 index for full-text search)
@@ -157,6 +157,19 @@ The use of SQLite allows for fast queries, reliable data storage, full-text sear
 | POST | `/api/contacts/pending/approve` | Approve pending contact |
 | POST | `/api/contacts/pending/reject` | Reject pending contact |
 | POST | `/api/contacts/pending/clear` | Clear all pending contacts |
+| POST | `/api/contacts/manual-add` | Add contact from URI or params |
+| POST | `/api/contacts/<key>/push-to-device` | Push cached contact to device |
+| POST | `/api/contacts/<key>/move-to-cache` | Move device contact to cache |
+| GET | `/api/contacts/repeaters` | List repeater contacts (for path picker) |
+| GET | `/api/contacts/<key>/paths` | Get contact paths |
+| POST | `/api/contacts/<key>/paths` | Add path to contact |
+| PUT | `/api/contacts/<key>/paths/<id>` | Update path (star, label) |
+| DELETE | `/api/contacts/<key>/paths/<id>` | Delete path |
+| POST | `/api/contacts/<key>/paths/reorder` | Reorder paths |
+| POST | `/api/contacts/<key>/paths/reset_flood` | Reset to FLOOD routing |
+| POST | `/api/contacts/<key>/paths/clear` | Clear all paths |
+| GET | `/api/contacts/<key>/no_auto_flood` | Get "Keep path" flag |
+| PUT | `/api/contacts/<key>/no_auto_flood` | Set "Keep path" flag |

 ### Channels

--- a/docs/user-guide.md
+++ b/docs/user-guide.md
@@ -12,6 +12,8 @@ This guide covers all features and functionality of mc-webui. For installation i
 - [Direct Messages (DM)](#direct-messages-dm)
 - [Global Search](#global-search)
 - [Contact Management](#contact-management)
+- [Adding Contacts](#adding-contacts)
+- [DM Path Management](#dm-path-management)
 - [Interactive Console](#interactive-console)
 - [Device Dashboard](#device-dashboard)
 - [Settings](#settings)
@@ -35,6 +37,8 @@ The main page displays chat history from the currently selected channel. The app

 By default, the live view shows messages from the last 7 days. Older messages are automatically archived and can be accessed via the date selector.

+On wide screens (tablets/desktops), a sidebar shows the channel list on the left side for quick switching.
+
 ---

 ## Managing Channels
@@ -183,6 +187,10 @@ Access the Direct Messages feature:
 - Each conversation shows unread indicator (*) in the dropdown
 - DM badge in the menu shows total unread DM count

+### Desktop Sidebar
+
+On wide screens (tablets/desktops), the DM page shows a sidebar with the contact list on the left side, making it easy to switch between conversations without using the dropdown selector.
+
 ---

 ## Global Search
@@ -345,6 +353,72 @@ You can schedule automatic cleanup to run daily at a specified hour:

 ---

+## Adding Contacts
+
+Add new contacts to your device from the Contact Management page:
+
+1. Click the "Add Contact" button at the top of the Contact Management page
+2. Opens a dedicated page with three methods:
+
+### Paste URI
+
+1. Paste a MeshCore contact URI (`meshcore://...`) into the text field
+2. The contact details (name, public key, type) are automatically parsed and previewed
+3. Click "Add to Device" to add the contact
+
+### Scan QR Code
+
+1. Click "Scan QR" to open the camera
+2. Point at a MeshCore QR code (from another user's Share tab)
+3. The URI is decoded and contact details are previewed
+4. Click "Add to Device" to add the contact
+
+### Manual Entry
+
+1. Enter the contact's public key (64 hex characters)
+2. Optionally enter name, type (COM/REP/ROOM/SENS), and location
+3. Click "Add to Device"
+
+### Cache vs Device Contacts
+
+- **Device contacts** are stored on the MeshCore hardware (limit: 350)
+- **Cache contacts** are stored only in the database (unlimited)
+- Use "Push to Device" to promote a cache contact to the device
+- Use "Move to Cache" to free a device slot while keeping the contact in the database
+
+---
+
+## DM Path Management
+
+Configure message routing paths for individual contacts:
+
+1. Open a DM conversation
+2. Click the contact info icon next to the contact name
+3. In the Contact Info modal, navigate to the "Paths" section
+
+### Path Configuration
+
+- **Add Path** - Add a repeater to the routing path using:
+  - **Repeater picker** - Browse available repeaters by name or ID
+  - **Map picker** - Select repeaters from a map view showing their GPS locations
+  - **Import current path** - Import the path currently stored on the device
+- **Reorder** - Drag paths to change priority (starred path is used first)
+- **Star** - Mark a preferred primary path (used first in retry rotation)
+- **Delete** - Remove individual paths
+
+### Keep Path Toggle
+
+- Enable "Keep path" to prevent the device from automatically switching to FLOOD routing
+- When enabled, the device will always use the configured DIRECT path(s)
+- Useful when you know the optimal route and don't want the device to override it
+
+### Path Operations
+
+- **Reset to FLOOD** - Clear all paths and switch to FLOOD routing
+- **Clear Paths** - Remove all configured paths without changing routing mode
+
+---
+
 ## Interactive Console

 Access the interactive console for direct MeshCore command execution:
@@ -414,6 +488,12 @@ Shows live device statistics:
 - Message counters (sent, received, forwarded)
 - Current airtime usage

+### Share Tab
+
+Share your device contact with others:
+- **QR Code** - Scannable QR code containing your contact URI
+- **URI** - Copyable `meshcore://` URI that others can paste into their Add Contact page
+
 ---

 ## Settings
@@ -439,6 +519,10 @@ Configure how direct messages are retried when delivery is not confirmed:

 - **Live view days** - Number of days of messages shown in the live view (older messages are archived)

+### Theme
+
+- **Dark / Light** - Toggle between dark and light UI themes. The preference is saved in local browser storage
+
 ---

 ## System Log