Chapter 5: Designing Business Logic in a Microservice Architecture

Every service has business logic at its core. How you organize that logic has a big impact on how easy the service is to understand, test, and change. There are two main patterns for organizing business logic: Transaction Script and Domain Model. They are alternatives to each other.

The Transaction Script pattern organizes business logic as a set of procedural methods. Each method handles one request from start to finish. The behavior (what to do) and the state (the data) live in separate places: methods contain the logic, and simple data objects hold the state.

The Domain Model pattern organizes business logic as an object-oriented model. Classes have both state and behavior together. Service methods are thin — they delegate most of the work to domain objects.

Domain-Driven Design (DDD) is an approach to building software that closely models the business domain. DDD provides a set of building blocks for creating domain models:

• Entity — an object with a persistent identity. Two entities are different even if all their other attributes are the same.
• Value Object — an object defined only by its attribute values. Two value objects are interchangeable if their values are equal.
• Factory — an object or method responsible for creating complex domain objects.
• Repository — an object that provides access to persistent entities (abstracts the database).
• Service — an object that contains business logic that does not naturally belong to any entity or value object.

The most important DDD building block for microservices is the Aggregate. It solves several problems that arise when a domain model is used across service boundaries.

A traditional domain model is a web of interconnected objects. In a monolith, this works fine. In a microservice architecture, fuzzy boundaries between objects cause serious problems. The Aggregate pattern solves this by drawing explicit boundaries around groups of objects.

Without clear boundaries, a domain model is just a web of interconnected classes. This causes three problems in a microservice architecture:

1. Cross-service reference problem — if objects freely reference each other, it is unclear which object belongs to which service. An object in Service A might hold a direct reference to an object in Service B. This creates tight coupling.
2. Transaction scope problem — in a monolith, you can update many objects in a single database transaction. In microservices, each service has its own database. You cannot use a single transaction to update objects across services.
3. Invariant enforcement problem — business rules that span multiple objects (like "the order total must equal the sum of line item prices") are hard to enforce when it is unclear which objects must be updated together.

An Aggregate is a cluster of domain objects that are treated as a single unit. Every aggregate has a root entity (the aggregate root) that is the only object outsiders can reference. All other objects inside the aggregate are accessed only through the root.

Three rules govern how aggregates work. These rules enforce loose coupling and consistency in a microservice architecture.

Rule #1: Reference only the aggregate root

From outside the aggregate, you can only reference the aggregate root. You cannot directly access or hold references to internal objects. This ensures the root can enforce all business invariants before any change is made.

Rule #2: Inter-aggregate references by primary key

Aggregates reference each other using primary keys (IDs), not direct object references. This keeps aggregates loosely coupled. It also makes the model friendly for NoSQL databases and for sharding data across multiple machines. There is no risk of accidentally creating a cross-service object reference.

Rule #3: One transaction creates or updates one aggregate

A single database transaction must only create or update one aggregate. If a business operation needs to update multiple aggregates, you must use a Saga (Chapter 4) to coordinate the updates across separate transactions.

How big should an aggregate be? There is a tradeoff between fine-grained and coarse-grained aggregates.

Business logic in a microservice is organized around aggregates. A typical service contains:

• Aggregates — the core domain objects with state and behavior.
• Domain Services — logic that does not fit inside any single aggregate.
• Repositories — persistence interfaces for loading and saving aggregates.
• Sagas — coordinate multi-aggregate or multi-service operations.

The service follows a hexagonal architecture. The business logic (aggregates, services, repositories, sagas) sits in the core. Around the core, there are two types of adapters:

• Inbound adapters — receive requests from the outside world. Examples: REST API controllers, command handlers, domain event consumers.
• Outbound adapters — interact with external systems on behalf of the business logic. Examples: database adapters, event publishers, command publishers.

Aggregates publish domain events when their state changes. Other services subscribe to these events to keep their own data up to date. This section covers the full lifecycle of domain events: why they exist, what they look like, and how to generate, publish, and consume them.

In a microservice architecture, services need to react to changes in other services. For example, when an order is created, the Kitchen Service needs to know about it so it can prepare the food. Domain events make this possible.

Common reasons to publish events:

• Maintain data replicas across services (e.g., Order Service stores a copy of restaurant data).
• Notify other services so they can take action (e.g., start a saga step).
• Update CQRS views that combine data from multiple services.
• Send notifications to users via webhooks or other channels.

A domain event is a message that describes something that happened to an aggregate. It is named using a past-participle verb, like OrderCreated, TicketAccepted, or DeliveryPickedUp.

Each event typically contains:

• The ID of the aggregate that changed.
• A timestamp.
• Data that describes what happened (event payload).

Event enrichment means including extra data in the event that consumers will need. Instead of just publishing "OrderCreated" with only the order ID, you also include the order details (items, total, customer ID, etc.).

How do you find the domain events your system needs? Two techniques help:

Requirements analysis

Look for requirements that follow the pattern: "When X happens, do Y." The "X" part is a domain event. For example: "When an order is created, notify the kitchen" tells you that OrderCreated is a domain event.

Event Storming

Event Storming is a workshop technique. Domain experts and developers work together to map out all the events in a business process. They write events on sticky notes, put them on a timeline, and then identify the commands and aggregates that produce them. It is a fast way to discover the events in a system.

There are two common ways for an aggregate to generate domain events:

Method return approach

The aggregate method that changes state returns a list of events. The service class then passes these events to the publisher. This is the preferred approach because it keeps the aggregate simple and free of infrastructure dependencies.

Accumulation approach

The aggregate extends an AbstractAggregateRoot base class that maintains an internal list of events. When the aggregate's state changes, it adds events to this list. The service class collects the accumulated events after calling the method. This approach is slightly more convenient but ties the aggregate to a base class.

Publishing events reliably

Events must be published reliably. If the service updates the database but fails to publish the event (or vice versa), the system becomes inconsistent. The solution is the Transactional Outbox pattern (Chapter 3).

The service inserts the event into an OUTBOX table as part of the same ACID database transaction that updates the aggregate. A separate process reads the OUTBOX table and publishes the events to the message broker. This guarantees that the database update and the event publication are atomic.

For type safety, a service can use a typed publisher like AbstractAggregateDomainEventPublisher<A, E> that is parameterized with the aggregate type (A) and the event type (E). This prevents accidentally publishing the wrong type of event for an aggregate.

A service consumes domain events using a DomainEventDispatcher. The dispatcher subscribes to event channels and routes each incoming event to the correct handler method based on the event type.

Consuming events is an inbound adapter in the hexagonal architecture. The handler method receives the event, looks up the relevant aggregate, and calls a method on it to react to the event.

The Kitchen Service is a relatively simple service. It participates in sagas started by other services (like the Order Service) but does not orchestrate sagas itself. It handles commands, updates its aggregates, and publishes domain events.

The central aggregate in Kitchen Service is the Ticket. A Ticket represents a kitchen order — the food items that need to be prepared. The Ticket aggregate:

• Is created when the Kitchen Service receives a command from a saga (e.g., "create ticket for this order").
• Tracks the preparation status of the order.
• Can be accepted or rejected by the kitchen.
• Publishes domain events when its state changes (e.g., TicketAccepted, TicketPreparationStarted).

The Kitchen Service follows the hexagonal architecture:

• Inbound adapters: command handlers (receive saga commands), domain event consumers (react to events from other services).
• Outbound adapters: database adapter (persist Ticket), event publisher (publish Ticket events).

The Order Service is more complex than the Kitchen Service. It orchestrates sagas that span multiple services. It also maintains replicas of data from other services (like restaurant menu data) by subscribing to their domain events.

The Order aggregate is the central aggregate in Order Service. It represents a customer's order and contains order line items, the order total, and the current order state.

PENDING semantic locks

Because the Order Service uses sagas, the Order aggregate uses *_PENDING states as semantic locks. For example, when a saga is creating an order, the order is in APPROVAL_PENDING state. While in a PENDING state, certain operations are blocked to prevent conflicting updates. Once the saga completes, the state moves to a final value like APPROVED or REJECTED.

Restaurant replica

The Order Service needs restaurant data (like menu items and prices) to validate orders. Instead of calling the Restaurant Service synchronously, the Order Service maintains a local Restaurant aggregate that is a replica of data from the Restaurant Service. It keeps this replica up to date by subscribing to domain events published by the Restaurant Service (e.g., RestaurantMenuUpdated).

The OrderService class is the main entry point for Order Service business logic. Most of its methods create sagas rather than directly updating the Order aggregate. This is because order operations (create, revise, cancel) involve multiple services that must be coordinated.

For example, when a customer creates an order:

1. The OrderService.createOrder() method creates an Order aggregate in APPROVAL_PENDING state.
2. It then creates a CreateOrderSaga that orchestrates the steps across Kitchen Service, Accounting Service, and others.
3. The saga sends commands to these services and waits for replies.
4. When all steps succeed, the saga updates the Order to APPROVED. If any step fails, compensating transactions roll back the changes and the Order becomes REJECTED.

The Order Service follows the hexagonal architecture:

• Inbound adapters: REST API controllers (receive client requests), domain event consumers (update Restaurant replica from Restaurant Service events), saga reply handlers.
• Outbound adapters: database adapter (persist Order and Restaurant aggregates), event publisher (publish Order events), command publisher (send saga commands to other services).

Designing business logic for microservices differs from designing it for a monolith in several important ways:

• Aggregates with explicit boundaries — the domain model is organized as aggregates, not a web of interconnected classes.
• References by primary key — aggregates reference each other by ID, not by direct object reference. This prevents cross-service object references.
• One transaction per aggregate — a single transaction only updates one aggregate. Sagas handle cross-aggregate consistency.
• Domain events on state changes — aggregates publish domain events when their state changes, using transactional messaging (Outbox pattern).
• Data replicas via event subscription — services maintain local copies of data from other services by subscribing to domain events. This eliminates synchronous dependencies.