docs: restore template structure with concise layered architecture

Co-authored-by: Zakary Timson (@ztimson)
2026-09-21 14:19:17 -04:00
parent e910855427
commit 1d46364ebb
1 changed files with 36 additions and 114 deletions
@@ -1,151 +1,73 @@
 # Multipurpose Radio Server (MRS)

---
+**Multipurpose Radio Server** is an offline-first connectivity and reconnaissance hub designed for isolated environments.

-###### By: Zakary Timson
-###### Date: September 2026
-###### Version: 1.0
+> Compact communication and information exchange server on Raspberry Pi for service-denied areas. Ideal for disasters, unserviced environments, long-range tracking, and offline-first operations.

---
+## Overview

-> Offline-first radio and connectivity hub for service-denied or isolated environments.
-> Designed for disaster response, long-range tracking, reconnaissance, and resilient communications.
+MRS provides a modular, hardware-focused foundation that interfaces with three supporting layers:

---
+- **MRS Core Layer**: Connectivity, radio, and reconnaissance tools
+- **OpenCast Layer**: Media casting, control panel, and remote desktop
+- **AI-harness Layer**: AI assistant, knowledge base, and file services

-## Architecture Overview
-
-MRS is now structured around three modular layers:
-
- **MRS (Core Layer)**: Hardware-focused connectivity and reconnaissance
- **OpenCast (Media/Control Layer)**: Screen casting, control panel, remote desktop
- **AI-harness (Interface Layer)**: Unified access to AI, knowledge base, and file services
-
---
-
-## Core Services
+## Core Capabilities

 ### Connectivity
-
- **900 MHz / 2.4/5 GHz Mesh WiFi** via B.A.T.M.A.N. routing (1 km+)
- **LoRa Radio** communication (Meshtastic node, 1-100s of km)
- **HaLow integration** for long-range WiFi mesh connectivity
+- 900 MHz HaLow / 2.4 & 5 GHz mesh WiFi via B.A.T.M.A.N.
+- LoRa radio communication via Meshtastic node
+- QR-code connection setup with captive portal

 ### Hardware Interface
-
- **TV/Display connection** via OpenCast for live data visualization
- **Meshtastic LoRa node** for field operations and tracking
- **Radio frequency tools** (SDRAngel for spectrum analysis)
+- Live data visualization to connected TV/display
+- Meshtastic LoRa node for field tracking
+- Spectrum analysis via SDRAngel

 ### Reconnaissance & Security
-
- WiFi & Bluetooth reconnaissance (Bettercap, nmap, masscan)
- Red team operations (aircrack, nikto, Metasploit)
+- WiFi/Bluetooth scanning (Bettercap, nmap, masscan)
 - Radio frequency recon (SDRAngel)
 - ADS-B plane tracking (tar1090)
+- Red team toolkit (aircrack, nikto, Metasploit)

-### Networking
+## Features

- Captive portal with QR code connection
- Hostapd + dnsmasq integration
- Local state feed at `localhost:8088/status`
- MCP server for LLM integration
+- **Connectivity**: Mesh networking for 1 km+ coverage
+- **Archive**: Kiwix offline Wikipedia and knowledge base
+- **Recon Tools**: Network and radio frequency scanning suite
+- **Messaging**: Federated chat via Synapse/Element (legacy support)
+- **Remote Desktop**: VNC integration via OpenCast backend

---
-
-## Layered Architecture
-
-### MRS Core Layer
-
-MRS runs as the foundational service layer, handling all hardware connectivity and reconnaissance tools. It provides:
-
- Mesh WiFi and LoRa backbone
- Reconnaissance tool orchestration
- Hardware telemetry and status
- Local API endpoint for layer communication
-
-### OpenCast Layer
-
-OpenCast serves as the control surface and media orchestrator:
-
- Screen casting to display hardware
- Control panel for system navigation
- Built-in VNC remote desktop access
- Puppeteer management via API endpoints
- Runs on port 3000
-
-### AI-harness Layer
-
-The harness provides a unified interface to knowledge and intelligence services:
-
- Offline AI assistant (Liter + Gemma4-e2b)
- ZIM archive access (Kiwix)
- File hosting and management
- Notes and data management
- Replaces legacy Ollama/OpenWebUI and FileBrowser
-
---
-
-## Services
-
-### Screen & Display
-
- **OpenCast TV**: Connects display hardware to MRS data streams
- **Blur/Sticky UI**: Persistent blur effect over idle data feeds
- **Notification overlay**: System alerts and event notifications
-
-### Media & Casting
-
- **Puppeteer casting**: Web page "casting" to display
- **Image gallery**: Fallback to random images or local photo selection
- **Remote desktop**: VNC integration via OpenCast backend
-
-### Intelligence & Tools
-
- **AI Assistant**: Gemma4-e2b-powered offline AI
- **ZIM Archive**: Kiwix offline knowledge base
- **Recon Suite**: Network, radio, and hardware scanning tools
- **File Management**: Harness-integrated file hosting and editing
-
---
-
-## Quick Start
+## Installation

 ```bash
-# Clone and install
 git clone https://git.zakscode.com/ztimson/mrs
 cd mrs
-
-# Install base dependencies
 npm ci
-
-# Start services
-# - MRS core:   defaults to port 8088
-# - OpenCast:   defaults to port 3000
-# - AI-harness: defaults to port 3001
 ```

---
+- MRS core: port 8088
+- OpenCast: port 3000
+- AI-harness: port 3001

 ## Documentation

 - [Setup Guide](docs/setup.md)
 - [Mesh Network](docs/mesh.md)
 - [Maps & Geolocation](docs/maps.md)
- [API Documentation](docs/api.md) - Coming soon
-
---

 ## Todo

- [ ] Finalize service separation across layers
- [ ] Publish API contracts between MRS, OpenCast, and harness
- [ ] Add telemetry endpoint for remote monitoring
- [ ] Implement automated OTA update mechanism
- [ ] Add more recon tools to the core suite
-
---
+- [ ] API contracts between layers
+- [ ] Telemetry endpoint
+- [ ] OTA update mechanism

 ## License

-This project is licensed under the [MIT License](LICENSE).
+[MIT License](LICENSE).
+
+---
+
+###### By: Zakary Timson
+###### Date: September 16, 2025
+###### Version: 1.0