nexusguard/Nexus-Guard-Suite
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 6 Wiki Activity
Files
d6610f82e9c694d7bcbcc4b44d95d8edb0181bff
Nexus-Guard-Suite/docs/superpowers/specs/2026-06-21-nexusguard-portfolio-design.md
T

6.7 KiB
Raw Blame History

NexusGuard Portfolio Design Spec

Date: 2026-06-21 Status: Draft Author: Sisyphus

Overview

Create a comprehensive technical portfolio for the NexusGuard SD-WAN Suite project, showcasing architecture, technology stack, features, and deployment options. Target audience: technical recruiters, potential clients, and fellow developers.

Goals

  1. Present NexusGuard as a production-grade enterprise SD-WAN solution
  2. Highlight unique selling points (zero-trust, stealth agent, memory-injected tunnels)
  3. Provide clear architecture overview for technical audience
  4. Document technology choices and reasoning
  5. Showcase deployment flexibility (Docker, native, development)

Scope

In Scope

  • Multi-file Markdown portfolio in docs/portfolio/
  • 5 files: README, architecture, tech-stack, features, deployment
  • ASCII/text-based diagrams (no external dependencies)
  • Internal navigation links between files
  • Focus on technical depth over marketing fluff

Out of Scope

  • Interactive VitePress integration (future enhancement)
  • Screenshots/demo embeds (requires running instances)
  • Video content
  • Multi-language support (Indonesian/English)

Design Decisions

File Structure

docs/portfolio/
├── README.md           # Landing page / entry point
├── architecture.md     # System architecture + diagrams
├── tech-stack.md       # Technology breakdown per component
├── features.md         # Feature showcase
└── deployment.md       # Deployment guide

Diagram Style

Use ASCII/text-based diagrams for portability and version control friendliness. Examples:

┌──────────────┐         ┌─────────────────┐         ┌──────────────┐
│  Dashboard   │──HTTP──▶│  Server Core    │◀─WG────▶│ Device Agent │
│  (Vue 3)     │  :8080  │  (Go/Gin)       │  :51820 │  (Go)        │
└──────────────┘         └─────────────────┘         └──────────────┘

Content Tone

Technical and precise. Avoid marketing buzzwords. Focus on:

  • What it does (functional description)
  • How it works (architecture/implementation)
  • Why these choices (technology rationale)

File Specifications

1. README.md (Landing Page)

Purpose: Quick overview, entry point to other sections

Content:

  • Project name + tagline: "Enterprise Zero-Trust SD-WAN with WireGuard"
  • 2-3 sentence description
  • Key highlights (3-4 bullet points):
    • Zero-attack surface (no public registration)
    • Stealth agent (memory-injected, no disk files)
    • Real-time nftables isolation
    • Cross-platform (Linux, Windows, macOS)
  • Tech badges: Go, Vue 3, WireGuard, PostgreSQL, Docker
  • Navigation links to other portfolio files

Length: ~100 lines

2. architecture.md (System Architecture)

Purpose: Technical deep-dive into system design

Content:

  • High-level architecture diagram (ASCII)
  • Component breakdown:
    • Server Core: API, gRPC signaling, IPAM, firewall, WireGuard management
    • Dashboard UI: Management interface, glassmorphism design
    • Device Agent: Stealth daemon, multi-platform, self-healing
  • Data flow:
    • Provisioning flow (HTTP → AES-256-GCM → memory injection)
    • Heartbeat flow (HTTP/gRPC, config sync, handshake monitoring)
    • Suspend/Resume flow (gRPC command → tunnel control)
  • Security model:
    • Zero-trust (admin CLI only, no public register)
    • Encrypted provisioning (AES-256-GCM)
    • Fileless tunnels (WireGuard config in RAM)
    • Hardware binding (HWID detection)

Length: ~250 lines

3. tech-stack.md (Technology Breakdown)

Purpose: Detailed technology choices per component

Content:

  • Backend (Server Core):
    • Go 1.25+, Gin framework, GORM ORM
    • PostgreSQL, Redis
    • grpc-go + cmux (port multiplexing)
    • nftables (google/nftables), WireGuard (wgctrl)
  • Frontend (Dashboard UI):
    • Vue 3.5 (Composition API, <script setup>)
    • Vite 8, TypeScript 6.0
    • TailwindCSS 4.3 (glassmorphism design system)
    • Pinia 2.3, Axios 1.16, HeadlessUI 1.7
  • Client (Device Agent):
    • Go 1.25+, fyne.io/systray
    • WireGuard (memory-injected via IpcSet)
    • Cross-compile targets: linux/amd64, arm64, arm; windows/amd64; darwin/arm64, amd64
  • Infrastructure:
    • PostgreSQL, Redis, nginx
    • Docker + docker-compose
    • Gitea Actions (CI/CD)

Length: ~200 lines

4. features.md (Feature Showcase)

Purpose: Highlight key capabilities

Content:

  • Zero-Trust Security:
    • No public registration (admin CLI only)
    • AES-256-GCM encrypted provisioning
    • Memory-injected WireGuard (no /etc/wireguard/ files)
    • Hardware ID binding (HWID)
  • Multi-Node Support:
    • Geographic scaling (multiple WG servers)
    • Centralized IPAM (IP pool allocation per node)
    • Per-node peer defaults
  • Real-time Firewall:
    • nftables integration (Linux kernel)
    • Per-peer rules (IP/CIDR + port ranges)
    • Instant sync to kernel (no restart)
  • Cross-Platform Agent:
    • Linux (systemd daemon)
    • Windows (system tray + service)
    • macOS (system tray)
    • Self-healing (exponential backoff reconnection)
  • Dashboard:
    • Futuristic glassmorphism UI
    • Live telemetry (10s polling)
    • QR code for mobile setup
    • Time-limited share links
  • Deployment Flexibility:
    • Docker (recommended)
    • Native install (systemd + nginx)
    • Development mode (hot-reload)

Length: ~200 lines

5. deployment.md (Deployment Guide)

Purpose: Practical deployment instructions

Content:

  • Docker (Recommended):
    • Quick start (setup.sh + update.sh)
    • Configuration (.env)
    • Makefile commands (up, down, logs, dev, migrate, reset-db)
  • Native Install:
    • Prerequisites (Go, Node.js, PostgreSQL, Redis, nginx, nftables, wireguard-tools)
    • Build binaries
    • Run installer (nexusguard-install.sh)
    • Create admin account
  • Development:
    • Local setup (database + .env)
    • Hot-reload (go run -tags dev, npm run dev)
    • Database migration
  • Agent Installation:
    • Linux (automated install_agent.sh)
    • Windows (manual + service setup)
    • Docker container

Length: ~250 lines

Success Criteria

  1. All 5 files created in docs/portfolio/
  2. Each file is self-contained (can be read independently)
  3. Internal links work between files
  4. ASCII diagrams render correctly in Markdown viewers
  5. Content is accurate and matches actual codebase
  6. No broken links or references

Implementation Notes

  • Use existing README content as base (avoid duplication)
  • Extract key information from AGENTS.md files
  • Verify technical details against actual code
  • Keep diagrams simple and readable
  • Use consistent Markdown formatting across all files
Reference in New Issue View Git Blame Copy Permalink