Enterprise Patterns

Language-agnostic tutorials based on "Enterprise Patterns and MDA" by Jim Arlow & Ila Neustadt

Software Archetypes is an open reference for the data patterns that underpin almost every business system: how to model people and organizations, products and catalogs, orders, payments, inventory and shipments. Each pattern starts from a real problem, walks through the structure with a UML class diagram, then shows the SQL schema, the lifecycle as a state machine, and the invariants that must hold at runtime.

The patterns are based on Jim Arlow and Ila Neustadt's Enterprise Patterns and MDA, refined with two decades of building production systems. They're written for backend engineers and architects who want a starting point that's been battle-tested across industries — not a textbook abstraction, but a working data model you can lift into PostgreSQL, MySQL or any RDBMS today.

All examples ship with working implementations in PHP, Java and TypeScript. Each pattern is roughly 10–15 minutes of reading and a self-contained mental model you can apply on its own or compose with the others.

Overview

Each pattern is presented with:

• Problem statement — When you need this pattern
• Conceptual overview — Core idea
• Structure — Mermaid class diagrams
• Behaviors — Pseudocode for operations
• State machines — Lifecycle diagrams
• Invariants — Business rules that must hold
• SQL schema — ANSI SQL for persistence
• Design considerations — Trade-offs and alternatives

Pattern Catalog

Party Archetype (Who)

Product Archetype (What)

Transaction Patterns (Commerce)

Pattern Relationships

End-to-End Integration Scenario

This walkthrough shows how all patterns connect in a typical e-commerce flow: a customer places an order, pays, stock is reserved, and the order is shipped.

1. Party Setup

// Jan Kowalski is registered as a Person with a Customer role
jan = new Person(firstName: "Jan", lastName: "Kowalski")
jan.addIdentifier(PESEL, "85031512345")
jan.addAddress(homeAddress)

customerRole = new Customer(
    party: jan,
    customerNumber: "CUST-00001234",
    loyaltyTier: LoyaltyTier.Gold,
    creditLimit: Money(1000000, "PLN")
)

2. Order Placement

order = new Order(
    orderNumber: "ORD-2026-000042",
    customer: customerRole,
    currency: "PLN",
    billingAddress: jan.getPrimaryAddress()
)

order.addLine(thinkpad, quantity: 1, unitPrice: Money(649900, "PLN"))
order.addLine(mouse,    quantity: 2, unitPrice: Money(44900, "PLN"))
// order.grandTotal = 909633 (with 23% VAT)

order.confirm()
// emits OrderConfirmed → triggers inventory reservation

3. Inventory Reservation

// Listener handles OrderConfirmed event
for line in order.lines:
    item = findInventoryItem(line.product, warehouse)
    item.reserve(line.quantity, order.orderNumber, "Order reservation")
    // emits StockReserved

// Warehouse state:
// ThinkPad: onHand=20, reserved=1, available=19
// Mouse:    onHand=50, reserved=2, available=48

4. Payment

payment = new Payment(
    reference: "PAY-2026-000089",
    order: order,
    amount: order.grandTotal,
    method: PaymentMethod.Card
)

payment.markProcessing()
// ... gateway webhook: payment.success ...
payment.complete("gw_txn_abc123")
// emits PaymentCompleted → triggers shipment creation

order.markPaid(payment)
// emits OrderPaid

5. Shipment Creation & Warehouse Flow

shipment = Shipment.fromOrder(order, "SHP-2026-000018", warehouseAddress)
shipment.addItemFromOrderLine(order.lines[0], 1)  // ThinkPad
shipment.addItemFromOrderLine(order.lines[1], 2)  // Mouse

shipment.startPicking()     // warehouse staff collects items
shipment.markPacked()       // items boxed
shipment.assignCarrier(dhl, "1234567890")
shipment.markLabelPrinted()
shipment.handOverToCarrier()
// emits ShipmentShipped

6. Inventory Issue

// Listener handles ShipmentShipped event
for item in shipment.items:
    inv = findInventoryItem(item.product, warehouse)
    inv.shipReserved(item.quantity, order.orderNumber)
    // emits StockIssued

// Warehouse state:
// ThinkPad: onHand=19, reserved=0, available=19
// Mouse:    onHand=48, reserved=0, available=48

7. Delivery

// Carrier webhook updates
shipment.markInTransit("Warszawa Hub")
shipment.markOutForDelivery()
shipment.markDelivered({ signature: "J. Kowalski" })
// emits ShipmentDelivered

order.markDelivered()
order.complete()
// emits OrderCompleted

Event Flow Summary

Common Design Principles

IDs and Keys

• Primary key: UUID v7 (time-sortable)
• Business key: Human-readable (ORD-2024-000001)
• External key: From other systems (gateway transaction ID)

Money

// NEVER use floating point!
// Store in smallest currency unit (cents, grosze)

amount_cents: 19999  // = 199.99
currency: "PLN"

Time

• Timestamps: UTC, immutable (createdAt)
• Dates: Local date without time (birthDate)
• Validity period: validFrom/validTo for time-bounded entities

Inheritance Strategies

Domain Events Catalog

Every pattern emits domain events when important state changes occur. These events enable loose coupling between patterns (e.g., OrderConfirmed triggers inventory reservation).

Party Domain

Product Domain

Commerce Domain

Fulfillment Domain

Key Event Chains

Rendering Mermaid Diagrams

These tutorials use Mermaid for diagrams. To render them:

1. GitHub — Renders automatically in Markdown files
2. VS Code — Install "Markdown Preview Mermaid Support" extension
3. Online — Use mermaid.live
4. CLI — Use mmdc (mermaid-cli)

Working Implementations

Three complete implementations available in a separate repository: software-archetypes-examples

Each demo creates the same scenario: Jan Kowalski (Person) places an order at Acme (Organization), pays by card, stock is reserved and shipped via DHL, and delivered.

Glossary

License

MIT License. Pattern concepts based on "Enterprise Patterns and MDA" by Jim Arlow & Ila Neustadt (Addison-Wesley, 2003).