goclean

README

goclean 🚀

A modern, production-grade Go Clean Architecture scaffolding and code generator CLI tool.

📖 Documentation · 🌐 Website · 📝 Changelog · 📦 Download the desktop installer

Bakes in enterprise-tested architecture from real-world Go backend production systems (Gin, GORM, PostgreSQL, Viper, Zerolog, migrations, Docker).

---

⚡ Worldwide Installation

Anyone with Go 1.22+ (goclean and generated projects target Go 1.23; Go will fetch that toolchain automatically) installed can install goclean globally with one command:

go install github.com/ebinskryfon/goclean@latest

Ensure your $(go env GOPATH)/bin is in your system's PATH:

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

---

🛠 Usage

1. Create a New Project

# Interactive mode (arrow-key menus for framework and database, prompts for module name)
goclean new my-saas

# Or non-interactive with flags
goclean new my-saas --module github.com/username/my-saas --db saas_db

# Pick the stack (defaults: gin + postgres)
goclean new my-api --router chi --database sqlite
goclean new my-shop --router gin --database mysql

Flag	Values	Notes
--router	gin (default), chi	chi uses plain net/http handlers; request validation uses the same binding:"..." tags
--database	postgres (default), mysql, sqlite	SQLite is pure Go (no cgo) and skips docker-compose.yml
--orm	gorm (default)	Saved in .goclean.json; more ORMs are planned (see Roadmap)

In a terminal, any of --router, --database that you don't pass is asked with an arrow-key menu. Passing the flag skips its question, and piped or CI runs never prompt.

The choice is saved in .goclean.json, so make:* generators emit matching handlers, routes, SQL types and migrations.

This bootstraps a complete Clean Architecture project in seconds:

• ✅ Scaffolds full Go Clean Architecture (Domain, Usecase, Delivery, Infrastructure)
• ✅ Auto-replaces all import paths with your Go module path
• ✅ Configures .env and .env.example
• ✅ Sets up docker-compose.yml (PostgreSQL)
• ✅ Configures .air.toml for live hot-reload
• ✅ Initializes Git repository (git init)
• ✅ Resolves and downloads Go dependencies (go mod tidy)

---

2. Scaffold Features (make:* generators)

Inside your project directory, generate complete Clean Architecture components instantly:

Generate a Complete Module (All 7 layers in 1 second)

goclean make:module Product

This creates:

• internal/domain/entity/product.go
• internal/types/product.go
• internal/domain/repository/product_repository.go
• internal/infrastructure/persistence/product_repository.go
• internal/usecase/interface/product_usecase.go
• internal/usecase/implementation/product_usecase.go
• internal/delivery/http/handlers/product_handler.go
• migrations/<NNNNNN>_create_products_table.up.sql
• migrations/<NNNNNN>_create_products_table.down.sql

Define fields (name:type)

goclean make:module Product name:string price:float stock:int active:bool

Fields flow into the entity, DTOs (create/update/response), usecase, handler and migration columns. Types: string, text, int, int64, float, bool, time, uuid (default string). Update requests use pointers, so omitted fields stay unchanged.

Auto-registration

make:module patches container.go and routes.go through the // goclean:* marker comments in projects created by goclean new. It is idempotent. Use --no-register to skip it; for older projects without markers it prints the manual steps instead.

Common flags

Flag	Applies to	Effect
--force	all generators, new	overwrite existing files (new: allow a non-empty directory)
--dry-run	all generators, new	list what would be written, change nothing
--no-register	make:module	don't patch container/routes
--no-git, --no-tidy	new	skip git init / go mod tidy

Every run ends with a created / overwritten / skipped summary.

Check your environment

goclean doctor   # verifies Go 1.22+ (1.23+ recommended), git and docker

Granular Generators

# Generate only an Entity
goclean make:entity Order

# Generate Request, Input, and Response DTO types
goclean make:types Order

# Generate Repository interface + GORM implementation
goclean make:repo Order

# Generate Usecase interface + implementation
goclean make:usecase Order

# Generate Gin HTTP Handler
goclean make:handler Order

# Generate SQL migration files (up/down)
goclean make:migration Order

---

📁 Architecture Overview

Every project generated by goclean follows strict Clean Architecture (Dependency Inversion):

├── cmd/
│   ├── api/                 # Server startup, graceful shutdown, logger, DI container
│   └── migrate/             # Database migration runner (up/down/version)
├── config/                  # Viper configuration loader (env + defaults)
├── internal/
│   ├── delivery/
│   │   └── http/
│   │       ├── handlers/    # Gin HTTP handlers
│   │       ├── middleware/  # Logger, Recovery, CORS, RequestID
│   │       ├── response/    # Standard JSON envelope (Success, Error, Paginated)
│   │       └── routes.go    # Route definitions & grouping
│   ├── domain/
│   │   ├── entity/          # Pure business entities (zero external dependencies)
│   │   ├── errors/          # Standard domain errors (ErrNotFound, ErrConflict, etc.)
│   │   ├── repository/      # Repository interface contracts
│   │   └── service/         # Domain service contracts
│   ├── infrastructure/
│   │   ├── container/       # Dependency Injection container (AppContainer)
│   │   ├── database/        # GORM PostgreSQL connection pool & fail-fast
│   │   ├── persistence/     # GORM implementations of repository interfaces
│   │   └── server/          # HTTP server lifecycle with graceful shutdown
│   ├── types/               # Request DTOs, Usecase Input/Query DTOs, and Response DTOs
│   └── usecase/
│       ├── interface/       # Usecase contracts / interactors
│       └── implementation/  # Concrete business logic implementations
├── pkg/
│   └── logger/              # Zerolog structured logging
└── migrations/              # PostgreSQL SQL migration files

---

🏃 Running Generated Projects

cd my-saas

# 1. Start local PostgreSQL
docker compose up -d

# 2. Run database migrations
make migrate

# 3. Start development server (hot-reload with Air)
make dev

# 4. Check API health
curl http://localhost:8080/health

---

🗺 Roadmap

Planned for a later version:

• Frameworks: Echo, Fiber
• ORMs / data access: sqlx, Bun, Ent (GORM stays the default)

These need the project templates split into per-router and per-ORM layers, so the wizard will list them once they are implemented.

---

🤝 Contributing

Contributions, issues, and feature requests are welcome!

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

---

📄 License

MIT License.

---

🧪 Development & Releases

make test    # unit tests
make smoke   # scaffold a project, add a module, go build (needs network)
make build   # ./bin/goclean with the version stamped in

CI (.github/workflows/ci.yml) runs format, vet, tests and the smoke test. Pushing a v* tag runs GoReleaser (.goreleaser.yaml) to publish binaries. go install github.com/ebinskryfon/goclean@vX.Y.Z reports its module version automatically.

---

📚 Learn more

• Quick Start: create your first project in minutes
• Project Structure: what goclean generates and why
• Available Commands: every command and flag
• Troubleshooting: common problems and fixes