digraph when_to_use {
    "Adding business logic?" [shape=diamond];
    "Where does data live?" [shape=diamond];
    "Put in domain object" [shape=box];
    "Put in service" [shape=box];
    "Creating new class?" [shape=diamond];
    "Add behavior methods" [shape=box];

    "Adding business logic?" -> "Where does data live?" [label="yes"];
    "Where does data live?" -> "Put in domain object" [label="in entity/aggregate"];
    "Where does data live?" -> "Put in service" [label="external/async"];
    "Adding business logic?" -> "Creating new class?" [label="no"];
    "Creating new class?" -> "Add behavior methods" [label="yes"];
}

// ✅ GOOD: Uses domain language
class Aquarium {
  stockFish(fish: Fish): void { ... }
  performWaterChange(percentage: Percentage): void { ... }
  cycleCompleted(): boolean { ... }
}

// ❌ BAD: Technical/generic language
class Aquarium {
  addItem(item: Item): void { ... }
  updateValue(field: string, value: number): void { ... }
  checkFlag(): boolean { ... }
}

// Sales Context: Customer has payment info, purchase history
class Customer {
  creditLimit: Money;
  paymentMethod: PaymentMethod;
  calculateLifetimeValue(): Money { ... }
}

// Support Context: Customer has tickets, satisfaction score
class Customer {
  openTickets: Ticket[];
  satisfactionScore: number;
  escalate(): void { ... }
}

// ENTITY: Identity matters, tracked over time
class Fish {
  constructor(
    private readonly id: FishId,
    private name: string,
    private species: Species
  ) {}

  equals(other: Fish): boolean {
    return this.id.equals(other.id);  // Identity comparison
  }

  rename(newName: string): void {
    this.name = newName;  // State can change
  }
}

// VALUE OBJECT: Immutable, equality by attributes
class Temperature {
  private constructor(
    private readonly value: number,
    private readonly unit: TemperatureUnit
  ) {
    this.validate();
  }

  static celsius(value: number): Temperature {
    return new Temperature(value, TemperatureUnit.Celsius);
  }

  equals(other: Temperature): boolean {
    return this.toCelsius() === other.toCelsius();  // Value comparison
  }

  add(delta: Temperature): Temperature {
    return Temperature.celsius(this.toCelsius() + delta.toCelsius());
  }

  private validate(): void {
    if (this.toCelsius() < -273.15) {
      throw new DomainError('Temperature below absolute zero');
    }
  }
}

// ✅ GOOD: Small aggregate, references by ID
class Order {
  private readonly id: OrderId;
  private readonly customerId: CustomerId;  // Reference by ID, not object
  private items: OrderItem[];
  private status: OrderStatus;

  // Invariant: Order total cannot exceed customer credit (checked at application layer)
  // Invariant: Cannot add items to confirmed order (protected here)
  addItem(productId: ProductId, quantity: Quantity, price: Money): void {
    this.assertNotConfirmed();
    this.items.push(new OrderItem(productId, quantity, price));
  }

  confirm(): void {
    this.assertHasItems();
    this.status = OrderStatus.Confirmed;
    this.apply(new OrderConfirmedEvent(this.id));  // Domain event
  }

  private assertNotConfirmed(): void {
    if (this.status !== OrderStatus.Draft) {
      throw new DomainError('Cannot modify confirmed order');
    }
  }
}

// ❌ BAD: Large aggregate with object references
class Order {
  customer: Customer;        // Full object = large transaction boundary
  products: Product[];       // Loading entire product catalog
  warehouse: Warehouse;      // Unrelated aggregate
}

class Aquarium extends AggregateRoot {
  private waterParameters: WaterParameters;

  recordMeasurement(params: WaterParameters): void {
    const previousParams = this.waterParameters;
    this.waterParameters = params;

    // Publish what happened, not what to do
    this.apply(new WaterParametersRecordedEvent(
      this.id,
      params,
      previousParams
    ));

    if (params.ammonia.isAbove(SafeLevel.AMMONIA)) {
      this.apply(new DangerousAmmoniaDetectedEvent(this.id, params.ammonia));
    }
  }
}

// Handler reacts to event (in different aggregate/service)
class NotificationHandler {
  handle(event: DangerousAmmoniaDetectedEvent): void {
    this.notificationService.alertUser(event.aquariumId, 'High ammonia detected!');
  }
}

// ✅ RICH: Domain object owns behavior
class Order {
  private items: OrderItem[];
  private status: OrderStatus;

  addItem(product: Product, quantity: number): void {
    if (this.status !== OrderStatus.Draft) {
      throw new DomainError('Cannot modify confirmed order');
    }
    this.items.push(new OrderItem(product, quantity));
  }

  getTotal(): Money {
    return this.items.reduce(
      (sum, item) => sum.add(item.getSubtotal()),
      Money.zero()
    );
  }

  confirm(): void {
    if (this.items.length === 0) {
      throw new DomainError('Cannot confirm empty order');
    }
    this.status = OrderStatus.Confirmed;
  }
}

// ❌ ANEMIC: Data container + logic in service
class Order {
  items: OrderItem[];  // Public data
  status: string;      // Primitive, no protection
}

class OrderService {
  addItem(order: Order, product: Product, qty: number): void {
    if (order.status !== 'draft') throw new Error('...');
    order.items.push({ product, qty });  // Direct manipulation
  }

  calculateTotal(order: Order): number {
    return order.items.reduce((sum, i) => sum + i.price * i.qty, 0);
  }
}

// ✅ TELL: Ask domain object to do its job
const hasInvertebrates = aquarium.hasInvertebrates();
const canAddFish = tank.canAccommodate(newFish);
const discount = customer.calculateDiscount(order);

// ❌ ASK: Extract data and decide externally (Law of Demeter violation)
const hasInvertebrates = aquarium.animals
  .filter(a => !a.removedAt)
  .some(a => INVERTEBRATE_TYPES.includes(a.type));

// ❌ TRAIN WRECK: Chaining through object graph
const city = order.getCustomer().getAddress().getCity();

class Account {
  // ✅ QUERY: Returns data, no side effects
  getBalance(): Money {
    return this.balance;
  }

  // ✅ COMMAND: Changes state, returns void
  withdraw(amount: Money): void {
    this.assertSufficientFunds(amount);
    this.balance = this.balance.subtract(amount);
  }

  // ❌ BAD: Mixed command and query
  withdrawAndReturnBalance(amount: Money): Money {
    this.balance = this.balance.subtract(amount);
    return this.balance;  // Side effect + return = confusing
  }
}

class BankAccount {
  /**
   * Withdraws money from account.
   *
   * @precondition amount > 0
   * @precondition amount <= this.balance
   * @postcondition this.balance === old(this.balance) - amount
   * @throws InsufficientFundsError if preconditions not met
   */
  withdraw(amount: Money): void {
    // Precondition checks (guard clauses)
    if (amount.isNegativeOrZero()) {
      throw new DomainError('Amount must be positive');
    }
    if (amount.isGreaterThan(this.balance)) {
      throw new InsufficientFundsError(this.balance, amount);
    }

    // Core logic
    this.balance = this.balance.subtract(amount);

    // Postcondition (invariant) could be asserted in tests
  }
}

// ✅ GOOD: Rich domain objects with behavior
interface StatusCalculationInput {
  aquarium: Aquarium;                    // Has type, size, etc.
  animalHistory: AquariumAnimalHistory;  // Has hasInvertebrates()
  plantHistory: AquariumPlantHistory;    // Has hasHighDemandPlants()
  referenceDate: Date;
}

service.calculate(input);  // 4 parameters

// ❌ BAD: Primitive obsession
service.calculate(
  aquariumId,           // Could get from aquarium
  aquariumType,         // Could get from aquarium
  animals,              // Raw data, no behavior
  hasInvertebrates,     // Pre-calculated flag
  shrimpType,           // Pre-calculated value
  plants,               // Raw data
  hasHighDemandPlants,  // Pre-calculated flag
  referenceDate
);  // 8+ parameters - a code smell

// ✅ GOOD: Strong contract - data that exists together is required
interface AquariumWithHistory {
  aquarium: Aquarium;                    // Required
  animalHistory: AquariumAnimalHistory;  // Required - created with aquarium
  plantHistory: AquariumPlantHistory;    // Required - created with aquarium
  settings: AquariumSettings;            // Required - created with aquarium
}

// ❌ BAD: Weak contract - everything optional
interface AquariumData {
  aquariumId?: number;
  aquariumType?: string | null;
  animalHistory?: Animal[] | null;
  plantHistory?: Plant[] | null;
}

// Result: defensive null checks everywhere
if (data.animalHistory && data.aquariumType) { ... }

// ✅ FACTORY: Encapsulates complex creation logic
class AquariumFactory {
  create(params: CreateAquariumParams): Aquarium {
    const aquarium = new Aquarium(
      AquariumId.generate(),
      params.name,
      params.type
    );

    // Factory ensures all invariants are satisfied at creation
    const defaultSettings = this.createDefaultSettings(params.type);
    aquarium.applySettings(defaultSettings);

    // Creates related entities together
    const emptyHistory = AquariumHistory.empty(aquarium.id);

    return aquarium;
  }

  private createDefaultSettings(type: AquariumType): AquariumSettings {
    // Complex logic to determine defaults based on type
    return type === AquariumType.Marine
      ? MarineDefaults.create()
      : FreshwaterDefaults.create();
  }
}

// ❌ BAD: Creation logic scattered in services
class AquariumService {
  create(params: CreateParams): Aquarium {
    const aquarium = new Aquarium();
    aquarium.id = generateId();  // Direct property access
    aquarium.name = params.name;
    aquarium.settings = this.settingsService.getDefaults(params.type);
    // Easy to forget steps, invariants not protected
    return aquarium;
  }
}

// ✅ SPECIFICATION: Encapsulates business rules
interface Specification<T> {
  isSatisfiedBy(candidate: T): boolean;
  and(other: Specification<T>): Specification<T>;
  or(other: Specification<T>): Specification<T>;
  not(): Specification<T>;
}

class HighDemandPlantSpecification implements Specification<Plant> {
  isSatisfiedBy(plant: Plant): boolean {
    return plant.co2Requirement === CO2Requirement.High ||
           plant.lightRequirement === LightRequirement.High;
  }
}

class InvertebrateSpecification implements Specification<Animal> {
  private readonly invertebrateTypes = [
    AnimalType.Shrimp,
    AnimalType.Snail,
    AnimalType.Crab
  ];

  isSatisfiedBy(animal: Animal): boolean {
    return this.invertebrateTypes.includes(animal.type);
  }
}

// Usage in domain
class AquariumPlantHistory {
  hasHighDemandPlants(): boolean {
    const spec = new HighDemandPlantSpecification();
    return this.activePlants.some(plant => spec.isSatisfiedBy(plant));
  }
}

// Composable specifications
const premiumCustomer = new HighValueSpecification()
  .and(new LongTermSpecification())
  .and(new GoodPaymentHistorySpecification().not().not());  // Double negation = itself

// DOMAIN SERVICE: Business logic that doesn't belong to single entity
class WaterCompatibilityService {
  // Pure domain logic, no I/O
  checkCompatibility(
    fish: Fish[],
    plants: Plant[],
    waterParams: WaterParameters
  ): CompatibilityReport {
    const issues: CompatibilityIssue[] = [];

    for (const f of fish) {
      if (!f.tolerates(waterParams.temperature)) {
        issues.push(new TemperatureIncompatibility(f, waterParams.temperature));
      }
    }

    return new CompatibilityReport(issues);
  }
}

// APPLICATION SERVICE: Orchestrates use case, handles I/O
class AddFishToAquariumUseCase {
  constructor(
    private readonly aquariumRepo: AquariumRepository,
    private readonly compatibilityService: WaterCompatibilityService
  ) {}

  async execute(aquariumId: AquariumId, fishToAdd: Fish): Promise<void> {
    // 1. Load aggregate
    const aquarium = await this.aquariumRepo.findById(aquariumId);

    // 2. Use domain service for cross-entity logic
    const report = this.compatibilityService.checkCompatibility(
      [...aquarium.fish, fishToAdd],
      aquarium.plants,
      aquarium.currentWaterParams
    );

    if (report.hasBlockingIssues()) {
      throw new IncompatibleFishError(report);
    }

    // 3. Domain logic in aggregate
    aquarium.addFish(fishToAdd);

    // 4. Persist
    await this.aquariumRepo.save(aquarium);
  }
}

// ✅ Appropriate: Cross-entity domain logic
class TaxCalculationService {
  calculate(order: Order, customer: Customer, jurisdiction: Jurisdiction): Tax {
    // Complex tax logic involving multiple entities
  }
}

// ✅ Appropriate: Application orchestration with I/O
class OrderFulfillmentService {
  async fulfill(orderId: OrderId): Promise<void> {
    const order = await this.orderRepo.findById(orderId);
    const inventory = await this.inventoryRepo.findForProducts(order.productIds);

    order.markAsFulfilling();           // Domain logic in entity
    inventory.reserve(order.items);     // Domain logic in entity

    await this.orderRepo.save(order);
    await this.inventoryRepo.save(inventory);
  }
}

// ✅ REPOSITORY: Collection-like interface, hides persistence details
interface AquariumRepository {
  findById(id: AquariumId): Promise<Aquarium | null>;
  findByOwner(ownerId: UserId): Promise<Aquarium[]>;
  save(aquarium: Aquarium): Promise<void>;
  remove(aquarium: Aquarium): Promise<void>;

  // Domain-specific queries
  findRequiringMaintenance(before: Date): Promise<Aquarium[]>;
}

// ❌ BAD: Generic repository (violates DDD principles)
interface Repository<T> {
  find(conditions: Partial<T>): Promise<T[]>;
  findOne(conditions: Partial<T>): Promise<T | null>;
  save(entity: T): Promise<void>;
}

// ✅ Easy to test: pure domain logic
test('order calculates total correctly', () => {
  const order = new Order();
  order.addItem(product, 2);
  expect(order.getTotal()).toEqual(Money.of(200, 'USD'));
});

// ❌ Harder to test: service with dependencies
test('service calculates total', () => {
  const mockRepo = mock<OrderRepository>();
  const service = new OrderService(mockRepo);
  // Setup mocks, call service, verify mocks...
});