Clean Architecture is a software architecture proposed by Robert C. Martin. Its goal is to clearly separate layers so the system is easier to maintain, extend, and test.

The pascalia-spec project applies Clean Architecture with 4 main layers:

Domain Layer: Core business logic (entities, interfaces, business rules)

Application / Usecase Layer: Application logic (orchestration, use cases)

Presentation Layer: User interface communication (handlers, APIs)

Infrastructure Layer: External technical concerns (DB, external APIs)

Key Principle:

Dependencies always point inward (outer layers depend on inner layers, never the opposite).

internal/
├── burton/                          # Bounded context for "burton" domain
│   ├── domain/                      # Domain Layer
│   │   └── repository/              # Interfaces (e.g., IAddPointRepository)
│   ├── infrastructure/              # Infrastructure Layer
│   │   └── repository/              # Repository implementations (DB access)
│   └── usecase/                     # Application / Usecase Layer
├── presentation/                    # Presentation Layer
│   └── grpc/
│       └── handler/                 # gRPC handlers
├── constant/                        # Constants (cross-cutting)
├── infrastructure/                  # Shared infrastructure (DB transactions)
└── validator/                       # Input validation (cross-cutting)

Dependency Direction:

Infrastructure → Domain ← Application ← Presentation

 Client (gRPC Request) ↓ Presentation Layer (SSOHandler) - Receive request - Validate input ↓ Application Layer (ISSOUsecase) - Orchestrate business logic ↓ Domain Layer (Repository Interface) - Define contracts ↓ Infrastructure Layer (Repository Implementation) - Access DB / External API ↓ Database / External Service 

 // internal/burton/domain/repository/add_point_repository.go type IAddPointRepository interface { FetchProcessingOrders(ctx context.Context, limit, offset int) ([]ProcessingOrders, error) SaveOrders(ctx context.Context, orders []ValidOrder) error } 

Purpose:

Define contracts for business logic

No implementation

No dependency on DB or frameworks

 // internal/burton/usecase/point_add_usecase.go type PointAddUsecase struct { repo IAddPointRepository }
 
func (u *PointAddUsecase) PointAdd(ctx context.Context) error {
orders, err := u.repo.FetchProcessingOrders(ctx, 200, 0) // Batch size 200
if err != nil {
return err
}
// Calculate points:
// product_total - adjusted_merchandize_total_tax
// Generate CSV, upload to Yappli
return nil
}

Purpose:

Orchestrate business logic

Use interfaces, not implementations

Easy to unit test using mocks

 // internal/presentation/grpc/handler/burton/SSO.go type SSOHandler struct { SSOService usecase.ISSOUsecase }
 
func (h *SSOHandler) Authenticate(
ctx context.Context,
req *pb.AuthRequest,
) (*pb.AuthResponse, error) {
 
// Validate input
if err := validator.ValidateSSO(req); err != nil {
    return nil, err
}
 
// Call usecase
return h.SSOService.Authenticate(ctx, req)
 
 
}

Purpose:

Receive requests

Validate input

Delegate logic to usecase

No business rules here

 // internal/burton/infrastructure/repository/pointadd_repository.go type AddPointRepository struct { db *sqlx.DB }
 
func (r *AddPointRepository) FetchProcessingOrders(
ctx context.Context,
limit, offset int,
) ([]ProcessingOrders, error) {
 
query := `
    SELECT ...
    FROM customers c
    INNER JOIN orders o ...
    LIMIT ? OFFSET ?
`
return r.db.SelectContext(ctx, &orders, query, limit, offset)
 
 
}

Purpose:

Implement domain interfaces

Handle DB / external APIs

Depends on Domain, not Usecase or Presentation

Domain → depends on nothing

Application → depends on Domain

Presentation → depends on Application

Infrastructure → depends on Domain (via interfaces)

Inject interfaces, not concrete structs Example: usecase.ISSOUsecase

Easy to mock for testing:

mockRepo := &MockAddPointRepository{}

Constants → internal/constant/ Example: DefaultChunk = 200

Validation → internal/validator/

Transactions / DB setup → internal/infrastructure/database/

Unit Tests

Test each layer independently

Mock dependencies

Integration Tests

End-to-end with real DB

Example:

Test usecase with a mock repository

Use fastmedia/errors for structured errors

Log with slog in:

Presentation layer

Usecase layer

Feature: Register Customer

Steps:

Domain

Create ICustomerRepository interface

Application

Create RegisterCustomerUsecase

Presentation

Create gRPC handler RegisterHandler

Infrastructure

Implement CustomerRepository using sqlx

Flow:

Handler → Usecase → Repository Interface → Repository Implementation → DB

By following Clean Architecture in this project:

Dependencies always point inward

Interfaces decouple layers

Each bounded context (e.g. burton) is cleanly separated

Code becomes easier to:

Maintain

Test

Scale