Monolith vs Microservices

<?php

declare(strict_types=1);

namespace App\Billing\Application;

use App\Orders\Contracts\OrderFinder; // Public API of Orders module.

/**
 * Modular monolith: Billing module calls Orders through a contract.
 * Billing does NOT touch orders table directly.
 * If Orders is extracted to a microservice later, this interface
 * becomes an HTTP / gRPC client without changing callers.
 */
final class ChargeOrderHandler
{
    public function __construct(
        private readonly OrderFinder $orders,
        private readonly PaymentGateway $gateway,
        private readonly InvoiceRepository $invoices,
    ) {}

    public function handle(ChargeOrderCommand $cmd): void
    {
        $order = $this->orders->findById($cmd->orderId)
            ?? throw new OrderNotFoundException($cmd->orderId);

        $payment = $this->gateway->charge($order->total, $cmd->cardToken);
        $this->invoices->save(new Invoice($order->id, $payment->id, $order->total));
    }
}

package billing

import (
	"context"
	"fmt"
	"net/http"
)

// Microservice version: Orders is a remote service.
// Same contract, but implementation uses HTTP with timeouts,
// retries, circuit breaker.
type OrdersHTTPClient struct {
	baseURL string
	client  *http.Client
	cb      CircuitBreaker
}

func (c *OrdersHTTPClient) Find(ctx context.Context, id string) (*Order, error) {
	return c.cb.Execute(ctx, func(ctx context.Context) (*Order, error) {
		req, _ := http.NewRequestWithContext(
			ctx, http.MethodGet,
			fmt.Sprintf("%s/orders/%s", c.baseURL, id), nil,
		)
		resp, err := c.client.Do(req)
		if err != nil {
			return nil, err // Circuit breaker counts failure.
		}
		defer resp.Body.Close()
		if resp.StatusCode == http.StatusNotFound {
			return nil, ErrOrderNotFound
		}
		if resp.StatusCode >= 500 {
			return nil, fmt.Errorf("orders svc 5xx: %d", resp.StatusCode)
		}
		return decodeOrder(resp.Body)
	})
}

using System;
using System.Net;
using System.Net.Http;
using System.Net.Http.Json;
using System.Threading;
using System.Threading.Tasks;

namespace App.Billing.Application;

// ---- Modular monolith: Billing calls Orders through a contract ----
// Billing never touches the orders table directly.
// If Orders is extracted into a service later, this interface gains an
// HTTP/gRPC implementation without changing a single caller.
public interface IOrderFinder
{
    Task<Order?> FindByIdAsync(string orderId, CancellationToken ct = default);
}

public sealed class ChargeOrderHandler(
    IOrderFinder orders,
    IPaymentGateway gateway,
    IInvoiceRepository invoices)
{
    public async Task HandleAsync(ChargeOrderCommand cmd, CancellationToken ct = default)
    {
        var order = await orders.FindByIdAsync(cmd.OrderId, ct)
                    ?? throw new OrderNotFoundException(cmd.OrderId);

        var payment = await gateway.ChargeAsync(order.Total, cmd.CardToken, ct);
        await invoices.SaveAsync(new Invoice(order.Id, payment.Id, order.Total), ct);
    }
}

// ---- Microservice version: same contract, Orders lives elsewhere ----
// The implementation now needs timeouts, retries and a circuit breaker.
// Register with AddHttpClient<IOrderFinder, OrdersHttpClient>() +
// a Polly resilience handler that owns retry/timeout/circuit-breaker policy.
public sealed class OrdersHttpClient(HttpClient client) : IOrderFinder
{
    public async Task<Order?> FindByIdAsync(string orderId, CancellationToken ct = default)
    {
        using var response = await client.GetAsync($"/orders/{orderId}", ct);

        if (response.StatusCode == HttpStatusCode.NotFound)
        {
            return null;
        }

        // Throws on 5xx so the resilience handler counts the failure.
        response.EnsureSuccessStatusCode();

        return await response.Content.ReadFromJsonAsync<Order>(ct);
    }
}

from __future__ import annotations

from typing import Protocol

import httpx

class OrderNotFoundError(Exception):
    pass

# ---- Modular monolith: Billing calls Orders through a contract ----
# Billing never touches the orders table directly.
# If Orders is extracted into a service later, this Protocol gains an
# HTTP/gRPC implementation without changing a single caller.
class OrderFinder(Protocol):
    async def find_by_id(self, order_id: str) -> Order | None: ...

class ChargeOrderHandler:
    def __init__(
        self,
        orders: OrderFinder,
        gateway: PaymentGateway,
        invoices: InvoiceRepository,
    ) -> None:
        self._orders = orders
        self._gateway = gateway
        self._invoices = invoices

    async def handle(self, cmd: ChargeOrderCommand) -> None:
        order = await self._orders.find_by_id(cmd.order_id)
        if order is None:
            raise OrderNotFoundError(cmd.order_id)

        payment = await self._gateway.charge(order.total, cmd.card_token)
        await self._invoices.save(Invoice(order.id, payment.id, order.total))

# ---- Microservice version: same contract, Orders lives elsewhere ----
# The implementation now needs timeouts, retries and a circuit breaker.
class OrdersHttpClient:
    """Satisfies OrderFinder structurally — no inheritance needed."""

    def __init__(self, client: httpx.AsyncClient, breaker: CircuitBreaker) -> None:
        self._client = client
        self._breaker = breaker

    async def find_by_id(self, order_id: str) -> Order | None:
        async with self._breaker:  # counts failures, opens on threshold
            response = await self._client.get(f"/orders/{order_id}")

            if response.status_code == httpx.codes.NOT_FOUND:
                return None

            # Raises on 5xx so the breaker registers the failure
            response.raise_for_status()

            return Order(**response.json())