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