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