Nexus-Guard-Suite/docs/superpowers/specs/2026-06-21-nexusguard-portfolio-design.md

# 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