DDD tactical building blocks and strategic concepts

package com.bank.model;

import jakarta.persistence.Entity;
import jakarta.persistence.Id;
import jakarta.persistence.Version;
import java.math.BigDecimal;
import java.util.Objects;

@Entity
public class Account {

    @Id
    private String accountId;   // identity
    private String holderName;
    private BigDecimal balance;
    @Version
    private Long version;

    public void debit(BigDecimal amount) {
        if (balance.compareTo(amount) < 0) {
            throw new IllegalStateException("Insufficient funds");
        }
        balance = balance.subtract(amount);
    }

    public void credit(BigDecimal amount) {
        balance = balance.add(amount);
    }

    // Equality by identity, not by field values.
    @Override
    public boolean equals(Object o) {
        if (this == o) return true;
        if (!(o instanceof Account a)) return false;
        return Objects.equals(accountId, a.accountId);
    }

    @Override
    public int hashCode() {
        return Objects.hash(accountId);
    }
}

Account SAV2001 (balance 500000) != Account SAV2002 (balance 500000)
Same balance, different identity -> different entities.

package com.bank.model;

import java.math.BigDecimal;

// Value Object: immutable, no identity, value-based equality.
// Java record gives all of this for free.
public record Money(BigDecimal amount, String currency) {

    public Money {
        if (amount == null || amount.compareTo(BigDecimal.ZERO) < 0) {
            throw new IllegalArgumentException("Amount must be non-negative");
        }
        if (currency == null || currency.isBlank()) {
            throw new IllegalArgumentException("Currency is required");
        }
    }

    public Money add(Money other) {
        if (!this.currency.equals(other.currency)) {
            throw new IllegalArgumentException("Cannot add different currencies");
        }
        return new Money(this.amount.add(other.amount), this.currency);
    }

    public Money subtract(Money other) {
        if (!this.currency.equals(other.currency)) {
            throw new IllegalArgumentException("Cannot subtract different currencies");
        }
        return new Money(this.amount.subtract(other.amount), this.currency);
    }
}

new Money(new BigDecimal("50000"), "INR")
  .equals(new Money(new BigDecimal("50000"), "INR"))  -> true

Value Objects prevent bugs:
  WRONG: account.debit(new BigDecimal("50000"))  // what currency?
  CORRECT: account.debit(new Money(new BigDecimal("50000"), "INR"))

package com.bank.model;

import java.math.BigDecimal;
import java.util.ArrayList;
import java.util.Collections;
import java.util.List;

public class LoanAccount {  // Aggregate Root

    private final String loanId;
    private BigDecimal principal;
    private final List<EmiPayment> payments = new ArrayList<>(); // child entities

    public LoanAccount(String loanId, BigDecimal principal) {
        this.loanId = loanId;
        this.principal = principal;
    }

    // All changes go through the root.
    public void recordEmiPayment(Money amount) {
        principal = principal.subtract(amount.amount());
        payments.add(new EmiPayment(loanId, amount, payments.size() + 1));
    }

    public List<EmiPayment> getPayments() {
        return Collections.unmodifiableList(payments);
    }
    // Never access EmiPayment directly. Always through LoanAccount root.
}

Aggregate = LoanAccount (root) + EmiPayment (child entities)
Invariant: principal decreases correctly with each EMI.
Access: only through root methods.

package com.bank.repository;

import com.bank.model.Account;
import org.springframework.data.jpa.repository.JpaRepository;

// One repository per aggregate root.
// There is NO EmiPaymentRepository. Access EMI through LoanAccountRepository.
public interface AccountRepository extends JpaRepository<Account, String> {
    // findById loads the entire Account aggregate.
    // save persists the entire Account aggregate.
}

Rule: one repository per aggregate root.
  AccountRepository -> loads/saves Account aggregate.
  LoanAccountRepository -> loads/saves LoanAccount aggregate (includes EMI payments).
  NEVER: EmiPaymentRepository (not an aggregate root).

package com.bank.domain;

import com.bank.model.Money;
import java.math.BigDecimal;
import org.springframework.stereotype.Service;

// Domain Service: stateless domain logic that spans entities.
@Service
public class InterestCalculator {

    public Money calculateInterest(BigDecimal principal, BigDecimal rate, int months) {
        BigDecimal interest = principal.multiply(rate)
            .multiply(BigDecimal.valueOf(months))
            .divide(BigDecimal.valueOf(1200), 2, java.math.RoundingMode.HALF_UP);
        return new Money(interest, "INR");
    }
}

package com.bank.application;

import com.bank.domain.InterestCalculator;
import com.bank.repository.AccountRepository;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;
import java.math.BigDecimal;

// Application Service: orchestrates the use case. No business rules here.
@Service
public class TransferApplicationService {

    private final AccountRepository accountRepo;
    private final InterestCalculator interestCalc;

    public TransferApplicationService(AccountRepository accountRepo,
                                       InterestCalculator interestCalc) {
        this.accountRepo = accountRepo;
        this.interestCalc = interestCalc;
    }

    @Transactional
    public void transfer(String fromId, String toId, BigDecimal amount) {
        var from = accountRepo.findById(fromId).orElseThrow();
        var to = accountRepo.findById(toId).orElseThrow();
        from.debit(amount);  // business rule inside entity
        to.credit(amount);   // business rule inside entity
        accountRepo.save(from);
        accountRepo.save(to);
    }
}

Domain Service: contains business rules (interest calculation).
Application Service: orchestrates (load, call, save). NO business rules.
Entities: enforce their own invariants (balance >= 0).

Strategic concepts:

  Bounded Context: boundary where one model is consistent.
    Deposits: Account = savings account
    Lending: Account = loan account

  Ubiquitous Language: team uses same words in code, docs, conversation.
    Lending team says "sanction", "EMI", "tenure".

  Context Mapping: how contexts relate.
    Shared Kernel: small shared model
    Customer-Supplier: one depends on another
    Anti-Corruption Layer: translation at border

  Domain Events: decouple contexts.
    Deposits publishes FundsDebited.
    Lending reacts without sharing Deposits model.