# Buque Project Structure

```
buque/
├── cmd/
│   └── buque/
│       └── main.go                    # Application entry point
│
├── internal/
│   ├── cmd/                           # CLI command implementations
│   │   ├── root.go                    # Root command and initialization
│   │   ├── init.go                    # Initialize command
│   │   ├── env.go                     # Environment management commands
│   │   ├── compose.go                 # Docker Compose operations (up/down/restart/update)
│   │   ├── stats.go                   # Statistics display command
│   │   ├── logs.go                    # Log viewing and container listing
│   │   ├── proxy.go                   # Nginx-proxy management commands
│   │   └── utils.go                   # Utility functions
│   │
│   ├── config/
│   │   └── config.go                  # Configuration management
│   │
│   ├── docker/
│   │   ├── client.go                  # Docker API client wrapper
│   │   └── compose.go                 # Docker Compose manager
│   │
│   ├── models/
│   │   └── models.go                  # Data structures
│   │
│   ├── proxy/
│   │   └── nginx.go                   # Nginx-proxy deployment and management
│   │
│   └── stats/
│       └── collector.go               # Container statistics collection
│
├── examples/
│   ├── config.example.yaml            # Example configuration file
│   ├── docker-compose.example.yml     # Basic docker-compose example
│   ├── docker-compose.multi-service.yml  # Multi-service example
│   └── example_usage.go               # Go library usage example
│
├── docs/
│   ├── QUICK_START.md                 # Quick start guide
│   └── DOCKER_SETUP.md                # Docker installation guide
│
├── scripts/
│   └── demo.sh                        # Interactive demo script
│
├── .github/
│   └── workflows/
│       └── ci.yml                     # GitHub Actions CI workflow
│
├── .gitignore                         # Git ignore rules
├── CHANGELOG.md                       # Version history
├── CONTRIBUTING.md                    # Contribution guidelines
├── LICENSE                            # MIT License
├── Makefile                           # Build automation
├── README.md                          # Main documentation
├── go.mod                             # Go module definition
├── go.sum                             # Go dependencies checksum
└── install.sh                         # Installation script
```

## Key Components

### Core Packages

#### `cmd/buque`
Main application entry point that initializes the CLI.

#### `internal/cmd`
Contains all CLI command implementations using the Cobra framework:
- Environment management (add, remove, list, enable, disable)
- Container operations (up, down, restart, update, pull)
- Monitoring and statistics
- Nginx-proxy management
- Logging and container listing

#### `internal/config`
Configuration management system that:
- Loads/saves YAML configuration
- Manages environment list
- Handles default settings
- Validates configuration

#### `internal/docker`
Docker integration layer:
- **client.go**: Direct Docker API interactions (containers, images, networks, stats)
- **compose.go**: Docker Compose command wrapper (up, down, pull, build, etc.)

#### `internal/models`
Data structures for:
- Environments
- Services/Containers
- Statistics
- Configuration
- Results and status

#### `internal/proxy`
Nginx-proxy management:
- Deployment automation
- Docker Compose file generation
- Network management
- SSL/Let's Encrypt configuration
- Service label generation

#### `internal/stats`
Container statistics collection:
- Real-time metrics (CPU, memory, network, disk)
- Aggregation across containers
- Continuous monitoring
- Sorting and formatting

## Features by File

### Configuration Management
- `internal/config/config.go`: Load, save, update configuration
- `examples/config.example.yaml`: Configuration template

### Environment Management
- `internal/cmd/env.go`: Add, remove, list, enable/disable environments
- `internal/models/models.go`: Environment data structure

### Container Operations
- `internal/cmd/compose.go`: Up, down, restart, update, pull commands
- `internal/docker/compose.go`: Docker Compose execution

### Monitoring
- `internal/cmd/stats.go`: Statistics display (continuous mode, sorting)
- `internal/stats/collector.go`: Metrics collection and aggregation
- `internal/docker/client.go`: Docker API for stats

### Nginx Proxy
- `internal/cmd/proxy.go`: Deploy, remove, status, example commands
- `internal/proxy/nginx.go`: Nginx-proxy setup and configuration

### Logging and Info
- `internal/cmd/logs.go`: View logs, list containers, prune resources

## Build System

### Makefile Targets
- `build`: Build the binary
- `install`: Install to $GOPATH/bin
- `test`: Run tests
- `fmt`: Format code
- `vet`: Run linter
- `clean`: Remove build artifacts
- `deps`: Download dependencies
- `build-all`: Build for multiple platforms

### Installation
- `install.sh`: Automated installation script
- Checks prerequisites (Go, Docker, Docker Compose)
- Builds and installs binary
- Verifies installation

## Documentation

### User Documentation
- `README.md`: Complete user guide with examples
- `docs/QUICK_START.md`: Quick reference guide
- `docs/DOCKER_SETUP.md`: Docker installation guide
- `CONTRIBUTING.md`: Contribution guidelines
- `CHANGELOG.md`: Version history

### Example Code
- `examples/example_usage.go`: Library usage examples
- `examples/*.yml`: Docker Compose templates
- `scripts/demo.sh`: Interactive demonstration

## Development

### CI/CD
- `.github/workflows/ci.yml`: GitHub Actions workflow
  - Runs tests
  - Builds for multiple platforms
  - Lints code

### Code Organization
- Clear separation of concerns
- Reusable components
- Testable architecture
- Idiomatic Go code

## Dependencies

### Main Dependencies
- `github.com/spf13/cobra`: CLI framework
- `github.com/docker/docker`: Docker client
- `gopkg.in/yaml.v3`: YAML parsing

### Build Tools
- Go 1.21+
- Make
- Git

## Usage Patterns

### As CLI Tool
Users interact through intuitive commands:
```bash
buque env add myapp /path/to/myapp
buque up myapp
buque stats --continuous
```

### As Library
Developers can import and use internal packages:
```go
import "github.com/yourusername/buque/internal/docker"

compose, _ := docker.NewComposeManager()
compose.Up(ctx, environment, true)
```

## Extension Points

### Adding New Commands
1. Create command file in `internal/cmd/`
2. Implement cobra.Command
3. Add to root command in `internal/cmd/root.go`

### Adding New Features
1. Update models in `internal/models/`
2. Implement business logic in appropriate package
3. Add CLI command to expose functionality
4. Update documentation

### Custom Statistics
Extend `internal/stats/collector.go` to add new metrics or aggregations.

### Custom Proxy Configurations
Modify `internal/proxy/nginx.go` to support different proxy setups.

## Testing Strategy

### Unit Tests
- Test individual functions and methods
- Mock Docker API calls
- Test configuration management

### Integration Tests
- Test with real Docker daemon
- Test compose operations
- Test proxy deployment

### Manual Testing
- Use `scripts/demo.sh` for manual verification
- Test on different platforms
- Verify documentation accuracy