UML Class Diagrams: Structural Architecture & Domain Modeling

The Unified Modeling Language (UML) Class Diagram is a universal engineering abstraction used to visualize, specify, construct, and document the structural architecture of Object-Oriented software systems. In enterprise architecture and Domain-Driven Design (DDD), class diagrams establish a clear blueprint of system domain constructs, clear boundaries of functional data ownership, polymorphic behaviors, and relational lifecycles before physical code synthesis takes place.

1. Core Structural Anatomy of a Class

A UML Class representation consists of a compartmentalized structural rectangle divided into three distinct operational sectors:

+-------------------------------------------------------------+
|                      <<Stereotype>>                         |
|                      ClassIdentifier                        |
+-------------------------------------------------------------+
| [Visibility] attributeName : DataType [Multiplicity] = Val  |
+-------------------------------------------------------------+
| [Visibility] methodName(param : DataType) : ReturnType     |
+-------------------------------------------------------------+

Visibility Modifiers

Visibility annotations specify data encapsulation boundary constraints and accessibility across class relationships:

2. Taxonomy of Class Relationships & Lifecycle Ownership

Understanding the syntactic representation and runtime memory mechanics of class relationships is critical for designing decoupled architectures.

classDiagram
    class Association_Client {
        -service: Association_Service
    }
    class Association_Service {
        +execute() void
    }
    Association_Client --> Association_Service : Directed Association

    class Aggregation_Department {
        -faculty: List~Professor~
    }
    class Aggregation_Professor {
        -name: String
    }
    Aggregation_Department o-- Aggregation_Professor : Aggregation (Shared Lifecycle)

    class Composition_Car {
        -engine: Engine
    }
    class Composition_Engine {
        -horsepower: int
    }
    Composition_Car *-- Composition_Engine : Composition (Owned Lifecycle)

    class Generalization_Account {
        <<Abstract>>
        #balance: Decimal
        +withdraw(val: Decimal)* void
    }
    class Generalization_SavingsAccount {
        -interestRate: float
        +withdraw(val: Decimal) void
    }
    Generalization_Account <|-- Generalization_SavingsAccount : Inheritance (Is-A)

    class Realization_Repository {
        <<Interface>>
        +save(obj: Any) boolean
    }
    class Realization_SQLRepository {
        +save(obj: Any) boolean
    }
    Realization_Repository <|.. Realization_SQLRepository : Realization (Implements)

    class Dependency_Controller {
        +process(logger: Logger) void
    }
    class Dependency_Logger {
        +log(msg: String) void
    }
    Dependency_Controller ..> Dependency_Logger : Dependency (Uses)

Deep Dive: Aggregation vs. Composition

Distinguishing between Aggregation and Composition requires analyzing data lifecycles and memory ownership semantics:

Aggregation (`o--` Open Diamond) — Has-a (Shared Lifecycle)

Conceptual Definition: Represents an asymmetrical part-whole relationship where child entities can outlive the lifetime of their parent container.
Database & Memory Implication: In relational databases, this maps to a foreign key relationship where deleting the parent record leaves child entities completely intact (e.g., ON DELETE SET NULL). In application memory, the child object is injected into the container via constructor references and is managed externally.
Example: A University Department aggregates Professor instances. If the department closes, the professors retain their academic standing and transition to other faculties.

Composition (`--` Filled Diamond) — Contains-a (Exclusive Owned Lifecycle)*

Conceptual Definition: Represents a strict part-whole structural hierarchy with strict physical lifecycle dependency. The part cannot exist independently of the composite container.
Database & Memory Implication: In database schemas, this requires an identifying foreign key configured with cascading deletion rules (ON DELETE CASCADE). In runtime memory, the parent container instantiated the child directly; when the parent is garbage-collected or explicitly dropped from memory, all constituent components are automatically destroyed.
Example: A Car composes an Engine. In strict domain modeling, a specific serialized engine belongs solely to that single vehicle structure; if the car object is purged from state, its internal mechanics cease to exist independently.

3. Multiplicity & Cardinality Constraints

Multiplicity notations define explicit numeric boundary validation parameters governing how many distinct instances of one class can link to another across a designated architectural relationship.

4. Comprehensive Production Domain Blueprint: E-Commerce Architecture

The diagram below integrates advanced UML structural relationships into a fully fully cohesive e-commerce checkout and logistics domain architecture.

classDiagram
    %% Core Domain Interfaces
    class IPaymentGateway {
        <<Interface>>
        +authorize(amount: Decimal) TransactionResult
        +capture(txId: String) boolean
        +refund(txId: String) boolean
    }

    class IAuditable {
        <<Interface>>
        +getCreatedAt() DateTime
        +getUpdatedAt() DateTime
    }

    %% Abstract Domain Entities
    class DomainEntity {
        <<Abstract>>
        #id: UUID
        #version: int
        +getId() UUID
        +validate()* boolean
    }
    DomainEntity ..|> IAuditable

    %% Concrete Domain Classes
    class Customer {
        -email: String
        -encryptedPassword: String
        -loyaltyTier: LoyaltyStatus
        +placeOrder(cart: ShoppingCart) Order
    }
    Customer --|> DomainEntity

    class ShoppingCart {
        -sessionToken: String
        -expiresAt: DateTime
        +addItem(product: Product, quantity: int) void
        +clear() void
    }
    ShoppingCart --|> DomainEntity

    class CartItem {
        -quantity: int
        -unitPriceSnapshot: Decimal
        +getSubtotal() Decimal
    }

    class Product {
        -sku: String
        -title: String
        -basePrice: Decimal
        -weightInGrams: int
        +checkInventory() boolean
    }
    Product --|> DomainEntity

    class Order {
        -orderStatus: OrderState
        -totalTax: Decimal
        -totalAmount: Decimal
        +confirmPayment(gateway: IPaymentGateway) void
    }
    Order --|> DomainEntity

    class OrderItem {
        -quantity: int
        -lockedPrice: Decimal
        +calculateItemTax() Decimal
    }

    class Shipment {
        -trackingNumber: String
        -carrier: CarrierType
        -shippedAt: DateTime
        +generateLabel() PDF Document
    }
    Shipment --|> DomainEntity

    class Address {
        <<Value Object>>
        -street: String
        -city: String
        -postalCode: String
        -country: String
    }

    %% Structural Relationships & Cardinalities
    Customer "1" --> "0..1" ShoppingCart : manages >
    Customer "1" --> "0..*" Order : executes >
    Customer "1" o-- "1..*" Address : billing / shipping addresses

    ShoppingCart "1" *-- "0..*" CartItem : owns components
    CartItem "0..*" --> "1" Product : references >

    Order "1" *-- "1..*" OrderItem : composition
    OrderItem "0..*" --> "1" Product : reserves >
    Order "1" o-- "1" Address : ships to >
    Order "1" --> "0..*" Shipment : fulfills >
    
    Order ..> IPaymentGateway : dependencies (uses)

5. Production Code Synthesis: Mapping UML to Code

To transform abstract structural models into robust implementations, engineers must apply consistent patterns for lifecycles and dependency injection. Below is a production-grade TypeScript implementation mapping out the exact structural semantics shown above.

import { randomUUID } from 'crypto';

// ============================================================================
// CORE ABSTRACTIONS & INTERFACES (UML Realization: ..|>)
// ============================================================================

export interface IAuditable {
  readonly createdAt: Date;
  updatedAt: Date;
}

export interface IPaymentGateway {
  authorize(amount: number): Promise<{ success: boolean; transactionId: string }>;
  capture(transactionId: string): Promise<boolean>;
  refund(transactionId: string): Promise<boolean>;
}

export abstract class DomainEntity implements IAuditable {
  protected readonly id: string;
  protected version: number = 1;
  public readonly createdAt: Date;
  public updatedAt: Date;

  constructor(id?: string) {
    this.id = id ?? randomUUID();
    this.createdAt = new Date();
    this.updatedAt = new Date();
  }

  public getId(): string {
    return this.id;
  }

  // Abstract contractual method required for polymorphic subclass instantiation
  public abstract validate(): boolean;
}

// ============================================================================
// VALUE OBJECTS (UML Composition & Immutable State)
// ============================================================================

export class Address {
  constructor(
    public readonly street: string,
    public readonly city: string,
    public readonly postalCode: string,
    public readonly country: string
  ) {
    Object.freeze(this); // Ensure strict runtime immutability
  }
}

// ============================================================================
// CONCRETE DOMAIN IMPLEMENTATIONS (UML Generalization & Inheritance: --|>)
// ============================================================================

export class Product extends DomainEntity {
  constructor(
    public readonly sku: string,
    public title: string,
    private basePrice: number,
    private inventoryCount: number
  ) {
    super();
  }

  public validate(): boolean {
    return this.basePrice >= 0 && this.inventoryCount >= 0 && this.sku.length > 0;
  }

  public getPrice(): number {
    return this.basePrice;
  }

  public decrementStock(quantity: number): void {
    if (this.inventoryCount < quantity) {
      throw new Error(`Insufficient stock for SKU: ${this.sku}`);
    }
    this.inventoryCount -= quantity;
    this.updatedAt = new Date();
  }
}

// UML Composition: OrderItem is totally dependent on Order lifecycle (*--)
export class OrderItem {
  private readonly lockedPrice: number;

  constructor(
    private readonly product: Product, // UML Association: --> references Product
    private readonly quantity: number
  ) {
    if (quantity <= 0) throw new Error('Quantity must be positive.');
    // Freeze price snapshot at moment of purchase
    this.lockedPrice = product.getPrice();
  }

  public getSubtotal(): number {
    return this.lockedPrice * this.quantity;
  }
}

export enum OrderState {
  PENDING = 'PENDING',
  PAID = 'PAID',
  SHIPPED = 'SHIPPED',
  CANCELLED = 'CANCELLED',
}

export class Order extends DomainEntity {
  private status: OrderState = OrderState.PENDING;
  private readonly items: OrderItem[] = []; // UML Composition: Order *-- OrderItem

  constructor(
    private readonly customerId: string,
    private readonly shippingAddress: Address // UML Aggregation / Association: o-- Address
  ) {
    super();
  }

  // Composition lifecycle enforcement: items exist solely within Order instantiation
  public addOrderItem(product: Product, quantity: number): void {
    if (this.status !== OrderState.PENDING) {
      throw new Error('Cannot append items to an already processed order.');
    }
    const item = new OrderItem(product, quantity);
    this.items.push(item);
    this.updatedAt = new Date();
  }

  public calculateTotal(): number {
    return this.items.reduce((sum, item) => sum + item.getSubtotal(), 0);
  }

  public validate(): boolean {
    return this.items.length > 0 && this.customerId.length > 0;
  }

  // UML Dependency: (Order ..> IPaymentGateway)
  // PaymentGateway is passed temporarily as a method parameter; Order does NOT own it
  public async processCheckout(gateway: IPaymentGateway): Promise<string> {
    if (!this.validate()) {
      throw new Error('Order verification failed: Invalid order state.');
    }

    const total = this.calculateTotal();
    const authResult = await gateway.authorize(total);

    if (!authResult.success) {
      this.status = OrderState.CANCELLED;
      throw new Error('Payment authorization rejected.');
    }

    const captured = await gateway.capture(authResult.transactionId);
    if (!captured) {
      this.status = OrderState.CANCELLED;
      throw new Error('Payment capture processing failed.');
    }

    this.status = OrderState.PAID;
    this.updatedAt = new Date();
    return authResult.transactionId;
  }
}

6. Mathematical Evaluation of Domain Model Complexity

Evaluating whether an object-oriented domain model is tightly coupled or well-structured requires calculating algorithmic architecture design quality metrics.

1. Structural Coupling & Instability Metrics (Robert C. Martin's Package Principles)

For any module or class package represented in a diagram, define two dependencies:

Centripetal Coupling ( $C_a$ , Incoming Dependencies): The number of external domain classes that depend on internal entities within the measured package (e.g., classes implementing interfaces defined in this package).
Centrifugal Coupling ( $C_e$ , Outgoing Dependencies): The number of internal classes that depend directly on external entities outside the measured package.

The architectural Instability ( $I$ ) metric is derived via the equation:

$I = \frac{C_e}{C_a + C_e}, \quad \text{where } I \in [0, 1]$

$I = 0$ (Maximally Stable): The class package has zero outgoing dependencies ( $C_e = 0$ ) but numerous dependents ( $C_a > 0$ ). Modifying structural implementations within this component introduces high breaking-change risk across downstream codebases.
$I = 1$ (Maximally Unstable): The package depends heavily on external utilities ( $C_e > 0$ ), but nothing depends on it ( $C_a = 0$ ). It can be refactored safely with zero blast radius.

2. The Main Sequence & Distance Approximation

To preserve adaptability, stable components ( $I \approx 0$ ) should be heavily abstract (composed primarily of Interfaces and Abstract classes), whereas unstable utility components ( $I \approx 1$ ) should be predominantly concrete implementations. Let Abstractness ( $A$ ) be defined as:

$A = \frac{\text{Number of Abstract Classes and Interfaces in Module}}{\text{Total Number of Classes in Module}}, \quad \text{where } A \in [0, 1]$

The structural health of an architectural component is evaluated by its Normalized Distance ( $D$ ) from the optimal structural equilibrium line ( $A + I = 1$ , known as The Main Sequence):

$D = |A + I - 1|, \quad \text{where } D \in [0, 1]$

$D \approx 0$ (Optimal Architectural Design): The component is balanced, exhibiting stability commensurate with its level of abstraction.
Zone of Pain ( $D \approx 1, A \approx 0, I \approx 0$ ): Highly stable components that are entirely concrete (e.g., legacy database global utility classes). Because many modules depend on them, altering their internal implementations induces cascading errors.
Zone of Uselessness ( $D \approx 1, A \approx 1, I \approx 1$ ): Highly abstract structural interfaces with zero external dependents, creating unnecessary mental overhead and boilerplates.

7. Common Architectural Antipatterns

When evaluating class diagrams during software architectural reviews, actively audit for these severe structural antipatterns:

The God Class / Blob (Anemia vs. Over-Consolidated Cohesion):
- Symptom: A single class coordinates dozens of divergent operational responsibilities, exhibiting dozens of incoming associations and high centrifugal dependency counts ( $C_e$ ).
- Remediation: Enforce the Single Responsibility Principle (SRP). Decompose the class into specialized structural value objects, dedicated service executors, and clear aggregate boundaries using composition ( $*--$ ).
Circular Dependency Loops ( $A \to B \to C \to A$ ):
- Symptom: Directed association chains create tight cyclical interdependencies, preventing clean module separation or independent testing.
- Remediation: Apply Dependency Inversion (DIP). Introduce an intermediary Interface ( $<<\text{Interface}>>$ ) at the structural boundary, converting directed operational association arcs into Interface Realizations ( $\dots|\rangle$ ).
Improper Inheritance for Code Reuse (The Banana-Monkey-Jungle Problem):
- Symptom: Subclasses generalize ( $---| \rangle$ ) from concrete base entities simply to inherit a small helper utility method, inadvertently pulling along massive inheritance trees and invalidating Liskov Substitution Principle semantics.
- Remediation: Favor Composition over Inheritance. Convert structural general subclasses into clear independent classes that delegate localized utility functions via private composition ( $*--$ ) references.

UML Class Diagrams: Structural Architecture & Domain Modeling

1. Core Structural Anatomy of a Class

A UML Class representation consists of a compartmentalized structural rectangle divided into three distinct operational sectors:

+-------------------------------------------------------------+
|                      <<Stereotype>>                         |
|                      ClassIdentifier                        |
+-------------------------------------------------------------+
| [Visibility] attributeName : DataType [Multiplicity] = Val  |
+-------------------------------------------------------------+
| [Visibility] methodName(param : DataType) : ReturnType     |
+-------------------------------------------------------------+

Visibility Modifiers

Visibility annotations specify data encapsulation boundary constraints and accessibility across class relationships:

2. Taxonomy of Class Relationships & Lifecycle Ownership

Understanding the syntactic representation and runtime memory mechanics of class relationships is critical for designing decoupled architectures.

classDiagram
    class Association_Client {
        -service: Association_Service
    }
    class Association_Service {
        +execute() void
    }
    Association_Client --> Association_Service : Directed Association

    class Aggregation_Department {
        -faculty: List~Professor~
    }
    class Aggregation_Professor {
        -name: String
    }
    Aggregation_Department o-- Aggregation_Professor : Aggregation (Shared Lifecycle)

    class Composition_Car {
        -engine: Engine
    }
    class Composition_Engine {
        -horsepower: int
    }
    Composition_Car *-- Composition_Engine : Composition (Owned Lifecycle)

    class Generalization_Account {
        <<Abstract>>
        #balance: Decimal
        +withdraw(val: Decimal)* void
    }
    class Generalization_SavingsAccount {
        -interestRate: float
        +withdraw(val: Decimal) void
    }
    Generalization_Account <|-- Generalization_SavingsAccount : Inheritance (Is-A)

    class Realization_Repository {
        <<Interface>>
        +save(obj: Any) boolean
    }
    class Realization_SQLRepository {
        +save(obj: Any) boolean
    }
    Realization_Repository <|.. Realization_SQLRepository : Realization (Implements)

    class Dependency_Controller {
        +process(logger: Logger) void
    }
    class Dependency_Logger {
        +log(msg: String) void
    }
    Dependency_Controller ..> Dependency_Logger : Dependency (Uses)

Deep Dive: Aggregation vs. Composition

Distinguishing between Aggregation and Composition requires analyzing data lifecycles and memory ownership semantics:

Aggregation (`o--` Open Diamond) — Has-a (Shared Lifecycle)

Conceptual Definition: Represents an asymmetrical part-whole relationship where child entities can outlive the lifetime of their parent container.
Database & Memory Implication: In relational databases, this maps to a foreign key relationship where deleting the parent record leaves child entities completely intact (e.g., ON DELETE SET NULL). In application memory, the child object is injected into the container via constructor references and is managed externally.
Example: A University Department aggregates Professor instances. If the department closes, the professors retain their academic standing and transition to other faculties.

Composition (`--` Filled Diamond) — Contains-a (Exclusive Owned Lifecycle)*

Conceptual Definition: Represents a strict part-whole structural hierarchy with strict physical lifecycle dependency. The part cannot exist independently of the composite container.
Database & Memory Implication: In database schemas, this requires an identifying foreign key configured with cascading deletion rules (ON DELETE CASCADE). In runtime memory, the parent container instantiated the child directly; when the parent is garbage-collected or explicitly dropped from memory, all constituent components are automatically destroyed.
Example: A Car composes an Engine. In strict domain modeling, a specific serialized engine belongs solely to that single vehicle structure; if the car object is purged from state, its internal mechanics cease to exist independently.

3. Multiplicity & Cardinality Constraints

Multiplicity notations define explicit numeric boundary validation parameters governing how many distinct instances of one class can link to another across a designated architectural relationship.

4. Comprehensive Production Domain Blueprint: E-Commerce Architecture

The diagram below integrates advanced UML structural relationships into a fully fully cohesive e-commerce checkout and logistics domain architecture.

classDiagram
    %% Core Domain Interfaces
    class IPaymentGateway {
        <<Interface>>
        +authorize(amount: Decimal) TransactionResult
        +capture(txId: String) boolean
        +refund(txId: String) boolean
    }

    class IAuditable {
        <<Interface>>
        +getCreatedAt() DateTime
        +getUpdatedAt() DateTime
    }

    %% Abstract Domain Entities
    class DomainEntity {
        <<Abstract>>
        #id: UUID
        #version: int
        +getId() UUID
        +validate()* boolean
    }
    DomainEntity ..|> IAuditable

    %% Concrete Domain Classes
    class Customer {
        -email: String
        -encryptedPassword: String
        -loyaltyTier: LoyaltyStatus
        +placeOrder(cart: ShoppingCart) Order
    }
    Customer --|> DomainEntity

    class ShoppingCart {
        -sessionToken: String
        -expiresAt: DateTime
        +addItem(product: Product, quantity: int) void
        +clear() void
    }
    ShoppingCart --|> DomainEntity

    class CartItem {
        -quantity: int
        -unitPriceSnapshot: Decimal
        +getSubtotal() Decimal
    }

    class Product {
        -sku: String
        -title: String
        -basePrice: Decimal
        -weightInGrams: int
        +checkInventory() boolean
    }
    Product --|> DomainEntity

    class Order {
        -orderStatus: OrderState
        -totalTax: Decimal
        -totalAmount: Decimal
        +confirmPayment(gateway: IPaymentGateway) void
    }
    Order --|> DomainEntity

    class OrderItem {
        -quantity: int
        -lockedPrice: Decimal
        +calculateItemTax() Decimal
    }

    class Shipment {
        -trackingNumber: String
        -carrier: CarrierType
        -shippedAt: DateTime
        +generateLabel() PDF Document
    }
    Shipment --|> DomainEntity

    class Address {
        <<Value Object>>
        -street: String
        -city: String
        -postalCode: String
        -country: String
    }

    %% Structural Relationships & Cardinalities
    Customer "1" --> "0..1" ShoppingCart : manages >
    Customer "1" --> "0..*" Order : executes >
    Customer "1" o-- "1..*" Address : billing / shipping addresses

    ShoppingCart "1" *-- "0..*" CartItem : owns components
    CartItem "0..*" --> "1" Product : references >

    Order "1" *-- "1..*" OrderItem : composition
    OrderItem "0..*" --> "1" Product : reserves >
    Order "1" o-- "1" Address : ships to >
    Order "1" --> "0..*" Shipment : fulfills >
    
    Order ..> IPaymentGateway : dependencies (uses)

5. Production Code Synthesis: Mapping UML to Code

import { randomUUID } from 'crypto';

// ============================================================================
// CORE ABSTRACTIONS & INTERFACES (UML Realization: ..|>)
// ============================================================================

export interface IAuditable {
  readonly createdAt: Date;
  updatedAt: Date;
}

export interface IPaymentGateway {
  authorize(amount: number): Promise<{ success: boolean; transactionId: string }>;
  capture(transactionId: string): Promise<boolean>;
  refund(transactionId: string): Promise<boolean>;
}

export abstract class DomainEntity implements IAuditable {
  protected readonly id: string;
  protected version: number = 1;
  public readonly createdAt: Date;
  public updatedAt: Date;

  constructor(id?: string) {
    this.id = id ?? randomUUID();
    this.createdAt = new Date();
    this.updatedAt = new Date();
  }

  public getId(): string {
    return this.id;
  }

  // Abstract contractual method required for polymorphic subclass instantiation
  public abstract validate(): boolean;
}

// ============================================================================
// VALUE OBJECTS (UML Composition & Immutable State)
// ============================================================================

export class Address {
  constructor(
    public readonly street: string,
    public readonly city: string,
    public readonly postalCode: string,
    public readonly country: string
  ) {
    Object.freeze(this); // Ensure strict runtime immutability
  }
}

// ============================================================================
// CONCRETE DOMAIN IMPLEMENTATIONS (UML Generalization & Inheritance: --|>)
// ============================================================================

export class Product extends DomainEntity {
  constructor(
    public readonly sku: string,
    public title: string,
    private basePrice: number,
    private inventoryCount: number
  ) {
    super();
  }

  public validate(): boolean {
    return this.basePrice >= 0 && this.inventoryCount >= 0 && this.sku.length > 0;
  }

  public getPrice(): number {
    return this.basePrice;
  }

  public decrementStock(quantity: number): void {
    if (this.inventoryCount < quantity) {
      throw new Error(`Insufficient stock for SKU: ${this.sku}`);
    }
    this.inventoryCount -= quantity;
    this.updatedAt = new Date();
  }
}

// UML Composition: OrderItem is totally dependent on Order lifecycle (*--)
export class OrderItem {
  private readonly lockedPrice: number;

  constructor(
    private readonly product: Product, // UML Association: --> references Product
    private readonly quantity: number
  ) {
    if (quantity <= 0) throw new Error('Quantity must be positive.');
    // Freeze price snapshot at moment of purchase
    this.lockedPrice = product.getPrice();
  }

  public getSubtotal(): number {
    return this.lockedPrice * this.quantity;
  }
}

export enum OrderState {
  PENDING = 'PENDING',
  PAID = 'PAID',
  SHIPPED = 'SHIPPED',
  CANCELLED = 'CANCELLED',
}

export class Order extends DomainEntity {
  private status: OrderState = OrderState.PENDING;
  private readonly items: OrderItem[] = []; // UML Composition: Order *-- OrderItem

  constructor(
    private readonly customerId: string,
    private readonly shippingAddress: Address // UML Aggregation / Association: o-- Address
  ) {
    super();
  }

  // Composition lifecycle enforcement: items exist solely within Order instantiation
  public addOrderItem(product: Product, quantity: number): void {
    if (this.status !== OrderState.PENDING) {
      throw new Error('Cannot append items to an already processed order.');
    }
    const item = new OrderItem(product, quantity);
    this.items.push(item);
    this.updatedAt = new Date();
  }

  public calculateTotal(): number {
    return this.items.reduce((sum, item) => sum + item.getSubtotal(), 0);
  }

  public validate(): boolean {
    return this.items.length > 0 && this.customerId.length > 0;
  }

  // UML Dependency: (Order ..> IPaymentGateway)
  // PaymentGateway is passed temporarily as a method parameter; Order does NOT own it
  public async processCheckout(gateway: IPaymentGateway): Promise<string> {
    if (!this.validate()) {
      throw new Error('Order verification failed: Invalid order state.');
    }

    const total = this.calculateTotal();
    const authResult = await gateway.authorize(total);

    if (!authResult.success) {
      this.status = OrderState.CANCELLED;
      throw new Error('Payment authorization rejected.');
    }

    const captured = await gateway.capture(authResult.transactionId);
    if (!captured) {
      this.status = OrderState.CANCELLED;
      throw new Error('Payment capture processing failed.');
    }

    this.status = OrderState.PAID;
    this.updatedAt = new Date();
    return authResult.transactionId;
  }
}

6. Mathematical Evaluation of Domain Model Complexity

Evaluating whether an object-oriented domain model is tightly coupled or well-structured requires calculating algorithmic architecture design quality metrics.

1. Structural Coupling & Instability Metrics (Robert C. Martin's Package Principles)

For any module or class package represented in a diagram, define two dependencies:

Centripetal Coupling ( $C_a$ , Incoming Dependencies): The number of external domain classes that depend on internal entities within the measured package (e.g., classes implementing interfaces defined in this package).
Centrifugal Coupling ( $C_e$ , Outgoing Dependencies): The number of internal classes that depend directly on external entities outside the measured package.

The architectural Instability ( $I$ ) metric is derived via the equation:

$I = \frac{C_e}{C_a + C_e}, \quad \text{where } I \in [0, 1]$

$I = 0$ (Maximally Stable): The class package has zero outgoing dependencies ( $C_e = 0$ ) but numerous dependents ( $C_a > 0$ ). Modifying structural implementations within this component introduces high breaking-change risk across downstream codebases.
$I = 1$ (Maximally Unstable): The package depends heavily on external utilities ( $C_e > 0$ ), but nothing depends on it ( $C_a = 0$ ). It can be refactored safely with zero blast radius.

2. The Main Sequence & Distance Approximation

$A = \frac{\text{Number of Abstract Classes and Interfaces in Module}}{\text{Total Number of Classes in Module}}, \quad \text{where } A \in [0, 1]$

The structural health of an architectural component is evaluated by its Normalized Distance ( $D$ ) from the optimal structural equilibrium line ( $A + I = 1$ , known as The Main Sequence):

$D = |A + I - 1|, \quad \text{where } D \in [0, 1]$

$D \approx 0$ (Optimal Architectural Design): The component is balanced, exhibiting stability commensurate with its level of abstraction.
Zone of Pain ( $D \approx 1, A \approx 0, I \approx 0$ ): Highly stable components that are entirely concrete (e.g., legacy database global utility classes). Because many modules depend on them, altering their internal implementations induces cascading errors.
Zone of Uselessness ( $D \approx 1, A \approx 1, I \approx 1$ ): Highly abstract structural interfaces with zero external dependents, creating unnecessary mental overhead and boilerplates.

7. Common Architectural Antipatterns

When evaluating class diagrams during software architectural reviews, actively audit for these severe structural antipatterns:

The God Class / Blob (Anemia vs. Over-Consolidated Cohesion):
- Symptom: A single class coordinates dozens of divergent operational responsibilities, exhibiting dozens of incoming associations and high centrifugal dependency counts ( $C_e$ ).
- Remediation: Enforce the Single Responsibility Principle (SRP). Decompose the class into specialized structural value objects, dedicated service executors, and clear aggregate boundaries using composition ( $*--$ ).
Circular Dependency Loops ( $A \to B \to C \to A$ ):
- Symptom: Directed association chains create tight cyclical interdependencies, preventing clean module separation or independent testing.
- Remediation: Apply Dependency Inversion (DIP). Introduce an intermediary Interface ( $<<\text{Interface}>>$ ) at the structural boundary, converting directed operational association arcs into Interface Realizations ( $\dots|\rangle$ ).
Improper Inheritance for Code Reuse (The Banana-Monkey-Jungle Problem):
- Symptom: Subclasses generalize ( $---| \rangle$ ) from concrete base entities simply to inherit a small helper utility method, inadvertently pulling along massive inheritance trees and invalidating Liskov Substitution Principle semantics.
- Remediation: Favor Composition over Inheritance. Convert structural general subclasses into clear independent classes that delegate localized utility functions via private composition ( $*--$ ) references.

UML Class Diagrams: Structural Architecture & Domain Modeling

1. Core Structural Anatomy of a Class

Visibility Modifiers

2. Taxonomy of Class Relationships & Lifecycle Ownership

Deep Dive: Aggregation vs. Composition

Aggregation (o-- Open Diamond) — Has-a (Shared Lifecycle)

Composition (*-- Filled Diamond) — Contains-a (Exclusive Owned Lifecycle)

3. Multiplicity & Cardinality Constraints

4. Comprehensive Production Domain Blueprint: E-Commerce Architecture

5. Production Code Synthesis: Mapping UML to Code

6. Mathematical Evaluation of Domain Model Complexity

1. Structural Coupling & Instability Metrics (Robert C. Martin's Package Principles)

2. The Main Sequence & Distance Approximation

7. Common Architectural Antipatterns

UML Class Diagrams: Structural Architecture & Domain Modeling

1. Core Structural Anatomy of a Class

Visibility Modifiers

2. Taxonomy of Class Relationships & Lifecycle Ownership

Deep Dive: Aggregation vs. Composition

Aggregation (o-- Open Diamond) — Has-a (Shared Lifecycle)

Composition (*-- Filled Diamond) — Contains-a (Exclusive Owned Lifecycle)

3. Multiplicity & Cardinality Constraints

4. Comprehensive Production Domain Blueprint: E-Commerce Architecture

5. Production Code Synthesis: Mapping UML to Code

6. Mathematical Evaluation of Domain Model Complexity

1. Structural Coupling & Instability Metrics (Robert C. Martin's Package Principles)

2. The Main Sequence & Distance Approximation

7. Common Architectural Antipatterns

Aggregation (`o--` Open Diamond) — Has-a (Shared Lifecycle)

Composition (`--` Filled Diamond) — Contains-a (Exclusive Owned Lifecycle)*

Aggregation (`o--` Open Diamond) — Has-a (Shared Lifecycle)

Composition (`--` Filled Diamond) — Contains-a (Exclusive Owned Lifecycle)*