Architecture patterns

TL;DR

1. The recipe

Follow these steps in order. Each one ends with a check.

1. Find the pattern. Call find_pattern with the words of the request. Add provider to keep only the patterns that come in that flavour, kind for flow, sequence, or schema, and tags to require a tag. Read the summaries and pick one. If nothing fits, write the diagram from the language reference instead.
2. Read it. Call get_pattern with the id and the flavour you want in provider. A flavour the pattern does not have is a problem that lists the ones it has. Read the slots, then the three notes: what to keep, what to rename, and when to split.
3. Choose the slot values. Use the names from the request. A value is plain text of at most 60 characters, with no quotes, backslashes, or line breaks. A value that breaks a rule comes back as a problem with the slot named, never as an exception.
4. Draw it. Call draw_from_pattern with the id, the flavour, and the values. It returns valid, the warnings, a summary for the picture's description, an outline to check against the request, and the SVG for the themes you asked for.
5. Adapt what the slots cannot. To add a node, remove a service, or change an edge, take the source that get_pattern returned, edit it, and call validate_diagram until no warning is left. Keep the shape of the groups: they carry the meaning.
6. Check the outline. Call outline_diagram, or read the outline in the answer, and compare it with the request line by line. Every service the request names is a node, and every node is something the request names.

A session for the request "a serverless API with a queue for slow work, on Google Cloud" looks like this:

2. Slots

A slot is a named part of a pattern. Every pattern has title and description: the first is the name of the diagram, and the second is the sentence that a screen reader reads in place of the picture. The others are named for what they hold, such as office, load-balancer, or primary-database.

A slot used in several places, such as the name of a load balancer drawn once for each tier, is set once and changes everywhere.

3. The patterns

Every id is stable. Tools and links use it, so it never changes.

4. The gallery

Each pattern is drawn below in its neutral flavour, with its slots. The defaults are placeholders: documentation address ranges such as 192.0.2.0/24 and generic names such as web-tier.

Three-tier network behind load balancers

An office network joins a cloud network through a VPN gateway, and three tiers each put a load balancer in front of a redundant set of machines.

When to use it. Start here when the request is a classic web, application, and data layering inside a private network, especially when an office or data center connects to it. It shows what each tier holds, where the redundancy is, and the one way operators get in.

Id and flavours. three-tier-network, drawn below in its neutral flavour. It also comes in: Azure.

PictureSourceOutline

Keep. Keep the order of the tiers, the edge from the middle machine of one tier to the load balancer of the next (it keeps the tiers level), the three overlays, and direction=down. Keep every machine in a tier as a member of that tier's overlay.

Rename. Rename the tiers, the machines, and the address ranges through the slots. Change the number of machines by adding a node, an edge from the load balancer, and the member id in the overlay, in all three places. Swap the generic icons for a provider's with the flavour you pick.

Split. Past about four machines in a tier, or a fourth tier, draw the tier alone in its own diagram and keep one machine of it here. Draw the management and monitoring paths in a second diagram if they pull in more than two nodes.

Two-zone network with a replicated database

A network spans two availability zones, each with a public, a private, and an isolated subnet, joined by one balancer set, one scaling group, and a replicated database.

When to use it. Start here when the request is a network that survives the loss of a zone: public subnets for the balancers, private subnets for the servers, isolated subnets for the data. It shows which resources are per zone, which span both, and how the data is kept in step.

Id and flavours. two-zone-network, drawn below in its neutral flavour. It also comes in: AWS.

PictureSourceOutline

Keep. Keep both zones as siblings with the same three subnets in the same order, one node in each subnet, and the two dashed sets: they are what shows the balancer and the scaling group span both zones. Keep the replication link between the two databases.

Rename. Rename the zones, subnets, and resources through the slots, and replace the sample address ranges with the real ones. Give a subnet more than one node by adding nodes inside it and edges to them; add the new servers to the scaling set's members.

Split. Past about three nodes in a subnet, or a third zone, draw one zone alone in a second diagram and show only the balancer, one server, and the database here. Draw the outbound path (a NAT gateway and the routes) in its own diagram.

Hub and spoke network

A hub network with a firewall and shared services links an office to several isolated spoke networks, so all traffic between them passes one place.

When to use it. Start here when several workloads need their own networks but share connectivity, security, and services: each workload gets a spoke, and the hub holds what they share. It shows that spokes reach each other and the office only through the hub firewall.

Id and flavours. hub-and-spoke-network, drawn below in its neutral flavour. It also comes in: Azure.

PictureSourceOutline

Keep. Keep every spoke connected to the hub firewall and to nothing else outside its own group: that is what the pattern says. Keep the hub in its own tone, and keep the office behind the gateway.

Rename. Rename the spokes after the workloads or teams that own them, and give each its real address range. Add a spoke by copying one group, its two nodes, and its two edges.

Split. Past about five spokes, draw the hub with two spokes here and list the others in a table, or draw a second hub for a second region in its own diagram.

Web application on a cloud

A single-page app is served through a CDN, backed by an API on a hosting plan, a database, a queue and worker, identity, storage, a delivery pipeline, and monitoring.

When to use it. Start here when the request is a typical web application and the reader needs to see every managed service around it: where files live, where code runs, how users sign in, how slow work is queued, and how changes ship. It is the usual first diagram of a cloud system.

Id and flavours. web-app-on-cloud, drawn below in its neutral flavour. It also comes in: Azure.

PictureSourceOutline

Keep. Keep one group for each concern (edge, sign-in, storage, hosting plan, messaging, delivery, monitoring), the queue between the API and the worker as a dotted link, and the deploy link from the pipeline to the API. Keep direction=down.

Rename. Rename the services for what the application does, and the stack marks for its technologies (up to three on a node). Add a node to a group for a second service of the same kind, with an edge from the node that uses it.

Split. Past about 20 nodes, move the data stores and the queue into a second diagram that starts at the API, and keep only the API here. Draw the pipeline alone when it has more than three steps.

Serverless API

A client calls an API gateway that checks sign-in and routes to three functions, which keep records in a managed database and files in object storage.

When to use it. Start here when the request is a small HTTP API built from managed services with no servers to run: a gateway, short-lived functions, a managed database, and a bucket. It shows where sign-in is checked and where telemetry goes. Start from the three-tier network pattern instead when the services run on machines you manage.

Id and flavours. serverless-api, drawn below in its neutral flavour. It also comes in: AWS, Google Cloud.

PictureSourceOutline

Keep. Keep the order of the groups (functions, sign-in, data stores, monitoring), the order of the functions (create, list, get), the sign-in check as the last edge from the gateway, the one dotted telemetry edge, which stands for every function, and direction=down. Keep the database and the storage in one group, because a group for each makes the arrows from the functions bunch at one point.

Rename. Rename the functions, the database, and the storage through the slots. Add a function by adding a node in the functions group, an edge from the gateway, and an edge to what it uses. Pick the aws or gcp flavour to swap the generic glyphs for that provider's icons.

Split. Past about five functions, draw the functions as one node here and give each route group its own diagram. Draw a deployment pipeline in a second diagram.

Microservices behind an API gateway

Clients call one API gateway that checks identity and routes to small services, which talk to each other through a message bus and each keep their own database.

When to use it. Start here when the request is a system split into small services that own their data: one public entry point, a sign-in check, and events between services instead of shared tables. It shows who may be called from outside and who only reacts to events. Start from the serverless API pattern instead when the services are short-lived functions.

Id and flavours. microservices-gateway, drawn below in its neutral flavour. It also comes in: AWS, Azure, Google Cloud.

PictureSourceOutline

Keep. Keep one database for each service and no edge from a service to another service's database, because that is what the pattern says. Keep the dotted edges through the message bus, the public and internal groups, the identity check as an edge from the gateway only, and direction=down.

Rename. Rename the services, the databases, the routes, and the event through the slots. Add a public service by adding a node in the public group, an edge from the gateway, and a database with an edge from the service. Pick the aws, azure, or gcp flavour to swap the generic glyphs for that provider's icons.

Split. Past about five services, draw the gateway and the public services in one diagram and give each group of related services its own, with the bus shown as an external node. Draw tracing, deployment, and the service mesh in separate diagrams.

Container platform

A delivery pipeline pushes images to a registry, and a managed cluster runs three services on a redundant node pool behind an ingress, with configuration, secrets, and monitoring.

When to use it. Start here when the request is a Kubernetes or managed container platform: where images come from, how traffic reaches the services, and what the services depend on. It does not show networks, multiple environments, or the data stores the services use.

Id and flavours. container-platform, drawn below in its neutral flavour. It also comes in: Google Cloud.

PictureSourceOutline

Keep. Keep the order from pipeline to registry to cluster to monitoring, the three services as the members of the node pool overlay, and direction=down. Keep a label on both the push edge and the traffic edge, or on neither, so the registry stays level with the first service. Keep the dotted edges: the image pull and the metrics are asynchronous.

Rename. Rename the services, the cluster, and the pipeline stages through the slots. Add a service by adding a node, an edge from the ingress, and its id in the overlay members. The pull and metrics edges each stand for every service. Swap the generic icons for a provider's with the flavour you pick.

Split. Past about five services, draw the cluster alone and show one service of it here. Draw the data stores, the network, and each environment in their own diagrams.

Queue and worker pool

A web API puts jobs on a queue, a pool of workers takes them and writes results to a database, failed jobs go to a dead-letter queue, and an alarm watches the queue depth.

When to use it. Start here when the request is background work: a request is accepted quickly and the slow part runs later on workers that can scale out. It shows the hand-off through a queue, the redundant pool, the retry path, and the alarm that tells you the workers fall behind. Start from the event-driven pipeline pattern instead when many independent consumers react to the same event.

Id and flavours. queue-worker, drawn below in its neutral flavour. It also comes in: AWS.

PictureSourceOutline

Keep. Keep the overlay around the workers, and the one edge from the pool to the database and the one to the dead-letter queue, because each stands for every worker. Keep the edge from the queue to the alarm without a label, because a label pushes the alarm one row below the pool. Keep the pool name short, because a long name makes a tab wide enough to cover the first arrow. Keep direction=down.

Rename. Rename the services, the queue, and the stores through the slots, and set the retry count in the retries slot. Change the number of workers by adding a node, a dotted edge from the queue, and the member id in the overlay, in all three places. Pick the aws flavour to swap the generic glyphs for AWS icons.

Split. Past about five workers, keep three nodes and say how many more in the pool name. Draw the scaling rules and what the alarm triggers, such as paging or adding workers, in a second diagram.

Event-driven pipeline

Several services publish events to an event bus, three independent consumers react to them, and events that keep failing go to a dead-letter queue.

When to use it. Start here when the request is publish and subscribe: services that emit events without knowing who listens, and consumers that work on their own. It shows the fan-out from one bus, the asynchronous links, and where failed events end up. Start from the queue and worker pattern instead when one service hands a job to a pool of workers.

Id and flavours. event-driven-pipeline, drawn below in its neutral flavour. It also comes in: Google Cloud.

PictureSourceOutline

Keep. Keep the dotted arrows from the producers to the bus and from the bus to each consumer, because they say the links are asynchronous, and keep the edge from the bus to the dead-letter queue. Keep the second line of the bus node about as long as it is, because a narrow node makes the three arrows into it bunch at one point.

Rename. Rename the services, the consumers, and the stores through the slots. Add a consumer by adding a node in the consumers group, a dotted edge from the bus, and an edge to what it writes. Pick the gcp flavour to swap the generic glyphs for Google Cloud icons.

Split. Past four producers or four consumers, draw the producers as one node and give each consumer its own diagram, or split by event type. Draw how dead letters are inspected and replayed in a second diagram.

Static site behind a CDN

Visitors resolve a name through DNS and reach a content delivery network with a certificate, which serves files from a storage bucket that a build pipeline updates and clears from the cache.

When to use it. Start here when the request is a static website, a documentation site, or a single-page app served from object storage through a CDN. It shows the name lookup, the HTTPS certificate, the origin, and how new files reach visitors. It does not show dynamic back ends or APIs behind the site.

Id and flavours. static-site-cdn, drawn below in its neutral flavour. It also comes in: AWS.

PictureSourceOutline

Keep. Keep the visitor path as the right column and the pipeline as the left column, the dotted edge from the publish step to the delivery network, and direction=down. Keep one label on each of the two chains that lead to the middle row, so the publish step stays level with the delivery network.

Rename. Rename the services, the bucket, and the pipeline steps through the slots. Add a step to the pipeline by adding a node and an edge before the publish step, and label no more than one edge in the chain. Swap the generic icons for a provider's with the flavour you pick.

Split. Add an API or a function behind the delivery network in a second diagram, and keep this one for the static path. Draw several sites, regions, or environments one per diagram, and show the extra origin here only when it changes how visitors are served.

Data lake and analytics

Sources feed an ingestion stage into a raw zone, a processing stage cleans the data into a curated zone, and a warehouse serves analysts through dashboards, with a catalog that describes the datasets.

When to use it. Start here when the request is a data platform: where data comes from, how it is landed and cleaned, and how people query it. It shows the raw and curated zones as separate stores. It does not show orchestration, access control, or machine learning workloads.

Id and flavours. data-lake-analytics, drawn below in its neutral flavour. It also comes in: Google Cloud.

PictureSourceOutline

Keep. Keep the single column from ingestion to analysts, the two zones as groups inside the data lake group, and direction=down. Keep the catalog as a leaf with one dotted edge from the curated store, because an edge into the raw zone pulls the whole column out of line.

Rename. Rename the sources, the stages, the zones, and the stores through the slots. Add a source by adding a node in the sources group and an edge to the ingestion stage. Swap the generic icons for a provider's with the flavour you pick.

Split. Past about five sources, group them by kind and show one node per kind. Draw orchestration, access control, and streaming paths in their own diagrams, and add a third zone only if the picture stays one column.

Multi-region failover

A global routing service sends users to a primary region and fails over to a standby region, which holds replicated data and an identical stack.

When to use it. Start here when the request is to survive the loss of a whole region: it shows which region serves normally, what switches, and what is copied. Use it to discuss recovery time, because the replication links are the part that decides how much data a failover loses.

Id and flavours. multi-region-failover, drawn below in its neutral flavour. It also comes in: AWS.

PictureSourceOutline

Keep. Keep both regions with the same three nodes in the same order, the dashed failover link beside the solid normal link, and the dotted replication link between the two databases, which stay side by side.

Rename. Rename the regions and the services through the slots. Keep one replicated pair in view: a second pair draws its link across the first, so put it in a second diagram.

Split. Past about five nodes in a region, draw one region alone in its own diagram and keep a single node per region here. Draw the failover procedure as a sequence diagram instead.

CI/CD delivery pipeline with an approval gate

A commit is built, tested, scanned, and stored as an image, then deployed to staging, held for an approval, and released to production.

When to use it. Start here for a continuous integration and delivery flow with a manual gate before production. It shows which steps belong to the pipeline, which environments hold running code, and where people are notified. Draw a different diagram for a pipeline that releases straight to production or for one with many parallel jobs.

Id and flavours. ci-cd-delivery-pipeline, drawn below in its neutral flavour. It also comes in: Azure.

PictureSourceOutline

Keep. Keep the order of the steps, the group around the pipeline steps, one group for each environment, and the approval node outside both environments. Keep the dotted arrows for notifications, because they mark a message that nothing waits for.

Rename. Rename the steps, environments, and channels through the slots. Add a step such as a lint or a performance test by adding a node and an edge between its neighbours, inside the pipeline group. Add an environment by copying the staging group and its two edges.

Split. Past about four steps in the pipeline or a third environment, draw the pipeline alone in one diagram and the environments with their rollout in another. Draw rollback and failure paths in a second diagram.

Sign-in with an authorization code and proof key

A browser app signs a person in through an identity provider with the authorization code flow and a proof key, calls a backend API with the access token, and refreshes it when it expires.

When to use it. Start here for the sign-in of a single-page or mobile app that has no client secret and calls its own backend API. It shows where the proof key is made and checked, what the API verifies, and how an expired token turns into a refresh and a retry. Draw a different diagram for a server-rendered app that keeps a client secret, or for machine-to-machine access with no person.

Id and flavours. sign-in-token-flow, drawn below in its neutral flavour. It has no provider flavour.

PictureSourceOutline

Keep. Keep the order of the messages: the verifier and challenge are made before the redirect, the code travels back by redirect, and only the exchange carries the verifier. Keep the alt block, because the expired branch is the part readers look for, and keep the retry after the refresh.

Rename. Rename the four participants, their second lines, and the data the API returns through the slots. To add a scope or an audience, change the message text by hand. Add a second API as a fifth participant to the right of the first, with its own request and response.

Split. Draw sign-out, a revoked refresh token, and a first sign-in with consent as separate diagrams. Past five participants, draw the backend services on their own in a second diagram and keep one participant for them here.

Multi-tenant application schema

Organizations own projects and an audit log, and users join organizations through a memberships table that carries a role.

When to use it. Start here for a software-as-a-service product where several customers share one database and every row belongs to an organization. It shows the join table for a many-to-many link with a role, the foreign key that scopes each row to its tenant, and an append-only log. Draw a different schema when each customer has its own database or when users belong to no organization.

Id and flavours. database-schema-starter, drawn below in its neutral flavour. It has no provider flavour.

PictureSourceOutline

Keep. Keep the organization_id foreign key on every table that holds tenant data, the pair of foreign keys in the join table, and the nullable flags on columns that are empty for a good reason. Keep the audit table append-only, and keep actor_id without a foreign key so the history survives when a user is deleted.

Rename. Rename the tables and their second lines through the slots. To rename a column, change it in the source by hand, in the table and in every relation that names it. Add business tables the same way projects is drawn: an id, an organization_id foreign key, and a relation to organizations.

Split. Past six tables, draw each area on its own: tenancy and access in one diagram, the business tables in another, and billing in a third. Keep organizations in each one so the foreign keys still have a parent.

5. Adapting a pattern

A pattern is a starting point, not a template to fill in blindly. If the request names a service that the pattern has no node for, add a node for it with its own icon. If the pattern has a node that the request does not mention, remove it.

See also