Mastering UML with VPasCode: Online Shop Architecture

PlantUML code and C4 model diagram showing order system architecture

In the world of software architecture, few tools are as critical for bridging the gap between business requirements and technical implementation as the Domain Model. The provided example showcases a classic “Online Shop” scenario, visualized using a UML Class Diagram generated via VPasCode (Visual Paradigm as Code). This approach allows developers to define complex system structures using text-based syntax, ensuring that the code and the design remain in sync.

This tutorial dissects the architecture shown in the diagram, exploring the relationships between Customers, Orders, and Products, while highlighting the specific modeling decisions that ensure data integrity and business logic accuracy.

1. The Core Entities: Customer and Order

The foundation of any e-commerce system lies in the interaction between the buyer and the transaction. In this model, the Customer and Order classes represent these primary actors.

The Customer class is kept relatively simple, focusing on unique identification and contact information. It utilizes standard data types like UUID for identifiers and specific value types like EmailAddress to enforce data validity at the type level.

class Customer {
   +customerId: UUID
   +email: EmailAddress
   +displayName: String
}

The Order class captures the state of a transaction. Crucially, it includes a status attribute of type OrderStatus. This attribute is not just a string, but an enumeration that restricts the lifecycle of the order to specific, valid states (e.g., DRAFT, PLACED, FULFILLED).

class Order {
   +orderId: UUID
   +placedAt: DateTime
   +status: OrderStatus
   +total: Money
}

2. The Power of Composition: Order and OrderLine

One of the most distinct features of this diagram is the relationship between Order and OrderLine. The diagram uses a filled diamond symbol, indicating Composition.

Why Model OrderLine Explicitly?
In a database, one might be tempted to simply store a foreign key linking an Order to a Product. However, an Order-Line is a domain concept. It carries specific data—quantity and the unitPrice at the time of purchase. It is a distinct entity that describes “how much of X was bought in Y.”

The VPasCode syntax for this composition is explicit:

Order "1" *-- "1..*" OrderLine : contains

This relationship dictates that an Order contains OrderLines. The composition symbol implies strong ownership: if the Order is deleted, the OrderLine objects cease to exist. They are not meaningful independently of the order they belong to.

3. Handling Price History and Value Objects

Perhaps the most critical architectural decision in this model is how it handles pricing. The diagram distinguishes between Product.currentPrice and OrderLine.unitPrice.

In the real world, product prices fluctuate. If you buy a laptop today for $1,000, but the price drops to $900 tomorrow, your historical order should still reflect the $1,000 you actually paid. Therefore, the OrderLine class captures a snapshot of the price.

This is further reinforced by the use of Value Objects. The Money class is marked with the stereotype <<value object>>. Unlike Entities, Value Objects do not have a unique identity; they are defined entirely by their attributes (amount and currency). By embedding Money directly into OrderLine, the model ensures that the price is immutable once the order is placed.

class Money <<value object>> {
   +amount: Decimal
   +currency: CurrencyCode
}

4. The Role of Payment and Status Enums

The diagram introduces a Payment class that is linked to the Order. This separation allows for complex payment scenarios, such as partial payments or multiple payment attempts, where a single order might not be tied to a single payment record.

The use of Enums like OrderStatus and PaymentStatus ensures that the system does not accept invalid states. For example, a payment cannot be “CAPTURED” if the order is in the “DRAFT” state.

enum OrderStatus {
   DRAFT
   PLACED
   PAID
   FULFILLED
   CANCELLED
}

5. Semantic Constraints in VPasCode

VPasCode allows developers to embed business rules directly into the diagram definition using note blocks. These notes serve as documentation for future developers, explaining the “why” behind the data structure.

For instance, the note attached to OrderLine clarifies that the quantity must be positive and that the unit price is historical:

note right of OrderLine
   quantity must be greater than zero
   unitPrice is the price captured
   when the order is placed
end note

Similarly, the note on the Product class warns against updating the historical price:

note right of Product
   Product.currentPrice may change.
   It does not replace OrderLine.unitPrice.
end note

Conclusion

This diagram serves as a robust blueprint for an e-commerce system. By using composition to manage OrderLines, value objects to handle Money, and enums to govern status, the architecture enforces business rules at the design level. The VPasCode tool allows this complex structure to be defined textually, making it version-controllable and easily integrated into CI/CD pipelines.