Extracting the Delivery Service - Step 1, Split the code

The previous post described the existing monolithic architecture. The first step is to split the code and convert delivery management into a separate, loosely coupled module within the monolith.

The following diagram shows the new structure:

Order Management invokes Delivery Management via coarse-grained API to schedule, reschedule, and cancel deliveries. At this stage, however, the Delivery Management shares the same database tables used by Order Management. For example, both the Order and Delivery entity are mapped to the ORDERS table.

This refactoring is primarily in this commit.
Let’s look at the changes.

New Gradle modules

Two new modules were added to settings.gradle:

include "ftgo-delivery-service-api"
include "ftgo-delivery-service"

The purpose of each module is as follows:

  • ftgo-delivery-service-api - contains the DeliveryService interface, which is the entry point into Delivery Management from the monolith

  • ftgo-delivery-service - contains the Delivery Management functionality

DeliveryService interface

The DeliveryService interface defines the coarse-grained, remotable API used by Order Management to schedule and cancel deliveries.

public interface DeliveryService  {
  void scheduleDelivery(LocalDateTime readyBy, Long orderId);
  void cancelDelivery(long orderId);

OrderService now calls DeliveryService

The delivery management functionality has been moved out of OrderService into DeliveryService:

public class OrderService {

  public Order cancel(Long orderId) {

  public void accept(long orderId, LocalDateTime readyBy) {
   deliveryService.scheduleDelivery(readyBy, order.getId());

Methods, such as accept() and cancel() invoke delivery management by calling the DeliveryService, which is injected into the OrderService.

DeliveryController class

The DeliveryController class implements the REST endpoints invoked by the courier’s mobile application. It calls the DeliveryCourierService, which is described below.

DeliveryServiceImpl class

The DeliveryServiceImpl class implements the delivery management logic that was previously in the DeliveryService.

public class DeliveryServiceImpl implements DeliveryService, DeliveryCourierService {

  public void scheduleDelivery(LocalDateTime readyBy, Long orderId) {...}
  public void cancelDelivery(long orderId) {...}

It also implements the DeliveryCourierService interface, which defines methods for updating the state of Couriers and Deliverys:

public interface DeliveryCourierService {
  void notePickedUp(long orderId);

  void noteDelivered(long orderId);

  void updateAvailability(long courierId, boolean available);

This interface is separate (i.e. Interface segregation principle) from DeliveryService since its called by DeliveryController rather than the OrderService.

Delivery Management domain classes

The ftgo-delivery-service module defines a self-contained set of domain classes including the following JPA @Entity classes:

  • Delivery - represents a delivery
  • DeliveryCourier - represents a courier
  • DeliveryRestaurant - represents a restaurant

These classes mirror those in the monolith and are mapped to the same tables. Each class contains just those fields that are needed by Delivery Management. For example, Delivery is mapped to the ORDERS table:

@Table(name = "orders")
public class Delivery {

  private Long id;
  private DeliveryState deliveryState;
  private DeliveryRestaurant restaurant;
  private DeliveryCourier assignedCourier;
  private Address deliveryAddress;
  private LocalDateTime deliveredTime;
  private LocalDateTime pickedUpTime;

It contains only those fields from the original Order class that are needed by Delivery Management.

DeliveryState is an enum, which is currently identical to the OrderState. A later step removes those values corresponding to states that are not relevant to Delivery Management.

Similarly, DeliveryCourier contains a subset of the fields from Courier.

@Table(name = "courier")
public class DeliveryCourier {

  private long id;
  private Plan plan;
  private Boolean available;

Delivery Management does not create or delete these entities. Instead, it only updates those fields of Delivery and DeliveryCourier that it owns.

In addition to those entity classes, the ftgo-delivery-service module also contains the @Embeddable Plan Action classes. Delivery Management creates, updates and deletes instances of these classes since it owns them.

Preserving read-only fields in ftgo-order-service

In order to minimize the scope of this refactoring step, the delivery-related fields (of classes) in ftgo-order-service are preserved as readonly fields. For example, the Courier class still has an available field even though the methods that update it have been removed from the class. Similarly, ftgo-order-service still contains read-only classes, such as Plan and Action. These fields are updated by being mapped to the same database columns as the corresponding read-write fields in ftgo-delivery-service.

Preserving these read-only fields eliminates the need to change the code that queries the delivery information. For example, OrderController obtains an Order’s assigned Courier and their pickup/dropoff schedule from the Order:

public class OrderController {
  private GetOrderResponse makeGetOrderResponse(Order order) {
    return new GetOrderResponse(order.getId(),
            order.getAssignedCourier() == null ? null : order.getAssignedCourier().getId(),
            order.getAssignedCourier() == null ? null : order.getAssignedCourier().actionsForDelivery(order)

If these fields had been deleted, then the OrderController would need to be changed to fetch the delivery information from the ftgo-delivery-service.

What’s next

Copyright © 2023 Chris Richardson • All rights reserved • Supported by Kong.

About Microservices.io

Microservices.io is brought to you by Chris Richardson. Experienced software architect, author of POJOs in Action, the creator of the original CloudFoundry.com, and the author of Microservices patterns.

Chris helps organizations improve agility and competitiveness through better software architecture. Learn more about his consulting engagements, and training workshops.


Premium content and office hours is now available for paid subscribers at premium.microservices.io.


Chris teaches comprehensive workshops for architects and developers that will enable your organization use microservices effectively.

Avoid the pitfalls of adopting microservices and learn essential topics, such as service decomposition and design and how to refactor a monolith to microservices.

Learn more

LEARN about microservices

Chris offers numerous other resources for learning the microservice architecture.

Get the book: Microservices Patterns

Read Chris Richardson's book:

Example microservices applications

Want to see an example? Check out Chris Richardson's example applications. See code

Remote consulting session

Got a specific microservice architecture-related question? For example:

  • Wondering whether your organization should adopt microservices?
  • Want to know how to migrate your monolith to microservices?
  • Facing a tricky microservice architecture design problem?

Consider signing up for a two hour, highly focussed, consulting session.

Virtual bootcamp: Distributed data patterns in a microservice architecture

My virtual bootcamp, distributed data patterns in a microservice architecture, is now open for enrollment!

It covers the key distributed data management patterns including Saga, API Composition, and CQRS.

It consists of video lectures, code labs, and a weekly ask-me-anything video conference repeated in multiple timezones.

The regular price is $395/person but use coupon KQAWEXBH to sign up for $120 (valid until November 21st, 2023). There are deeper discounts for buying multiple seats.

Learn more

Learn how to create a service template and microservice chassis

Take a look at my Manning LiveProject that teaches you how to develop a service template and microservice chassis.

Signup for the newsletter

BUILD microservices

Ready to start using the microservice architecture?

Consulting services

Engage Chris to create a microservices adoption roadmap and help you define your microservice architecture,

The Eventuate platform

Use the Eventuate.io platform to tackle distributed data management challenges in your microservices architecture.

Eventuate is Chris's latest startup. It makes it easy to use the Saga pattern to manage transactions and the CQRS pattern to implement queries.

ASSESS your architecture

Assess your application's microservice architecture and identify what needs to be improved.

Consulting services

Engage Chris to conduct an architectural assessment.

Join the microservices google group


Note: tagging is work-in-process

Microservices adoption   ·  ancient lore   ·  anti-patterns   ·  application api   ·  application architecture   ·  architecting   ·  architecture   ·  architecture documentation   ·  assemblage   ·  beer   ·  books   ·  containers   ·  dark energy and dark matter   ·  deployment   ·  design-time coupling   ·  developer experience   ·  development   ·  devops   ·  docker   ·  eventuate platform   ·  generative AI   ·  glossary   ·  health   ·  hexagonal architecture   ·  implementing commands   ·  implementing queries   ·  inter-service communication   ·  kubernetes   ·  loose coupling   ·  microservice architecture   ·  microservice chassis   ·  microservices adoption   ·  microservicesio updates   ·  modular monolith   ·  multi-architecture docker images   ·  observability   ·  pattern   ·  refactoring to microservices   ·  resilience   ·  sagas   ·  security   ·  service api   ·  service architecture   ·  service collaboration   ·  service design   ·  service discovery   ·  service granularity   ·  service template   ·  software delivery metrics   ·  success triangle   ·  tacos   ·  team topologies   ·  transaction management   ·  transactional messaging

All content


24 Jul 2017 » Revised data patterns