Layered architecture

TL;DR

Ask your agent

Use Plotwork to draw a layered diagram of our online banking platform. Four layers: Experience (web app, mobile app, API gateway), Domain services (accounts, payments, ledger), Data (PostgreSQL, Redis, Kafka) and Infrastructure (Kubernetes, the private network). Put security and monitoring in an aside beside the layers, and show the calls between the layers with their protocols.

Use Plotwork to draw a three-tier web app: a browser and a CDN, a REST API with an auth service and background jobs, and a database and an object store. Show which blocks call which, and label each call.

Example

PictureSourceOutline

The four tones carry meaning: blue is what customers touch, violet is the business logic, aqua is where data lives, and neutral is the platform underneath. The PostgreSQL block has span=2, so it is as wide as two columns of the Data layer. The dotted line is an asynchronous call, the dashed line is a looser link, and the line with two heads is a two-way call. The aside stands beside the stack and is as tall as it, because security and monitoring touch every layer.

Three-tier web app

The oldest layered picture. counts=on shows how many blocks each layer holds, and the call from the CDN to the object store skips the application layer, so it runs down the lane on the right of the stack instead of through a block.

PictureSourceOutline

Hexagonal ports and adapters

The domain depends on nothing, the application owns the ports, and the adapters on both sides plug into them. Three dashed links leave the Ports block, skip the Domain layer, and take a lane each.

PictureSourceOutline

A cloud platform on AWS

Provider icons work as they do in a flow diagram: find them with the search_icons tool or in the icon reference. A vendor's own icon is drawn unmodified on its own tile in place of the chip. The link from API Gateway to Lambda joins two blocks of one row, so it runs under the row, inside the layer.

PictureSourceOutline

Microservices, from the foundation up

With direction=up the first layer written is the foundation, at the bottom, so the picture reads from the stores up to the clients. Seven services do not fit one row at a readable width, so the layer wraps to two rows and the last row is centred. A link from a block in the upper row goes along the gap between the rows to the lane, so write the blocks that have links in the row nearest the layer they link to.

PictureSourceOutline

The language

One statement to a line. Text is always in double quotes, options are key=value, and # starts a comment. Indentation is for the reader and means nothing to the parser: nesting comes from the braces.

A block's id is the word a link names. It starts with a letter, may contain letters, digits, _ and -, and is unique in the diagram. A link may be written before the blocks it joins.

1layers "Shop"2
3layer "App" {4  block web "Storefront" icon=lucide:globe5  block api "API" sub="Checkout and catalog" icon=lucide:server6}7
8layer "Data" {9  block db "Database" icon=lucide:database10}11
12web -> api : "HTTPS"13api -> db : "SQL"

Layers and tone

A layer takes the next tone of a rotation (blue, violet, aqua, orange, amber, neutral) unless tone= sets one, and its blocks keep the tone. A block may choose its own, to mark one block out. Choose tones for meaning, as the example does, and nobody writes a color value: the theme owns every color in light and dark. Green and red are left out of the rotation because they read as good and bad news; choose them with tone= when they should mean that.

Blocks, columns, and spans

A layer divides its width into equal columns and puts one block in each, 12px apart. When the blocks fit one row with every word whole, they fill it, so a layer of three blocks has three wide cards. When they do not, the blocks wrap to the fewest rows, as even as the order allows, and a short last row is centred so its cards keep the width of the rows above. What a card holds, the icon and the text, is centred in it, so the room at its left and its right is the same.

span=2 makes a block as wide as two columns, and the other blocks keep their one. A span can be at most 6, and never more columns than the layer has.

Asides

An aside is a tall band beside the stack for what cuts across every layer: security, monitoring, delivery. It has a dashed edge, which says it cuts across, its own corner tab, and its blocks hang from the tab one under the other. It stands on the right of the stack, as wide as its widest block or its name needs, and as tall as the stack; if its blocks need more height than the layers, the layers grow to match. Two asides stand side by side. A block in an aside takes no links, and a link to one is an error that says why.

Links

Links leave and enter the top and bottom of a block, so a line is never squeezed into the gap between two cards. Between layers that are next to each other a link runs along the gap between them. A link between two blocks of one row runs under the row, inside the layer. A link that skips a layer runs along the gap to a lane on the right of the stack, down the lane, and back along the gap above its target. Every line stays out of every block, and a link between blocks that stand over each other is straight.

Keep the few links that show how the layers depend on each other. A layered picture with forty links is a flow diagram that wants to be one.

Direction and counts

direction=up puts the first layer at the bottom, for a stack built on its foundation, and everything else reads the same. counts=on shows how many blocks each layer and aside holds, in a pill in its tab.

Limits and warnings

The picture is 880px wide, the width a Markdown column keeps text readable at, and grows taller with the rows and with the room the links need. The layout is plain arithmetic, so 80 blocks and 80 links are laid out in a few milliseconds.

A block is as wide as its column, and its label wraps to at most three lines, so a word is kept whole by giving its layer fewer, wider columns. Text is cut with an ellipsis, and W203 says so, only when no column could hold the word. The full text is always in the text description of the picture.

Every mistake comes back as a result with a code, a line, a column, and a hint. Warnings never stop the drawing.

From Mermaid

Mermaid block-beta is not read yet. It draws a grid of blocks with no layers and no meaning for a layer, so no mapping from it to a layered picture is right, and the converter reports it as a type it does not draw. Two things work today. Describe the system to your agent, or paste the Mermaid and say which blocks are tiers, and ask it to draw the layers; that is a better picture than a converted grid. If the Mermaid is a flowchart with subgraph blocks for the tiers, it converts to a flow diagram with a group for each tier, which keeps the arrows between the boxes. The migration guide covers the converter in full.

Use Plotwork to draw this Mermaid block diagram as a layered architecture. Make each row a layer, name the layers from what is in them, and keep the arrows as links between blocks.

See also