hello-go - Clean Architecture Project

A Go application following Clean Architecture principles (Uncle Bob's style) with Domain-Driven Design (DDD). This project demonstrates best practices for building maintainable, testable, and scalable Go applications.

🏗️ Architecture

This project follows Clean Architecture with clear separation of concerns:

• Domain Layer: Business entities and interfaces (no dependencies)
• Use Case Layer: Application business logic
• Repository Layer: Data persistence implementations
• Delivery Layer: HTTP handlers and routing

🚀 Quick Start

New Developer Setup

# Complete project setup (creates .env, installs deps)
make setup

# Start development server with hot reloading
make dev

# Verify everything works
make test

Development Commands

# Start development server
make dev

# Run tests with coverage
make test-coverage

# Build for all platforms  
make build

# Format and lint code
make check

# View all available commands
make help

📁 Project Structure

├── cmd/app/                   # Application entry point
├── internal/                  # Private application code
│   ├── domain/               # Domain layer (entities, interfaces)
│   ├── usecase/              # Use case layer (business logic)
│   ├── repository/           # Repository implementations
│   └── delivery/http/        # HTTP delivery layer
├── pkg/                      # Public shared packages
├── configs/                  # Configuration management
├── test/integration/         # Integration tests
├── scripts/                  # Development scripts
├── deployments/              # Docker and deployment configs
└── docs/                     # Documentation

🔧 Environment Configuration

Setup Environment File

# Create .env from template
make env-setup

# Check current environment
make env-check

# Reset .env file (overwrites existing)
make env-reset

Required Environment Variables

APP_NAME=hello-go
ENVIRONMENT=development
DEBUG=true
PORT=8080
HOST=localhost

See docs/ENVIRONMENT.md for complete configuration guide.

🧪 Testing

Test Commands

# All tests
make test

# Unit tests only
make test-unit

# Integration tests only
make test-integration

# Tests with coverage report
make test-coverage

# Race condition detection
make test-race

# Benchmark tests
make test-bench

Coverage

• Overall Coverage: 95.5%
• Domain Layer: 100%
• Use Case Layer: 100%
• Repository Layer: 100%
• Delivery Layer: 90.4%

🔒 Security

Comprehensive Security Analysis

The project features enterprise-grade security scanning with 5 security layers:

# Complete security analysis
make security

Security Features:

• 🛡️ Static Analysis - 50+ security patterns via gosec
• 🔍 Vulnerability Detection - CVE scanning with govulncheck
• 📦 Dependency Audit - Supply chain security
• 🔐 Secret Detection - Prevents credential leaks
• 📜 License Compliance - Legal and security compliance

Security Highlights

• Zero Security Issues - All gosec rules passing
• Cryptographically Secure - Uses crypto/rand for ID generation
• No Known Vulnerabilities - Clean vulnerability scan
• Secure Dependencies - All modules verified
• Environment Security - Proper secret management

Individual Security Commands

make security-gosec        # Static security analysis
make security-vulncheck    # Vulnerability scanning
make security-deps         # Dependency security audit
make security-secrets      # Secret pattern detection
make security-licenses     # License compliance check
make security-report       # Generate detailed reports

📋 Repository Management

.gitignore Improvements

The project features a comprehensive .gitignore with 350+ patterns organized into 11 sections:

# Test .gitignore patterns
make gitignore-test

# Validate .gitignore effectiveness
make gitignore-validate

Key Features:

• 🔒 Security-focused - Prevents credential leaks
• 🛠️ Development tools - Covers all major IDEs and tools
• 🌐 Cross-platform - Windows, macOS, Linux patterns
• ☁️ Cloud-ready - AWS, GCP, Azure, Terraform patterns
• 📊 Monitoring - Profiling and metrics artifacts
• 🐳 Containers - Docker and Kubernetes patterns

Categories Covered:

• Go artifacts (binaries, coverage, vendor)
• Development environment (debug, generated files)
• IDE/Editor files (VS Code, JetBrains, Vim, etc.)
• OS files (macOS, Windows, Linux)
• Security files (keys, certificates, secrets)
• Docker and containers
• Cloud deployment artifacts
• Monitoring and profiling data

See docs/GITIGNORE.md for complete documentation.

🏗️ Build & Deploy

Build Commands

# Build for current platform
make build-local

# Build for all platforms
make build

# Build for specific platform
make build-linux
make build-darwin
make build-windows

Docker

# Build Docker image
make docker-build

# Run with Docker Compose
make docker-run

# Production environment
make docker-production

# Stop containers
make docker-down

🔍 Code Quality

Quality Commands

# Format code
make fmt

# Lint code
make lint

# Go vet
make vet

# All quality checks
make check

Security Commands

# Comprehensive security analysis
make security

# Individual security scans
make security-gosec        # Static security analysis
make security-vulncheck    # Vulnerability detection
make security-deps         # Dependency audit
make security-secrets      # Secret detection
make security-licenses     # License compliance

# Security reporting
make security-report       # Generate detailed report
make security-install-tools # Install security tools

# Quick vulnerability check
make vuln

Development Tools

# Install all development tools
make install-tools

# Tools included:
# - air (hot reloading)
# - golangci-lint (advanced linting)
# - goimports (import formatting)
# - govulncheck (vulnerability scanning)
# - gosec (security analysis)

🚀 CI/CD Pipeline

Pipeline Commands

# Full CI pipeline
make ci

# Pre-commit checks
make pre-commit

# Release build
make release

Pipeline Steps

1. Dependencies: make deps
2. Code Quality: make check
3. Testing: make test
4. Build: make build

📚 Documentation

• docs/ARCHITECTURE.md - Clean Architecture details
• docs/TESTING.md - Testing strategy and coverage
• docs/SECURITY.md - Comprehensive security guide
• docs/ENVIRONMENT.md - Environment configuration
• docs/GITIGNORE.md - .gitignore patterns and security
• docs/GO_VERSION_UPGRADE.md - Go version upgrade guide
• docs/MAKEFILE.md - Makefile commands reference
• docs/API.md - API endpoint documentation

🛠️ Available Make Commands

Run make help to see all available commands organized by category:

• Main: dev, build, test, run
• Testing: test-unit, test-integration, test-coverage
• Quality: lint, fmt, vet, check, security
• Repository: gitignore-test, gitignore-validate
• Docker: docker-build, docker-run, docker-down
• Build: build-local, build-linux, build-darwin, build-windows
• Environment: env-setup, env-check, env-reset
• Utility: clean, deps, info, setup

🔗 API Endpoints

Endpoint	Method	Description
/	GET	Hello World message
/health	GET	Health check
/messages	GET	Get all messages
/messages	POST	Create new message

See docs/API.md for detailed API documentation.

🤝 Contributing

1. Setup: make setup
2. Develop: make dev
3. Test: make test
4. Quality: make pre-commit
5. Build: make build

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🎯 Features

• ✅ Clean Architecture with proper dependency inversion
• ✅ Go 1.24.4 with latest language features and performance
• ✅ Comprehensive testing with 95.5% coverage
• ✅ Enterprise security with comprehensive scanning suite
• ✅ Hot reloading for development
• ✅ Multi-platform builds
• ✅ Docker support with production configs
• ✅ Environment management with templates
• ✅ Code quality tools and linting
• ✅ CI/CD ready with complete pipeline
• ✅ Extensive documentation
• ✅ Developer-friendly Makefile with 35+ commands