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/)

   go

   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)

   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