Clean Architecture & Hexagonal (Ports & Adapters)

┌─────────────────────────────────────┐
│  👤 UI / HTTP Handler / Scheduler   │  ← Interface Layer
├─────────────────────────────────────┤
│  📦 Use Cases / Services             │  ← Application Layer
├─────────────────────────────────────┤
│  🎯 Domain / Business Rules          │  ← Domain Layer (THE CENTER)
├─────────────────────────────────────┤
│  💾 Repository / Cache / Queue       │  ← Infrastructure Layer
├─────────────────────────────────────┤
│  🔧 Frameworks (Gin, GORM, Redis)   │  ← Framework Layer
└─────────────────────────────────────┘

// ✓ OK: Framework depends on domain
import "myapp/domain/order"

// ❌ NEVER: Domain depends on framework
import "github.com/gin-gonic/gin"

// domain/order/order.go
package order

import "errors"

type Order struct {
    id        string
    items     []OrderItem
    status    OrderStatus
    createdAt time.Time
}

type OrderStatus string

const (
    StatusCreated   OrderStatus = "created"
    StatusConfirmed OrderStatus = "confirmed"
    StatusShipped   OrderStatus = "shipped"
)

// Business rule: order phải có items
func (o *Order) Confirm() error {
    if len(o.items) == 0 {
        return errors.New("order must have items")
    }
    o.status = StatusConfirmed
    return nil
}

// Pure function: no DB, no HTTP
func (o *Order) Total() float64 {
    sum := 0.0
    for _, item := range o.items {
        sum += item.Price() * float64(item.Quantity())
    }
    return sum
}

// Value Object
type Money struct {
    amount   float64
    currency string
}

func NewMoney(amount float64, currency string) (Money, error) {
    if amount < 0 {
        return Money{}, errors.New("amount cannot be negative")
    }
    return Money{amount, currency}, nil
}

// application/service/confirm_order.go
package service

import (
    "context"
    "myapp/domain/order"
)

// UseCase Input (DTO)
type ConfirmOrderInput struct {
    OrderID string
}

// UseCase Output
type ConfirmOrderOutput struct {
    OrderID string
    Total   float64
}

type ConfirmOrderUseCase struct {
    orderRepo order.Repository      // ← Interface (defined in domain)
    eventBus  order.EventPublisher  // ← Interface
}

// Execute use case
func (uc *ConfirmOrderUseCase) Execute(
    ctx context.Context,
    input ConfirmOrderInput,
) (*ConfirmOrderOutput, error) {
    
    // Load aggregate
    ord, err := uc.orderRepo.FindByID(ctx, input.OrderID)
    if err != nil {
        return nil, err
    }
    
    // Invoke business rule
    if err := ord.Confirm(); err != nil {
        return nil, err
    }
    
    // Persist
    if err := uc.orderRepo.Save(ctx, ord); err != nil {
        return nil, err
    }
    
    // Publish events
    for _, event := range ord.PendingEvents() {
        _ = uc.eventBus.Publish(ctx, event)
    }
    ord.ClearEvents()
    
    return &ConfirmOrderOutput{
        OrderID: ord.ID(),
        Total:   ord.Total(),
    }, nil
}

// interface/http/handler/order.go
package handler

import (
    "github.com/gin-gonic/gin"
    "myapp/application/service"
)

type OrderHandler struct {
    confirmOrderUseCase *service.ConfirmOrderUseCase
}

// HTTP request DTO
type ConfirmOrderRequest struct {
    OrderID string `json:"order_id"`
}

// HTTP response DTO
type ConfirmOrderResponse struct {
    OrderID string  `json:"order_id"`
    Total   float64 `json:"total"`
}

// Adapter: HTTP → UseCase
func (h *OrderHandler) ConfirmOrder(c *gin.Context) {
    var req ConfirmOrderRequest
    if err := c.BindJSON(&req); err != nil {
        c.JSON(400, gin.H{"error": err.Error()})
        return
    }
    
    // Convert HTTP request → UseCase input
    useCaseInput := service.ConfirmOrderInput{
        OrderID: req.OrderID,
    }
    
    // Execute use case
    output, err := h.confirmOrderUseCase.Execute(c.Request.Context(), useCaseInput)
    if err != nil {
        c.JSON(400, gin.H{"error": err.Error()})
        return
    }
    
    // Convert UseCase output → HTTP response
    c.JSON(200, ConfirmOrderResponse{
        OrderID: output.OrderID,
        Total:   output.Total,
    })
}

// infrastructure/postgres/order_repository.go
package postgres

import (
    "context"
    "database/sql"
    "myapp/domain/order"
)

type OrderRepository struct {
    db *sql.DB
}

// Adapter: SQL row → Order domain object
func (r *OrderRepository) FindByID(ctx context.Context, id string) (*order.Order, error) {
    row := r.db.QueryRowContext(ctx, `
        SELECT id, status FROM orders WHERE id = $1
    `, id)
    
    var ordID, status string
    if err := row.Scan(&ordID, &status); err != nil {
        return nil, err
    }
    
    // Reconstruct domain object from DB
    ord := order.NewOrder(ordID)
    ord.SetStatus(order.OrderStatus(status))
    
    return ord, nil
}

// Adapter: Order domain object → SQL insert
func (r *OrderRepository) Save(ctx context.Context, ord *order.Order) error {
    _, err := r.db.ExecContext(ctx, `
        UPDATE orders SET status = $1 WHERE id = $2
    `, ord.Status(), ord.ID())
    return err
}

// infrastructure/cache/redis_cache.go
package cache

import "github.com/redis/go-redis/v9"

type RedisCache struct {
    client *redis.Client
}

func (c *RedisCache) Get(key string) (string, error) {
    return c.client.Get(ctx, key).Result()
}

// main.go
package main

import (
    "database/sql"
    "github.com/gin-gonic/gin"
    _ "github.com/lib/pq"
    
    "myapp/application/service"
    "myapp/infrastructure/postgres"
    "myapp/interface/http/handler"
)

func main() {
    // Wire infrastructure
    db, _ := sql.Open("postgres", "...")
    orderRepo := postgres.NewOrderRepository(db)
    eventBus := inmemory.NewEventBus()
    
    // Wire application
    confirmOrderUseCase := &service.ConfirmOrderUseCase{
        orderRepo: orderRepo,
        eventBus:  eventBus,
    }
    
    // Wire interface
    orderHandler := &handler.OrderHandler{
        confirmOrderUseCase: confirmOrderUseCase,
    }
    
    // Setup web framework
    r := gin.Default()
    r.POST("/orders/:id/confirm", orderHandler.ConfirmOrder)
    r.Run(":8080")
}

           🔶 Web (HTTP Adapter)
           ↓
        ┌─────────────────┐
        │                 │
        │ 🎯 Application  │ ← Ports (interfaces)
        │                 │
        └─────────────────┘
           ↓
    🔶 Database (SQL Adapter)
    🔶 Cache (Redis Adapter)
    🔶 Queue (RabbitMQ Adapter)

// domain/order/port.go
package order

import "context"

// Output Port: what the domain needs from outside
type Repository interface {
    FindByID(ctx context.Context, id string) (*Order, error)
    Save(ctx context.Context, order *Order) error
}

// Another output port
type EventPublisher interface {
    Publish(ctx context.Context, event interface{}) error
}

// Input Port: the use case interface
type ConfirmOrderPort interface {
    Execute(ctx context.Context, orderID string) error
}

// infrastructure/postgres/order_repository.go
type OrderRepository struct { db *sql.DB }

// Implement domain.Repository port
func (r *OrderRepository) FindByID(...) (*order.Order, error) { ... }
func (r *OrderRepository) Save(...) error { ... }

// ✓ Any implementation of domain.Repository can be used:
// - PostgreSQL adapter
// - In-memory adapter (for testing)
// - MongoDB adapter (future)

myapp/
├── cmd/
│   └── server/
│       └── main.go                    ← Wiring
├── domain/
│   └── order/
│       ├── order.go                   ← Domain model
│       ├── port.go                    ← Interfaces (output ports)
│       └── status.go                  ← Domain constants
├── application/
│   └── service/
│       └── confirm_order.go           ← Use case (input port impl)
├── interface/
│   ├── http/
│   │   └── handler/
│   │       └── order.go               ← HTTP adapter
│   └── cli/
│       └── command.go                 ← CLI adapter
└── infrastructure/
    ├── postgres/
    │   └── order_repository.go        ← PostgreSQL adapter
    ├── cache/
    │   └── redis_cache.go             ← Redis adapter
    └── event/
        └── inmemory_bus.go            ← In-memory event bus

// Wire dependencies in main.go
type Container struct {
    OrderRepo      order.Repository
    EventBus       order.EventPublisher
    ConfirmUseCase *service.ConfirmOrderUseCase
    OrderHandler   *handler.OrderHandler
}

func NewContainer() *Container {
    repo := postgres.NewOrderRepository(db)
    bus := inmemory.NewEventBus()
    useCase := service.NewConfirmOrderUseCase(repo, bus)
    handler := handler.NewOrderHandler(useCase)
    
    return &Container{
        OrderRepo:      repo,
        EventBus:       bus,
        ConfirmUseCase: useCase,
        OrderHandler:   handler,
    }
}

// Testing: swap implementations
func TestConfirmOrder(t *testing.T) {
    mockRepo := &MockOrderRepository{}
    mockBus := &MockEventBus{}
    useCase := service.NewConfirmOrderUseCase(mockRepo, mockBus)
    
    // Test pure use case logic, no DB/framework
    output, err := useCase.Execute(context.Background(), input)
    if err != nil {
        t.Fatalf("unexpected error: %v", err)
    }
}

// ❌ WRONG: Treating layer = folder
myapp/
├── layer1/
├── layer2/
└── layer3/

// ✓ RIGHT: Layers are logical, folders are by domain
myapp/
├── domain/
│   ├── order/
│   ├── payment/
│   └── customer/
├── application/
├── interface/
└── infrastructure/

// ❌ WRONG: Business logic in handler
func (h *OrderHandler) ConfirmOrder(c *gin.Context) {
    order, _ := h.orderRepo.FindByID(c.Param("id"))
    
    // ← Business logic here!
    if len(order.Items) == 0 {
        return error
    }
    order.Status = "confirmed"
    h.orderRepo.Save(order)
}

// ✓ RIGHT: Business logic in domain, handler is thin
func (h *OrderHandler) ConfirmOrder(c *gin.Context) {
    input := service.ConfirmOrderInput{OrderID: c.Param("id")}
    output, err := h.confirmOrderUseCase.Execute(c.Request.Context(), input)
    if err != nil {
        c.JSON(400, err)
        return
    }
    c.JSON(200, output)
}

// ❌ WRONG: Repository exposes SQL error
func (r *OrderRepository) FindByID(id string) (*Order, error) {
    // User sees: pq: column "status" does not exist (SQL error)
    return nil, fmt.Errorf("pq: %w", err)
}

// ✓ RIGHT: Repository translates error
func (r *OrderRepository) FindByID(id string) (*Order, error) {
    if errors.Is(err, sql.ErrNoRows) {
        return nil, errors.New("order not found")  // ← Domain error
    }
    return nil, errors.New("database error")
}

application → domain ← infrastructure
            ↓
         ❌ PROBLEM: infrastructure imports application

// ❌ OVERKILL: 6+ layers untuk simple CRUD
Request
  ↓ Handler
  ↓ Router
  ↓ Validator
  ↓ Transformer
  ↓ UseCase
  ↓ Service
  ↓ Helper
  ↓ Repository
  ↓ Database

// ✓ PRAGMATIC: 3-4 layers + clear responsibilities
Request
  ↓ Handler (HTTP ↔ Domain)
  ↓ UseCase (Orchestration)
  ↓ Domain (Business logic)
  ↓ Repository (Domain ↔ DB)