meshcore-usb-dashboard/PROJECT_SUMMARY.md

Meshtastic MQTT Dashboard - Project Summary

Overview

A complete, production-ready Node.js web application for monitoring and managing Meshtastic mesh networks via MQTT. This is a fully self-contained solution similar to the Home Assistant integration.

What Was Built

Backend (Node.js + Express)

Core Server (src/server.js)

• Express.js web server
• Session management with express-session
• Security middleware (Helmet, CORS, rate limiting)
• Graceful shutdown handling
• Error handling middleware

Authentication System (src/auth/)

• User registration and login with bcrypt password hashing
• Session-based authentication
• Activity logging for security auditing
• User creation script for initial setup

Database Layer (src/database/)

• SQLite database with better-sqlite3
• Comprehensive schema for:
  • Users and authentication
  • Meshtastic nodes
  • GPS positions
  • Text messages
  • Device telemetry
  • Activity logs
• Prepared statements for performance and security
• Automatic database initialization

MQTT Client (src/mqtt/)

• Automatic connection to Meshtastic MQTT broker
• Real-time message processing
• Support for multiple message types:
  • Text messages
  • Position updates
  • Node information
  • Telemetry data
• Message publishing for sending to mesh
• Automatic reconnection handling

REST API (src/routes/api.js)

Complete API with endpoints for:

• Authentication (login/logout)
• Node management (list all, get details)
• Position tracking (latest positions, history)
• Message history (view and send)
• Telemetry data
• Statistics dashboard
• Data purging

Background Services (src/services/)

• Cron service for scheduled tasks
• Automatic data purging based on retention policy
• Configurable schedule (default: daily at 2 AM)

Logging System (src/utils/)

• Winston-based structured logging
• Multiple log files (combined, errors)
• Log rotation
• Configurable log levels

Configuration (src/config/)

• Environment variable based configuration
• Secure defaults
• Easy customization for different deployments

Frontend (Vanilla JavaScript)

Modern Web Interface (public/)

• Responsive Design: Works on desktop, tablet, and mobile
• Clean UI: Modern styling with CSS variables for easy theming
• No Framework Dependencies: Pure JavaScript for simplicity

Features:

1. Login Screen

   • Secure authentication
   • Form validation
   • Error handling

2. Dashboard Overview

   • Real-time statistics cards
   • Recent message feed
   • MQTT connection status indicator

3. Interactive Map

   • Leaflet.js integration
   • GPS position tracking
   • Clickable markers with node info
   • Auto-fit to show all nodes

4. Message Management

   • Send messages to mesh network
   • View message history with metadata
   • Channel selection
   • Signal quality indicators (SNR, RSSI)

5. Node Monitoring

   • Grid view of all nodes
   • Online/offline status
   • Detailed node information modal
   • Battery levels, signal strength
   • Hardware information

6. Settings Panel

   • Manual data purging
   • Configurable retention periods
   • Application information

Security Features

• Password hashing with bcrypt (10 rounds)
• Session-based authentication
• HTTP security headers (Helmet)
• Rate limiting on API endpoints
• CSRF protection ready
• Activity logging for audit trails
• Secure session cookies

Database Schema

Tables Created:

1. users - User accounts
2. nodes - Meshtastic node information
3. positions - GPS location history
4. messages - Text message history
5. telemetry - Device telemetry data
6. activity_log - User activity tracking

Indexes Created:

• Node ID lookups
• Position timestamps
• Message timestamps and senders
• Telemetry tracking

Configuration Options

All configurable via .env:

• Server port
• MQTT broker settings
• Session secrets
• Data retention policies
• Cron schedules
• Log levels
• Rate limiting

File Structure

meshtastic-mqtt-dashboard/
├── src/
│   ├── auth/
│   │   └── auth.js                 # Authentication logic
│   ├── config/
│   │   └── config.js               # Configuration management
│   ├── database/
│   │   ├── db.js                   # Database initialization
│   │   └── queries.js              # Prepared statements
│   ├── mqtt/
│   │   └── client.js               # MQTT client implementation
│   ├── routes/
│   │   └── api.js                  # REST API endpoints
│   ├── scripts/
│   │   └── createUser.js           # User creation utility
│   ├── services/
│   │   └── cron.js                 # Background job scheduler
│   ├── utils/
│   │   └── logger.js               # Logging utility
│   └── server.js                   # Main application entry
├── public/
│   ├── css/
│   │   └── style.css               # Modern UI styles
│   ├── js/
│   │   └── app.js                  # Frontend application
│   └── index.html                  # Single page app
├── .env.example                    # Environment template
├── .gitignore                      # Git ignore rules
├── package.json                    # Dependencies
├── README.md                       # Full documentation
├── QUICKSTART.md                   # Quick start guide
└── PROJECT_SUMMARY.md              # This file

Technology Stack

Backend

• Node.js: Runtime environment
• Express.js: Web framework
• better-sqlite3: Fast SQLite database
• mqtt: MQTT client library
• bcryptjs: Password hashing
• express-session: Session management
• winston: Logging
• node-cron: Job scheduling
• helmet: Security headers
• express-rate-limit: Rate limiting

Frontend

• Vanilla JavaScript: No frameworks, pure JS
• Leaflet.js: Interactive maps
• OpenStreetMap: Map tiles
• CSS3: Modern styling with variables
• Fetch API: HTTP requests

Database

• SQLite: Embedded database
• WAL mode: Better concurrency

Key Features Implemented

✅ MQTT automatic connection and message storage ✅ SQLite database with comprehensive schema ✅ User authentication with bcrypt ✅ Session management ✅ REST API for all operations ✅ Interactive map with GPS tracking ✅ Message viewing and sending ✅ Node monitoring and metadata ✅ Automatic data purging with cron ✅ Manual data purging button ✅ Activity logging ✅ Comprehensive error handling ✅ Security best practices ✅ Modern, responsive UI ✅ Real-time statistics ✅ Configurable via environment variables ✅ Complete documentation

Getting Started

1. Install dependencies: npm install
2. Copy environment file: cp .env.example .env
3. Edit .env with your settings
4. Create user: npm run create-user
5. Start server: npm start
6. Open browser: http://localhost:3000

See QUICKSTART.md for detailed instructions.

Production Ready

This application is production-ready with:

• Proper error handling
• Security best practices
• Logging and monitoring
• Graceful shutdown
• Session management
• Rate limiting
• Input validation
• SQL injection protection (prepared statements)
• XSS protection
• CSRF ready

Future Enhancement Ideas

• WebSocket support for real-time updates
• User management interface
• Email notifications
• Export data to CSV/JSON
• Advanced filtering and search
• Grafana integration
• Multi-user permissions
• Custom alerts and triggers
• Mobile app (PWA)

License

MIT License - Free to use, modify, and distribute

Support

See README.md for troubleshooting and detailed documentation.

---

Built with ❤️ for the Meshtastic community