buque/docs/PROJECT_STRUCTURE.md

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:

buque env add myapp /path/to/myapp
buque up myapp
buque stats --continuous

As Library

Developers can import and use internal packages:

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