edge-connect-client/project.md

Edge Connect Client - Project Analysis

Overview

The Edge Connect Client is a command-line interface (CLI) tool built in Go for managing Edge Connect applications and their instances. It provides a structured way to interact with Edge Connect APIs for creating, showing, listing, and deleting applications and application instances.

Project Structure

edge-connect-client/
├── .claude/                    # Claude Code configuration and commands
├── api/
│   └── swagger.json           # API specification (370KB)
├── client/                    # Core client library
│   ├── client.go             # HTTP client implementation
│   └── models.go             # Data models and types
├── cmd/                      # CLI command implementations
│   ├── root.go              # Root command and configuration
│   ├── app.go               # Application management commands
│   └── instance.go          # Instance management commands
├── main.go                  # Application entry point
├── go.mod                   # Go module definition
├── go.sum                   # Dependency checksums
├── README.md               # Documentation
├── config.yaml.example     # Configuration template
├── Dockerfile              # Empty container definition
└── .gitignore             # Git ignore rules

Architecture

Core Components

1. Main Entry Point (main.go)

• Simple entry point that delegates to the command package
• Follows standard Go CLI application pattern

2. Command Layer (cmd/)

• Root Command (root.go): Base command with global configuration

  • Uses Cobra for CLI framework
  • Uses Viper for configuration management
  • Supports config files, environment variables, and command-line flags
  • Configuration precedence: flags → env vars → config file

• App Commands (app.go): Application lifecycle management

  • Create, show, list, delete applications
  • Handles organization, name, version, and region parameters

• Instance Commands (instance.go): Instance lifecycle management

  • Create, show, list, delete application instances
  • Manages cloudlet assignments and flavors

3. Client Layer (client/)

• HTTP Client (client.go): Core API communication

  • Token-based authentication with login endpoint
  • Generic call() function for API requests
  • Structured error handling with custom ErrResourceNotFound
  • JSON-based request/response handling

• Models (models.go): Type definitions and data structures

  • Generic response handling with Responses[T] and Response[T]
  • Domain models: App, AppInstance, AppKey, CloudletKey, Flavor
  • Input types: NewAppInput, NewAppInstanceInput
  • Message interface for error handling

Configuration Management

• File-based: $HOME/.edge-connect.yaml (default) or custom via --config
• Environment Variables: Prefixed with EDGE_CONNECT_
  • EDGE_CONNECT_BASE_URL
  • EDGE_CONNECT_USERNAME
  • EDGE_CONNECT_PASSWORD
• Command-line Flags: Override other sources

Dependencies

Direct Dependencies

• Cobra v1.10.1: CLI framework for command structure and parsing
• Viper v1.21.0: Configuration management (files, env vars, flags)

Key Indirect Dependencies

• fsnotify: File system watching for config changes
• go-viper/mapstructure: Configuration unmarshaling
• pelletier/go-toml: TOML configuration support
• Standard Go libraries for HTTP, JSON, system operations

API Integration

Authentication Flow

1. Client sends username/password to /api/v1/login
2. Receives JWT token in response
3. Token included in Authorization: Bearer header for subsequent requests

API Endpoints

• /api/v1/auth/ctrl/CreateApp - Create applications
• /api/v1/auth/ctrl/ShowApp - Retrieve applications
• /api/v1/auth/ctrl/DeleteApp - Delete applications
• /api/v1/auth/ctrl/CreateAppInst - Create instances
• /api/v1/auth/ctrl/ShowAppInst - Retrieve instances
• /api/v1/auth/ctrl/DeleteAppInst - Delete instances

Response Handling

• Streaming JSON responses parsed line-by-line
• Generic type-safe response wrapper
• Comprehensive error handling with status codes
• Built-in logging for debugging

Key Features

Application Management

• Multi-tenant support with organization scoping
• Version-aware application handling
• Region-based deployments
• Configurable security rules and deployment options

Instance Management

• Cloudlet-based instance deployment
• Flavor selection for resource allocation
• Application-to-instance relationship tracking
• State and power state monitoring

Error Handling

• Custom error types (ErrResourceNotFound)
• HTTP status code awareness
• Detailed error messages with context
• Graceful handling of missing resources

Development Notes

Code Quality

• Clean separation of concerns (CLI/Client/Models)
• Generic programming for type safety
• Consistent error handling patterns
• Comprehensive logging for troubleshooting

Configuration

• Flexible configuration system supporting multiple sources
• Secure credential handling via environment variables
• Example configuration provided for easy setup

API Design

• RESTful API integration with structured endpoints
• Token-based security model
• Streaming response handling for efficiency
• Comprehensive swagger specification (370KB)

Missing Components

• Empty Dockerfile suggests containerization is planned but not implemented
• No tests directory - testing framework needs to be established
• No CI/CD configuration visible
• Limited error recovery and retry mechanisms

Potential Improvements

1. Testing: Implement unit and integration tests
2. Containerization: Complete Docker implementation
3. Retry Logic: Add resilient API call mechanisms
4. Configuration Validation: Validate config before use
5. Output Formatting: Add JSON/YAML output options
6. Caching: Implement token caching to reduce login calls