🏗️ MoMo-Nexus Architecture
Version: 1.1.0 | Last Updated: 2025-12-20
MoMo-Nexus is the central communication hub for the MoMo ecosystem. This document describes the technical architecture.
Goal
Priority
Description
Reliability P0
Never lose messages
Flexibility P0
Support multiple channels
Intelligence P1
Smart routing decisions
Simplicity P1
Easy to deploy and manage
Scalability P2
Handle many devices
┌─────────────────────────────────────────────────────────────────────────────┐
│ NEXUS SYSTEM │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ FIELD DEVICES NEXUS HUB │
│ ═════════════ ════════ │
│ │
│ ┌─────────┐ ┌─────────────────────────────────┐ │
│ │ MoMo │ ───┐ │ │ │
│ └─────────┘ │ │ ┌───────────────────────────┐ │ │
│ │ ┌─────────┐ │ │ CHANNEL LAYER │ │ │
│ ┌─────────┐ ├───►│ LoRa │──────┼──│ │ │ │
│ │ Ghost │ ───┤ │ Mesh │ │ │ LoRa │ 4G │ WiFi │ BLE │ │ │
│ │ Bridge │ │ └─────────┘ │ │ │ │ │
│ └─────────┘ │ │ └───────────┬───────────────┘ │ │
│ │ ┌─────────┐ │ │ │ │
│ ┌─────────┐ ├───►│ WiFi │──────┼──────────────┤ │ │
│ │ Mimic │ ───┤ │ │ │ │ │ │
│ └─────────┘ │ └─────────┘ │ ┌───────────▼───────────────┐ │ │
│ │ │ │ ROUTING ENGINE │ │ │
│ ┌─────────┐ │ ┌─────────┐ │ │ │ │ │
│ │ Swarm │ ───┴───►│ 4G │──────┼──│ Queue │ Priority │ ACK │ │ │
│ │ Nodes │ │ Internet│ │ │ │ │ │
│ └─────────┘ └─────────┘ │ └───────────┬───────────────┘ │ │
│ │ │ │ │
│ │ ┌───────────▼───────────────┐ │ │
│ │ │ APPLICATION LAYER │ │ │
│ │ │ │ │ │
│ │ │ Fleet │ Alerts │ Cmds │ │ │
│ │ │ │ │ │
│ │ └───────────┬───────────────┘ │ │
│ │ │ │ │
│ │ ┌───────────▼───────────────┐ │ │
│ │ │ PRESENTATION LAYER │ │ │
│ │ │ │ │ │
│ OPERATOR │ │ Web UI │ API │ Mobile │ │ │
│ ════════ │ │ │ │ │
│ │ └───────────────────────────┘ │ │
│ ┌─────────┐ ┌─────────┐ │ │ │
│ │ 📱 │◄───────►│ Web │◄─────┤ │ │
│ │ Mobile │ │Dashboard│ │ │ │
│ └─────────┘ └─────────┘ └─────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────────────────┐
│ CHANNEL LAYER │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ ABSTRACT CHANNEL │ │
│ │ │ │
│ │ interface Channel: │ │
│ │ - name: str │ │
│ │ - status: ChannelStatus │ │
│ │ - send(message) → bool │ │
│ │ - receive() → Message │ │
│ │ - get_latency() → ms │ │
│ │ - get_bandwidth() → kbps │ │
│ │ - health_check() → bool │ │
│ │ │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ┌─────────────────────────┼─────────────────────────┐ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ LoRaChannel │ │ CellChannel │ │ WiFiChannel │ │
│ │ │ │ │ │ │ │
│ │ • Meshtastic│ │ • SIM7600 │ │ • Client │ │
│ │ • Serial │ │ • AT cmds │ │ • AP mode │ │
│ │ • Long range│ │ • PPP │ │ • Local net │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ BLEChannel │ │ SatChannel │ │ MeshChannel │ │
│ │ │ │ │ │ │ │
│ │ • GATT │ │ • Iridium │ │ • WiFi Mesh │ │
│ │ • Short rng │ │ • SBD │ │ • batman-adv│ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
Channel
Latency
Bandwidth
Range
Cost
Reliability
LoRa 2-5s
0.3 kbps
15 km
Free
High
4G/LTE 50ms
10 Mbps
Global
$$
Medium
WiFi 10ms
100 Mbps
100m
Free
Medium
BLE 20ms
1 Mbps
30m
Free
High
Satellite 30s
2 kbps
Global
$$$
High
┌─────────────────────────────────────────────────────────────────────────────┐
│ ROUTING ENGINE │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ INBOUND MESSAGE │
│ │ │
│ ▼ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ Parser │────►│ Validator │────►│ Router │ │
│ │ │ │ │ │ │ │
│ │ • Decode │ │ • Auth │ │ • Dest │ │
│ │ • Validate │ │ • Replay │ │ • Priority │ │
│ └─────────────┘ └─────────────┘ └──────┬──────┘ │
│ │ │
│ ┌────────────────────┼────────────────────┐ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌─────────────┐ ┌─────────────┐ ┌──────────┐ │
│ │ To Fleet │ │ To Queue │ │ To App │ │
│ │ (devices) │ │ (store) │ │ (alert) │ │
│ └─────────────┘ └─────────────┘ └──────────┘ │
│ │
│ OUTBOUND MESSAGE │
│ │ │
│ ▼ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ Priority │────►│ Channel │────►│ Sender │ │
│ │ Classifier │ │ Selector │ │ │ │
│ │ │ │ │ │ • Serialize │ │
│ │ • Critical │ │ • Score │ │ • Transmit │ │
│ │ • High │ │ • Failover │ │ • ACK wait │ │
│ │ • Normal │ │ • Load bal │ │ │ │
│ │ • Low │ │ │ │ │ │
│ └─────────────┘ └──────┬──────┘ └─────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ CHANNEL SELECTION ALGORITHM │ │
│ │ │ │
│ │ score(channel) = w1*availability + w2*latency + w3*cost │ │
│ │ │ │
│ │ Weights by priority: │ │
│ │ • CRITICAL: availability=0.8, latency=0.2, cost=0.0 │ │
│ │ • HIGH: availability=0.6, latency=0.3, cost=0.1 │ │
│ │ • NORMAL: availability=0.5, latency=0.3, cost=0.2 │ │
│ │ • LOW: availability=0.3, latency=0.2, cost=0.5 │ │
│ │ │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────────────────┐
│ MESSAGE QUEUE │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ PRIORITY QUEUES │ │
│ │ │ │
│ │ ┌─────────────────┐ Processed first │ │
│ │ │ CRITICAL │ ════════════════ │ │
│ │ │ [msg1][msg2] │ │ │
│ │ └─────────────────┘ │ │
│ │ ┌─────────────────┐ │ │
│ │ │ HIGH │ │ │
│ │ │ [msg3][msg4] │ │ │
│ │ └─────────────────┘ │ │
│ │ ┌─────────────────┐ │ │
│ │ │ NORMAL │ │ │
│ │ │ [msg5][msg6]... │ │ │
│ │ └─────────────────┘ │ │
│ │ ┌─────────────────┐ Processed last │ │
│ │ │ LOW / BULK │ ═══════════════ │ │
│ │ │ [msg7][msg8]... │ │ │
│ │ └─────────────────┘ │ │
│ │ │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │
│ Queue Behavior: │
│ • Messages persisted to disk (SQLite) │
│ • Automatic retry with exponential backoff │
│ • Dead letter queue for failed messages │
│ • TTL expiration for old messages │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────────────────┐
│ DEVICE STATES │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌───────────────┐ │
│ │ UNREGISTERED │ │
│ └───────┬───────┘ │
│ │ register() │
│ ▼ │
│ ┌───────────────┐ │
│ ┌───────►│ OFFLINE │◄───────┐ │
│ │ └───────┬───────┘ │ │
│ │ │ connect() │ disconnect() │
│ │ ▼ │ │
│ │ ┌───────────────┐ │ │
│ │ ┌───│ ONLINE │────────┘ │
│ │ │ └───────┬───────┘ │
│ │ │ │ sleep() │
│ │ │ ▼ │
│ │ │ ┌───────────────┐ │
│ │ └───│ SLEEPING │ │
│ │ └───────┬───────┘ │
│ │ │ wake() / timeout │
│ │ ▼ │
│ │ ┌───────────────┐ │
│ └────────│ LOST │ │
│ timeout > 24h └───────────────┘ │
│ │
│ Status Indicators: │
│ 🟢 ONLINE - Active, responding │
│ 🟡 SLEEPING - Low power, periodic check-in │
│ 🔴 OFFLINE - Not reachable │
│ ⚫ LOST - No contact for extended period │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
-- Devices tableCREATE TABLE devices (
id TEXT PRIMARY KEY ,
type TEXT NOT NULL , -- momo, ghostbridge, mimic, swarmTEXT ,
status TEXT DEFAULT ' offline' TIMESTAMP ,
last_location TEXT , -- JSON: {"lat": x, "lon": y}INTEGER ,
channels TEXT , -- JSON arrayTEXT , -- JSONTIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
-- Messages tableCREATE TABLE messages (
id TEXT PRIMARY KEY ,
source TEXT NOT NULL ,
destination TEXT ,
channel TEXT ,
priority TEXT DEFAULT ' normal' TEXT NOT NULL ,
data TEXT , -- JSONTEXT DEFAULT ' pending' INTEGER DEFAULT 0 ,
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ,
sent_at TIMESTAMP ,
acked_at TIMESTAMP ,
FOREIGN KEY (source) REFERENCES devices(id)
);
-- Channels tableCREATE TABLE channels (
name TEXT PRIMARY KEY ,
type TEXT NOT NULL ,
status TEXT DEFAULT ' down' TEXT , -- JSONTIMESTAMP ,
stats TEXT -- JSON: latency, bandwidth, etc-- Alerts tableCREATE TABLE alerts (
id INTEGER PRIMARY KEY AUTOINCREMENT,
device_id TEXT ,
type TEXT NOT NULL ,
severity TEXT DEFAULT ' info' TEXT ,
acknowledged INTEGER DEFAULT 0 ,
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ,
FOREIGN KEY (device_id) REFERENCES devices(id)
);┌─────────────────────────────────────────────────────────────────────────────┐
│ SECURITY LAYERS │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ 1. Transport Encryption │
│ └── LoRa: AES-256 (Meshtastic PSK) │
│ └── 4G: TLS 1.3 │
│ └── WiFi: WPA3 │
│ │
│ 2. Message Authentication │
│ └── HMAC-SHA256 signature │
│ └── Timestamp validation (±5 min) │
│ └── Sequence numbers (replay protection) │
│ │
│ 3. Device Authentication │
│ └── Pre-shared device keys │
│ └── Challenge-response registration │
│ └── Device whitelist │
│ │
│ 4. API Security │
│ └── JWT tokens │
│ └── Rate limiting │
│ └── Input validation │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
🌐 Web Dashboard Architecture ┌─────────────────────────────────────────────────────────────────────────────┐
│ DASHBOARD ARCHITECTURE │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ REACT APPLICATION │ │
│ │ │ │
│ │ ┌───────────────────────────────────────────────────────────┐ │ │
│ │ │ PRESENTATION LAYER │ │ │
│ │ │ │ │ │
│ │ │ Pages: │ │ │
│ │ │ ├── Dashboard (stats, fleet, activity) │ │ │
│ │ │ ├── Fleet (device management) │ │ │
│ │ │ ├── Captures (handshakes) │ │ │
│ │ │ ├── Cracking (job queue) │ │ │
│ │ │ ├── Phishing (evilginx sessions) │ │ │
│ │ │ ├── Analytics (charts, reports) │ │ │
│ │ │ └── Settings (config, theme) │ │ │
│ │ │ │ │ │
│ │ │ Components: │ │ │
│ │ │ ├── Layout (Sidebar, Header, MobileNav) │ │ │
│ │ │ ├── UI (StatCard, DeviceCard, Toast, Modal, Skeleton) │ │ │
│ │ │ └── Maps (DeviceMap with Leaflet) │ │ │
│ │ │ │ │ │
│ │ └───────────────────────────────────────────────────────────┘ │ │
│ │ │ │ │
│ │ ┌───────────────────────────▼───────────────────────────────┐ │ │
│ │ │ STATE & HOOKS │ │ │
│ │ │ │ │ │
│ │ │ ├── useWebSocket (real-time connection) │ │ │
│ │ │ ├── useApi (REST API calls) │ │ │
│ │ │ ├── useTheme (dark/light mode) │ │ │
│ │ │ └── useKeyboardShortcuts (navigation) │ │ │
│ │ │ │ │ │
│ │ └───────────────────────────────────────────────────────────┘ │ │
│ │ │ │ │
│ │ ┌───────────────────────────▼───────────────────────────────┐ │ │
│ │ │ DATA LAYER │ │ │
│ │ │ │ │ │
│ │ │ ├── API Client (fetch wrapper) │ │ │
│ │ │ ├── WebSocket Client (Socket.IO) │ │ │
│ │ │ └── Local Storage (theme, settings) │ │ │
│ │ │ │ │ │
│ │ └───────────────────────────────────────────────────────────┘ │ │
│ │ │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
Layer
Technology
Purpose
Framework React 18
UI components
Language TypeScript
Type safety
Build Vite
Fast bundling
Styling Tailwind CSS
Utility-first CSS
Icons Lucide React
SVG icons
Charts Recharts
Data visualization
Maps Leaflet + react-leaflet
Device locations
Routing React Router v7
Page navigation
Notifications react-hot-toast
Toast alerts
dashboard/
├── public/
│ └── nexus.svg # Logo
├── src/
│ ├── components/
│ │ ├── layout/ # Sidebar, Header, MobileNav
│ │ └── ui/ # Reusable components
│ ├── hooks/ # Custom React hooks
│ ├── lib/ # Utilities, export functions
│ ├── pages/ # Route components
│ ├── types/ # TypeScript definitions
│ ├── App.tsx # Root component
│ ├── main.tsx # Entry point
│ └── index.css # Global styles
├── package.json
├── tailwind.config.js
├── vite.config.ts
└── tsconfig.json
// REST API endpoints (via FastAPI backend)
GET / api / devices # List all devices
GET / api / devices / :id # Get device details
POST / api / devices / :id / command # Send command
GET / api / handshakes # List captures
GET / api / jobs # Cracking jobs
GET / api / sessions # Phishing sessions
GET / api / stats # Dashboard statistics
// WebSocket events
ws://localhost:8080/ws
├── handshake_captured # New handshake
├── password_cracked # Crack complete
├── device_status # Online / offline
├── alert # System alerts
└── job_progress # Crack progress Performance Optimizations
Optimization
Implementation
Code Splitting Lazy-loaded routes
Chunk Separation vendor, charts, maps
Lazy Components DeviceMap loaded on demand
Skeleton Loading Placeholder UI during fetch
Memoization React.memo for static components
MoMo-Nexus Architecture v1.1.0