GitHub - phankieuphu/go-hexagonal-cli: Go CLI that generates Hexagonal Architecture project scaffolding using templates.

# Hexagonal Project Generator (Go CLI)


A command-line tool that scaffolds production-ready **Hexagonal Architecture (Ports & Adapters)** services in Go.

Reference: [Hexagon](https://en.wikipedia.org/wiki/Hexagonal_architecture_(software))

This generator creates:

- Full domain layer  
- Application/use-case layer  
- Infrastructure adapters  
- HTTP controller & router  
- External client adapter  
- DynamoDB repository  
- Configuration loader  
- `go.mod`  
- Makefile  
- Complete project folder structure  
- Dynamic naming based on the service name  

Everything is produced using `.tmpl` template files and rendered into a clean Go project.
---

## 🚀 Features

- Generate an entire Go project with **one command**
- Full Hexagonal Architecture (Domain → Application → Infrastructure)
- Dynamic templates using Go’s `text/template`
- Automatic folder creation
- AWS DynamoDB repository scaffolding
- HTTP controller + router
- External service adapter (generic)
- Config loader
- Makefile included
- Ready to `go build` and `go run`

---

## 🛠 Installation

Install globally:

```bash
go install github.com/<your-github>/go-hexagonal-cli@latest

Make sure your Go bin is in PATH:

export PATH=$PATH:$(go env GOPATH)/bin

🏗 Usage

Generate a new hexagonal Go service:

hexagon init your--service

This creates a folder:

with all layers pre-configured.

📁 Generated Folder Structure

your--service/
│
├── go.mod
├── Makefile
│
├── cmd/
│   └── your--service/
│       └── main.go
│
└── internal/
    ├── domain/
    │   └── your-service/
    │       ├── entity.go
    │       ├── repository.go
    │       └── service.go
    │
    ├── application/
    │   └── your-service/
    │       ├── handler.go
    │       ├── request.go
    │       └── command.go
    │
    └── infrastructure/
        ├── http/
        │   ├── controller.go
        │   └── router.go
        │
        ├── external/
        │   └── client.go
        │
        ├── repository/
        │   └── dynamo.go
        │
        └── config/
            └── config.go

🎛 Dynamic Naming

Example:

hexagon init your--service

Automatically generates:

Input	Output
`your--service`	project module: `your--service`
`your--service`	package name: `your-service`
`your--service`	service name: `your-Service`

Template variables:

{{ .Project }}
{{ .Package }}
{{ .Service }}

Are injected into all template files.

⚙️ Build & Run

Build:

Run:

Dev mode:

🧪 Testing

🔧 Development (contributing to the CLI)

Run CLI directly from source:

go run cmd/hexagon/main.go init demo

Build binary:

Clean artifacts:

📦 Template System

All templates live in:

Examples:

domain/entity.go.tmpl
application/handler.go.tmpl
infrastructure/http/controller.go.tmpl
go.mod.tmpl

These are standard Go templates processed by text/template.

🙌 Contributions

Pull requests are welcome! Template improvements, new adapters, codegen features, and documentation PRs are appreciated.

📄 License

MIT Free to use, modify, and distribute.