dto

DTO and Data Definition Placement Rules

Overview

Rules for where to define data types (DTOs, wire types, presentation types) and where to place conversion logic in the Clean Architecture layers of internal/.

Layer Summary

Interface Adapters  → defines: presentation input/output types (CLI args, HTTP body, gRPC message)
                      converts: presentation → application DTO before calling use case

Application Layer   → defines: canonical cross-boundary DTOs (internal/application/dto/)
                      port interfaces use ONLY these types in their signatures

Infrastructure      → defines: internal wire/DB types (JSON-tagged structs, ORM models)
                      converts: wire types ↔ application DTOs at the boundary

Domain Layer        → defines: domain entities, value objects (with business logic — NOT DTOs)
                      no conversion, no DTOs

Rules

1. Application DTOs Are the Canonical Cross-Boundary Types

All types used in application/ports/ interface signatures MUST be defined in internal/application/dto/. Infrastructure types MUST NOT appear in port interface signatures.

// ✅ GOOD: port interface uses application DTO
// internal/application/ports/api/xrp/interface.go
type TransactionPreparer interface {
    CreateRawTransaction(
        ctx context.Context,
        senderAccount, receiverAccount string,
        amount float64,
        instructions *dtoxrp.Instructions,  // application DTO
    ) (*dtoxrp.TxInput, string, error)       // application DTO
}

// ❌ BAD: port interface returns an infrastructure package type
type KeyGenerator interface {
    WalletPropose(ctx context.Context, passphrase string) (*xrprpcadmin.ResponseWalletPropose, error)
    //                                                      ^^^^^^^^^ infrastructure type in port
}

2. Infrastructure Defines Wire Types Locally, Converts at the Boundary

Infrastructure packages may define their own internal types optimised for wire format (JSON tags, protocol buffer fields, etc.). These must be converted to/from application DTOs before crossing the boundary.