The
Engineer's
Codex

// DDD Aggregate in Java 21 — the full idiom
public class Payment {  // Aggregate Root
    private final PaymentId   id;          // typed identity, not String
    private final Money       amount;      // Value Object, not BigDecimal
    private       PaymentStatus status;
    private final List<DomainEvent> events = new ArrayList<>();

    // Business methods express domain language, not CRUD
    public void authorize(RiskAssessment risk) {
        if (status != PaymentStatus.PENDING)
            throw new InvalidPaymentStateException(id, status, "authorize");
        if (risk.isHighRisk() && amount.exceeds(Money.of(10000, USD)))
            throw new RiskLimitExceededException(id, risk);
        
        this.status = PaymentStatus.AUTHORIZED;
        events.add(new PaymentAuthorized(id, Instant.now(), amount));
    }

    // Invariant: amount must be positive — enforced in constructor/factory
    public static Payment create(Money amount, Merchant merchant) {
        if (!amount.isPositive()) throw new IllegalArgumentException("Amount must be positive");
        var p = new Payment(PaymentId.generate(), amount, merchant);
        p.events.add(new PaymentCreated(p.id, amount, merchant.id()));
        return p;
    }
}

// JWT = Header.Payload.Signature (base64url encoded, dot-separated)
// Spring Security 6 JWT Resource Server
@Configuration
@EnableWebSecurity
class SecurityConfig {
    @Bean
    SecurityFilterChain chain(HttpSecurity http) throws Exception {
        return http
            .authorizeHttpRequests(auth -> auth
                .requestMatchers("/actuator/health").permitAll()
                .requestMatchers(HttpMethod.POST, "/payments")
                    .hasAuthority("SCOPE_payments:write")   // scope-based
                .requestMatchers(HttpMethod.GET, "/payments/**")
                    .hasAuthority("SCOPE_payments:read")
                .anyRequest().authenticated())
            .oauth2ResourceServer(o -> o
                .jwt(j -> j.jwtAuthenticationConverter(jwtConverter())))
            .sessionManagement(s -> s
                .sessionCreationPolicy(STATELESS))   // no session cookies
            .build();
    }
}

// Every financial movement = two ledger entries that sum to zero
record LedgerEntry(
    UUID       id,
    UUID       transactionId,
    AccountId accountId,
    Money      amount,       // positive = debit, negative = credit
    EntryType type,         // DEBIT or CREDIT
    Instant   postedAt
) {}

// Transfer $100 from Customer A to Customer B:
var entries = List.of(
    new LedgerEntry(uuid(), txId, customerA, Money.of(100), DEBIT,  now()),
    new LedgerEntry(uuid(), txId, customerB, Money.of(100), CREDIT, now())
);

// INVARIANT: sum of all entries for a transaction = 0
// DEBIT 100 + CREDIT -100 = 0  ✓
assert entries.stream()
    .map(e -> e.type() == DEBIT ? e.amount() : e.amount().negate())
    .reduce(Money.ZERO, Money::add)
    .equals(Money.ZERO);  // Must always pass