Unveiling the Modular Monolith — Laracon EU 2024

1. Mateus Guimarães Unveiling the Modular Monolith Attacking complexity in monolithic Laravel applications Developer and Educator @mateusjatenee Laracon EU 2024
2. A little bit about myself
3. Mateus Guimarães Software Developer & Educator • Powerlifting • Playing guitar • Photography • Content creation • Spending time with my wife @mateusjatenee MateusGuimarães
7. The Monolith The good parts • Everyone knows them • Simpler infrastructure • Simple method calls • ( Usually) one database • Database Transactions • One artifact • Easier to debug
8. The Monolith The bad parts • Tight coupling between components • No well-defined boundaries • Hard to fully understand • Difficult to maintain • Hard to onboard
12. Microservices The good parts • Easy to scale • Well-defined boundaries • Independent deployment • Resilience
13. Microservices The bad parts • Multiple repositories • Complex infrastructure • Network calls • Multiple databases • Consistency • Harder to debug • Distributed Transactions
15. The Modular Monolith A fair middle-ground • One artifact • Simple infrastructure • Database Transactions! • Easy to test • Method Calls • Logical boundaries • Low coupling between component • Independent Modules • Easier to maintain and scale
17. Have you ever worked on feature A… And broke feature B?
19. What do we want in a modular application? • Allow modules to be developed independently • Allow modules to own all of their data • Empower teams to work in parallel • Decrease surface area and blast radius of changes
20. Source: Modular Monoliths - Simon Brown GOTO 2018
21. Code Organization
22. Regular Laravel Application Modularized Laravel Application
23. Regular Laravel Application Modularized Laravel Application Grouping by type
24. Regular Laravel Application Modularized Laravel Application Grouping by type Grouping by context
29. Regular Laravel Structure
32. { "autoload": { "psr-4": { "App\\": "app/", "Database\\Factories\\": "database/factories/", "Database\\Seeders\\": "database/seeders/" } } }
33. { "autoload": { "psr-4": { "App\\": "app/", "Database\\Factories\\": "database/factories/", "Database\\Seeders\\": "database/seeders/" "Modules\\": "modules/" } } }
34. The most interesting part… (Imo)
35. Boundaries!
37. readonly class User { public function __ construct( public int $id, public string $email ) {} } class TokenIssuer { public function issue(int $uniqueIdentifier): Token { / / some magic return new Token($payload); } } $user = new App\User('Mateus', 'mateus@mateusguimaraes.com'); $token = (new App\Auth\TokenIssuer) -> issue($user -> id);
38. readonly class User { public function __ construct( public int $id, public string $email ) {} } class TokenIssuer { public function issue(int $uniqueIdentifier): Token { / / some magic return new Token($payload); } } $user = new App\User('Mateus', 'mateus@mateusguimaraes.com'); $token = (new App\Auth\TokenIssuer) -> issue($user -> id);
39. readonly class User { public function __ construct( public int $id, public string $email ) {} } class TokenIssuer { public function issue(int $uniqueIdentifier): Token { / / some magic return new Token($payload); } } $user = new App\User('Mateus', 'mateus@mateusguimaraes.com'); $token = (new App\Auth\TokenIssuer) -> issue($user -> id);
41. Cross Boundary Communication
45. Useful Guidelines Remember: there are no hard rules • Allow modules to be developed independently • A module should not know about other module’s internals • Incoming messages should be translated into something meaningful to the module’s domain • The producer can have contracts redirect their implementation without the consumer ever being aware
46. Data Transfer Objects • Bags of data • No behavior • Immutable • Plain Old PHP Objects • Meant to be passed around! • It’s… a contract!
47. readonly class PendingPayment { public function __ construct( public string $id, public Token $token, public Cents $totalInCents, public Gateway $gateway, public string $gatewayId, ) {} }
48. class CheckoutController { public function __ invoke(CheckoutRequest $request): JsonResponse { $items = $request - > items(); $total = $this - > calculateTotal($items); $order = DB::transaction(function () use ($request, $total) { $order = $request -> user() -> orders() -> make([ 'total' => $total ]); foreach ($items as $item) { $order - > addLine($item -> product, $item -> price, $item -> quantity); $item - > product - > decreaseStock($item - > quantity); } $order -> save(); $charge = $this -> paymentGateway - > charge($request -> token(), $total); $this -> createPaymentForOrder($order, $charge); $order -> prepareForShipment(); return $order; }); return new OrderResource($order); } }
49. class CheckoutController { public function __ invoke(CheckoutRequest $request): JsonResponse { $items = $request - > items(); $total = $this - > calculateTotal($items); $order = DB::transaction(function () use ($request, $total) { $order = $request -> user() -> orders() -> make([ 'total' => $total ]); foreach ($items as $item) { $order - > addLine($item -> product, $item -> price, $item -> quantity); $item - > product - > decreaseStock($item - > quantity); } $order -> save(); $charge = $this -> paymentGateway - > charge($request -> token(), $total); $this -> createPaymentForOrder($order, $charge); $order -> prepareForShipment(); return $order; }); return new OrderResource($order); } }
50. class CheckoutController { public function __ invoke(CheckoutRequest $request): JsonResponse { $items = $request - > items(); $total = $this - > calculateTotal($items); $order = DB::transaction(function () use ($request, $total) { $order = $request -> user() -> orders() -> make([ 'total' => $total ]); foreach ($items as $item) { $order - > addLine($item -> product, $item -> price, $item -> quantity); $item - > product - > decreaseStock($item - > quantity); } $order -> save(); $charge = $this -> paymentGateway - > charge($request -> token(), $total); $this -> createPaymentForOrder($order, $charge); $order -> prepareForShipment(); return $order; }); return new OrderResource($order); } }
51. class CheckoutController { public function __ invoke(CheckoutRequest $request): JsonResponse { $items = $request - > items(); $total = $this - > calculateTotal($items); $order = DB::transaction(function () use ($request, $total) { $order = $request -> user() -> orders() -> make([ 'total' => $total ]); foreach ($items as $item) { $order - > addLine($item -> product, $item -> price, $item -> quantity); $item - > product - > decreaseStock($item - > quantity); } $order -> save(); $charge = $this -> paymentGateway - > charge($request -> token(), $total); $this -> createPaymentForOrder($order, $charge); $order -> prepareForShipment(); return $order; }); return new OrderResource($order); } }
52. class CheckoutController { public function __ invoke(CheckoutRequest $request): JsonResponse { $items = $request - > items(); $total = $this - > calculateTotal($items); $order = DB::transaction(function () use ($request, $total) { $order = $request -> user() -> orders() -> make([ 'total' => $total ]); foreach ($items as $item) { $order - > addLine($item -> product, $item -> price, $item -> quantity); $item - > product - > decreaseStock($item - > quantity); } $order -> save(); $charge = $this -> paymentGateway - > charge($request -> token(), $total); $this -> createPaymentForOrder($order, $charge); $order -> prepareForShipment(); return $order; }); return new OrderResource($order); } }
53. class CheckoutController { public function __ invoke(CheckoutRequest $request): JsonResponse { $items = $request - > items(); $total = $this - > calculateTotal($items); $order = DB::transaction(function () use ($request, $total) { $order = $request -> user() -> orders() -> make([ 'total' => $total ]); foreach ($items as $item) { $order - > addLine($item -> product, $item -> price, $item -> quantity); $item - > product - > decreaseStock($item - > quantity); } $order -> save(); $charge = $this -> paymentGateway - > charge($request -> token(), $total); $this -> createPaymentForOrder($order, $charge); $order -> prepareForShipment(); return $order; }); return new OrderResource($order); } }
54. class CheckoutController { public function __ invoke(CheckoutRequest $request): JsonResponse { $items = $request - > items(); $total = $this - > calculateTotal($items); $order = DB::transaction(function () use ($request, $total) { $order = $request -> user() -> orders() -> make([ 'total' => $total ]); foreach ($items as $item) { $order - > addLine($item -> product, $item -> price, $item -> quantity); $item - > product - > decreaseStock($item - > quantity); } $order -> save(); $charge = $this -> paymentGateway - > charge($request -> token(), $total); $this -> createPaymentForOrder($order, $charge); $order -> prepareForShipment(); return $order; }); return new OrderResource($order); } }
55. use Modules\Checkout\PurchaseItems; use Modules\Payment\PaymentGateway; use Modules\Product\FetchCartItemsByProductIds; class CheckoutController { public function __ construct( protected FetchCartItemsByProductIds $fetchCartItems, protected PurchaseItems $purchaseItems, protected PaymentGateway $paymentGateway ) {} public function __ invoke(CheckoutRequest $request): JsonResponse { $items = $this - > fetchCartItemsByProductIds -> fromCheckoutRequest($request); $this -> paymentGateway -> setToken($request -> paymentToken()); try { $order = $this - > purchaseItems -> handle($items, $this -> paymentGateway, $request - > user() -> id); } catch (ProductsOutOfStockException | PaymentFailedException) { } return new OrderResource($order); } }
56. class PurchaseItems { public function __ construct( protected Database $database, ) {} public function handle(CartItemCollection $items, PaymentGateway $paymentGateway, int $userId): Order { $order = $this -> database -> transaction(function () use ($items, $paymentGateway, $userId) { $order = Order::start($userId); $order -> addLinesFromCartItems($items); $order -> save(); // So we have an ID. A UUID would suffice. foreach ($items as $item) { $item -> product -> decrement('stock', $item -> quantity); } $charge = $paymentGateway -> charge($order -> total); $payment = Payment::create([...]); $order -> complete(); Shipment::create([...]); return $order; }); return $order; } }
57. class PurchaseItems { public function __ construct( protected Database $database, ) {} public function handle(CartItemCollection $items, PaymentGateway $paymentGateway, int $userId): Order { $order = $this -> database -> transaction(function () use ($items, $paymentGateway, $userId) { $order = Order::start($userId); $order -> addLinesFromCartItems($items); $order -> save(); // So we have an ID. A UUID would suffice. foreach ($items as $item) { $item -> product -> decrement('stock', $item -> quantity); } $charge = $paymentGateway -> charge($order -> total); $payment = Payment::create([...]); $order -> complete(); Shipment::create([...]); return $order; }); return $order; } }
58. class PurchaseItems { public function __ construct( protected Database $database, ) {} public function handle(CartItemCollection $items, PaymentGateway $paymentGateway, int $userId): Order { $order = $this -> database -> transaction(function () use ($items, $paymentGateway, $userId) { $order = Order::start($userId); $order -> addLinesFromCartItems($items); $order -> save(); // So we have an ID. A UUID would suffice. foreach ($items as $item) { $item -> product -> decrement('stock', $item -> quantity); } $charge = $paymentGateway -> charge($order -> total); $payment = Payment::create([...]); $order -> complete(); Shipment::create([...]); return $order; }); return $order; } }
59. class PurchaseItems { public function __ construct( protected Database $database, ) {} public function handle(CartItemCollection $items, PaymentGateway $paymentGateway, int $userId): Order { $order = $this -> database -> transaction(function () use ($items, $paymentGateway, $userId) { $order = Order::start($userId); $order -> addLinesFromCartItems($items); $order -> save(); // So we have an ID. A UUID would suffice. foreach ($items as $item) { $item -> product -> decrement('stock', $item -> quantity); } $charge = $paymentGateway -> charge($order -> total); $payment = Payment::create([...]); $order -> complete(); Shipment::create([...]); return $order; }); return $order; } }
60. class PurchaseItems { public function __ construct( protected Database $database, ) {} public function handle(CartItemCollection $items, PaymentGateway $paymentGateway, int $userId): Order { $order = $this -> database -> transaction(function () use ($items, $paymentGateway, $userId) { $order = Order::start($userId); $order -> addLinesFromCartItems($items); $order -> save(); // So we have an ID. A UUID would suffice. foreach ($items as $item) { $item -> product -> decrement('stock', $item -> quantity); } $charge = $paymentGateway -> charge($order -> total); $payment = Payment::create([...]); $order -> complete(); Shipment::create([...]); return $order; }); return $order; } }
62. class PurchaseItems { public function __ construct( protected Database $database, protected InventoryService $inventoryService, protected PaymentService $paymentService, protected ShipmentService $shipmentService, ) {} public function handle(CartItemCollection $items, PaymentGateway $paymentGateway, int $userId): OrderDto { return $this -> database -> transaction(function () use ($items, $paymentGateway, $userId) { $order = Order::start($userId); $order -> addLinesFromCartItems($items); $order -> save(); $orderDto = OrderDto::fromModel($order); foreach ($items as $item) { $this -> inventoryService -> decreaseStock($item - > productId, $item -> quantity); } $payment = $this -> paymentService -> payOrder($orderDto, $paymentGateway); $order -> complete(); $this -> shipmentService -> startShipmentForOrder($orderDto); return $orderDto; }); } }
64. Event-Driven Communication
67. class PurchaseItems { public function __ construct( protected Bus $events, ) {} public function handle(CartItemCollection $items, PaymentGateway $paymentGateway, int $userId): OrderDto { $order = Order::start($userId); $order -> addLinesFromCartItems($items); $order -> initiate(); $this -> events - > dispatch( new OrderPlaced( order: $order -> toDto(), PaymentGateway: $paymentGateway, ) ); return OrderDto::fromModel($Order); } }
68. class PurchaseItems { public function __ construct( protected Bus $events, ) {} public function handle(CartItemCollection $items, PaymentGateway $paymentGateway, int $userId): OrderDto { $order = Order::start($userId); $order -> addLinesFromCartItems($items); $order -> initiate(); $this -> events - > dispatch( new OrderPlaced( order: $order -> toDto(), PaymentGateway: $paymentGateway, ) ); return OrderDto::fromModel($Order); } }
69. class PayOrder { public function __ construct( protected Bus $events, protected PaymentService $paymentService, ) {} public function handle(OrderPlaced $event): void { try { $payment = $this -> paymentService -> payOrder($event - > order, $event -> paymentGateway); } catch (PaymentFailedException $exception) { $this -> events - > dispatch( new PaymentFailed( orderId: $event -> order - > id, reason: $exception -> getMessage(), ) ); return; } $this - > events - > dispatch( new PaymentSucceeded( orderId: $event - > order -> id, payment: $payment - > toDto(), ) ); } }
70. class PayOrder { public function __ construct( protected Bus $events, protected PaymentService $paymentService, ) {} public function handle(OrderPlaced $event): void { try { $payment = $this -> paymentService -> payOrder($event - > order, $event -> paymentGateway); } catch (PaymentFailedException $exception) { $this -> events - > dispatch( new PaymentFailed( orderId: $event -> order - > id, reason: $exception -> getMessage(), ) ); return; } $this - > events - > dispatch( new PaymentSucceeded( orderId: $event - > order -> id, payment: $payment - > toDto(), ) ); } }
71. class PayOrder { public function __ construct( protected Bus $events, protected PaymentService $paymentService, ) {} public function handle(OrderPlaced $event): void { try { $payment = $this -> paymentService -> payOrder($event - > order, $event -> paymentGateway); } catch (PaymentFailedException $exception) { $this -> events - > dispatch( new PaymentFailed( orderId: $event -> order - > id, reason: $exception -> getMessage(), ) ); return; } $this - > events - > dispatch( new PaymentSucceeded( orderId: $event - > order -> id, payment: $payment - > toDto(), ) ); } }
72. class FulfillOrder { public function handle(PaymentSucceeded $event): void { $order = $this - > getOrderSomehow($event -> order -> id); $order - > fulfill(); Mail::to($order -> user -> email) -> send(new OrderCompleted($order)); } }
73. class FulfillOrder { public function handle(PaymentSucceeded $event): void { $order = $this - > getOrderSomehow($event -> order -> id); $order - > fulfill(); Mail::to($order -> user -> email) -> send(new OrderCompleted($order)); } }
74. class StartShipmentForOrder { public function __ construct( protected ShipmentService $shipmentService ) public function handle(PaymentSucceeded $event): void { $this -> shipmentService -> startShipmentForOrder($event -> order -> id); } }
75. class StartShipmentForOrder { public function __ construct( protected ShipmentService $shipmentService ) public function handle(PaymentSucceeded $event): void { $this -> shipmentService -> startShipmentForOrder($event -> order -> id); } }
76. class DecreaseProductStock { public function __ construct( protected InventoryService $inventoryService ) {} public function handle(PaymentSucceeded $event): void { foreach ($event -> order - > lines as $orderLine) { $this -> inventoryService - > decreaseStockForProduct($orderLine -> productId, $orderLine -> quantity); } } }
77. class DecreaseProductStock { public function __ construct( protected InventoryService $inventoryService ) {} public function handle(PaymentSucceeded $event): void { foreach ($event -> order - > lines as $orderLine) { $this -> inventoryService - > decreaseStockForProduct($orderLine -> productId, $orderLine -> quantity); } } }
78. Tradeoffs • An additional layer of indirection • Eventual consistency (with queued listeners) • Need for compensatory events • Harder to reason about everything a piece of code does
79. Data Ownership
81. Your System “Can this user access this course?”
82. Can a user access this course? • Does the user have an order • That has an order item • That is a product • That the course is attached to
92. Can a student access this course? • Does the student have the course unlocked?
94. Modularization encourages you to actively think about your systems and their relationships.
95. Okay, so…
106. OrderPlaced
107. OrderPlaced
108. OrderPlaced Publish
109. OrderPlaced Publish
110. OrderPlaced Publish
111. OrderPlaced Publish
112. OrderPlaced Publish Subscribe
113. Suggestions • Intra-module coupling is less “concerning" than inter-module coupling • Always try to expose a small, well-defined public API • Modules allow and encourage you to employ different strategies for different problems. Use that!
114. Applying modules to Laravel • Set up a namespace to hold your modules (e.g \Modules) • Leverage Service Providers to set up everything related to the module: views, config files, routes, etc • Think about whether a module should hold all of its data or not • Leverage the Event Bus to pass messages between different modules
115. Packages • nWidart/laravel-modules • Internachi/modular • Deptrac and Pest Architectural Tests
116. Some good stuff • Shopify: Deconstructing the Monolith • Strategic Monoliths and Microservices ( Vaughn Vernon) • RailsConf 2023 — Applying Microservices patterns to a modular monolith ( Guillermo Aguirre) • ( Booooooo! ) My Laracasts course: Modular Laravel
119. Thank you!