internal-interface

Interface Definition Rules for internal/

Overview

Rules for defining and using interfaces inside the internal/ directory. These rules enforce the Interface Segregation Principle (ISP) throughout the codebase.

Core Principles

Interfaces are defined where they are used, not where they are implemented. The application/ports layer owns all interface definitions. The infrastructure layer contains only concrete implementations — never interface definitions.

Depend only on the methods you actually call. Use cases and adapters must declare only the interface surface they need — never a broader one.

Rules

0. Interface Ownership: application/ports Defines, infrastructure Implements

All interfaces for external dependencies (blockchain APIs, repositories, file storage) MUST be defined in internal/application/ports/. The infrastructure/ layer MUST NOT define any interfaces — only concrete structs that implement them.

internal/application/ports/api/btc/interface.go  ← interface definitions live here
internal/infrastructure/api/btc/bitcoin.go        ← concrete implementation only

// ❌ BAD: interface defined in infrastructure layer
// internal/infrastructure/api/btc/bitcoin.go
type BitcoinAPI interface {
    GetBalance() (float64, error)
}

// ✅ GOOD: interface defined in application/ports, infrastructure only implements
// internal/application/ports/api/btc/interface.go
type BalanceChecker interface {
    GetBalance() (btcutil.Amount, error)
}

// internal/infrastructure/api/btc/bitcoin.go
type Bitcoin struct { ... }
func (b *Bitcoin) GetBalance() (btcutil.Amount, error) { ... } // implements BalanceChecker

1. Never Use Bitcoiner or BCHer Directly

apibtc.Bitcoiner and apibtc.BCHer are legacy monolithic interfaces. They must NEVER appear as parameters or field types in use cases or adapters.

// ❌ BAD: depends on the full monolithic interface
type myUseCase struct {
    btc apibtc.Bitcoiner
}

// ✅ GOOD: depends on only what is needed
type myUseCase struct {
    btc apibtc.MultisigManager
}