clean-architecture-golang

name

clean-architecture-golang

description

Expert implementation guide for custom Clean Architecture pattern in Golang projects. Use when implementing features with domain-driven design, creating API endpoints, or working with this specific 4-layer architecture (Domain, Application, Integration, Infrastructure). NOT Uncle Bob's standard Clean Architecture - this is a specialized adaptation with strict dependency rules and specific conventions.

Custom Clean Architecture Implementation Guide

Expert guidance for implementing features using this project's custom Clean Architecture pattern with Golang. This is NOT Uncle Bob's standard Clean Architecture - it's a specialized adaptation.

Architecture Overview

Four layers with strict dependency rules:

Integration → Application → Domain ← Infrastructure

Dependency Rule: Inner layers NEVER depend on outer layers.

🚨 Critical Rules

MUST DO

• START with BDD feature file - Never skip test-first development
• Integration adapters MUST implement usecase interfaces - Enable type casting
• Use context.Context as first parameter - Always
• Convert at boundaries - DTO↔Entity↔Model
• Follow error code format - PREFIX-XXYYYY
• Type cast repositories to usecases - In dependency injection

NEVER DO

• Skip BDD test creation - Tests come first
• Create adapters without usecase interfaces - Will break dependency injection
• Put business logic in controllers/repositories - Only in services
• Use DTOs in domain/application - Only in integration layer
• Access database from services - Only through usecases
• Create circular dependencies - Dependencies flow inward only

Implementation Workflow

Step 1: Create BDD Test (MANDATORY)

Start here ALWAYS. Location: /test/integration/features/

Feature: Create entity functionality
  Scenario: Create entity success
    When I call "POST" "/v1/entities" with payload
    Then status should be 201
    And db should contain entity

Step 2: Domain Layer

1. Entity (/internal/domain/entity/)

   • Simple structs, NO logic
   • Audit fields (CreatedAt, UpdatedAt)

2. Errors (/internal/domain/error/)

   • Format: PREFIX-XXYYYY
   • One error per file

3. Enums (/internal/domain/enums/)

   • String types
   • SCREAMING_SNAKE_CASE values

Step 3: Application Layer

1. Adapter Interface (/internal/application/adapter/)

   • Service contracts
   • Use domain entities

2. UseCase Interfaces (/internal/application/usecase/)

   • Atomic operations
   • FindX, SaveX, UpdateX, DeleteX

3. Service Implementation (/internal/application/service/)

   • Business logic HERE
   • Orchestrate usecases

Step 4: Integration Layer

1. Adapter Interfaces (/internal/integration/adapter/)

   type Repository interface {
       usecase.Find    // MUST embed
       usecase.Save    // MUST embed
   }
   

2. DTOs (/internal/integration/entrypoint/dto/)

   • Request/Response structs
   • ToEntity() methods
   • Validation tags

3. Controller (/internal/integration/entrypoint/controller/)

   • Handle HTTP
   • DTO↔Entity conversion

4. Model (/internal/integration/persistence/model/)

   • GORM annotations
   • ToEntity() methods

5. Repository (/internal/integration/persistence/)

   • Implements usecase interfaces
   • Entity↔Model conversion

Step 5: Infrastructure Layer

1. Dependency Injection (/internal/infra/dependency/injector.go)

   // Type cast repository to usecase
   usecase.Find(i.GetRepository())
   

2. Router (/internal/infra/server/router/router.go)

   • Add routes
   • Validation middleware

Step 6: Run Tests

make test-integration

Quick Patterns

Integration Adapter Pattern (CRITICAL)

// Application defines need
type FindProduct interface {
    FindById(ctx, id) (*entity, error)
}

// Integration MUST implement
type ProductRepository interface {
    usecase.FindProduct  // EMBED!
}

// Type cast in DI
usecase.FindProduct(repository)

Error Codes

• CLI-01409 = Client conflict (409)
• USR-01404 = User not found (404)
• PRD-02500 = Product server error (500)

Conversion Flow

Request → DTO → Entity → Model → DB
Response ← DTO ← Entity ← Model ← DB

Reference Documentation

Detailed guides in references/:

• Layer Implementation - Complete layer examples
• Critical Patterns - Must-know patterns
• Implementation Workflow - Step-by-step guide

Templates

Ready-to-use templates in assets/:

• entity-template.go - Domain entity template
• service-template.go - Application service template
• repository-template.go - Repository template

Implementation Checklist

Before starting any feature:

• BDD feature file exists
• Domain entity defined
• Domain errors created
• Application adapter interface defined
• Application usecases created
• Application service implemented
• Integration adapters created WITH usecase interfaces
• DTOs with ToEntity() methods
• Controller handling HTTP
• Model with ToEntity() method
• Repository implementing usecases
• Dependencies wired in injector
• Routes added to router
• Tests passing

Common Mistakes to Avoid

1. Forgetting usecase interfaces on adapters - Breaks type casting
2. Business logic in wrong layer - Only in services
3. Wrong dependency direction - Check imports
4. Missing BDD test - Always start with test
5. Wrong error code format - Use PREFIX-XXYYYY
6. Not converting at boundaries - DTO↔Entity↔Model

Example Implementations

Study these existing implementations:

• Client: /internal/{domain,application,integration}/*/client*.go
• User: /internal/{domain,application,integration}/*/user*.go
• Forest: /internal/{domain,application,integration}/*/forest*.go