Cheat sheet · Architecture
Microservices
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
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_payMermaid: 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=48211D2
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_payPlantUML: 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
@endumlPlantUML: 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
@endumlRecap
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
| Metric | Start | End |
|---|---|---|
| Deploys | 0.1/day | 6/day |
| Request p95 | 140 ms | 280 ms |
| Services per order | 1 | 4 |
| Failed requests | 0.3% | 0.4% |
Steps
- Case One app, one database
The shop is one app with one database.
- Problem One team's problem is everyone's problem
Two years later: 40 developers in five teams, one codebase.
- Fix Split out the part that hurts
Search becomes its own service with its own index, owned by one team.
- Case The API gateway: one front door
Customers see one host.
- Fix Payments get their own service and database
The payments team wants to deploy daily and keep card data away from everything else.
- Problem Partial failure
Payments goes down.
- Problem Reading another service's tables
To show the order total, the payments team reads the shop DB directly.
- Fix Own your data, publish events
The shared read and the direct call are gone.
- Case The bill: debugging across services
One order now touches the gateway, the app, the event log and payments.
- 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.