mufassall

Cheat sheet · Architecture

Microservices

13 min · Intermediate · mufassall.dtwin.uz/en/l/microservices/

← Open the lesson

The problem

An online bookshop starts as one app and one database. When does splitting it into services help, what does each split cost, and where does an API gateway fit.

What you learn

  • Why to start with a monolith, and the signals that it is time to split
  • What a split buys: independent deploys, teams and scaling
  • What it costs: network calls, partial failure, data ownership, distributed debugging
  • What an API gateway does at the edge
Final scene
40%35%50%30%

Diagram as code

The lesson's final design as text: paste it into Jira, GitLab, GitHub, Notion or your docs, where Mermaid renders by itself. There are D2 and PlantUML (Confluence, IntelliJ) versions too.

Mermaid: flowchart

flowchart LR
  n_client(["Customer"])
  n_app["Shop app"]
  n_db[("Shop DB")]
  n_gw{"API gateway"}
  n_search["Search service"]
  n_pay["Payments service"]
  n_paydb[("Payments DB")]
  n_queue[["Event log"]]
  n_app --> n_db
  n_client --> n_gw
  n_gw --> n_app
  n_gw --> n_search
  n_pay --> n_paydb
  n_app --> n_queue
  n_queue --> n_pay

Mermaid: request sequence

sequenceDiagram
  participant n_app as Shop app
  participant n_db as Shop DB
  participant n_client as Customer
  participant n_gw as API gateway
  participant n_search as Search service
  participant n_pay as Payments service
  participant n_queue as Event log
  Note over n_app,n_db: One app, one database
  n_app->>n_db: BEGIN#59;
  Note over n_client,n_app: One team's problem is everyone's problem
  n_client->>n_app: GET /v1/search?q=dune HTTP/1.1
  n_app-->>n_client: HTTP/1.1 200 OK
  Note over n_gw,n_search: Split out the part that hurts
  n_gw->>n_search: GET /v1/search?q=dune HTTP/1.1
  n_search-->>n_gw: HTTP/1.1 200 OK
  Note over n_client,n_gw: The API gateway: one front door
  n_client->>n_gw: GET /api/search?q=dune HTTP/1.1
  n_gw-->>n_client: HTTP/1.1 200 OK
  Note over n_app,n_pay: Payments get their own service and database
  n_app->>n_pay: POST /internal/payments HTTP/1.1
  n_pay-->>n_app: HTTP/1.1 201 Created
  Note over n_app,n_pay: Partial failure
  n_app-xn_pay: POST /internal/payments HTTP/1.1
  Note over n_pay,n_db: Reading another service's tables
  n_pay->>n_db: SELECT total FROM orders WHERE id = 9001#59;
  n_db-->>n_pay: ERROR: column #34;total#34; does not exist
  Note over n_app,n_queue: Own your data, publish events
  n_app->>n_queue: produce topic=orders.events key=9001
  Note over n_queue,n_pay: The bill: debugging across services
  n_queue->>n_pay: consume orders.events partition=2 offset=48211

D2

direction: right

n_client: "Customer" {
  shape: rectangle
}
n_app: "Shop app" {
  shape: rectangle
}
n_db: "Shop DB" {
  shape: cylinder
}
n_gw: "API gateway" {
  shape: diamond
}
n_search: "Search service" {
  shape: rectangle
}
n_pay: "Payments service" {
  shape: rectangle
}
n_paydb: "Payments DB" {
  shape: cylinder
}
n_queue: "Event log" {
  shape: queue
}

n_app -> n_db
n_client -> n_gw
n_gw -> n_app
n_gw -> n_search
n_pay -> n_paydb
n_app -> n_queue
n_queue -> n_pay

PlantUML: request sequence

@startuml
participant "Shop app" as n_app
database "Shop DB" as n_db
participant "Customer" as n_client
participant "API gateway" as n_gw
participant "Search service" as n_search
participant "Payments service" as n_pay
queue "Event log" as n_queue
note over n_app, n_db : One app, one database
n_app -> n_db : BEGIN;
note over n_client, n_app : One team's problem is everyone's problem
n_client -> n_app : GET /v1/search?q=dune HTTP/1.1
n_app --> n_client : HTTP/1.1 200 OK
note over n_gw, n_search : Split out the part that hurts
n_gw -> n_search : GET /v1/search?q=dune HTTP/1.1
n_search --> n_gw : HTTP/1.1 200 OK
note over n_client, n_gw : The API gateway: one front door
n_client -> n_gw : GET /api/search?q=dune HTTP/1.1
n_gw --> n_client : HTTP/1.1 200 OK
note over n_app, n_pay : Payments get their own service and database
n_app -> n_pay : POST /internal/payments HTTP/1.1
n_pay --> n_app : HTTP/1.1 201 Created
note over n_app, n_pay : Partial failure
n_app ->x n_pay : [lost] POST /internal/payments HTTP/1.1
note over n_pay, n_db : Reading another service's tables
n_pay -> n_db : SELECT total FROM orders WHERE id = 9001;
n_db --> n_pay : ERROR: column "total" does not exist
note over n_app, n_queue : Own your data, publish events
n_app -> n_queue : produce topic=orders.events key=9001
note over n_queue, n_pay : The bill: debugging across services
n_queue -> n_pay : consume orders.events partition=2 offset=48211
@enduml

PlantUML: components

@startuml
left to right direction
agent "Customer" as n_client
component "Shop app" as n_app
database "Shop DB" as n_db
node "API gateway" as n_gw
component "Search service" as n_search
component "Payments service" as n_pay
database "Payments DB" as n_paydb
queue "Event log" as n_queue
n_app --> n_db
n_client --> n_gw
n_gw --> n_app
n_gw --> n_search
n_pay --> n_paydb
n_app --> n_queue
n_queue --> n_pay
@enduml

Recap

Start with a monolith with clean modules. Split only for a reason you can name.

1) Good reasons: teams blocking each other, one part with very different load, a part needing its own release pace or isolation. 2) Each split turns function calls into network calls: timeouts, partial failure, no shared transaction. 3) Each service owns its data; others use its API or events. 4) Put a gateway at the edge for auth, limits and routing. 5) Budget for tracing and central logs before you split, not after.

Numbers: at the start and at the end

MetricStartEnd
Deploys0.1/day6/day
Request p95140 ms280 ms
Services per order14
Failed requests0.3%0.4%

Steps

  1. Case One app, one database

    The shop is one app with one database.

  2. Problem One team's problem is everyone's problem

    Two years later: 40 developers in five teams, one codebase.

  3. Fix Split out the part that hurts

    Search becomes its own service with its own index, owned by one team.

  4. Case The API gateway: one front door

    Customers see one host.

  5. Fix Payments get their own service and database

    The payments team wants to deploy daily and keep card data away from everything else.

  6. Problem Partial failure

    Payments goes down.

  7. Problem Reading another service's tables

    To show the order total, the payments team reads the shop DB directly.

  8. Fix Own your data, publish events

    The shared read and the direct call are gone.

  9. Case The bill: debugging across services

    One order now touches the gateway, the app, the event log and payments.

  10. Recap Recap

    Start with a monolith with clean modules.

Terms

Microservice
A small service with its own deploys and its own data; others reach it only through its API or events. The cost is network calls, partial failure and no shared transaction, so you start with a clean monolith.
API gateway
One front door in front of all services: it checks the token, applies rate limits, adds a request id and routes by path. It hides the inside from clients.