Services

BoxOffice started, like most companies, as one Spring Boot application: events, seats, orders, payments and e-mails in one codebase, one PostgreSQL database, one deployable .jar. For the first year that was exactly right. Then three things happened at once. On sale days only the seat map and checkout were overloaded, but the only way to scale them was to run more copies of everything. A bug in the venue-image upload took checkout down with it. And four teams now shared one codebase: every release needed all of them to agree on the same day.

Nothing was wrong with the code. The shape of the system no longer fitted the load or the organization. This page is about choosing that shape: how big a deployable unit should be, where to draw the boundaries between services, and how to organize the code inside one service so that it survives years of change.

The spectrum: monolith to microservices

"Monolith or microservices" is not a binary choice; it is a spectrum of how many independently deployable units the system has, and how strongly their boundaries are enforced.

flowchart LR
    subgraph mono ["Monolith"]
        direction TB
        m1["one app<br/>catalog · inventory · order · payment"] --> mdb[("one database")]
    end
    subgraph modular ["Modular monolith"]
        direction TB
        mm["one app"] --- c1["module catalog"]
        mm --- c2["module inventory"]
        mm --- c3["module order"]
        c1 --> s1[("schema catalog")]
        c2 --> s2[("schema inventory")]
        c3 --> s3[("schema order")]
    end
    subgraph micro ["Microservices"]
        direction TB
        gw["gateway"] --> x1["catalog"]
        gw --> x2["inventory"]
        gw --> x3["order"]
        x1 --> d1[("catalog DB")]
        x2 --> d2[("inventory DB")]
        x3 --> d3[("order DB")]
    end
    mono --> modular --> micro

The modular monolith deserves more attention than it gets. It gives you the main benefit of microservices — clear boundaries, each module owning its data — without paying for the network. If a module later needs independent scaling or a different team, it can be extracted along a boundary that already exists. Shopify, for example, publicly described its choice to modularize a large Rails monolith rather than split it into services⁷.

When splitting pays off

Split a part of the system into its own service when at least one of these forces is strong — and write down which one, because it tells you where to cut:

And the costs you accept when you split:

• Every call can fail or be slow (distributed systems): timeouts, retries, circuit breakers become mandatory.
• No cross-service transactions: "hold seat, create order, charge card" becomes a saga with compensations (messaging).
• Availability multiplies down along synchronous chains: three services at 99.9% in series give ≈ 99.7%.
• Operations multiply: N pipelines, N dashboards, distributed tracing to debug one request (observability).

How small is "micro"? Not a number of lines. A service is the right size when one team can own it end to end, it can be deployed without coordinating with others, and it maps to one business capability. Services that are too small ("nanoservices", e.g. one per table) spend more time talking to each other than working.

Finding boundaries with Domain-Driven Design

You have decided to split. Where do you cut? By database table (events, seats, orders)? By layer (a "UI service", a "logic service")? Each produces services that must change together. Domain-Driven Design (DDD)¹ gives a better answer: cut where the business itself has a seam.

DDD works at two levels:

Strategic design decides the services; tactical design shapes the code inside each one.

Subdomains: where to invest

Not every part of the business deserves the same effort:

That last row is why BoxOffice has an external integrations problem at all: it deliberately does not build its own card processing or mail servers.

Ubiquitous language and bounded contexts

The ubiquitous language is the vocabulary shared by developers and domain experts and used verbatim in code: if the box-office staff say hold, on-sale, seat map and allocation, the code says Hold, OnSale, SeatMap and Allocation — not TempReservation or Lock.

But the same word often means different things in different parts of the business. A bounded context is the boundary inside which one model, and one meaning of each word, applies:

flowchart LR
    subgraph cat ["Catalog context"]
        e1["Event<br/>artist · date · venue · description · images"]
    end
    subgraph inv ["Inventory context"]
        e2["Event<br/>seat map · sections · holds · capacity"]
    end
    subgraph ord ["Order context"]
        e3["Event (as sold)<br/>event id · seat · price paid · fees"]
    end
    cat -. "same word,<br/>different model" .- inv
    inv -. "same word,<br/>different model" .- ord

Trying to build one Event class that serves all three — with images, a seat map and historical prices — produces a bloated object that serves none well and couples three teams. Instead each context owns its own model, and they exchange ids and events. Note the Order context in particular: an order stores the price paid, not a reference to the current price, because if the catalog changes a price tomorrow, yesterday's order must not change.

A bounded context typically maps to one service (or a small group of closely related ones). That is the main heuristic for service boundaries.

Context maps: how contexts relate

Contexts exchange data, and the relationship between each pair is a design decision. A context map draws them³:

flowchart LR
    catalog["Catalog"] -->|"Open Host: REST + OpenAPI"| order["Order"]
    catalog -->|"Published Language:<br/>EventPublished events"| search["Search"]
    inventory["Inventory"] -->|"Customer / Supplier:<br/>hold & confirm API"| order
    order -->|"OrderConfirmed event"| notification["Notification"]
    psp["Payment provider"] -->|"Anti-Corruption Layer"| payment["Payment"]
    payment -->|"PaymentSucceeded event"| order
    mail["E-mail provider"] -->|"Anti-Corruption Layer"| notification

The two anti-corruption layers matter most in practice: the payment provider's model (its "payment intents", its status names, its error codes) must not spread through BoxOffice. The payment service translates it into BoxOffice's own Payment model at the border — the integrations page shows that adapter.

Aggregates: the unit of consistency

Inside a context, an aggregate is a cluster of objects changed together as one unit, with one root as the only entry point. The root enforces the invariants — rules that must always hold. Two rules make aggregates fit microservices:

• Reference other aggregates by id only. A Hold keeps the seatId and the fanId, never a Fan object. That is what lets the two live in different services.
• One transaction changes one aggregate. If a use case must change two aggregates, the second change happens afterwards, triggered by a domain event (eventual consistency).

public class Hold {                                   // aggregate root
    private static final Duration TTL = Duration.ofMinutes(10);
    private static final int MAX_SEATS = 6;           // per fan, per event

    private final HoldId id;
    private final EventId eventId;                    // other aggregates: by id only
    private final FanId fanId;
    private final Set<SeatId> seats;
    private final Instant expiresAt;
    private HoldStatus status = HoldStatus.ACTIVE;

    public static Hold place(EventId event, FanId fan, Set<SeatId> seats, Clock clock) {
        if (seats.isEmpty() || seats.size() > MAX_SEATS)
            throw new HoldRejected("between 1 and " + MAX_SEATS + " seats");
        return new Hold(HoldId.random(), event, fan, Set.copyOf(seats),
                        clock.instant().plus(TTL));
    }

    public void confirm(Clock clock) {                // called when the payment succeeds
        if (status != HoldStatus.ACTIVE || clock.instant().isAfter(expiresAt))
            throw new HoldExpired(id);
        status = HoldStatus.CONFIRMED;
    }
}

The invariant "a seat belongs to at most one active hold" spans all holds of an event, so it cannot be checked inside one Hold object; it is enforced by the database (a unique constraint on (event_id, seat_id) for active holds) — exactly the kind of decision class 6 is about.

Conway's law

"Any organization that designs a system will produce a design whose structure is a copy of the organization's communication structure." — Melvin Conway, 1968⁴

Boundaries in the code drift to match boundaries between teams, because communication within a team is cheap and communication between teams is expensive. The plot below shows BoxOffice's evolution: as teams form around business capabilities, the codebase splits along the same lines.

Two practical consequences:

• If boundaries and teams disagree, the teams win. A service owned by three teams becomes a coordination bottleneck; three services owned by one team tend to merge back into a distributed monolith.
• The inverse Conway maneuver: shape the teams first — one stream-aligned team per business capability, plus a platform team that provides deployment, observability and databases as self-service — so that the architecture follows⁵.

Owning the data

Database per service means no service reads or writes another service's tables. It does not require one database server per service: one PostgreSQL cluster can host several schemas, as long as each schema has exactly one owner.

flowchart LR
    order["order"] -->|"POST /holds/{id}/confirm"| inventory["inventory"]
    inventory --> inv[("inventory schema")]
    order --> ord[("order schema")]
    order -.-x|"no direct SQL"| inv

When order needs to confirm a hold, it calls the inventory API, never the holds table. That keeps the inventory team free to change its schema, add a cache or move to another database. Two consequences follow:

• Queries across services become API calls — or a local, read-only copy of the other service's data kept up to date by events (CQRS, messaging). search keeps its own index of events this way.
• Business transactions across services become a sequence of local transactions coordinated by events or an orchestrator, with compensations when a step fails: the saga pattern. "Payment failed → release the hold" is a compensation.

datasource:
  url: jdbc:postgresql://${DB_HOST:db}:${DB_PORT:5432}/${DB_NAME:boxoffice}?currentSchema=orders
  username: ${DB_USER:boxoffice}
  password: ${DB_PASSWORD:boxoffice}
flyway:
  schemas: orders

Talking to each other

sequenceDiagram
    participant F as Fan
    participant O as order
    participant I as inventory
    F->>O: POST /orders
    O->>I: confirm hold H-7
    I-->>O: confirmed
    O-->>F: 201 Created

sequenceDiagram
    participant O as order
    participant K as Kafka
    participant N as notification
    participant A as analytics
    O->>K: OrderConfirmed
    Note over O: answers the fan immediately
    K->>N: OrderConfirmed → e-mail tickets
    K->>A: OrderConfirmed → sales dashboard

Class 8 (messaging) goes deep on events; the API styles page covers the request/response options.

Try it. The microservices scenario splits the app into catalog, inventory, order and notify, each with its own database, behind a gateway, and buying is a synchronous chain: order calls inventory, catalog and notify before it answers. Press Run: at 2,000 req/s the catalog cannot get the pods it needs and about 25% of the requests fail (pods and nodes are class 11's story). Open it in the full playground (↗) and press Show a possible solution: more room in the cluster, and a queue between order and notify; p99 falls to about 60 ms. Now delete the queue and connect order straight to notify again: with the same capacity, p99 climbs back to about 360 ms, because every buyer now waits for the confirmation (120 ms on average, with a long tail) before getting an answer.

Inside one service: internal architecture

Splitting the system decides the boundaries between services. Each service still needs a structure inside, and the same principle applies at a smaller scale: protect the business rules from things that change more often — frameworks, databases, protocols, providers.

SOLID in one table

The five SOLID principles⁸ are class-level rules that make that protection possible:

Layered, clean and hexagonal

Most Spring Boot services start layered: controller → service → repository → database. It separates HTTP from business logic, but the business layer still depends on the persistence layer. Clean Architecture (Robert C. Martin) and Hexagonal Architecture, a.k.a. ports and adapters (Alistair Cockburn), invert that one arrow: the core defines interfaces (ports) in business terms, and infrastructure (adapters) implements them⁹¹⁰.

flowchart LR
    rest["REST controller<br/>(driving adapter)"] --> uc["PayForOrder<br/>use case"]
    kafka["Kafka listener<br/>(driving adapter)"] --> uc
    uc --> port1["«port»<br/>PaymentGateway"]
    uc --> port2["«port»<br/>PaymentRepository"]
    stripe["ProviderAdapter<br/>(HTTP client)"] -.->|implements| port1
    fake["FakeGateway<br/>(tests)"] -.->|implements| port1
    jpa["JpaPaymentRepository"] -.->|implements| port2

For the payment service this is not academic. The port is the anti-corruption layer from the context map:

// core — knows nothing about HTTP, JSON or any provider SDK
public interface PaymentGateway {
    ChargeResult charge(PaymentId id, Money amount, PaymentMethodToken method,
                        IdempotencyKey key);
}

// adapter — the only class that knows the provider's API and vocabulary
@Component
class ProviderPaymentGateway implements PaymentGateway {
    private final ProviderClient client;   // generated or hand-written HTTP client

    @Override
    public ChargeResult charge(PaymentId id, Money amount, PaymentMethodToken method,
                               IdempotencyKey key) {
        var response = client.createPayment(amount.cents(), amount.currency().code(),
                                            method.value(), key.value());
        return switch (response.status()) {            // translate THEIR states to OURS
            case "succeeded"       -> ChargeResult.succeeded(response.id());
            case "requires_action" -> ChargeResult.needsCustomerAction(response.nextActionUrl());
            case "processing"      -> ChargeResult.pending(response.id());
            default                -> ChargeResult.failed(response.failureCode());
        };
    }
}

The payoff: use-case tests run in milliseconds with a FakeGateway; adding a second provider for failover is a new adapter, not a rewrite; and the provider's status names stop at one class.

Shared capabilities as services

Some capabilities are needed by many parts of the system and appear as their own components in the palette. They are usually the first services extracted — and often the first ones bought:

Two patterns repeat: these services are mostly fed by events rather than called synchronously, and their data is often derived — search and analytics can be rebuilt from the source of truth, which makes them cheaper to operate.

BoxOffice service map

routes:
  - id: auth
    uri: ${AUTH_URL:http://auth:8081}
    predicates:
      - Path=/auth/**
  - id: catalog
    uri: lb://catalog              # "lb": pick one instance of "catalog" per request
    predicates:
      - Path=/catalog/**
  - id: inventory
    uri: ${INVENTORY_URL:http://inventory:8083}
    predicates:
      - Path=/inventory/**

How it connects

flowchart LR
    MONO["monolith"] --> MOD["modular monolith"]
    MOD --> MS["microservices<br/>when a force is real"]
    DDD["DDD: subdomains,<br/>bounded contexts"] --> MS
    CONWAY["Conway's law<br/>teams shape services"] --> MS
    AGG["aggregates<br/>reference by id"] --> OWN
    MS --> OWN["each service owns its data<br/>→ Databases"]
    MS --> TALK["APIs and events<br/>→ API Styles, Messaging"]
    OWN --> SAGA["no cross-service transactions<br/>→ sagas, outbox"]
    HEX["ports and adapters"] --> INT["provider adapters<br/>→ Integrations"]
    MS --> SHARED["shared capabilities:<br/>auth, search, notifications"]

Palette components: app (each service is its own stateless tier) · apigw (gateway, the single entry point) · auth · search · notifications · analytics · scheduler (shared capabilities, often bought) · sql (one database per service, never shared tables) · stream (events feed the derived services). Scenarios: monolith, event-fanout, microservices. Continues in: API Styles, Databases (one database per service), Messaging — patterns (outbox, saga), Distributed — transactions, Hands-on 1.

Key takeaways