A comprehensive, production-ready Go boilerplate implementing Hexagonal Architecture (Ports & Adapters) with best practices for building scalable, maintainable microservices.
- Architecture
- Features
- Project Structure
- Getting Started
- API Documentation
- Configuration
- Best Practices
- Testing
- Observability
- Design Patterns
- Alternative Adapters
- Extending
- Contributing
- License
# Clone the repository
git clone https://github.com/ubaidillahhf/hexagonal-boilerplate.git
cd hexagonal-boilerplate
# Set up environment
cp .env.example .env
# Start infrastructure (MongoDB, Redis, RabbitMQ, Jaeger)
docker-compose up -d
# Run the application
go run cmd/main.goThe server will start on http://localhost:8080
Test it:
curl http://localhost:8080/healthThis boilerplate follows true Hexagonal Architecture principles with clear separation of concerns:
┌─────────────────────────────────────────────────────────────┐
│ Primary Adapters │
│ (REST API, gRPC, CLI, etc.) │
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ HTTP │ │ gRPC │ │ CLI │ │
│ │ Handlers │ │ Handlers │ │ Commands │ │
│ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ │
└─────────┼─────────────────┼─────────────────┼───────────────┘
│ │ │
└─────────────────┼─────────────────┘
▼
┌─────────────────────────────────────┐
│ Application Layer (Ports) │
│ │
│ ┌────────────────────────────────┐ │
│ │ Input Ports (Use Cases) │ │
│ │ - OrderUseCase │ │
│ └────────────┬───────────────────┘ │
│ │ │
│ ┌────────────▼───────────────────┐ │
│ │ Use Case Implementations │ │
│ │ (Application Services) │ │
│ └────────────┬───────────────────┘ │
│ │ │
│ ┌────────────▼───────────────────┐ │
│ │ Output Ports (Interfaces) │ │
│ │ - OrderRepository │ │
│ │ - CacheRepository │ │
│ │ - EventPublisher │ │
│ └────────────┬───────────────────┘ │
└───────────────┼─────────────────────┘
│
┌───────────────▼─────────────────────┐
│ Domain Layer │
│ │
│ ┌────────────────────────────────┐ │
│ │ Entities & Value Objects │ │
│ │ - Order, OrderItem │ │
│ │ - Money (Value Object) │ │
│ └────────────────────────────────┘ │
│ │
│ ┌────────────────────────────────┐ │
│ │ Domain Errors │ │
│ │ - Enhanced error tracking │ │
│ └────────────────────────────────┘ │
└──────────────────────────────────────┘
▲
│
┌───────────────┴─────────────────────┐
│ Secondary Adapters │
│ │
│ ┌──────────┐ ┌──────────┐ │
│ │ MongoDB │ │ Redis │ │
│ │Repository│ │ Cache │ │
│ └──────────┘ └──────────┘ │
│ │
│ ┌──────────┐ ┌──────────┐ │
│ │RabbitMQ │ │ Feature │ │
│ │Publisher │ │ Flags │ │
│ └──────────┘ └──────────┘ │
└──────────────────────────────────────┘
- ✅ Pure Hexagonal Architecture - True ports & adapters pattern
- ✅ SOLID Principles - Single Responsibility, Open/Closed, Liskov Substitution, Interface Segregation, Dependency Inversion
- ✅ Domain-Driven Design - Rich domain models with business logic
- ✅ Dependency Injection - Clean dependency management
- ✅ Protocol Agnostic - Domain layer independent of HTTP/gRPC
- ✅ MongoDB - Document database with optimistic locking
- ✅ Redis - Caching with distributed locks
- ✅ RabbitMQ - Event-driven messaging with auto-reconnection
- ✅ Transaction Manager - Database-agnostic transaction abstraction (PostgreSQL, MongoDB, Elasticsearch)
- ✅ ACID Transactions - Optimistic locking for concurrency control
- ✅ OpenTelemetry Tracing - Distributed tracing with Jaeger
- ✅ Structured Logging - Zap logger with context propagation
- ✅ Error Tracking - Enhanced error handling with stack traces
- ✅ Health Checks - Readiness and liveness endpoints
- ✅ Race Condition Prevention - Distributed locks and optimistic locking
- ✅ Rate Limiting - Redis-backed rate limiter
- ✅ Connection Pooling - Optimized database connections
- ✅ Graceful Shutdown - Clean resource cleanup
- ✅ Circuit Breaker Ready - Resilient external service calls
- ✅ Feature Flags - Runtime feature toggling
- ✅ Hot Reload Ready - Environment-based configuration
- ✅ Docker Compose - Local development environment
- ✅ Makefile - Common development tasks
- ✅ Clean Code - Well-documented and maintainable
hexagonal-boilerplate/
├── cmd/
│ └── main.go # Application entry point
│
├── internal/
│ ├── domain/ # Domain Layer (Core Business Logic)
│ │ ├── entity/ # Domain entities
│ │ │ └── order.go # Order aggregate with business rules
│ │ ├── valueobject/ # Value objects
│ │ │ └── money.go # Money value object
│ │ └── error/ # Domain errors
│ │ └── error.go # Enhanced error with stack trace
│ │
│ ├── application/ # Application Layer (Use Cases)
│ │ ├── port/
│ │ │ ├── input/ # Input ports (use case interfaces)
│ │ │ │ └── order_usecase.go
│ │ │ └── output/ # Output ports (repository interfaces)
│ │ │ ├── order_repository.go
│ │ │ ├── cache_repository.go
│ │ │ ├── event_publisher.go
│ │ │ ├── feature_flag.go
│ │ │ ├── logger.go # Logger abstraction
│ │ │ ├── tracer.go # Tracer abstraction
│ │ │ └── transaction_manager.go # Transaction abstraction
│ │ └── service/ # Use case implementations
│ │ ├── order_service.go # Order business logic
│ │ └── observability_helper.go # Tracing & logging helpers
│ │
│ └── infrastructure/ # Infrastructure Layer (Adapters)
│ ├── adapter/
│ │ ├── primary/ # Inbound adapters
│ │ │ └── rest/
│ │ │ ├── handler/ # HTTP handlers
│ │ │ ├── middleware/ # Rate limiting, tracing, recovery
│ │ │ └── router.go # Route definitions
│ │ │
│ │ └── secondary/ # Outbound adapters
│ │ ├── persistence/
│ │ │ ├── mongodb/ # MongoDB repository
│ │ │ ├── postgres/ # PostgreSQL repository
│ │ │ └── elasticsearch/ # Elasticsearch repository
│ │ ├── cache/ # Redis/Valkey cache
│ │ ├── messaging/ # RabbitMQ/NATS publisher
│ │ └── feature/ # Feature flag service
│ │
│ ├── config/ # Configuration
│ ├── database/ # Database clients
│ ├── observability/ # Logging & tracing adapters
│ │ ├── zap_logger.go # Zap logger adapter
│ │ └── otel_tracer.go # OpenTelemetry tracer adapter
│ └── transaction/ # Transaction manager adapters
│ ├── postgres_transaction_manager.go
│ ├── mongodb_transaction_manager.go
│ └── noop_transaction_manager.go
│
├── docker-compose.yml # Local infrastructure
├── Makefile # Development commands
├── go.mod # Go dependencies
└── .env.example # Environment variables template
- Go 1.21+
- Docker & Docker Compose
- Make (optional)
- Clone the repository:
git clone https://github.com/ubaidillahhf/hexagonal-boilerplate.git
cd hexagonal-boilerplate- Set up environment:
cp .env.example .env
# Edit .env with your configuration- Start infrastructure services:
make docker-up
# or
docker-compose up -d- Install dependencies:
make deps
# or
go mod download- Run the application:
make run
# or
go run cmd/main.goThe server will start on http://localhost:8080
curl http://localhost:8080/healthcurl -X POST http://localhost:8080/api/v1/orders \
-H "Content-Type: application/json" \
-d '{
"customer_id": "customer-123",
"items": [
{
"product_id": "product-456",
"quantity": 2,
"price": 29.99
}
]
}'curl http://localhost:8080/api/v1/orders/{order_id}curl "http://localhost:8080/api/v1/orders?page=1&limit=20&customer_id=customer-123"curl -X POST http://localhost:8080/api/v1/orders/{order_id}/confirmcurl -X POST http://localhost:8080/api/v1/orders/{order_id}/paymentcurl -X POST http://localhost:8080/api/v1/orders/{order_id}/cancelAll configuration is managed through environment variables. See .env.example for available options:
- Server: Port, timeouts, shutdown timeout
- MongoDB: Connection URI, pool sizes
- Redis: Address, pool configuration
- RabbitMQ: Connection URL, exchange, queue
- Feature Flags: Enable/disable features at runtime
- Rate Limiting: Requests per window
- Tracing: Jaeger endpoint, sampling
- Logging: Level (debug/info/warn/error), format (json/console)
// Domain errors with stack traces and context
err := domainErr.Wrapf(
domainErr.ErrCodeNotFound,
originalErr,
"order not found: %s",
orderID,
)
err.WithField("customer_id", customerID)// Distributed locks with Redis
lockKey := fmt.Sprintf("lock:order:%s", orderID)
acquired, err := cache.SetNX(ctx, lockKey, "1", 10*time.Second)
// Optimistic locking with version control
err := repo.UpdateWithOptimisticLock(ctx, order, expectedVersion)ctx, span := tracer.Start(ctx, "OrderService.CreateOrder")
defer span.End()
span.SetAttributes(
attribute.String("order_id", order.ID),
attribute.Float64("amount", order.TotalAmount),
)// Database-agnostic transaction abstraction
// Application layer controls transaction boundaries
err := txManager.ExecuteInTransaction(ctx, func(txCtx context.Context) error {
if err := orderRepo.Create(txCtx, order); err != nil {
return err
}
if err := inventoryRepo.Reserve(txCtx, items); err != nil {
return err
}
return nil // Auto-commit on success, auto-rollback on error
})
// Works with PostgreSQL, MongoDB, or no-op for Elasticsearch
// No database-specific code in application layerif !featureFlag.IsEnabled(ctx, FeatureOrderCreation) {
return domainErr.ErrFeatureDisabled
}// Redis-backed rate limiter per IP
// Configured via RATE_LIMIT_REQUESTS and RATE_LIMIT_WINDOW// Coordinated shutdown with timeout
// Closes HTTP server, databases, message brokers cleanly# Run tests
make test
# Run tests with coverage
make test-coverage
# Run with race detector
go test -race ./...Access distributed traces at: http://localhost:16686
Access RabbitMQ console at: http://localhost:15672
- Username:
guest - Password:
guest
Structured JSON logs with trace IDs for correlation:
{
"level": "info",
"timestamp": "2024-03-12T08:00:00Z",
"caller": "service/order_service.go:45",
"message": "Order created successfully",
"order_id": "550e8400-e29b-41d4-a716-446655440000",
"customer_id": "customer-123",
"total_amount": 59.98,
"trace_id": "4bf92f3577b34da6a3ce929d0e0e4736"
}- Single Responsibility: Each layer has one reason to change
- Open/Closed: Extend behavior via interfaces, not modification
- Liskov Substitution: Implementations are interchangeable
- Interface Segregation: Small, focused interfaces
- Dependency Inversion: Depend on abstractions, not concretions
- Hexagonal Architecture (Ports & Adapters)
- Repository Pattern (Data access abstraction)
- Transaction Manager Pattern (Database-agnostic transaction control)
- Dependency Injection (Loose coupling)
- Factory Pattern (Object creation)
- Strategy Pattern (Feature flags)
- Observer Pattern (Event publishing)
- Adapter Pattern (Logger, Tracer, Transaction abstractions)
- Connection pooling for MongoDB and Redis
- Caching with TTL and invalidation
- Optimistic locking for minimal blocking
- Efficient JSON serialization
- Context-aware timeouts
- Resource cleanup on shutdown
make help # Show all available commands
make build # Build the application
make run # Run the application
make test # Run tests
make test-coverage # Run tests with coverage
make clean # Clean build artifacts
make docker-up # Start Docker services
make docker-down # Stop Docker services
make docker-logs # View Docker logs
make lint # Run linter
make deps # Download dependenciesThis boilerplate includes multiple adapter implementations for each infrastructure component, demonstrating the true power of Hexagonal Architecture. Switch adapters without changing your domain logic!
| Component | Default | Alternatives | Switch Guide |
|---|---|---|---|
| HTTP Framework | Fiber | Echo | Guide |
| Cache | Redis | Valkey | Guide |
| Message Broker | RabbitMQ | NATS | Guide |
| Database | MongoDB | PostgreSQL, Elasticsearch | Guide |
From: Fiber + MongoDB + Redis + RabbitMQ
To: Echo + PostgreSQL + Valkey + NATS
Just update cmd/main.go dependency injection - domain layer stays unchanged!
// Before
import "github.com/ubaidillahhf/hexagonal-boilerplate/internal/infrastructure/adapter/primary/rest"
app := rest.NewRouter(...)
// After
import echoAdapter "github.com/ubaidillahhf/hexagonal-boilerplate/internal/infrastructure/adapter/primary/echo"
app := echoAdapter.NewRouter(...)- SWITCHING_GUIDE.md - Step-by-step switching instructions
- ADAPTERS.md - Complete adapter reference and comparison
- EXAMPLES.md - Copy-paste examples for different stacks
✅ Demonstrates Hexagonal Architecture - Shows true adapter swapping
✅ Technology Freedom - Choose the best tool for your needs
✅ Migration Path - Easy to switch as requirements evolve
✅ Learning Resource - See different implementations of same interface
- Create entity in
internal/domain/entity/ - Define repository interface in
internal/application/port/output/ - Implement repository in
internal/infrastructure/adapter/secondary/persistence/ - Create use case interface in
internal/application/port/input/ - Implement use case in
internal/application/service/ - Create HTTP handler in
internal/infrastructure/adapter/primary/rest/handler/ - Register routes in
internal/infrastructure/adapter/primary/rest/router.go
// 1. Define in output port
const FeatureNewFeature = "new_feature"
// 2. Add to .env
FEATURE_NEW_FEATURE_ENABLED=true
// 3. Use in service
if !s.featureFlag.IsEnabled(ctx, output.FeatureNewFeature) {
return domainErr.ErrFeatureDisabled
}MIT License - see the LICENSE file for details.
This boilerplate is free to use for both personal and commercial projects.
Contributions are welcome! Here's how you can help:
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
- Follow the existing code style and architecture patterns
- Add tests for new features
- Update documentation as needed
- Ensure all tests pass before submitting PR
- 📖 Documentation: Check the guidelines folder for detailed guides
- 💬 Issues: Open an issue for bugs or feature requests
- 🌟 Star: If you find this helpful, please star the repository!
This boilerplate is inspired by:
- Hexagonal Architecture by Alistair Cockburn
- Clean Architecture by Robert C. Martin (Uncle Bob)
- Domain-Driven Design by Eric Evans
- Best practices from companies like Uber, Netflix, Google, and Spotify
Built with ❤️ following Hexagonal Architecture best practices
⭐ If this boilerplate helps you, please consider giving it a star!