# 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