golang-clean-architecture

Golang Clean Architecture

Audit Go services for Clean Architecture compliance. Ensures proper layering, dependency rules, and separation of concerns in gRPC → Usecase → Repository → Domain architectures.

When to Apply

Use this skill when:

• Auditing service architecture
• Reviewing new features for layer violations
• Refactoring toward Clean Architecture
• Code review for dependency rules
• Planning service structure
• Migrating to layered architecture
• Ensuring testability through dependency injection

Architecture Layers

┌─────────────────────────────────────┐
│  Delivery (gRPC/HTTP/GraphQL)       │ ← Thin, no business logic
├─────────────────────────────────────┤
│  Usecase (Business Logic)           │ ← Orchestration
├─────────────────────────────────────┤
│  Repository (Data Access)           │ ← CRUD only
├─────────────────────────────────────┤
│  Domain (Entities/Interfaces)       │ ← Pure business logic
└─────────────────────────────────────┘

Dependency Rule: Dependencies point INWARD only (toward domain).

Rules Covered (9 total)

High-Impact Patterns (4)

• high-business-logic-handler - Keep delivery layer thin
• high-business-logic-repository - No business logic in data layer
• high-constructor-creates-deps - Inject dependencies, don't create
• high-transaction-in-repository - Transactions belong in usecase

Architecture Rules (5)

• arch-domain-import-infra - Domain must not import infrastructure
• arch-concrete-dependency - Depend on interfaces, not concrete types
• arch-repository-business-logic - Repositories do CRUD only
• arch-usecase-orchestration - Usecases orchestrate, entities decide
• arch-interface-segregation - Small, consumer-defined interfaces

Common Violations

❌ Business Logic in Handler

// gRPC handler doing calculations
func (h *Handler) CreateOrder(ctx context.Context, req *pb.Request) (*pb.Response, error) {
    total := req.Price * req.Quantity // BAD: calculation in handler
    discount := total * 0.1           // BAD: business rules in delivery layer
    
    order := &domain.Order{
        Total: total - discount,
    }
    return h.orderRepo.Save(ctx, order)
}