Hexagonal Architecture #

// port/inbound/create_order.go
// Inbound Port: defined by the application core
// External actors (HTTP, CLI, gRPC) call through this interface
package inbound

import "context"

// CreateOrderRequest is a framework-agnostic input DTO
type CreateOrderRequest struct {
	CustomerID string
	Items      []CreateOrderItem
}

type CreateOrderItem struct {
	ProductID string
	Quantity  int
	PriceCents int64
}

type CreateOrderResponse struct {
	OrderID    string
	TotalCents int64
	Status     string
}

// CreateOrderPort is an inbound port — the contract the core offers to the outside world
type CreateOrderPort interface {
	CreateOrder(ctx context.Context, req CreateOrderRequest) (*CreateOrderResponse, error)
}

// application/create_order_service.go
// The Application Service implements the inbound port
package application

import (
	"context"
	"errors"

	"myapp/domain"
	"myapp/port/inbound"
	"myapp/port/outbound"
)

// CreateOrderService implements inbound.CreateOrderPort
// ✓ It does not know whether it is called from HTTP, CLI, or gRPC
type CreateOrderService struct {
	orderRepo    outbound.OrderRepository  // outbound port
	inventory    outbound.InventoryChecker // outbound port
	eventBus     outbound.EventPublisher   // outbound port
}

func NewCreateOrderService(
	orderRepo outbound.OrderRepository,
	inventory outbound.InventoryChecker,
	eventBus outbound.EventPublisher,
) *CreateOrderService {
	return &CreateOrderService{
		orderRepo: orderRepo,
		inventory: inventory,
		eventBus:  eventBus,
	}
}

// CreateOrder implements inbound.CreateOrderPort
func (s *CreateOrderService) CreateOrder(
	ctx context.Context,
	req inbound.CreateOrderRequest,
) (*inbound.CreateOrderResponse, error) {
	if req.CustomerID == "" {
		return nil, errors.New("customer ID is required")
	}

	// Build domain objects from the request
	items := make([]domain.OrderItem, len(req.Items))
	for i, item := range req.Items {
		items[i] = domain.OrderItem{
			ProductID: domain.ProductID(item.ProductID),
			Quantity:  item.Quantity,
			Price:     domain.Money{Cents: item.PriceCents},
		}
	}

	// Check stock via an outbound port
	if err := s.inventory.CheckAvailability(ctx, items); err != nil {
		return nil, err
	}

	// Create the domain entity
	order, err := domain.NewOrder(domain.CustomerID(req.CustomerID), items)
	if err != nil {
		return nil, err
	}

	// Save via an outbound port
	if err := s.orderRepo.Save(ctx, order); err != nil {
		return nil, err
	}

	// Publish events via an outbound port
	for _, event := range order.PullEvents() {
		_ = s.eventBus.Publish(ctx, event)
	}

	return &inbound.CreateOrderResponse{
		OrderID:    string(order.ID()),
		TotalCents: order.Total().Cents,
		Status:     string(order.Status()),
	}, nil
}

// adapter/inbound/http/order_handler.go
// HTTP Inbound Adapter: translates HTTP requests into inbound port calls
package http

import (
	"encoding/json"
	"net/http"

	"myapp/port/inbound"
)

// OrderHandler is the inbound adapter for HTTP
// ✓ It only translates HTTP → inbound port, no business logic
type OrderHandler struct {
	createOrder inbound.CreateOrderPort
}

func NewOrderHandler(createOrder inbound.CreateOrderPort) *OrderHandler {
	return &OrderHandler{createOrder: createOrder}
}

type createOrderHTTPRequest struct {
	CustomerID string          `json:"customer_id"`
	Items      []orderItemHTTP `json:"items"`
}

type orderItemHTTP struct {
	ProductID string `json:"product_id"`
	Quantity  int    `json:"quantity"`
	Price     int64  `json:"price"`
}

func (h *OrderHandler) CreateOrder(w http.ResponseWriter, r *http.Request) {
	var httpReq createOrderHTTPRequest
	if err := json.NewDecoder(r.Body).Decode(&httpReq); err != nil {
		http.Error(w, "invalid request", http.StatusBadRequest)
		return
	}

	// Map HTTP request → inbound port request
	portReq := inbound.CreateOrderRequest{
		CustomerID: httpReq.CustomerID,
		Items:      make([]inbound.CreateOrderItem, len(httpReq.Items)),
	}
	for i, item := range httpReq.Items {
		portReq.Items[i] = inbound.CreateOrderItem{
			ProductID:  item.ProductID,
			Quantity:   item.Quantity,
			PriceCents: item.Price,
		}
	}

	// Call the inbound port — does not know its implementation
	resp, err := h.createOrder.CreateOrder(r.Context(), portReq)
	if err != nil {
		http.Error(w, err.Error(), http.StatusUnprocessableEntity)
		return
	}

	w.Header().Set("Content-Type", "application/json")
	w.WriteHeader(http.StatusCreated)
	json.NewEncoder(w).Encode(resp)
}

// port/outbound/repository.go
// Outbound Ports: defined by the core, implemented by adapters
package outbound

import (
	"context"

	"myapp/domain"
)

// OrderRepository is the outbound port for persistence
// ✓ Defined on the core side, not the database side
type OrderRepository interface {
	Save(ctx context.Context, order *domain.Order) error
	FindByID(ctx context.Context, id domain.OrderID) (*domain.Order, error)
	FindByCustomer(ctx context.Context, customerID domain.CustomerID) ([]*domain.Order, error)
}

// InventoryChecker is the outbound port for checking stock availability
type InventoryChecker interface {
	CheckAvailability(ctx context.Context, items []domain.OrderItem) error
}

// EventPublisher is the outbound port for publishing domain events
type EventPublisher interface {
	Publish(ctx context.Context, event domain.DomainEvent) error
}

// EmailSender is the outbound port for sending emails
type EmailSender interface {
	Send(ctx context.Context, to, subject, body string) error
}

// adapter/outbound/postgres/order_repository.go
// PostgreSQL Outbound Adapter: implements outbound.OrderRepository
package postgres

import (
	"context"
	"database/sql"
	"fmt"

	"myapp/domain"
	"myapp/port/outbound"
)

// PostgresOrderRepository is the PostgreSQL adapter for outbound.OrderRepository
// ✓ Only this knows about SQL — the core does not need to
type PostgresOrderRepository struct {
	db *sql.DB
}

// Make sure PostgresOrderRepository implements the interface correctly
var _ outbound.OrderRepository = (*PostgresOrderRepository)(nil)

func NewPostgresOrderRepository(db *sql.DB) *PostgresOrderRepository {
	return &PostgresOrderRepository{db: db}
}

func (r *PostgresOrderRepository) Save(ctx context.Context, order *domain.Order) error {
	tx, err := r.db.BeginTx(ctx, nil)
	if err != nil {
		return fmt.Errorf("failed to begin transaction: %w", err)
	}
	defer tx.Rollback()

	_, err = tx.ExecContext(ctx,
		`INSERT INTO orders (id, customer_id, status, total_cents, created_at)
		 VALUES ($1, $2, $3, $4, NOW())
		 ON CONFLICT (id) DO UPDATE
		 SET status = $3, total_cents = $4`,
		string(order.ID()), string(order.CustomerID()),
		string(order.Status()), order.Total().Cents,
	)
	if err != nil {
		return fmt.Errorf("failed to save order: %w", err)
	}

	return tx.Commit()
}

func (r *PostgresOrderRepository) FindByID(
	ctx context.Context,
	id domain.OrderID,
) (*domain.Order, error) {
	// query implementation...
	return nil, nil
}

func (r *PostgresOrderRepository) FindByCustomer(
	ctx context.Context,
	customerID domain.CustomerID,
) ([]*domain.Order, error) {
	// query implementation...
	return nil, nil
}

// adapter/outbound/sendgrid/email_sender.go
// SendGrid Outbound Adapter: implements outbound.EmailSender
package sendgrid

import (
	"context"
	"fmt"
)

// SendGridEmailSender is the SendGrid adapter
// ✓ Swapping the email vendor only means swapping this adapter
type SendGridEmailSender struct {
	apiKey    string
	fromEmail string
}

var _ outbound.EmailSender = (*SendGridEmailSender)(nil)

func NewSendGridEmailSender(apiKey, fromEmail string) *SendGridEmailSender {
	return &SendGridEmailSender{apiKey: apiKey, fromEmail: fromEmail}
}

func (s *SendGridEmailSender) Send(ctx context.Context, to, subject, body string) error {
	// Call the SendGrid API...
	fmt.Printf("[SendGrid] Sending to %s: %s\n", to, subject)
	return nil
}

// application/create_order_service_test.go
package application_test

import (
	"context"
	"testing"

	"myapp/application"
	"myapp/domain"
	"myapp/port/inbound"
)

// Mock adapter for OrderRepository
type mockOrderRepository struct {
	savedOrders []*domain.Order
	shouldFail  bool
}

func (m *mockOrderRepository) Save(ctx context.Context, order *domain.Order) error {
	if m.shouldFail {
		return errors.New("database error")
	}
	m.savedOrders = append(m.savedOrders, order)
	return nil
}

func (m *mockOrderRepository) FindByID(ctx context.Context, id domain.OrderID) (*domain.Order, error) {
	return nil, nil
}

func (m *mockOrderRepository) FindByCustomer(ctx context.Context, customerID domain.CustomerID) ([]*domain.Order, error) {
	return nil, nil
}

// Mock adapter for InventoryChecker
type mockInventory struct {
	available bool
}

func (m *mockInventory) CheckAvailability(ctx context.Context, items []domain.OrderItem) error {
	if !m.available {
		return errors.New("insufficient stock")
	}
	return nil
}

// Mock adapter for EventPublisher
type mockEventPublisher struct {
	publishedEvents []domain.DomainEvent
}

func (m *mockEventPublisher) Publish(ctx context.Context, event domain.DomainEvent) error {
	m.publishedEvents = append(m.publishedEvents, event)
	return nil
}

// Test: testing CreateOrderService without a real database, HTTP, or Kafka
func TestCreateOrderService_Success(t *testing.T) {
	repo := &mockOrderRepository{}
	inventory := &mockInventory{available: true}
	events := &mockEventPublisher{}

	// ✓ Using mock adapters — no PostgreSQL or Kafka needed
	svc := application.NewCreateOrderService(repo, inventory, events)

	resp, err := svc.CreateOrder(context.Background(), inbound.CreateOrderRequest{
		CustomerID: "cust-123",
		Items: []inbound.CreateOrderItem{
			{ProductID: "prod-1", Quantity: 2, PriceCents: 50000},
		},
	})

	if err != nil {
		t.Fatalf("expected no error, got: %v", err)
	}
	if resp.OrderID == "" {
		t.Error("order ID must not be empty")
	}
	if resp.TotalCents != 100000 {
		t.Errorf("total should be 100000, got %d", resp.TotalCents)
	}
	if len(repo.savedOrders) != 1 {
		t.Errorf("expected 1 saved order, got %d", len(repo.savedOrders))
	}
	if len(events.publishedEvents) == 0 {
		t.Error("expected events to be published")
	}
}

func TestCreateOrderService_OutOfStock(t *testing.T) {
	repo := &mockOrderRepository{}
	inventory := &mockInventory{available: false} // ✓ simulate out of stock
	events := &mockEventPublisher{}

	svc := application.NewCreateOrderService(repo, inventory, events)

	_, err := svc.CreateOrder(context.Background(), inbound.CreateOrderRequest{
		CustomerID: "cust-123",
		Items: []inbound.CreateOrderItem{
			{ProductID: "prod-1", Quantity: 999, PriceCents: 50000},
		},
	})

	if err == nil {
		t.Error("expected an error when out of stock")
	}
	if len(repo.savedOrders) != 0 {
		t.Error("order must not be saved when out of stock")
	}
}

// Test using the CLI inbound adapter directly — no HTTP server
func TestCreateOrder_ViaDirectPort(t *testing.T) {
	// ✓ The test suite can call the inbound port directly — no HTTP server needed
	var svc inbound.CreateOrderPort = application.NewCreateOrderService(
		&mockOrderRepository{},
		&mockInventory{available: true},
		&mockEventPublisher{},
	)

	_, err := svc.CreateOrder(context.Background(), inbound.CreateOrderRequest{
		CustomerID: "cust-456",
		Items: []inbound.CreateOrderItem{
			{ProductID: "prod-2", Quantity: 1, PriceCents: 75000},
		},
	})

	if err != nil {
		t.Fatalf("expected no error: %v", err)
	}
}

// Before: using PostgreSQL
pgRepo := postgres.NewPostgresOrderRepository(postgresDB)

// After: migrating to MongoDB — only swap the adapter
// ✓ The application service does not change at all
mongoRepo := mongodb.NewMongoOrderRepository(mongoClient)

// Wiring in main.go — the only file that changes
svc := application.NewCreateOrderService(
	mongoRepo,   // ← swap this
	inventoryChecker,
	eventPublisher,
)

// ✗ Domain importing adapters — the most fundamental violation
package domain

import "myapp/adapter/outbound/postgres" // ✗ domain must not know about postgres

type OrderService struct {
    repo *postgres.PostgresOrderRepository // ✗ dependency on a concrete adapter
}

// ✓ Domain only knows about ports (interfaces)
package domain

import "myapp/port/outbound" // ✓ only interfaces

type OrderService struct {
    repo outbound.OrderRepository // ✓ dependency on an interface
}

// ✗ Business logic in an adapter — adapters should only translate
func (h *OrderHandler) CreateOrder(w http.ResponseWriter, r *http.Request) {
    // ✗ business validation in an HTTP handler
    if req.Quantity > 100 {
        http.Error(w, "quantity too large", http.StatusBadRequest)
        return
    }
    // ✗ price calculation in the HTTP adapter
    total := req.Quantity * req.Price * 0.9 // 10% discount
    // ...
}

// ✓ Thin adapters — only parse, delegate, format
func (h *OrderHandler) CreateOrder(w http.ResponseWriter, r *http.Request) {
    var req createOrderHTTPRequest
    json.NewDecoder(r.Body).Decode(&req)
    resp, err := h.createOrder.CreateOrder(r.Context(), mapToPortRequest(req)) // ✓
    if err != nil {
        http.Error(w, err.Error(), http.StatusUnprocessableEntity)
        return
    }
    json.NewEncoder(w).Encode(resp)
}

// ✗ Outbound ports defined on the adapter side — ownership violation
// adapter/outbound/postgres/repository.go
package postgres

type OrderRepository interface { // ✗ interface on the implementation side
    Save(order *Order) error
}

// ✓ Outbound ports are defined on the core side — the core determines the needs
// port/outbound/repository.go
package outbound

type OrderRepository interface { // ✓ interface on the core side
    Save(ctx context.Context, order *domain.Order) error
}