Beginner

// Anemic model - just data, no behavior
class BankAccount {
  // => BankAccount: domain model element
  constructor(
    // => Maintains consistency boundary
    public accountNumber: string, // => Public fields break encapsulation
    // => Applies domain event
    public balance: number, // => Can be modified without validation
    // => Coordinates with bounded context
    public isActive: boolean,
    // => Field: isActive (public)
  ) {}
  // => Executes domain logic
}
// => Updates aggregate state

// Business logic in separate service
class BankingService {
  // => BankingService: domain model element
  withdraw(account: BankAccount, amount: number): void {
    // => Operation: withdraw()
    if (!account.isActive) {
      // => Business rule in service (not domain object)
      throw new Error("Account inactive");
      // => Raise domain exception
    }
    // => Validates business rule

    if (account.balance < amount) {
      // => Operation: if()
      throw new Error("Insufficient funds");
      // => Raise domain exception
    }
    // => Enforces invariant

    account.balance -= amount; // => Direct mutation, no protection or events
    // => Implements tactical pattern
  }
  // => Encapsulates domain knowledge
}
// => Delegates to domain service

// Usage
const account = new BankAccount("123", 1000, true);
// => account: {accountNumber: "123", balance: 1000, isActive: true}
const service = new BankingService();
// => Protects aggregate integrity
service.withdraw(account, 500); // => account.balance becomes 500
// => Ensures transactional consistency
console.log(account.balance); // => Output: 500

// Rich domain model - data + behavior + business rules
class BankAccount {
  // => BankAccount: domain model element
  constructor(accountNumber: string, initialBalance: number) {
    // => Initialize object with parameters
    this.accountNumber = accountNumber;
    // => Update accountNumber state
    this.balance = initialBalance;
    // => Update balance state
    this.isActive = true;
    // => New accounts active by default
    // => Business rule: accounts start active
  }
  // => Executes domain logic

  withdraw(amount: number): void {
    // => Operation: withdraw()
    this.ensureIsActive();
    // => Business rule #1: must be active to withdraw
    this.ensureSufficientFunds(amount);
    // => Business rule #2: sufficient funds required
    this.balance -= amount;
    // => Updates aggregate state
  }
  // => Validates business rule

  private ensureIsActive(): void {
    // => Helper: ensureIsActive()
    if (!this.isActive) {
      // => Operation: if()
      throw new Error("Cannot withdraw from inactive account");
      // => Raise domain exception
    }
    // => Enforces invariant
  }
  // => Encapsulates domain knowledge

  private ensureSufficientFunds(amount: number): void {
    // => Helper: ensureSufficientFunds()
    if (this.balance < amount) {
      // => Operation: if()
      throw new Error(`Insufficient funds. Balance: ${this.balance}, Requested: ${amount}`);
      // => Raise domain exception
    }
    // => Delegates to domain service
  }
  // => Maintains consistency boundary

  getBalance(): number {
    // => Read-only access to balance
    // => No setBalance() method exists
    return this.balance;
    // => Return result to caller
  }
  // => Applies domain event
}
// => Coordinates with bounded context

// Usage
const account = new BankAccount("123", 1000);
// => balance=1000, isActive=true
account.withdraw(500);
// => ensureSufficientFunds(500) validates balance >= 500
// => balance becomes 500
console.log(account.getBalance());
// => Output: 500

// Domain: Healthcare appointment scheduling
// Ubiquitous Language terms: Patient, Practitioner, Appointment, TimeSlot

// ❌ WRONG: Using technical terms instead of domain language
class Person1 {
  // => Person1: domain model element
  constructor(public id: string) {}
  // => Initialize object with parameters
}

class Person2 {
  // => Person2: domain model element
  constructor(public id: string) {}
  // => Initialize object with parameters
}

class Event {
  // => Event: domain model element
  constructor(
    public person1Id: string, // => Who is person1?
    public person2Id: string, // => Who is person2?
    public startTime: Date,
    // => Field: startTime (public)
    public endTime: Date,
    // => Field: endTime (public)
  ) {}
}

// ✅ CORRECT: Using domain language directly
class Patient {
  // => Patient: domain model element
  constructor(
    private readonly patientId: string, // => Domain-specific identifier
    private readonly name: string,
    // => Field: readonly (private)
    // => Encapsulated state, not directly accessible
    private readonly dateOfBirth: Date,
    // => Field: readonly (private)
    // => Encapsulated state, not directly accessible
  ) {}

  getPatientId(): string {
    return this.patientId; // => Returns patient ID
  }
}

class Practitioner {
  // => Practitioner: domain model element
  constructor(
    private readonly practitionerId: string, // => Domain-specific identifier
    private readonly name: string,
    private readonly specialty: string, // => Domain term: specialty, not "skill"
  ) {}

  getPractitionerId(): string {
    return this.practitionerId; // => Returns practitioner ID
  }
}

class TimeSlot {
  // => TimeSlot: domain model element
  constructor(
    private readonly startTime: Date, // => Slot start time
    private readonly endTime: Date, // => Slot end time
  ) {}

  getDurationMinutes(): number {
    const diff = this.endTime.getTime() - this.startTime.getTime(); // => Calculate difference
    return diff / (1000 * 60); // => Convert milliseconds to minutes
  }
}

class Appointment {
  // => Appointment: domain model element
  constructor(
    private readonly appointmentId: string, // => Unique appointment identifier
    private readonly patient: Patient, // => Who is being seen
    private readonly practitioner: Practitioner, // => Who is providing care
    private readonly timeSlot: TimeSlot, // => When the appointment occurs
    private status: AppointmentStatus, // => Current state: scheduled, completed, cancelled
  ) {}

  cancel(): void {
    // => Operation: cancel()
    if (this.status === AppointmentStatus.Completed) {
      // => Operation: if()
      throw new Error("Cannot cancel completed appointment");
      // => Raise domain exception
    }
    this.status = AppointmentStatus.Cancelled; // => Update to cancelled
    // => Appointment cancelled
  }
}

enum AppointmentStatus {
  // => Domain vocabulary for appointment states
  Scheduled = "SCHEDULED", // => Appointment is booked
  Completed = "COMPLETED", // => Visit finished
  Cancelled = "CANCELLED", // => Appointment cancelled
}

// Usage with domain language
const patient = new Patient("P123", "John Doe", new Date("1980-05-15")); // => Create patient
const doctor = new Practitioner("D456", "Dr. Smith", "Cardiology"); // => Create practitioner
const slot = new TimeSlot(new Date("2026-02-01T10:00"), new Date("2026-02-01T10:30")); // => 30-minute slot
const appointment = new Appointment("A789", patient, doctor, slot, AppointmentStatus.Scheduled); // => Schedule appointment
appointment.cancel(); // => status becomes Cancelled

// Domain: E-commerce orders
class Order {
  // => Entity: defined by identity
  private readonly orderId: string; // => Unique identifier (never changes)
  private customerId: string; // => Can change (customer reassignment)
  private items: OrderItem[]; // => Can change (add/remove items)
  private status: OrderStatus; // => Can change (order lifecycle)

  constructor(orderId: string, customerId: string) {
    this.orderId = orderId; // => Set immutable ID
    this.customerId = customerId; // => Set initial customer
    this.items = []; // => Start with empty items
    this.status = OrderStatus.Draft; // => New orders start as draft
    // => Order created: id=orderId, customer=customerId, items=[], status=Draft
  }

  addItem(productId: string, quantity: number, price: number): void {
    // => Domain operation: addItem
    const item = new OrderItem(productId, quantity, price); // => Create new item
    this.items.push(item); // => Add to items array
    // => Item added: items.length increased by 1
  }

  submit(): void {
    // => Domain operation: submit
    if (this.items.length === 0) {
      // => Validate has items
      throw new Error("Cannot submit empty order");
    }
    this.status = OrderStatus.Submitted; // => Change status to submitted
    // => Order submitted
  }

  equals(other: Order): boolean {
    // => Domain operation: equals
    return this.orderId === other.orderId; // => Identity comparison (not attribute comparison)
  }

  getOrderId(): string {
    // => Domain operation: getOrderId
    return this.orderId; // => Read-only access to ID
  }
}

class OrderItem {
  constructor(
    public readonly productId: string, // => Product being ordered
    public readonly quantity: number, // => How many
    public readonly price: number, // => Price per unit
  ) {}
}

enum OrderStatus {
  Draft = "DRAFT", // => Order being built
  Submitted = "SUBMITTED", // => Order placed
  Shipped = "SHIPPED", // => Order sent to customer
  Delivered = "DELIVERED", // => Order received by customer
}

// Usage demonstrating identity
const order1 = new Order("ORD-001", "CUST-123"); // => order1: id=ORD-001
order1.addItem("PROD-A", 2, 50.0); // => order1: items=[{PROD-A, qty=2, price=50}]

const order2 = new Order("ORD-001", "CUST-456"); // => order2: id=ORD-001 (same ID)
// => order1.equals(order2) returns TRUE even though customers differ
// => Identity (orderId) defines equality, not attributes

const order3 = new Order("ORD-002", "CUST-123"); // => order3: id=ORD-002 (different ID)
// => order1.equals(order3) returns FALSE even though customer same
// => Different identity = different entity

// Domain: Order processing with state transitions
class Order {
  private readonly orderId: string; // => Immutable identity
  private status: OrderStatus; // => Current lifecycle state

  constructor(orderId: string) {
    this.orderId = orderId; // => Set ID
    this.status = OrderStatus.Draft; // => Initial state: Draft
    // => Order created in Draft state
  }

  submit(): void {
    // => Domain operation: submit
    this.ensureCanTransitionTo(OrderStatus.Submitted); // => Validate transition allowed
    this.status = OrderStatus.Submitted; // => Transition to Submitted
    // => Status: Draft → Submitted
  }

  ship(): void {
    // => Domain operation: ship
    this.ensureCanTransitionTo(OrderStatus.Shipped); // => Validate transition allowed
    this.status = OrderStatus.Shipped; // => Transition to Shipped
    // => Status: Submitted → Shipped
  }

  deliver(): void {
    // => Domain operation: deliver
    this.ensureCanTransitionTo(OrderStatus.Delivered); // => Validate transition allowed
    this.status = OrderStatus.Delivered; // => Transition to Delivered
    // => Status: Shipped → Delivered
  }

  cancel(): void {
    // => Domain operation: cancel
    this.ensureCanTransitionTo(OrderStatus.Cancelled); // => Validate transition allowed
    this.status = OrderStatus.Cancelled; // => Transition to Cancelled
    // => Status: [any state] → Cancelled
  }

  private ensureCanTransitionTo(newStatus: OrderStatus): void {
    // => Internal logic (not part of public API)
    const allowedTransitions = this.getAllowedTransitions(); // => Get valid next states

    if (!allowedTransitions.includes(newStatus)) {
      // => Check if transition valid
      throw new Error(
        `Invalid transition from ${this.status} to ${newStatus}. ` + `Allowed: ${allowedTransitions.join(", ")}`,
        // => Delegates to internal method
      );
    }
    // => Transition validated
  }

  private getAllowedTransitions(): OrderStatus[] {
    // => Internal logic (not part of public API)
    const transitions: Record<OrderStatus, OrderStatus[]> = {
      [OrderStatus.Draft]: [OrderStatus.Submitted, OrderStatus.Cancelled], // => Draft can go to Submitted or Cancelled
      [OrderStatus.Submitted]: [OrderStatus.Shipped, OrderStatus.Cancelled], // => Submitted can go to Shipped or Cancelled
      [OrderStatus.Shipped]: [OrderStatus.Delivered, OrderStatus.Cancelled], // => Shipped can go to Delivered or Cancelled
      [OrderStatus.Delivered]: [], // => Delivered is terminal (no transitions)
      [OrderStatus.Cancelled]: [], // => Cancelled is terminal (no transitions)
    };

    return transitions[this.status]; // => Return allowed transitions for current state
    // => Returns transitions[this.status]; // => Return allowed transitions for current state
  }

  getStatus(): OrderStatus {
    // => Domain operation: getStatus
    return this.status; // => Read current status
  }
}

enum OrderStatus {
  Draft = "DRAFT",
  Submitted = "SUBMITTED",
  Shipped = "SHIPPED",
  Delivered = "DELIVERED",
  Cancelled = "CANCELLED",
}

// Usage showing valid and invalid transitions
const order = new Order("ORD-001"); // => order: status=Draft
console.log(order.getStatus()); // => Output: DRAFT

order.submit(); // => status: Draft → Submitted (valid)
console.log(order.getStatus()); // => Output: SUBMITTED

order.ship(); // => status: Submitted → Shipped (valid)
console.log(order.getStatus()); // => Output: SHIPPED

// order.submit();                           // => Would throw error: cannot Submitted from Shipped
order.deliver(); // => status: Shipped → Delivered (valid)
console.log(order.getStatus()); // => Output: DELIVERED

// order.ship();                             // => Would throw error: Delivered is terminal state

// Domain: Banking - Account with overdraft protection
public class BankAccount {
    private final String accountId;          // => Immutable identity
    private Money balance;                   // => Current balance (changes over time)
    private final Money overdraftLimit;      // => Maximum allowed negative balance
    private boolean isFrozen;                // => Account status flag

    public BankAccount(String accountId, Money initialBalance, Money overdraftLimit) {
        if (overdraftLimit.isNegative()) {   // => Validate: overdraft limit cannot be negative
            throw new IllegalArgumentException("Overdraft limit must be non-negative");
              // => Raise domain exception
        }

        this.accountId = accountId;          // => Set immutable ID
        this.balance = initialBalance;       // => Set initial balance
        this.overdraftLimit = overdraftLimit;  // => Set overdraft protection
        this.isFrozen = false;               // => Account starts active (not frozen)

        this.ensureInvariants();             // => Validate invariants on creation
        // => Account created with valid state
    }

    public void deposit(Money amount) {
        if (amount.isNegativeOrZero()) {     // => Validate: deposit must be positive
            throw new IllegalArgumentException("Deposit amount must be positive");
              // => Raise domain exception
        }

        this.ensureNotFrozen();              // => Validate: account not frozen
        this.balance = this.balance.add(amount);  // => Add to balance
        this.ensureInvariants();             // => Validate invariants after change
        // => balance increased by amount
    }

    public void withdraw(Money amount) {
        if (amount.isNegativeOrZero()) {     // => Validate: withdrawal must be positive
            throw new IllegalArgumentException("Withdrawal amount must be positive");
              // => Raise domain exception
        }

        this.ensureNotFrozen();              // => Validate: account not frozen
        this.ensureSufficientFundsWithOverdraft(amount);  // => Validate: within overdraft limit

        this.balance = this.balance.subtract(amount);     // => Deduct from balance
        this.ensureInvariants();             // => Validate invariants after change
        // => balance decreased by amount
    }

    public void freeze() {
        this.isFrozen = true;                // => Set frozen flag
        // => Account frozen (no deposits/withdrawals allowed)
    }

    private void ensureNotFrozen() {
        if (this.isFrozen) {                 // => Check frozen status
            throw new IllegalStateException("Cannot perform operations on frozen account");
              // => Raise domain exception
        }
        // => Validation passed: account is active
    }

    private void ensureSufficientFundsWithOverdraft(Money amount) {
        Money minimumAllowed = this.overdraftLimit.negate();  // => Calculate minimum balance (negative overdraft)
        Money balanceAfterWithdrawal = this.balance.subtract(amount);  // => Calculate new balance

        if (balanceAfterWithdrawal.isLessThan(minimumAllowed)) {  // => Check if below overdraft limit
            throw new IllegalStateException(
              // => Raise domain exception
                String.format("Insufficient funds. Balance: %s, Withdrawal: %s, Overdraft limit: %s",
                    this.balance, amount, this.overdraftLimit)
            );
        }
        // => Validation passed: withdrawal within limits
    }

    private void ensureInvariants() {
      // => Field: void (private)
      // => Encapsulated state, not directly accessible
        // Invariant 1: Balance + overdraft limit >= 0
        Money minimumAllowed = this.overdraftLimit.negate();  // => Calculate minimum allowed balance
        if (this.balance.isLessThan(minimumAllowed)) {        // => Check invariant
            throw new IllegalStateException("Invariant violation: balance below overdraft limit");
              // => Raise domain exception
        }

        // Invariant 2: Overdraft limit is non-negative
        if (this.overdraftLimit.isNegative()) {               // => Check invariant
            throw new IllegalStateException("Invariant violation: overdraft limit cannot be negative");
              // => Raise domain exception
        }

        // => All invariants satisfied
    }

    public Money getBalance() {
        return this.balance;                 // => Return current balance
    }
}

// Value Object for Money (see next section for details)
public class Money {
  // => Field: class (public)
    private final BigDecimal amount;
      // => Field: final (private)
      // => Encapsulated state, not directly accessible
    private final String currency;
      // => Field: final (private)
      // => Encapsulated state, not directly accessible

    public Money(BigDecimal amount, String currency) {
      // => Operation: Money()
        this.amount = amount;
          // => Update amount state
        this.currency = currency;
          // => Update currency state
    }

    public Money add(Money other) {
      // => Field: Money (public)
        this.ensureSameCurrency(other);
        // => Delegates to internal method
        return new Money(this.amount.add(other.amount), this.currency);
          // => Return result to caller
    }

    public Money subtract(Money other) {
      // => Field: Money (public)
        this.ensureSameCurrency(other);
        // => Delegates to internal method
        return new Money(this.amount.subtract(other.amount), this.currency);
          // => Return result to caller
    }

    public Money negate() {
      // => Field: Money (public)
        return new Money(this.amount.negate(), this.currency);
          // => Return result to caller
    }

    public boolean isNegative() {
      // => Field: boolean (public)
        return this.amount.compareTo(BigDecimal.ZERO) < 0;
          // => Return result to caller
    }

    public boolean isNegativeOrZero() {
      // => Field: boolean (public)
        return this.amount.compareTo(BigDecimal.ZERO) <= 0;
          // => Return result to caller
    }

    public boolean isLessThan(Money other) {
      // => Field: boolean (public)
        this.ensureSameCurrency(other);
        // => Delegates to internal method
        return this.amount.compareTo(other.amount) < 0;
          // => Return result to caller
    }

    private void ensureSameCurrency(Money other) {
      // => Field: void (private)
      // => Encapsulated state, not directly accessible
        if (!this.currency.equals(other.currency)) {
          // => Conditional check
            throw new IllegalArgumentException("Cannot operate on different currencies");
              // => Raise domain exception
        }
    }
}

// Usage
Money initialBalance = new Money(new BigDecimal("1000.00"), "USD");     // => Create initial balance
Money overdraftLimit = new Money(new BigDecimal("500.00"), "USD");      // => Allow $500 overdraft
BankAccount account = new BankAccount("ACC-001", initialBalance, overdraftLimit);  // => Create account

account.deposit(new Money(new BigDecimal("500.00"), "USD"));            // => balance: $1000 → $1500
account.withdraw(new Money(new BigDecimal("2000.00"), "USD"));          // => balance: $1500 → -$500 (within overdraft)
// account.withdraw(new Money(new BigDecimal("100.00"), "USD"));        // => Would throw: exceeds overdraft limit (-$600 < -$500)

account.freeze();                                                       // => Account frozen
// account.deposit(new Money(new BigDecimal("100.00"), "USD"));         // => Would throw: frozen account

// Domain: Customer management
class Customer {
  // => Entity with identity
  private readonly customerId: string; // => Unique identifier
  private email: string; // => Customer email
  private name: string; // => Customer name
  private createdAt: Date; // => Registration timestamp

  constructor(customerId: string, email: string, name: string) {
    this.customerId = customerId; // => Set ID
    this.email = email; // => Set email
    this.name = name; // => Set name
    this.createdAt = new Date(); // => Record creation time
    // => Customer created
  }

  changeEmail(newEmail: string): void {
    // => Domain operation: changeEmail
    if (!this.isValidEmail(newEmail)) {
      // => Validate email format
      throw new Error("Invalid email format");
      // => Raise domain exception
    }
    this.email = newEmail; // => Update email
    // => Email changed
  }

  private isValidEmail(email: string): boolean {
    // => Internal logic (not part of public API)
    return email.includes("@"); // => Simple validation (real impl would use regex)
    // => Returns email.includes("@"); // => Simple validation (real impl would use regex)
  }

  getCustomerId(): string {
    // => Domain operation: getCustomerId
    return this.customerId;
    // => Return result to caller
  }

  getEmail(): string {
    // => Domain operation: getEmail
    return this.email;
    // => Return result to caller
  }
}

// Repository interface (domain layer - no database details)
interface CustomerRepository {
  save(customer: Customer): Promise<void>; // => Persist customer
  // => Domain operation: save
  findById(customerId: string): Promise<Customer | null>; // => Retrieve by ID
  // => Domain operation: findById
  findByEmail(email: string): Promise<Customer | null>; // => Retrieve by email
  // => Domain operation: findByEmail
  delete(customerId: string): Promise<void>; // => Remove customer
  // => Domain operation: delete
}

// Repository implementation (infrastructure layer - database details)
class PostgresCustomerRepository implements CustomerRepository {
  constructor(private db: DatabaseConnection) {} // => Database connection injected

  async save(customer: Customer): Promise<void> {
    // => Operation: save()
    const query = `
      // => Store value in query
      INSERT INTO customers (customer_id, email, name, created_at)
      VALUES ($1, $2, $3, $4)
      ON CONFLICT (customer_id) DO UPDATE
      SET email = $2, name = $3
    `;
    // => Upsert query (insert or update if exists)

    await this.db.execute(query, [
      customer.getCustomerId(),
      // => Execute method
      customer.getEmail(),
      // => Execute method
      customer.getName(),
      // => Execute method
      customer.getCreatedAt(),
      // => Execute method
    ]);
    // => Customer saved to database
  }

  async findById(customerId: string): Promise<Customer | null> {
    const query = `SELECT * FROM customers WHERE customer_id = $1`; // => SQL query
    const row = await this.db.queryOne(query, [customerId]); // => Execute query

    if (!row) {
      return null; // => Customer not found
      // => Returns null; // => Customer not found
    }

    return this.mapRowToCustomer(row); // => Convert database row to domain entity
  }

  async findByEmail(email: string): Promise<Customer | null> {
    const query = `SELECT * FROM customers WHERE email = $1`; // => SQL query
    const row = await this.db.queryOne(query, [email]); // => Execute query

    if (!row) {
      return null; // => Customer not found
      // => Returns null; // => Customer not found
    }

    return this.mapRowToCustomer(row); // => Convert to domain entity
  }

  async delete(customerId: string): Promise<void> {
    const query = `DELETE FROM customers WHERE customer_id = $1`; // => SQL delete
    await this.db.execute(query, [customerId]); // => Execute deletion
    // => Customer deleted from database
  }

  private mapRowToCustomer(row: any): Customer {
    // => Internal logic (not part of public API)
    return new Customer(
      row.customer_id, // => Reconstruct entity from database row
      row.email,
      row.name,
    );
  }
}

// Usage (domain service using repository)
class CustomerService {
  constructor(private customerRepo: CustomerRepository) {} // => Inject repository

  async changeCustomerEmail(customerId: string, newEmail: string): Promise<void> {
    const customer = await this.customerRepo.findById(customerId); // => Load entity

    if (!customer) {
      // => Operation: if()
      throw new Error("Customer not found");
      // => Raise domain exception
    }

    customer.changeEmail(newEmail); // => Domain logic (validates email)
    await this.customerRepo.save(customer); // => Persist changes
    // => Email changed and saved
  }
}

// Usage example
const db = new DatabaseConnection(); // => Database connection
const customerRepo = new PostgresCustomerRepository(db); // => Create repository
const customerService = new CustomerService(customerRepo); // => Create service

// Change email for customer
await customerService.changeCustomerEmail("CUST-123", "newemail@example.com");
// => Loads customer, validates email, saves changes

// Domain: E-commerce product creation
public class Product {
    private final String productId;          // => Unique identifier
    private final String name;               // => Product name
    private final Money price;               // => Product price
    private final ProductCategory category;  // => Product category
    private final List<String> tags;         // => Search tags
    private ProductStatus status;            // => Current status

    // Private constructor - only factory can create
    private Product(
      // => Field: Product (private)
      // => Encapsulated state, not directly accessible
        String productId,
        String name,
        Money price,
        ProductCategory category,
        List<String> tags
    ) {
        this.productId = productId;          // => Set ID
        this.name = name;                    // => Set name
        this.price = price;                  // => Set price
        this.category = category;            // => Set category
        this.tags = new ArrayList<>(tags);   // => Copy tags (defensive copy)
        this.status = ProductStatus.DRAFT;   // => New products start as draft
        // => Product created in valid initial state
    }

    public void publish() {
      // => Field: void (public)
        if (this.status != ProductStatus.DRAFT) {
          // => Operation: if()
            throw new IllegalStateException("Can only publish draft products");
              // => Raise domain exception
        }
        this.status = ProductStatus.PUBLISHED;  // => Change status to published
        // => Product published
    }

    // Factory for creating products
    public static class Factory {
        private final IdGenerator idGenerator;        // => ID generation service
        private final PricingService pricingService;  // => Pricing validation

        public Factory(IdGenerator idGenerator, PricingService pricingService) {
            this.idGenerator = idGenerator;      // => Inject ID generator
            this.pricingService = pricingService;  // => Inject pricing service
            // => Factory initialized
        }

        public Product createProduct(
          // => Field: Product (public)
            String name,
            BigDecimal basePrice,
            String currency,
            ProductCategory category,
            List<String> tags
        ) {
            // Step 1: Validate inputs
            this.validateName(name);             // => Ensure name is valid
            this.validateCategory(category);     // => Ensure category is valid
            this.validateTags(tags);             // => Ensure tags are valid
            // => All validations passed

            // Step 2: Generate ID
            String productId = this.idGenerator.generateProductId();  // => Create unique ID
            // => ID generated: productId

            // Step 3: Calculate price (may involve complex logic)
            Money price = this.pricingService.calculatePrice(
                basePrice,
                currency,
                category
            );
            // => Price calculated with category-specific rules

            // Step 4: Normalize tags
            List<String> normalizedTags = tags.stream()
                .map(String::toLowerCase)        // => Convert to lowercase
                .map(String::trim)               // => Remove whitespace
                .distinct()                      // => Remove duplicates
                .collect(Collectors.toList());
            // => Tags normalized

            // Step 5: Create product
            Product product = new Product(
              // => Create Product instance
                productId,
                name,
                price,
                category,
                normalizedTags
            );
            // => Product created with valid state

            return product;                      // => Return fully initialized product
            // => Returns product;                      // => Return fully initialized product
        }

        public Product createProductFromExisting(Product template, String newName) {
          // => Field: Product (public)
            // Clone existing product with new name
            String newProductId = this.idGenerator.generateProductId();  // => New ID

            return new Product(
                newProductId,                    // => New ID (not same as template)
                newName,                         // => New name
                template.price,                  // => Copy price from template
                template.category,               // => Copy category from template
                new ArrayList<>(template.tags)   // => Copy tags from template
            );
            // => New product created based on template
        }

        private void validateName(String name) {
          // => Field: void (private)
          // => Encapsulated state, not directly accessible
            if (name == null || name.trim().isEmpty()) {
              // => Conditional check
                throw new IllegalArgumentException("Product name cannot be empty");
                  // => Raise domain exception
            }
            if (name.length() > 200) {
              // => Conditional check
                throw new IllegalArgumentException("Product name too long (max 200 chars)");
                  // => Raise domain exception
            }
            // => Name validation passed
        }

        private void validateCategory(ProductCategory category) {
          // => Field: void (private)
          // => Encapsulated state, not directly accessible
            if (category == null) {
              // => Operation: if()
                throw new IllegalArgumentException("Product category is required");
                  // => Raise domain exception
            }
            // => Category validation passed
        }

        private void validateTags(List<String> tags) {
          // => Field: void (private)
          // => Encapsulated state, not directly accessible
            if (tags == null || tags.isEmpty()) {
              // => Conditional check
                throw new IllegalArgumentException("At least one tag is required");
                  // => Raise domain exception
            }
            if (tags.size() > 10) {
              // => Conditional check
                throw new IllegalArgumentException("Too many tags (max 10)");
                  // => Raise domain exception
            }
            // => Tags validation passed
        }
    }
}

enum ProductCategory {
    ELECTRONICS, CLOTHING, BOOKS, FOOD
}

enum ProductStatus {
    DRAFT, PUBLISHED, DISCONTINUED
}

// Usage
IdGenerator idGen = new UUIDGenerator();     // => ID generation service
PricingService pricing = new TieredPricingService();  // => Pricing calculation service
Product.Factory productFactory = new Product.Factory(idGen, pricing);  // => Create factory

// Create new product
Product laptop = productFactory.createProduct(
    "Gaming Laptop X1",                      // => Product name
    new BigDecimal("1500.00"),               // => Base price
    "USD",                                   // => Currency
    ProductCategory.ELECTRONICS,             // => Category
    Arrays.asList("gaming", "laptop", "electronics", "computers")  // => Tags
);
// => Product created: id=generated, name="Gaming Laptop X1", status=DRAFT
// => Price calculated with electronics category markup
// => Tags normalized: ["gaming", "laptop", "electronics", "computers"]

laptop.publish();                            // => status: DRAFT → PUBLISHED

// Create product from template
Product similarLaptop = productFactory.createProductFromExisting(laptop, "Gaming Laptop X2");
// => New product with same price/category/tags but different ID and name

// Domain: Geographic location
class Address {
  // => Value Object: defined by attributes
  private readonly street: string; // => Immutable field
  private readonly city: string; // => Immutable field
  private readonly postalCode: string; // => Immutable field
  private readonly country: string; // => Immutable field

  constructor(street: string, city: string, postalCode: string, country: string) {
    if (!street || !city || !postalCode || !country) {
      // => Validate all fields required
      throw new Error("All address fields are required");
    }

    this.street = street; // => Set immutable street
    this.city = city; // => Set immutable city
    this.postalCode = postalCode; // => Set immutable postal code
    this.country = country; // => Set immutable country
    // => Address created (immutable)
  }

  equals(other: Address): boolean {
    // => Domain operation: equals
    return (
      // => Returns (
      this.street === other.street && // => Compare all attributes
      this.city === other.city &&
      this.postalCode === other.postalCode &&
      this.country === other.country
    );
  }

  toString(): string {
    // => Domain operation: toString
    return `${this.street}, ${this.city} ${this.postalCode}, ${this.country}`;
    // => Returns `${this.street}, ${this.city} ${this.postalCode}, ${this.country}`
  }
}

// Usage demonstrating value object characteristics
const addr1 = new Address("123 Main St", "New York", "10001", "USA"); // => Create address
const addr2 = new Address("123 Main St", "New York", "10001", "USA"); // => Create identical address
const addr3 = new Address("456 Elm St", "Boston", "02101", "USA"); // => Create different address

console.log(addr1.equals(addr2)); // => Output: true (same attributes = equal)
console.log(addr1 === addr2); // => Output: false (different object references)
console.log(addr1.equals(addr3)); // => Output: false (different attributes)

// addr1.city = "Boston";                    // => Compile error: readonly field cannot be changed
// => To "change" address, create new value object
const updatedAddr = new Address(
  "123 Main St",
  "Boston", // => Changed city
  "10001",
  "USA",
);
// => New address created (original addr1 unchanged)

// Domain: Financial transactions
public class Money {
    private final BigDecimal amount;         // => Immutable amount (using BigDecimal for precision)
    private final Currency currency;         // => Immutable currency

    public Money(BigDecimal amount, Currency currency) {
      // => Operation: Money()
        if (amount == null) {
          // => Operation: if()
            throw new IllegalArgumentException("Amount cannot be null");
              // => Raise domain exception
        }
        if (currency == null) {
          // => Operation: if()
            throw new IllegalArgumentException("Currency cannot be null");
              // => Raise domain exception
        }

        this.amount = amount.setScale(currency.getDefaultFractionDigits(), RoundingMode.HALF_UP);  // => Round to currency precision
        this.currency = currency;            // => Set currency
        // => Money created: amount rounded to currency decimal places
    }

    public Money add(Money other) {
        this.ensureSameCurrency(other);      // => Validate: cannot add different currencies
        BigDecimal newAmount = this.amount.add(other.amount);  // => Add amounts
        return new Money(newAmount, this.currency);  // => Return new Money (immutable)
    }

    public Money subtract(Money other) {
        this.ensureSameCurrency(other);      // => Validate: cannot subtract different currencies
        BigDecimal newAmount = this.amount.subtract(other.amount);  // => Subtract amounts
        return new Money(newAmount, this.currency);  // => Return new Money (immutable)
    }

    public Money multiply(BigDecimal multiplier) {
        BigDecimal newAmount = this.amount.multiply(multiplier);  // => Multiply amount
        return new Money(newAmount, this.currency);  // => Return new Money (same currency)
    }

    public boolean isGreaterThan(Money other) {
        this.ensureSameCurrency(other);      // => Validate: cannot compare different currencies
        return this.amount.compareTo(other.amount) > 0;  // => Compare amounts
    }

    public boolean equals(Object obj) {
        if (this == obj) return true;        // => Same reference = equal
        if (!(obj instanceof Money)) return false;  // => Different type = not equal

        Money other = (Money) obj;
        return this.amount.equals(other.amount) &&     // => Compare amount
               this.currency.equals(other.currency);   // => Compare currency
    }

    @Override
    public int hashCode() {
        return Objects.hash(amount, currency);  // => Hash based on amount and currency
        // => Returns Objects.hash(amount, currency);  // => Hash based on amount and currency
        // => Enables using Money as HashMap key
    }

    private void ensureSameCurrency(Money other) {
        if (!this.currency.equals(other.currency)) {  // => Check currency match
            throw new IllegalArgumentException(
              // => Raise domain exception
                String.format("Cannot operate on different currencies: %s vs %s",
                    this.currency.getCurrencyCode(),
                    // => Delegates to internal method
                    other.currency.getCurrencyCode())
                      // => Execute method
            );
        }
        // => Validation passed: same currency
    }

    @Override
    public String toString() {
        return String.format("%s %s", this.currency.getCurrencyCode(), this.amount);
        // => Returns String.format("%s %s", this.currency.getCurrencyCode(), this.amount)
    }
}

// Usage
Money price = new Money(new BigDecimal("99.99"), Currency.getInstance("USD"));     // => price: USD 99.99
Money tax = new Money(new BigDecimal("8.00"), Currency.getInstance("USD"));        // => tax: USD 8.00
Money total = price.add(tax);                                                      // => total: USD 107.99
System.out.println(total);                                                         // => Output: USD 107.99

Money discount = total.multiply(new BigDecimal("0.10"));                           // => 10% discount: USD 10.80 (rounded)
Money finalPrice = total.subtract(discount);                                       // => finalPrice: USD 97.19
System.out.println(finalPrice);                                                    // => Output: USD 97.19

// Money errorPrice = new Money(new BigDecimal("50.00"), Currency.getInstance("EUR"));  // => EUR 50.00
// total.add(errorPrice);                                                          // => Throws: cannot add USD and EUR