# WireGuard Client Manager - Go TUI Implementation Plan

## Executive Summary

Converting the bash-based `wg-client-manager` to a modern, responsive Go TUI application using Bubble Tea and the Charm ecosystem. This will provide a better user experience with interactive forms, real-time status updates, and intuitive navigation.

## Technology Stack

### Core Framework
- **bubbletea** (v1.3.10) - Elm-architecture TUI framework
- **lipgloss** - Expressive styling and theming

### Component Libraries
- **huh** - Terminal forms for client creation
- **bubble-table** - Interactive table for client list
- **bubbles** - Text input and other UI components
- **qrterminal** - QR code generation for terminal display

### Go Modules
- WireGuard Go library (if available) or exec-based wrapper
- Configuration management (Viper or native config)
- File system operations (os, path/filepath)

## Functional Requirements Analysis

### Commands to Implement

| Command | Current Behavior | TUI Implementation |
|---------|-----------------|-------------------|
| **add** | Interactive prompts or WGI_ env vars | Form modal with fields: name, DNS, PSK option |
| **remove** | Command-line with confirmation | Select from list → Confirm modal → Delete |
| **list** | Table view with status | Interactive table with sorting, filtering |
| **show** | Display client config | Detail view with copyable sections |
| **qr** | Display QR code | Inline QR code in modal |

### Key Features

#### 1. Client Management
- **Add client**
  - Name input (regex validation: `[a-zA-Z0-9_-]+`, max 64 chars)
  - Optional DNS configuration
  - PSK toggle (yes/no)
  - Auto-assign IPv4/IPv6 addresses
  - Generate client keys
  - Create server and client configs
  - Generate QR code

- **Remove client**
  - Select from list
  - Confirmation dialog
  - Remove config files
  - Reload WireGuard

- **List clients**
  - Table view: Name, IPv4, IPv6, Status (Connected/Disconnected)
  - Sorting by column
  - Filtering/search
  - Real-time status refresh

- **Show client details**
  - Full configuration display
  - Copy to clipboard functionality
  - Status information (last handshake, transfer stats)

- **QR code display**
  - ANSI-colored QR code in terminal
  - Toggle fullscreen/inline mode

#### 2. Configuration Loading
- Read `/etc/wg-admin/config.conf`
- Environment variable support
- Validation of required settings (SERVER_DOMAIN, WG_PORT, etc.)

#### 3. Validation
- Client name format
- IP availability checks
- DNS server format validation
- Pre-install checks (WireGuard installed, config exists)

#### 4. Security
- Run as root required
- Proper file permissions (0600 for keys)
- Atomic config writes
- Temporary key cleanup

#### 5. Backup & Recovery
- Auto-backup before add/remove
- Config backup/restore functionality

## Architecture Design

### Package Structure

```
wg-admin-tui/
├── cmd/
│   └── main.go              # Entry point
├── internal/
│   ├── config/
│   │   ├── config.go        # Configuration loading
│   │   └── defaults.go      # Default values
│   ├── wireguard/
│   │   ├── client.go        # Client management
│   │   ├── keys.go          # Key generation
│   │   ├── config.go        # WireGuard config parsing
│   │   └── status.go        # Status monitoring
│   ├── tui/
│   │   ├── app.go           # Main TUI application
│   │   ├── model.go         # Application state
│   │   ├── update.go        # Message handlers
│   │   ├── view.go          # Rendering
│   │   ├── screens/
│   │   │   ├── list.go      # Client list view
│   │   │   ├── add.go       # Add client form
│   │   │   ├── detail.go    # Client detail view
│   │   │   └── qr.go        # QR code view
│   │   ├── components/
│   │   │   ├── table.go     # Client table
│   │   │   ├── statusbar.go # Status bar
│   │   │   └── modal.go     # Modal dialogs
│   │   └── theme/
│   │       ├── colors.go    # Color scheme
│   │       └── style.go     # Styling utilities
│   ├── validation/
│   │   ├── client.go        # Client name validation
│   │   ├── network.go       # IP/DNS validation
│   │   └── config.go        # Config syntax validation
│   └── backup/
│       ├── backup.go        # Backup operations
│       └── restore.go       # Restore operations
├── pkg/
│   └── util/
│       ├── exec.go          # Command execution helpers
│       └── file.go          # File operations
└── go.mod
```

### Component Design

#### 1. Main Application (app.go)
```go
type Application struct {
    model     Model
    programs  *tea.Program
    config    *config.Config
    wireguard *wireguard.Client
}

func NewApplication() (*Application, error)
func (a *Application) Run() error
```

#### 2. Model (model.go)
```go
type Model struct {
    screen      Screen          // Current active screen
    clients     []Client        // Client data
    selected    int             // Selected client
    loading     bool            // Loading state
    error       error           // Error message
    table       table.Model     // Client table
    form        *huh.Form       // Add client form
    modal       *Modal          // Active modal
    status      Status          // Status bar state
}

type Screen interface {
    Init() tea.Cmd
    Update(msg tea.Msg) (Screen, tea.Cmd)
    View() string
}
```

#### 3. Screens
- **ListScreen**: Display client table
- **AddScreen**: Form for adding client
- **DetailScreen**: Show client configuration
- **QRScreen**: Display QR code

#### 4. WireGuard Integration
```go
type Client struct {
    Name       string
    IPv4       string
    IPv6       string
    PublicKey  string
    HasPSK     bool
    Status     ConnectionStatus
    LastSeen   time.Time
    Handshake  string
    ConfigPath string
}

type Manager interface {
    ListClients() ([]Client, error)
    AddClient(name, dns string, usePSK bool) (*Client, error)
    RemoveClient(name string) error
    GetClient(name string) (*Client, error)
    GetStatus() (Status, error)
    ReloadConfig() error
}
```

## Implementation Roadmap

### Phase 1: Project Setup & Foundation (Days 1-2)

**Goal**: Establish project structure and core framework

**Tasks**:
- [ ] Initialize Go module
- [ ] Set up project structure
- [ ] Add dependencies (bubbletea, lipgloss, huh, bubble-table, qrterminal)
- [ ] Create configuration loading from `/etc/wg-admin/config.conf`
- [ ] Implement root check
- [ ] Create basic TUI skeleton with empty screens
- [ ] Set up logging (both file and console)

**Deliverables**:
- Working TUI that launches and shows a placeholder screen
- Configuration system in place

### Phase 2: Client List View (Days 3-4)

**Goal**: Display clients in interactive table

**Tasks**:
- [ ] Implement WireGuard client list parsing
- [ ] Create `Client` struct
- [ ] Set up bubble-table with columns: Name, IPv4, IPv6, Status
- [ ] Parse client configs from `/etc/wireguard/conf.d/client-*.conf`
- [ ] Check connection status using `wg show`
- [ ] Implement keyboard navigation (j/k, arrows, Enter, q)
- [ ] Add status bar with help text
- [ ] Implement auto-refresh (every 30 seconds)

**Deliverables**:
- Functional client list with real-time status

### Phase 3: Add Client Form (Days 5-6)

**Goal**: Create interactive form for adding clients

**Tasks**:
- [ ] Create add screen with `huh` form
- [ ] Implement fields:
  - Client name (text input)
  - DNS servers (text input with default)
  - Use PSK (toggle/confirm)
- [ ] Add validation:
  - Client name regex
  - IP availability check
  - DNS format validation
- [ ] Implement WireGuard key generation
- [ ] Auto-assign IPv4/IPv6 addresses
- [ ] Create server config file
- [ ] Create client config file
- [ ] Generate QR code
- [ ] Implement atomic config writes
- [ ] Auto-backup before add
- [ ] Reload WireGuard config

**Deliverables**:
- Working add client form with all validations

### Phase 4: Client Detail View (Days 7-8)

**Goal**: Show full client configuration

**Tasks**:
- [ ] Create detail screen
- [ ] Display:
  - Client name
  - IP addresses
  - Public key
  - Full configuration
  - Connection status
  - Last handshake
  - Transfer stats (Rx/Tx)
- [ ] Implement copy to clipboard
- [ ] Add "Back" and "Delete" buttons
- [ ] Delete confirmation modal
- [ ] Remove client with config deletion
- [ ] Auto-backup before remove
- [ ] Reload WireGuard config

**Deliverables**:
- Functional detail view with delete capability

### Phase 5: QR Code Display (Days 9-10)

**Goal**: Display QR codes for mobile setup

**Tasks**:
- [ ] Create QR screen
- [ ] Read client config
- [ ] Generate QR code using `qrterminal`
- [ ] Display QR code inline
- [ ] Implement fullscreen QR mode
- [ ] Add resize handling for QR codes
- [ ] Test with various terminal sizes

**Deliverables**:
- Working QR code display

### Phase 6: Polish & UX Improvements (Days 11-12)

**Goal**: Improve user experience

**Tasks**:
- [ ] Add color themes
- [ ] Implement modal dialogs for confirmations
- [ ] Add toast notifications for success/error
- [ ] Implement search/filter clients
- [ ] Add sorting by columns
- [ ] Improve error messages with actionable guidance
- [ ] Add keyboard shortcuts help
- [ ] Implement loading indicators

**Deliverables**:
- Polished, user-friendly interface

### Phase 7: Backup & Recovery (Days 13-14)

**Goal**: Add backup and restore functionality

**Tasks**:
- [ ] Implement backup operations
- [ ] Create restore functionality
- [ ] Add backup history view
- [ ] Implement retention policy
- [ ] Add backup/restore screens

**Deliverables**:
- Complete backup/restore system

## User Experience Design

### Screen Flow

```
┌─────────────────────────────────────┐
│         Client List (Main)          │
│  ┌─────┬─────┬──────────┬─────────┐│
│  │Name │IPv4 │  IPv6    │ Status  ││
│  ├─────┼─────┼──────────┼─────────┤│
│  │laptop│ .2 │ ::2      │Connected││ ← Selected
│  │phone │ .3 │ ::3      │  Disc   ││
│  └─────┴─────┴──────────┴─────────┘│
│                                     │
│ [a] Add  [d] Detail  [?] Help  [q] Quit│
└─────────────────────────────────────┘
              ↓ Enter
┌─────────────────────────────────────┐
│       Client Detail: laptop          │
│                                     │
│  Name: laptop                        │
│  IPv4: 10.10.69.2                   │
│  IPv6: fd69:dead:beef:69::2        │
│  Status: Connected                   │
│  Last Handshake: 2m ago             │
│  Rx: 1.2 MB  Tx: 3.4 MB            │
│                                     │
│  [Interface]                        │
│  PrivateKey = ...                    │
│  Address = 10.10.69.2/24...         │
│                                     │
│  [ESC] Back  [x] Delete  [c] Copy  │
└─────────────────────────────────────┘
              ↓ 'a' from list
┌─────────────────────────────────────┐
│          Add New Client              │
│                                     │
│  Client Name: [_________]           │
│  DNS Servers: [8.8.8.8, 8.8.4.4]   │
│  Use PSK? [x] Yes                  │
│                                     │
│  [Enter] Submit  [ESC] Cancel       │
└─────────────────────────────────────┘
              ↓ 'q' from detail
┌─────────────────────────────────────┐
│         Delete Confirmation         │
│                                     │
│  Delete client 'laptop'?           │
│                                     │
│  [Enter] Yes  [ESC] No             │
└─────────────────────────────────────┘
```

### Keyboard Shortcuts

| Key | Action |
|-----|--------|
| `q` | Quit |
| `a` | Add client |
| `d` | Show details |
| `x` | Delete |
| `r` | Refresh |
| `/` | Search/filter |
| `↑/k` | Move up |
| `↓/j` | Move down |
| `Enter` | Select/Confirm |
| `Esc` | Back/Cancel |
| `?` | Help |
| `c` | Copy to clipboard |

### Color Scheme

```go
// Default theme
const (
    ColorPrimary   lipgloss.Color
    ColorSecondary lipgloss.Color
    ColorSuccess   lipgloss.Color
    ColorWarning   lipgloss.Color
    ColorError     lipgloss.Color
    ColorMuted     lipgloss.Color
)

// Example
ColorPrimary   = lipgloss.Color("#007AFF")   // Blue
ColorSuccess   = lipgloss.Color("#34C759")   // Green
ColorWarning   = lipgloss.Color("#FF9500")   // Orange
ColorError     = lipgloss.Color("#FF3B30")   // Red
ColorMuted     = lipgloss.Color("#8E8E93")   // Gray
```

## Error Handling Strategy

### Validation Errors
- Display inline validation messages
- Show specific error with action guidance
- Keep form state on error
- Highlight invalid fields

### System Errors
- Show modal with error message
- Log full error to file
- Provide actionable guidance
- Offer retry or cancel options

### Examples
```
ERROR: Client 'laptop' already exists
Action: Choose a different name or remove existing client first

ERROR: No available IPv4 addresses
Action: Remove unused clients or expand VPN range
```

## Performance Considerations

1. **Lazy Loading**
   - Load clients on screen init
   - Cache client data between refreshes

2. **Asynchronous Operations**
   - Run WireGuard status checks in background
   - Use tea.Cmd for async operations

3. **Throttled Refresh**
   - Auto-refresh every 30 seconds (configurable)
   - Manual refresh with 'r' key

4. **QR Code Optimization**
   - Generate on demand, not cached
   - Use appropriate error correction level

## Security Considerations

1. **Root Privileges**
   - Check for root at startup
   - Display clear error if not root

2. **Key Storage**
   - Write keys with 0600 permissions
   - Clean up temporary key files

3. **Atomic Operations**
   - Write to temp file, then move
   - Prevent config corruption

4. **Input Validation**
   - Strict regex for client names
   - IP availability checks
   - DNS format validation

## Testing Strategy

### Unit Tests
- Validation functions
- Configuration parsing
- Client model methods

### Integration Tests
- WireGuard config generation
- Key generation
- Backup/restore

### Manual Testing
- End-to-end workflows
- Terminal size handling
- Error scenarios

## Milestones

| Milestone | Days | Goal |
|-----------|------|------|
| M1: Foundation | 2 | Project setup, basic TUI |
| M2: List View | 4 | Client list with status |
| M3: Add Client | 6 | Working add form |
| M4: Detail & Delete | 8 | Full client management |
| M5: QR Codes | 10 | QR code display |
| M6: Polish | 12 | UX improvements |
| M7: Complete | 14 | Fully functional TUI |

## Success Criteria

- ✅ All bash functionality replicated in TUI
- ✅ Responsive and performant UI
- ✅ Clear error messages with actionable guidance
- ✅ Keyboard shortcuts for all actions
- ✅ Real-time client status updates
- ✅ Working QR code generation
- ✅ Backup/restore functionality
- ✅ Polished, intuitive user experience

## Future Enhancements

- Config import/export
- Client statistics dashboard
- Connection monitoring view
- Multiple server support
- Template-based client creation
- Bulk operations
- Dark/Light theme toggle

---

**Estimated Timeline**: 14 days for MVP
**Primary Dependencies**: bubbletea, lipgloss, huh, bubble-table, qrterminal
**Minimum Go Version**: 1.21+
**Target Terminal**: ANSI-compatible terminals (Linux, macOS, Windows with WSL)