wild-cloud/CLI_ARCHITECTURE.md

Wild CLI - Go Architecture Design

Project Structure

wild-cli/
├── cmd/
│   └── wild/
│       ├── main.go                 # Main entry point
│       ├── root.go                 # Root command and global flags
│       ├── setup/                  # Setup commands
│       │   ├── setup.go            # Setup root command
│       │   ├── scaffold.go         # wild setup scaffold
│       │   ├── cluster.go          # wild setup cluster
│       │   └── services.go         # wild setup services
│       ├── app/                    # App management commands
│       │   ├── app.go              # App root command
│       │   ├── list.go             # wild app list
│       │   ├── fetch.go            # wild app fetch
│       │   ├── add.go              # wild app add
│       │   ├── deploy.go           # wild app deploy
│       │   ├── delete.go           # wild app delete
│       │   ├── backup.go           # wild app backup
│       │   ├── restore.go          # wild app restore
│       │   └── doctor.go           # wild app doctor
│       ├── cluster/                # Cluster management commands
│       │   ├── cluster.go          # Cluster root command
│       │   ├── config.go           # wild cluster config
│       │   ├── nodes.go            # wild cluster nodes
│       │   └── services.go         # wild cluster services
│       ├── config/                 # Configuration commands
│       │   ├── config.go           # Config root command
│       │   ├── get.go              # wild config get
│       │   └── set.go              # wild config set
│       ├── secret/                 # Secret management commands
│       │   ├── secret.go           # Secret root command
│       │   ├── get.go              # wild secret get
│       │   └── set.go              # wild secret set
│       └── util/                   # Utility commands
│           ├── backup.go           # wild backup
│           ├── dashboard.go        # wild dashboard
│           ├── template.go         # wild template
│           ├── status.go           # wild status
│           └── version.go          # wild version
├── internal/                       # Internal packages
│   ├── config/                     # Configuration management
│   │   ├── manager.go              # Config/secrets YAML handling
│   │   ├── template.go             # Template processing (gomplate)
│   │   ├── validation.go           # Schema validation
│   │   └── types.go                # Configuration structs
│   ├── kubernetes/                 # Kubernetes operations
│   │   ├── client.go               # K8s client management
│   │   ├── apply.go                # kubectl apply operations
│   │   ├── namespace.go            # Namespace management
│   │   └── resources.go            # Resource utilities
│   ├── talos/                      # Talos Linux operations
│   │   ├── config.go               # Talos config generation
│   │   ├── node.go                 # Node operations
│   │   └── client.go               # Talos client wrapper
│   ├── backup/                     # Backup/restore functionality
│   │   ├── restic.go               # Restic backup wrapper
│   │   ├── postgres.go             # PostgreSQL backup
│   │   ├── pvc.go                  # PVC backup
│   │   └── manager.go              # Backup orchestration
│   ├── apps/                       # App management
│   │   ├── catalog.go              # App catalog management
│   │   ├── fetch.go                # App fetching logic
│   │   ├── deploy.go               # Deployment logic
│   │   └── health.go               # Health checking
│   ├── environment/                # Environment detection
│   │   ├── paths.go                # WC_ROOT, WC_HOME detection
│   │   ├── nodes.go                # Node detection
│   │   └── validation.go           # Environment validation
│   ├── external/                   # External tool management
│   │   ├── kubectl.go              # kubectl wrapper
│   │   ├── talosctl.go             # talosctl wrapper
│   │   ├── yq.go                   # yq wrapper
│   │   ├── gomplate.go             # gomplate wrapper
│   │   ├── kustomize.go            # kustomize wrapper
│   │   └── restic.go               # restic wrapper
│   ├── output/                     # Output formatting
│   │   ├── formatter.go            # Output formatting
│   │   ├── progress.go             # Progress indicators
│   │   └── logger.go               # Structured logging
│   └── common/                     # Shared utilities
│       ├── errors.go               # Error handling
│       ├── validation.go           # Input validation
│       ├── files.go                # File operations
│       └── network.go              # Network utilities
├── pkg/                            # Public packages
│   └── wildcloud/                  # Public API (if needed)
│       └── client.go               # SDK for other tools
├── test/                           # Test files
│   ├── integration/                # Integration tests
│   ├── fixtures/                   # Test fixtures
│   └── mocks/                      # Mock implementations
├── scripts/                        # Build and development scripts
│   ├── build.sh                    # Build script
│   ├── test.sh                     # Test runner
│   └── install.sh                  # Installation script
├── docs/                           # Documentation
│   ├── commands/                   # Command documentation
│   └── development.md              # Development guide
├── go.mod                          # Go module definition
├── go.sum                          # Go module checksums
├── Makefile                        # Build automation
├── README.md                       # Project README
└── LICENSE                         # License file

Core Architecture Principles

1. Cobra CLI Framework

• Root command with global flags (--config-dir, --verbose, --dry-run)
• Nested command structure mirroring the logical organization
• Consistent flag patterns across similar commands
• Auto-generated help and completion

2. Dependency Injection

• Interface-based design for external tools and K8s client
• Testable components through dependency injection
• Mock implementations for testing
• Configuration-driven tool selection

3. Error Handling Strategy

// Wrapped errors with context
func (m *Manager) ApplyApp(ctx context.Context, name string) error {
    if err := m.validateApp(name); err != nil {
        return fmt.Errorf("validating app %s: %w", name, err)
    }
    
    if err := m.kubernetes.Apply(ctx, appPath); err != nil {
        return fmt.Errorf("applying app %s to cluster: %w", name, err)
    }
    
    return nil
}

4. Configuration Management

type ConfigManager struct {
    configPath  string
    secretsPath string
    template    *template.Engine
}

type Config struct {
    Cluster struct {
        Name     string `yaml:"name"`
        Domain   string `yaml:"domain"`
        VIP      string `yaml:"vip"`
        Nodes    []Node `yaml:"nodes"`
    } `yaml:"cluster"`
    
    Apps map[string]AppConfig `yaml:"apps"`
}

5. External Tool Management

type ExternalTool interface {
    IsInstalled() bool
    Version() (string, error)
    Execute(ctx context.Context, args ...string) ([]byte, error)
}

type KubectlClient struct {
    binary string
    config string
}

func (k *KubectlClient) Apply(ctx context.Context, file string) error {
    args := []string{"apply", "-f", file}
    if k.config != "" {
        args = append([]string{"--kubeconfig", k.config}, args...)
    }
    
    _, err := k.Execute(ctx, args...)
    return err
}

Key Features & Improvements

1. Enhanced User Experience

• Progress indicators for long-running operations
• Interactive prompts for setup and configuration
• Colored output for better readability
• Shell completion for commands and flags

2. Better Error Handling

• Contextualized errors with suggestion for fixes
• Validation before execution to catch issues early
• Rollback capabilities for failed operations
• Detailed error reporting with troubleshooting tips

3. Parallel Operations

• Concurrent node operations during cluster setup
• Parallel app deployments where safe
• Background status monitoring during operations

4. Cross-Platform Support

• Abstracted file paths using filepath package
• Platform-specific executables (kubectl.exe on Windows)
• Docker fallback for missing tools

5. Testing Infrastructure

• Unit tests for all business logic
• Integration tests with real Kubernetes clusters
• Mock implementations for external dependencies
• Benchmark tests for performance-critical operations

Implementation Strategy

Phase 1: Foundation (Week 1-2)

1. Project structure - Set up Go module and directory structure
2. Core interfaces - Define interfaces for external tools and K8s
3. Configuration management - Implement config/secrets handling
4. Basic commands - Implement wild config and wild secret commands

Phase 2: App Management (Week 3-4)

1. App catalog - Implement app listing and fetching
2. App deployment - Core deployment logic with Kustomize
3. App lifecycle - Add, deploy, delete commands
4. Health checking - Basic app health validation

Phase 3: Cluster Operations (Week 5-6)

1. Setup commands - Scaffold, cluster, services setup
2. Node management - Node detection and configuration
3. Service deployment - Infrastructure services deployment

Phase 4: Advanced Features (Week 7-8)

1. Backup/restore - Implement restic-based backup system
2. Progress tracking - Add progress indicators and status reporting
3. Error recovery - Implement rollback and retry mechanisms
4. Documentation - Generate command documentation

Technical Considerations

Dependencies

// Core dependencies
github.com/spf13/cobra       // CLI framework
github.com/spf13/viper       // Configuration management
k8s.io/client-go             // Kubernetes client
k8s.io/apimachinery          // Kubernetes types
sigs.k8s.io/yaml             // YAML processing

// Utility dependencies
github.com/fatih/color       // Colored output
github.com/schollz/progressbar/v3  // Progress bars
github.com/manifoldco/promptui     // Interactive prompts
go.uber.org/zap              // Structured logging

Build & Release

• Multi-platform builds using GitHub Actions
• Automated testing on Linux, macOS, Windows
• Release binaries for major platforms
• Installation script for easy setup
• Homebrew formula for macOS users

This architecture provides a solid foundation for migrating Wild Cloud's functionality to Go while adding modern CLI features and maintaining the existing workflow.