A production-ready Go REST API boilerplate following Clean Architecture principles with Hexagonal Architecture patterns. This template provides a solid foundation for building scalable and maintainable Go applications with clear separation of concerns and high testability.

• Clean Architecture: Well-structured codebase following Uncle Bob's Clean Architecture principles
• Hexagonal Architecture: Clear separation between business logic and external concerns
• Domain-Driven Design: Organized by business domains rather than technical layers
• Dependency Injection: Using Google Wire for compile-time DI
• Database Integration: PostgreSQL with GORM ORM
• Middleware Support: CORS, JWT authentication, logging, and recovery
• Configuration Management: Environment-based configuration with Viper
• Auto-migration: Database schema management
• Production Ready: Structured for deployment and scaling

• Go 1.21+
• PostgreSQL database
• Make (optional, for using Makefile commands)
• Wire - Dependency injection framework

1. Clone and setup your project:

git clone <your-repo-url>
cd your-project-name

2. Setup environment variables:

cp .env.example .env
# Edit .env with your database credentials and configuration

3. Install dependencies:

go mod tidy

4. Install Wire and generate dependency injection:

make install-wire
make generate-wire

5. Run database migration and start server:

make automigrate
make dev

The server will start on the configured port (default: http://localhost:3000)

This boilerplate implements Clean Architecture with Hexagonal Architecture patterns, ensuring:

• Independence: Business logic doesn't depend on external frameworks
• Testability: Easy to test with clear boundaries between layers
• Flexibility: Easy to change external dependencies (database, web framework, etc.)
• Maintainability: Well-organized code structure

HTTP Request → Handler (Interface) → Use Case (Application) → Domain Logic → Repository (Infrastructure) → Database

your-project/
├── cmd/
│   ├── api/
│   │   ├── main.go         # Application entry point
│   │   ├── wire.go         # Dependency injection configuration
│   │   └── wire_gen.go     # Generated Wire code
│   └── automigrate/        # Database migration commands
├── internal/               # Private application packages
│   ├── adapter/            # Adapters (Interface Layer)
│   │   ├── handler/        # HTTP handlers (controllers)
│   │   ├── repository/     # Data access implementations
│   │   └── service/        # External service adapters
│   ├── config/             # Configuration management
│   ├── infra/              # Infrastructure components
│   │   ├── database/       # Database connection
│   │   └── logger/         # Logging infrastructure
│   ├── auth/               # Authentication domain
│   │   ├── application/    # Auth use cases
│   │   ├── domain/         # Auth business logic
│   │   └── port/           # Auth interfaces
│   └── user/               # User domain (example)
│       ├── application/    # Application services & use cases
│       ├── domain/         # Domain entities and business logic
│       └── port/           # Domain interfaces/ports
├── pkg/                    # Public packages (reusable)
│   ├── auth/               # JWT utilities
│   ├── middlewares/        # HTTP middlewares
│   ├── response/           # Response utilities
│   └── server/             # Server setup
├── examples/               # Usage examples and documentation
├── Makefile               # Build and development commands
├── docker-compose.yml     # Development environment
├── go.mod
├── go.sum
└── README.md

1. Presentation Layer (cmd/, internal/adapter/handler/)

• Application entry points and HTTP handlers
• Request/response serialization and validation
• Route definitions and middleware setup

2. Application Layer (internal/*/application/)

• Use cases and application services
• Business workflow orchestration
• Cross-domain coordination and DTOs

3. Domain Layer (internal/*/domain/, internal/*/port/)

• Core business entities and domain logic
• Business rules and domain validation
• Domain interfaces (ports) for external dependencies

4. Infrastructure Layer (internal/adapter/repository/, internal/infra/)

• Database implementations and external integrations
• Configuration, logging, and infrastructure concerns

• Language: Go 1.21+
• Web Framework: Chi router v5
• Database: PostgreSQL with GORM v2
• Dependency Injection: Google Wire
• Configuration: Viper
• Logging: Logrus
• Authentication: JWT tokens
• Architecture: Clean Architecture + Hexagonal Architecture + DDD

# Install Wire dependency injection tool
make install-wire

# Generate Wire dependency injection code
make generate-wire

# Start development server (auto-generates Wire code)
make dev

# Build production binary
make build

# Run database migration
make automigrate

# Clean generated files
make clean

# Run tests
make test

1. Create domain structure:

mkdir -p internal/your-domain/{domain,application,port}
mkdir -p internal/your-domain/application/dto

2. Define domain entities in internal/your-domain/domain/
3. Create ports/interfaces in internal/your-domain/port/
4. Implement use cases in internal/your-domain/application/
5. Add handlers in internal/adapter/handler/
6. Implement repositories in internal/adapter/repository/
7. Update Wire configuration in cmd/api/wire.go

1. Domain-First Development: Start with domain entities and business rules
2. Port Definition: Define interfaces for external dependencies
3. Use Case Implementation: Implement application services
4. Adapter Implementation: Create handlers and repositories
5. Wire Integration: Configure dependency injection

Currently, we have no test.

Build and run with Docker:

docker-compose up -d

Key environment variables:

# Server
HOST=localhost
PORT=3000

# Database
DB_HOST=localhost
DB_PORT=5432
DB_USER=your_user
DB_PASSWORD=your_password
DB_NAME=your_database
DB_SSLMODE=disable

# JWT
JWT_SECRET=your-secret-key
JWT_EXPIRY_HOURS=24

Check the examples/ directory for:

• JWT authentication usage
• API endpoint examples
• Domain implementation patterns

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request