docs: add NexusGuard portfolio (architecture, tech-stack, features, deployment)
This commit is contained in:
datadunia
@@ -0,0 +1,190 @@
|
||||
# Architecture Overview
|
||||
|
||||
NexusGuard is a three-component SD-WAN system: a central API server, a web dashboard, and cross-platform device agents. All communication is encrypted. Tunnels are fileless. Access is zero-trust.
|
||||
|
||||
## High-Level Architecture
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────────┐
|
||||
│ Dashboard (Vue 3) │
|
||||
│ Glassmorphism Web Interface │
|
||||
│ Manages: Nodes, Devices, Rules │
|
||||
└───────────────────────────────────┬─────────────────────────────────┘
|
||||
│ HTTP (port 80)
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────────┐
|
||||
│ Nginx Reverse Proxy │
|
||||
│ Routes: /api/ → :8080, / → SPA │
|
||||
└───────────────────────────────────┬─────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────────┐
|
||||
│ Server Core (Go/Gin) │
|
||||
│ │
|
||||
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────────────┐ │
|
||||
│ │ HTTP API │ │ gRPC │ │ IPAM │ │ nftables │ │
|
||||
│ │ (20+ │ │ Signaling│ │ Manager │ │ Firewall │ │
|
||||
│ │ handlers)│ │ (cmux) │ │ │ │ │ │
|
||||
│ └────┬─────┘ └────┬─────┘ └────┬─────┘ └────────┬─────────┘ │
|
||||
│ │ │ │ │ │
|
||||
│ ▼ ▼ ▼ ▼ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||||
│ │ PostgreSQL Database │ │
|
||||
│ │ (wg_servers, devices, rules, users) │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
│ ┌──────────────────────┐ ┌──────────────────────┐ │
|
||||
│ │ Redis │ │ WireGuard │ │
|
||||
│ │ (Heartbeat TTL) │ │ (wg0 interface) │ │
|
||||
│ └──────────────────────┘ └──────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
┌───────────────┴───────────────┐
|
||||
│ │
|
||||
▼ ▼
|
||||
┌───────────────────────────┐ ┌───────────────────────────┐
|
||||
│ Device Agent (Linux) │ │ Device Agent (Win/Mac) │
|
||||
│ Systemd Daemon │ │ System Tray │
|
||||
│ Memory-injected WG │ │ Memory-injected WG │
|
||||
└───────────────────────────┘ └───────────────────────────┘
|
||||
```
|
||||
|
||||
## Component Breakdown
|
||||
|
||||
### Server Core
|
||||
|
||||
The central API and VPN hub. Written in Go with Gin framework.
|
||||
|
||||
| Responsibility | Implementation |
|
||||
|----------------|----------------|
|
||||
| API endpoints | 20+ Gin handlers (`api/` directory) |
|
||||
| gRPC signaling | Bidirectional streaming via cmux (port 8080) |
|
||||
| IPAM | IP pool allocation from CIDR per node |
|
||||
| Firewall | nftables rule management (add/remove per peer) |
|
||||
| WireGuard | Interface control, peer sync, config push |
|
||||
| Auth | JWT middleware, admin-only enforcement |
|
||||
| Heartbeat | Config sync, handshake monitoring |
|
||||
|
||||
### Dashboard UI
|
||||
|
||||
Admin web interface. Built with Vue 3 and glassmorphism design system.
|
||||
|
||||
| Responsibility | Implementation |
|
||||
|----------------|----------------|
|
||||
| Node management | Register/edit WireGuard servers |
|
||||
| Device management | CRUD, provisioning tokens, QR codes |
|
||||
| Firewall rules | Per-peer nftables rule editor |
|
||||
| Live telemetry | 10s polling for device health |
|
||||
| Traffic history | Time-range filtering, export |
|
||||
|
||||
### Device Agent
|
||||
|
||||
Stealth VPN daemon. Cross-platform Go binary.
|
||||
|
||||
| Responsibility | Implementation |
|
||||
|----------------|----------------|
|
||||
| Provisioning | HTTP POST with AES-256-GCM encrypted response |
|
||||
| Tunnel | Memory-injected WireGuard (no disk files) |
|
||||
| Heartbeat | HTTP/gRPC, config sync, handshake monitoring |
|
||||
| gRPC | Bidirectional stream for real-time commands |
|
||||
| Self-healing | Exponential backoff reconnection |
|
||||
|
||||
## Data Flow
|
||||
|
||||
### Provisioning Flow
|
||||
|
||||
```
|
||||
1. Admin creates device via Dashboard → API generates registration token
|
||||
2. Agent sends token + HWID to POST /api/v1/provision
|
||||
3. Server validates token, allocates IP from pool
|
||||
4. Server responds with WireGuard config (AES-256-GCM encrypted)
|
||||
5. Agent decrypts config, injects into WireGuard via IpcSet
|
||||
6. Tunnel established — no files written to disk
|
||||
```
|
||||
|
||||
### Heartbeat Flow
|
||||
|
||||
```
|
||||
Every 30 seconds:
|
||||
1. Agent reads last_handshake_time from WireGuard IPC
|
||||
2. Agent computes config_hash = endpoint + internalIP + serverPub
|
||||
3. Agent POSTs {config_hash, last_handshake, tunnel_up} to server
|
||||
4. Server compares with stored config
|
||||
5. If config changed → server responds with new config
|
||||
6. Agent detects change → rebuilds tunnel
|
||||
```
|
||||
|
||||
### Suspend/Resume Flow
|
||||
|
||||
```
|
||||
Suspend:
|
||||
1. Admin clicks "Suspend" in Dashboard
|
||||
2. Dashboard POSTs /api/v1/devices/:id/suspend
|
||||
3. Server updates DB (is_suspended = true)
|
||||
4. Server sends gRPC SuspendCommand to agent
|
||||
5. Server removes WireGuard peer from kernel
|
||||
6. Agent receives command → stops tunnel
|
||||
|
||||
Resume:
|
||||
1. Admin clicks "Resume" in Dashboard
|
||||
2. Server updates DB (is_suspended = false)
|
||||
3. Server re-adds WireGuard peer to kernel
|
||||
4. Server sends gRPC ResumeCommand with full ConfigUpdate
|
||||
5. Agent receives command → rebuilds tunnel
|
||||
```
|
||||
|
||||
## Security Model
|
||||
|
||||
### Zero-Trust Principles
|
||||
|
||||
| Principle | Implementation |
|
||||
|-----------|----------------|
|
||||
| No public registration | `/auth/register` locked; admin via CLI only |
|
||||
| Encrypted provisioning | AES-256-GCM for WireGuard config transfer |
|
||||
| Fileless tunnels | WireGuard config in process memory only |
|
||||
| Hardware binding | HWID (DMI/CPU serial) bound to registration token |
|
||||
| Per-peer isolation | nftables rules per device, default deny |
|
||||
| JWT authentication | All API endpoints require valid token |
|
||||
|
||||
### Trust Boundaries
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────┐
|
||||
│ Trusted Zone │
|
||||
│ │
|
||||
│ ┌──────────┐ ┌──────────┐ ┌──────────────────────┐ │
|
||||
│ │ Server │ │ Database │ │ WireGuard Interface │ │
|
||||
│ │ Core │ │ (PG) │ │ (wg0) │ │
|
||||
│ └──────────┘ └──────────┘ └──────────────────────┘ │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────┘
|
||||
│
|
||||
Encrypted Channel
|
||||
(AES-256-GCM / WG)
|
||||
│
|
||||
┌─────────────────────────────────────────────────────────┐
|
||||
│ Untrusted Zone │
|
||||
│ │
|
||||
│ ┌──────────────────────────────────────────────────┐ │
|
||||
│ │ Device Agent │ │
|
||||
│ │ (Memory-only WireGuard config) │ │
|
||||
│ └──────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Port Multiplexing
|
||||
|
||||
Server Core uses cmux to serve both HTTP and gRPC on port 8080:
|
||||
|
||||
```go
|
||||
m := cmux.New(lis)
|
||||
grpcLis := m.MatchWithWriters(cmux.HTTP2MatchHeaderFieldSendSettings(
|
||||
"content-type", "application/grpc",
|
||||
))
|
||||
httpLis := m.Match(cmux.Any())
|
||||
```
|
||||
|
||||
- gRPC matched by `content-type: application/grpc` header
|
||||
- HTTP matched by `Any()` (catch-all)
|
||||
- Single port, single listener, zero extra config
|
||||
Reference in New Issue
Block a user