Add Domain Entity

Create domain layer components for a new entity following DDD patterns.

Prerequisites

• Database table created (use add-database-table skill first)
• SQLBoiler model generated via

  make migrate.up

Quick Workflow

1. Domain Model     → internal/domain/model/{entity}.go
2. Domain Error     → internal/domain/errors/errors.go
3. Repository Interface → internal/domain/repository/{entity}.go
4. Marshaller       → internal/infrastructure/{db}/internal/marshaller/{entity}.go
5. Repository Impl  → internal/infrastructure/{db}/repository/{entity}.go
6. Generate Mocks   → make generate.mock

Step 1: Create Domain Model

Location:

internal/domain/model/{entity}.go

Create the entity struct, constructor, update methods, and type aliases.

Key requirements:

• Use

  id.New()

  for ID generation in constructor
• Set both

  CreatedAt

  and

  UpdatedAt

  to the same time parameter
• Define

  ReadonlyReference

  for relations (always nil in constructor)
• Create slice type alias:

  type Examples []*Example

See: references/domain-model-patterns.md

Step 2: Add Domain Error

Location:

internal/domain/errors/errors.go

Add a not-found error for the entity:

ExampleNotFoundErr = NewNotFoundError("E2xxxxx", "Example not found")

Follow error code conventions from

.claude/rules/domain-errors.md

.

Step 3: Create Repository Interface

Location:

internal/domain/repository/{entity}.go

Define the repository interface with standard CRUD operations and query structs.

Key requirements:

• Add

  //go:generate

  directive for mock generation
• Use

  nullable.Type[T]

  for optional enum/custom type filter fields
• Embed

  BaseGetOptions

  /

  BaseListOptions

  in query structs

See: references/repository-patterns.md

Step 4: Create Marshaller

Location:

internal/infrastructure/{mysql|postgresql|spanner}/internal/marshaller/{entity}.go

Convert between DB models and domain models.

Key requirements:

• Related entity's

  ReadonlyReference

  must remain nil (no recursive loading)
• Use var declaration pattern for nullable timestamp fields
• Include both

  ToModel

  and

  ToDBModel

  functions

See: references/marshaller-patterns.md

Step 5: Create Repository Implementation

Location:

internal/infrastructure/{mysql|postgresql|spanner}/repository/{entity}.go

Implement the repository interface using SQLBoiler.

Key requirements:

• Use

  transactable.GetContextExecutor(ctx)

  for all DB operations
• Implement

  buildListQuery

  helper for reusable filter logic
• Implement

  buildPreload

  helper for relation loading
• Use base helper functions:

  addForUpdateFromBaseGetOptions

  ,

  addForUpdateFromBaseListOptions

See: references/repository-patterns.md

Step 6: Generate Mocks

make generate.mock

This generates mock implementations in

internal/domain/repository/mock/

.

Checklist

Domain Model

• Entity struct with all fields

• ReadonlyReference

  for relations (if any)
• Constructor with

  id.New()

  and

  ReadonlyReference: nil

• Update method using

  null.*

  types for optional fields
• Slice type alias (

  Examples []*Example

  )
• Helper methods on slice (

  IDs()

  ,

  MapByID()

  )

Status/Enum Types (if needed)

• Type definition with

  Unknown

  as first constant

• String()

  and

  Valid()

  methods

• New{Type}(str string)

  constructor

Repository

• Interface with

  //go:generate

  directive
• Query structs with

  nullable.Type[T]

  for optional enums
• Domain error added for not-found case

Implementation

• Marshaller with

  ToModel

  ,

  ToDBModel

  ,

  ToModels

  ,

  ToDBModels

• Marshaller handles

  ReadonlyReference

  correctly
• Repository implementation with all CRUD methods

• buildListQuery

  and

  buildPreload

  helpers
• Mocks generated

Next Steps

After creating domain entity, use add-api-endpoint skill to create:

• Usecase input/output structs
• Interactor interface and implementation
• Protocol Buffers definition
• gRPC handler