Claude-skill-registry kratos-biz-layer

<essential_principles>

How Kratos Business Layer Works

Clean Architecture Dependency Rule

The business layer (biz) is the core of Clean Architecture in Kratos microservices:

Dependency Flow: Service → Biz → Data

• Biz defines interfaces that data layer implements
• Biz contains business logic independent of frameworks
• Biz uses domain models not ORM entities

Domain-Driven Structure (Current Pattern)

The biz layer follows domain-driven design with these subdirectories:

1. Domain Layer (

internal/biz/domain/

)

• models.go

  - Domain entities with validation tags

• interfaces.go

  - Repository, use case, and event publisher interfaces

• errors.go

  - Domain errors (ErrSymbolNotFound) and data layer errors (ErrDataNotFound)

2. Use Case Layer (

internal/biz/{entity}/

)

• usecase.go

  - Use case implementation

• usecase_test.go

  - Use case tests with event assertions

• validator.go

  - Validation logic factory

3. Event Layer (

internal/biz/event/

) - Optional

• mapper.go

  - Event payload transformations

• topics.go

  - Event topic constants

4. Provider (

internal/biz/provider.go

)

• Wire ProviderSet for dependency injection

Error Separation Pattern

Data Layer Errors (returned by repositories):

• domain.ErrDataNotFound

  - Record not found

• domain.ErrDataDuplicateEntry

  - Unique constraint violation

• domain.ErrDataDatabase

  - Generic database error

Domain Errors (returned by use cases):

• domain.ErrSymbolNotFound

  - Symbol not found (business error)

• domain.ErrDuplicateSymbol

  - Duplicate symbol (business error)

• domain.ErrDatabaseOperation

  - Database operation failed

Pattern: Repositories return data errors, use cases map to domain errors via

toDomainError()

helper.

Event Publishing Pattern

Use cases integrate event publishing for domain events:

• Accept

  domain.{Entity}EventPublisher

  interface
• Publish events within transactions
• Transaction rolls back if publishing fails

Example:

err := uc.tm.InTx(ctx, func(ctx context.Context) error {
    symbol, err = uc.repo.Create(ctx, s)
    if err != nil {
        return err
    }
    return uc.pub.PublishSymbolCreated(ctx, symbol)
})

Wire Dependency Injection

All constructors must be added to

ProviderSet

in

internal/biz/provider.go

:

var ProviderSet = wire.NewSet(symbol.NewValidator, symbol.NewUseCase)

After changes, run

make generate

to regenerate Wire code. </essential_principles>

<intake> What would you like to do?

1. Create a new entity (use case + interface + model + validator)
2. Add methods to existing use case
3. Create standalone validator
4. View examples and patterns

Wait for response before proceeding. </intake>

<routing> | Response | Workflow | |----------|----------| | 1, "create", "new entity", "new" | `workflows/create-entity.md` | | 2, "add method", "add", "extend" | `workflows/add-methods.md` | | 3, "validator", "validation" | `workflows/create-validator.md` | | 4, "examples", "patterns", "help" | `workflows/view-examples.md` |

After reading the workflow, follow it exactly. </routing>

<reference_index> All domain knowledge in

references/

:

Core Patterns: use-case-pattern.md, interface-pattern.md, model-pattern.md Code Style: naming-conventions.md

Additional patterns (error handling, logging, transactions, testing) are covered within use-case-pattern.md. </reference_index>

<workflows_index>

Workflow	Purpose
create-entity.md	Generate complete biz layer for new entity
add-methods.md	Add CRUD methods to existing use case
create-validator.md	Create standalone validator
view-examples.md	Show patterns and examples
</workflows_index>

<success_criteria> Business layer code is correct when:

Structure:

• Domain models in

  internal/biz/domain/models.go

• Interfaces in

  internal/biz/domain/interfaces.go

• Errors in

  internal/biz/domain/errors.go

• Use case in

  internal/biz/{entity}/usecase.go

• Validator in

  internal/biz/{entity}/validator.go

• Tests in

  internal/biz/{entity}/usecase_test.go

Use Case Implementation:

• Struct has repo, pub, log, validator, tm fields
• Constructor returns interface type (domain.{Entity}UseCase)
• Methods accept context.Context as first parameter
• Validation happens before repository calls
• Data errors mapped to domain errors via

  toDomainError()

• Events published within transactions
• All errors logged with context

Domain Layer:

• Repository interface in

  domain/interfaces.go

• Event publisher interface in

  domain/interfaces.go

  (if events)
• Business model in

  domain/models.go

  with validation tags
• Domain errors (ErrSymbolNotFound) separated from data errors (ErrDataNotFound)

Wire Integration:

• Constructor added to ProviderSet in

  internal/biz/provider.go

• User reminded to run

  make generate

  </success_criteria>