Go Clean Architecture CLI (gcg)

A CLI tool to generate Go/Gin clean architecture projects and modules. This tool helps you scaffold Go applications following clean architecture principles with Gin-Gonic framework.

Features

• 🚀 Project Scaffolding - Generate a complete Go project with clean architecture structure
• 📦 Resource Generator - Create CRUD resources with entity, repository, usecase, and handler
• ⚡ Service Generator - Add custom services to existing resources
• 🗑️ Module Removal - Clean removal of resources

Tech Stack

The generated projects use:

• Framework: Gin-Gonic - High-performance HTTP web framework
• ORM: GORM - The fantastic ORM library for Go
• Database: PostgreSQL
• Validation: go-playground/validator
• Configuration: Viper / godotenv
• Logging: Zap - Blazing fast structured logger
• UUID: google/uuid

Installation

npm install -g go-clean-cli

Or using npx:

npx go-clean-cli <command>

Commands

Create New Project

gcg new
# or
gcg n

This will:

1. Prompt for project name
2. Prompt for Go module name (e.g., github.com/username/project)
3. Generate complete project structure with clean architecture

Generate Resource

gcg g res
# or
gcg g resource

This will:

1. Prompt for resource name (e.g., user, product, order)
2. Generate entity, repository, usecase, handler, and DTO files
3. Update router with CRUD endpoints

Generate Service

gcg g s
# or
gcg g service

This will:

1. Select an existing module
2. Prompt for service name (e.g., getByEmail, activate)
3. Add service method to repository, usecase, and handler

Remove Resource

gcg rm res
# or
gcg rm resource

This will:

1. List existing resources
2. Remove selected resource files and directories
3. Update router (manual cleanup may be needed)

List Resources

gcg ls
# or
gcg list

Help

gcg --help
# or
gcg -h

Version

gcg --version
# or
gcg -v

Project Structure

Generated projects follow the NestJS Clean Architecture pattern:

project-name/
├── src/
│   ├── domain/                      # Domain layer (business logic)
│   │   ├── dtos/                    # Data transfer objects
│   │   ├── logger/                  # Logger interface
│   │   ├── models/                  # Domain models
│   │   └── repositories/            # Repository interfaces
│   ├── infrastructure/              # Infrastructure layer
│   │   ├── common/
│   │   │   ├── filter/              # Exception filters
│   │   │   ├── interceptors/        # Request interceptors
│   │   │   └── middleware/          # HTTP middleware
│   │   ├── config/
│   │   │   ├── database/            # Database configuration
│   │   │   └── environment/         # Environment configuration
│   │   ├── controllers/             # HTTP controllers
│   │   ├── entities/                # Database entities (GORM)
│   │   ├── logger/                  # Logger implementation
│   │   ├── repositories/            # Repository implementations
│   │   └── usecases-proxy/          # Usecases proxy (DI container)
│   ├── usecases/                    # Application usecases
│   ├── shared/utils/                # Shared utilities
│   ├── main.go                      # Application entry point
│   └── app.go                       # Application module
├── .env                             # Environment variables
├── .env.example                     # Environment template
├── .gitignore
├── Dockerfile
├── docker-compose.yml
├── Makefile
└── go.mod

Generated Resource Structure

When you generate a resource (e.g., user), the following files are created:

src/
├── domain/
│   ├── dtos/
│   │   └── user.go                  # User DTOs
│   ├── models/
│   │   └── user.go                  # User domain model
│   └── repositories/
│       └── user.go                  # User repository interface
├── infrastructure/
│   ├── controllers/user/
│   │   └── user.go                  # User HTTP controller
│   ├── entities/
│   │   └── user.go                  # User database entity
│   └── repositories/user/
│       └── user.go                  # User repository implementation
└── usecases/
    └── user.go                      # User usecase implementation

Quick Start

1. Create a new project:

   gcg new
   # Enter: my-api
   # Enter: github.com/myuser/my-api

2. Navigate to project:

   cd my-api

3. Install dependencies:

   go mod tidy

4. Set up database:

   # Create PostgreSQL database
   createdb my_api
      
   # Update .env with your database credentials

5. Run the application:

   go run src/main.go
   # or
   make run

6. Generate a resource:

   gcg g res
   # Enter: user

7. Add auto-migration in main.go:

   import "github.com/myuser/my-api/domain/entity"
      
   // After database connection
   database.AutoMigrate(db, &entity.User{})

API Endpoints

Generated resources include these endpoints:

| Method | Endpoint | Description | |--------|----------|-------------| | GET | /api/v1/{resource}s | Get all with pagination | | GET | /api/v1/{resource}s/:id | Get by ID | | POST | /api/v1/{resource}s | Create new | | PUT | /api/v1/{resource}s/:id | Update existing | | DELETE | /api/v1/{resource}s/:id | Delete (soft delete) |

Query Parameters

• page - Page number (default: 1)
• page_size - Items per page (default: 10, max: 100)
• search - Search term
• sort_by - Sort field
• sort_order - Sort order (asc/desc)

Makefile 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 files
make fmt            # Format code
make lint           # Run linter
make tidy           # Tidy dependencies
make docker-build   # Build Docker image
make docker-run     # Run with Docker Compose
make docker-stop    # Stop Docker containers
make migrate-up     # Run migrations
make migrate-down   # Rollback migrations

Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | APP_NAME | Application name | project-name | | APP_ENV | Environment (development/production) | development | | APP_DEBUG | Debug mode | true | | SERVER_HOST | Server host | 0.0.0.0 | | SERVER_PORT | Server port | 8080 | | SERVER_READ_TIMEOUT | Read timeout (seconds) | 10 | | SERVER_WRITE_TIMEOUT | Write timeout (seconds) | 10 | | DB_HOST | Database host | localhost | | DB_PORT | Database port | 5432 | | DB_USER | Database user | postgres | | DB_PASSWORD | Database password | | | DB_NAME | Database name | | | DB_SSL_MODE | SSL mode | disable | | DB_TIMEZONE | Timezone | UTC |

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.