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)

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

- Format: PREFIX-XXYYYY - One error per file

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

- String types - SCREAMINGSNAKECASE values

Step 3: Application Layer

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

- Service contracts - Use domain entities

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

- Atomic operations - FindX, SaveX, UpdateX, DeleteX

1. 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 } ``

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

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

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

- Handle HTTP - DTO↔Entity conversion

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

- GORM annotations - ToEntity() methods

1. 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()) ``

1. 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](references/layer-implementation.md) - Complete layer examples
• [Critical Patterns](references/critical-patterns.md) - Must-know patterns
• [Implementation Workflow](references/implementation-workflow.md) - 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