# 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 ```go // 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 ```go 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 ```go 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 ```go // 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.