docs: add NexusGuard portfolio (architecture, tech-stack, features, deployment)
This commit is contained in:
datadunia
@@ -0,0 +1,209 @@
|
||||
# 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
Block a user