initial commit

2025-10-11 17:03:31 -07:00
commit 4767b67460
25 changed files with 5098 additions and 0 deletions
@@ -0,0 +1,281 @@
+# 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**