E-commerce architecture, modelled
One online shop, drawn three times: the domain it deals in, the services it is built from, and the machines it runs on. Three diagrams, three different questions, and nothing on any of them that belongs on another.
9 min readUML 2.5.120 of 23
01Three diagrams, three questions
A shop is the example everybody reaches for, and the reason most shop diagrams are useless is that they try to be one picture. The vocabulary, the service boundaries and the machines are three different subjects, and a drawing that mixes them answers none of them - it is the diagram with an Order class, a Kubernetes logo and a queue on the same canvas.
Split by question and each one becomes checkable:
- What are the nouns? A class diagram of the domain. What an Order is, what it is made of, what it may not exist without.
- Who may call whom? A component diagram of services and the contracts between them.
- Where does it run? A deployment diagram of nodes and the artifacts on them.
Nothing here is a queue diagram, a sequence diagram or an infrastructure-as-code listing, and that is on purpose. Those exist and are useful; they are also where a documentation set goes to die if the first three are not right.
021. The domain
This is the diagram that settles vocabulary, and vocabulary is where shops go wrong first. Is a "basket" an Order that has not been placed, or a different thing? Does an OrderLine hold the price at the time of purchase, or read it from the Product? The second question is answered on the figure - unitPrice lives on the line - and that single attribute is the difference between a shop whose old invoices stay correct after a price change and one whose do not.
032. The services
The figure at the top of this article. Two clients, one order service, and two contracts it depends on - stock and payment. Read it by covering a box: cover the order service and what remains is IOrders, IStock and IPayment, which is exactly the specification a replacement would have to satisfy.
The adapter is the piece worth copying. IPaymentis a contract the shop owns; the Stripe adapter realizes it. Nothing in the order service names a provider, so "what would switching to Adyen cost?" has an answer you can see - one box and whatever the adapter turns out to have leaked. Drawn the other way round, with the order service depending on a Stripe component directly, the same question needs a codebase search.
What is deliberately absent: the cart, the search index, the recommendation engine, the email sender. Each of them is real, and none of them changes the answer to "who may call whom in the checkout path". They go on their own diagram, when somebody has a question about them.
043. The deployment
This is the diagram nobody draws until the first incident, and the one that answers questions the other two cannot: what is reachable from the internet, what talks to the database, and where the boundary to a third party sits. The Stripe API is drawn as an external node precisely because it is not yours - the box is a reminder that its availability is a dependency you do not control.
It is also the only one of the three that goes out of date on a normal Tuesday. The domain model survives a re-platforming untouched and so does the component view; the deployment diagram is invalidated by a cluster migration. That asymmetry is a good reason to keep it separate rather than folding "runs on Kubernetes" into the component boxes.
In one line each
- 01Three diagrams, three questions: the nouns, the contracts, the machines.
- 02Composition versus association on Order, OrderLine and Product is the domain model's whole payload.
- 03Own the payment contract and let an adapter name the provider - that is what makes a switch costable.
- 04Cover any component: what remains must specify its replacement.
- 05Leave search, email and recommendations off the checkout diagram; they answer a different question.
- 06Only the deployment view goes stale on a re-platforming, which is why it is its own picture.
The notation behind the middle diagram, with five more topologies, is in component diagram examples. To produce a first draft of any of the three from a description rather than by hand, see generating UML with AI.
05Common questions
Which diagrams do I need to document an e-commerce system?
Three cover almost every conversation: a class diagram for the domain vocabulary, a component diagram for which service may call which contract, and a deployment diagram for where it all runs. Add a sequence diagram only for the one or two flows that are genuinely contested, usually checkout and refunds.
How do I model payment providers without locking the diagram to one?
Draw the contract, not the provider. An IPayment interface with a Stripe adapter realizing it says the shop depends on the capability and not on the vendor, which is both truer and the thing you want to be able to check when somebody proposes switching providers.
Should the shopping cart be its own service?
On the diagram it is a decision, not a fact, so draw it whichever way your system actually works. A cart that lives in the storefront is a client concern and needs no box; a cart that survives across devices is state somebody owns, and it gets a component with a contract like anything else.
Where does the database go on an architecture diagram?
On the deployment diagram as a node, and on the component diagram only as the adapter in front of it. That split keeps the component view about contracts your code depends on, and keeps the question of which Postgres version runs where in the one diagram that is about machines.
Related reading