docs: add NexusGuard portfolio (architecture, tech-stack, features, deployment)

2026-06-21 14:25:33 +07:00
parent a485c8df42
commit d6c53f6f86
6 changed files with 1358 additions and 0 deletions
@@ -0,0 +1,134 @@
+# Technology Stack
+
+NexusGuard uses a modern, production-grade technology stack. Each component is built with tools optimized for its domain.
+
+## Backend — Server Core
+
+| Technology | Version | Purpose |
+|------------|---------|---------|
+| Go | 1.25+ | Primary language |
+| Gin | 1.12 | HTTP framework |
+| GORM | 1.31 | ORM (PostgreSQL) |
+| grpc-go | latest | gRPC signaling |
+| cmux | latest | Port multiplexing (HTTP + gRPC on :8080) |
+| go-redis | 9.x | Heartbeat TTL cache |
+| google/nftables | 0.3 | Linux firewall management |
+| wgctrl | latest | WireGuard interface control |
+| JWT v5 | latest | Authentication tokens |
+
+### Why Go?
+
+- **Static binaries** — No runtime dependencies, easy deployment
+- **Concurrency** — Goroutines for handling 10000+ concurrent agent connections
+- **WireGuard ecosystem** — Native Go WireGuard libraries (wgctrl, wireguard-go)
+- **Performance** — Low memory footprint, fast cold start
+
+### Why cmux?
+
+Single port for HTTP and gRPC eliminates:
+- Firewall rules for multiple ports
+- Load balancer complexity
+- Docker port mapping overhead
+
+## Frontend — Dashboard UI
+
+| Technology | Version | Purpose |
+|------------|---------|---------|
+| Vue | 3.5 | UI framework (Composition API) |
+| Vite | 8 | Build tool + dev server |
+| TypeScript | 6.0 | Type safety |
+| TailwindCSS | 4.3 | Styling (glassmorphism design system) |
+| Pinia | 2.3 | State management |
+| Axios | 1.16 | HTTP client |
+| HeadlessUI | 1.7 | Accessible UI primitives |
+| Iconify | 5.0 | Icon system |
+| VueUse | 14.3 | Composition utilities |
+
+### Why Vue 3?
+
+- **Composition API** — Better TypeScript support, reusable logic via composables
+- **`<script setup>`** — Cleaner SFC syntax, less boilerplate
+- **Ecosystem** — Mature ecosystem with Pinia, Vue Router, VueUse
+
+### Why TailwindCSS 4?
+
+- **Design tokens** — `@theme` block for consistent colors, spacing, typography
+- **Glassmorphism** — Utility classes for backdrop-blur, transparency, gradients
+- **No PostCSS** — Uses `@tailwindcss/vite` plugin (faster builds)
+
+## Client — Device Agent
+
+| Technology | Version | Purpose |
+|------------|---------|---------|
+| Go | 1.25+ | Primary language |
+| wireguard-go | latest | Userspace WireGuard |
+| fyne.io/systray | latest | Cross-platform system tray |
+| wintun | latest | Windows WireGuard driver |
+
+### Cross-Compile Targets
+
+| Platform | Architecture | Binary |
+|----------|--------------|--------|
+| Linux | amd64 | `nexusguard-device-agent-linux-amd64` |
+| Linux | arm64 | `nexusguard-device-agent-linux-arm64` |
+| Linux | arm | `nexusguard-device-agent-linux-arm` |
+| Windows | amd64 | `nexusguard-device-agent-gui.exe` |
+| macOS | arm64 | `nexusguard-device-agent-darwin-arm64` |
+| macOS | amd64 | `nexusguard-device-agent-darwin-amd64` |
+
+### Why Memory-Injected Tunnels?
+
+Traditional WireGuard setups write config to `/etc/wireguard/`. NexusGuard avoids this:
+
+1. **Security** — No config files on disk = no file theft risk
+2. **Stealth** — Tunnel exists only in process memory
+3. **Cleanup** — Process exit = tunnel gone (no lingering configs)
+4. **Multi-tenant** — Multiple agents can run without config conflicts
+
+## Infrastructure
+
+| Technology | Purpose |
+|------------|---------|
+| PostgreSQL | Primary database (wg_servers, devices, rules, users) |
+| Redis | Heartbeat TTL cache, session tracking |
+| nginx | Reverse proxy, SPA fallback, API routing |
+| Docker | Container orchestration |
+| docker-compose | Multi-service deployment |
+
+### Why PostgreSQL?
+
+- **ACID compliance** — Critical for IPAM allocation (no duplicate IPs)
+- **JSON support** — Flexible config storage
+- **Maturity** — Battle-tested for production workloads
+
+### Why Redis?
+
+- **Heartbeat TTL** — Fast expiry checks for agent health
+- **Session cache** — gRPC session tracking
+- **Pub/Sub** — Real-time event distribution (future)
+
+## Build & CI
+
+| Tool | Purpose |
+|------|---------|
+| Go build | Static binary compilation |
+| Vite build | SPA bundling (vue-tsc + vite) |
+| Gitea Actions | CI/CD per submodule |
+| Makefile | Quick commands (up, down, dev, migrate) |
+
+### Build Flags
+
+```bash
+# Server Core (production)
+CGO_ENABLED=0 go build -o server-core .
+
+# Device Agent (stripped)
+go build -ldflags="-s -w" -o device-agent .
+
+# Dashboard UI
+VITE_API_BASE_URL=/api/v1 npm run build
+```
+
+- `CGO_ENABLED=0` — Static binary, no CGO dependencies
+- `-ldflags="-s -w"` — Strip debug symbols (~30% smaller binary)
+- `VITE_API_BASE_URL` — Build-time API endpoint injection