Goca - Go Clean Architecture Code Generator

Goca is a powerful CLI code generator for Go that helps you create Clean Architecture projects following best practices. It generates clean, well-structured layered code, allowing you to focus on business logic instead of repetitive configuration tasks.

Documentation

• Complete Documentation Website - Beautiful, searchable VitePress docs
• Quick Start Guide - Get started in 5 minutes
• Complete Tutorial - Build a real application
• Clean Architecture Guide - Learn the principles
• Commands Reference - All commands documented

Clean Architecture Philosophy

Every feature generated by Goca strictly follows Clean Architecture principles:

• 🟡 Domain Layer: Pure entities without external dependencies
• 🔴 Use Case Layer: Application logic with DTOs and business validations
• 🟢 Adapter Layer: HTTP, gRPC, CLI interfaces that adapt input/output
• 🔵 Infrastructure Layer: Repositories that implement data persistence

✅ Best Practices Guaranteed

• Dependencies oriented towards the system core
• Clear interfaces and contracts between layers
• Business logic encapsulated in internal layers
• Clearly segregated responsibilities
• Dependency injection for maximum testability

🚫 Bad Practices Prevention

• Prevents mixing technical logic with business logic
• Prevents direct dependencies from entities to infrastructure
• Generates well-structured and cohesive packages

🧠 Implemented Principles and Anti-Patterns

✅ Applied Patterns

• Repository Pattern: Data persistence abstraction
• Dependency Injection: Inversion of control between layers
• CQRS: Separation of commands and queries in use cases
• Interface Segregation: Specific contracts per responsibility

🚫 Prevented Anti-Patterns

• Fat Controller: Business logic in handlers
• God Object: Entities with too many responsibilities
• Anemic Domain Model: Entities without behavior
• Direct Database Access: Direct dependencies to infrastructure

🔍 Clean Architecture Validation

Goca guarantees that every generated file complies with:

• Dependency Rule: Internal code never depends on external code
• Separation of Concerns: Each layer has a single reason to change
• Inversion Principle: Details depend on abstractions
• Clean Interfaces: Clear contracts between layers

🚀 Main Features

• Layer-based Generation: Each command generates code specific to a Clean Architecture layer
• Complete Feature: One command generates all necessary structure for a feature
• Domain Entities: Generates pure entities with business validations
• Use Cases: Creates application services with well-defined DTOs
• Repositories: Generates interfaces and implementations following Repository Pattern
• Multi-Protocol Handlers: Supports HTTP, gRPC, CLI maintaining layer separation
• Dependency Injection: Structure prepared for DI from the start
• Integration Testing: Auto-generate comprehensive integration tests with fixtures and helpers (v1.14.0+)

📦 Installation

Recommended: Binary from GitHub Releases

Download the latest stable version with proper version info from GitHub Releases:

Linux:

# Download latest release
wget https://github.com/sazardev/goca/releases/latest/download/goca-linux-amd64
chmod +x goca-linux-amd64
sudo mv goca-linux-amd64 /usr/local/bin/goca

# Verify installation
goca version

macOS:

# Intel Macs
wget https://github.com/sazardev/goca/releases/latest/download/goca-darwin-amd64
chmod +x goca-darwin-amd64
sudo mv goca-darwin-amd64 /usr/local/bin/goca

# Apple Silicon Macs  
wget https://github.com/sazardev/goca/releases/latest/download/goca-darwin-arm64
chmod +x goca-darwin-arm64
sudo mv goca-darwin-arm64 /usr/local/bin/goca

# Verify installation
goca version

Windows:

# Download goca-windows-amd64.exe from GitHub Releases
# Rename to goca.exe and add to PATH

# Verify installation
goca version

Alternative: Using Go Install

# Install from source (version info will show "dev")
go install github.com/sazardev/goca@latest

# Note: go install builds from source without version injection
# For proper version info, use binary releases above

For Development

# Clone and build with proper version injection
git clone https://github.com/sazardev/goca.git
cd goca
make build

# The binary will be created in current directory
# Move to PATH if needed:
sudo mv goca /usr/local/bin/goca

🛠️ Quick Start

Initialize Clean Architecture Project

# Create new project with Clean Architecture structure
goca init myproject --module github.com/sazardev/myproject

# Navigate to project
cd myproject

# Install dependencies
go mod tidy

Generate Complete Feature (NEW - Auto-Integrated)

# Generate complete feature with all layers + automatic integration
goca feature Employee --fields "name:string,email:string,role:string"

# Ready to go! The feature is completely functional
go run main.go

Integrate Existing Features (NEW)

# For projects with features not integrated
goca integrate --all

# Automatically detects all features and connects them

⚡ NEW in v1.11.0: Safety & Dependency Features

Goca now includes production-ready safety features to prevent common mistakes:

🛡️ Safety Features

• 🔍 Dry-Run Mode (--dry-run): Preview all changes before creating files
• ⚠️ File Conflict Detection: Automatically detects existing files to prevent accidental overwrites
• 👤 Name Conflict Detection: Scans project for duplicate entity/feature names
• 📦 Automatic Backup (--backup): Backup files before overwriting
• 💪 Force Overwrite (--force): Override protection when needed
• 📚 Version Compatibility: Verifies Go version compatibility (1.21+)

📦 Dependency Management

• 🤖 Automatic go.mod Updates: Auto-updates dependencies when generating features
• � Smart Suggestions: Recommends optional dependencies based on feature type
• ✅ Version Verification: Validates dependency versions and integrity

Example Usage

# Preview changes before generating
goca feature User --fields "name:string,email:string" --dry-run

# Safe generation with conflict detection
goca feature User --fields "name:string,email:string"

# Update existing feature with backup
goca feature User --fields "name:string,email:string,role:string" --force --backup

📖 Complete Safety Features Documentation

�📋 Main Commands

| Command | Purpose | Automatic Integration | | -------------------- | --------------------------------------- | --------------------------- | | goca init | Initialize Clean Architecture project | ✅ Complete structure + Git | | goca feature | Generate complete feature (all layers) | ✅ Auto-DI + Routes + Safety | | goca integrate | NEW: Integrate existing features | ✅ Repair/update integration | | goca entity | Generate domain entities only | ❌ Manual | | goca usecase | Generate use cases only | ❌ Manual | | goca repository | Generate repositories only | ❌ Manual | | goca handler | Generate handlers only | ❌ Manual | | goca di | Generate dependency injection container | ❌ Manual |

🔄 Recommended Workflow

1. Generate Domain: goca entity Employee --fields "name:string,email:string"
2. Generate Use Cases: goca usecase EmployeeService --entity Employee
3. Generate Repository: goca repository Employee --database postgres
4. Generate Handlers: goca handler Employee --type http
5. Generate DI: goca di --features Employee

📚 Commands by Layer

🟡 Domain Layer

goca entity

Generates pure domain entities following DDD.

goca entity <name> [flags]

# Flags:
--fields string     Entity fields "name:type,email:string"
--validation       Add domain validations
--business-rules   Include business rule methods

Example:

goca entity Product --fields "name:string,price:float64,category:string" --validation --business-rules

Generated Code:

// domain/product.go
package domain

type Product struct {
    ID       int
    Name     string
    Price    float64
    Category string
}

func (p *Product) Validate() error {
    if p.Name == "" || p.Price <= 0 {
        return ErrInvalidProductData
    }
    return nil
}

func (p *Product) IsExpensive() bool {
    return p.Price > 1000.0
}

🔴 Use Case Layer

goca usecase

Generates application services with DTOs and business logic.

goca usecase <name> [flags]

# Flags:
--entity string    Associated entity
--operations string CRUD operations (creat