Get started
Examples to copy
Eight finished diagrams with the text that makes each one and the prompt that gets an agent to write it. Copy the text into a diagram fence, or paste the prompt into your agent and change the names to yours. It is for anyone who learns faster from a working diagram than from a reference.
TL;DR
| Question | Answer |
|---|---|
| How do I use one? | Two ways. Paste the prompt into your agent and change the names, or copy the text into a diagram fence in a Markdown file and ask your agent to render the file. |
| Which kinds are here? | Flow (a login check, an online shop, a serverless app on AWS, a release pipeline, and a data flow that moves), sequence (a sign-in, and a password reset with numbered steps), and schema (a shop database). |
| What about the other kinds? | Git graphs, Gantt charts, class diagrams, state diagrams, timelines, user journeys, and mind maps each have a finished example in their own guide: see Git graphs, Gantt charts, Class diagrams, State diagrams, Timelines, User journeys, and Mind maps. |
| Can I change them? | Yes. Rename nodes, add lines, change direction. Ask your agent to check the text: it names the line and says how to fix it. |
| Where is the full language? | Writing diagrams, kind by kind, and the language reference. |
| Where are cloud examples? | Cloud examples for Azure, AWS, and Google Cloud, and Architecture patterns for ready-made networks. |
Starter text
Start from one of these when none of the examples is close. Replace the names and add lines.
Plotwork
flow "Title" direction=down
node a service "First"node b database "Second"
a -> b : "label"Plotwork
sequence "Title"
actor a client "First"actor b service "Second"
a -> b : "Request"b --> a : "Response"Plotwork
schema "Title"
table things { id uuid pk name text}
table parts { id uuid pk thing_id uuid fk}
parts.thing_id -> things.id1. A login check
A flow with a decision. Two possible endings, drawn as terminal nodes with status icons.
Ask your agent:
text
Use Plotwork to draw how a login request is checked. A user sends an email and password to an Auth API, which looks the user up in a Users database. If the password is correct a session is issued, otherwise the API answers 401 Unauthorized.
Plotwork
flow "How a login request is checked" desc="A user signs in through an API that checks the password against a database and answers with a session or an error." direction=down
node user person "User"node api service "Auth API" sub="POST /login"node db database "Users DB"node check decision "Password correct?"node ok terminal "Session issued" icon=status:successnode deny terminal "401 Unauthorized" icon=status:error
user -> api : "email and password"api -> db : "look up user" role=datadb -> checkcheck -> ok : "yes"check -> deny : "no"Nodes:
- User, person
- Auth API (POST /login), service
- Users DB, database
- Password correct?, decision
- Session issued, terminal
- 401 Unauthorized, terminal
Connections:
- User to Auth API: email and password
- Auth API to Users DB (stored data line): look up user
- Users DB to Password correct?
- Password correct? to Session issued: yes
- Password correct? to 401 Unauthorized: no
2. An online shop with groups
Groups draw a box around related nodes. type=edge and type=data-tier give a group its icon and its color.
Ask your agent:
text
Use Plotwork to draw an online shop. A web app calls an API gateway. Behind it are Orders, Payments and Inventory services, and each has its own database. Orders calls Payments to charge and Inventory to reserve items. Put the gateway in an Edge group, the services in a Services group, and the databases in a Databases group.
Plotwork
flow "Online shop services" desc="A web app calls an API gateway. The orders service asks the payments and inventory services to do their part, and each service keeps its own database." direction=down
node client client "Web app" sub="Browser"
group edge "Edge" type=edge { node gw gateway "API gateway" sub="TLS, rate limits"}
group services "Services" { node orders service "Orders" node payments service "Payments" node stock service "Inventory"}
group data "Databases" type=data-tier { node ordersdb database "Orders DB" node paydb database "Payments DB" node stockdb database "Inventory DB"}
client -> gwgw -> orders : "POST /orders"orders -> payments : "charge"orders -> stock : "reserve items"orders -> ordersdbpayments -> paydbstock -> stockdbNodes:
- Web app (Browser), client
- Edge: Edge
- API gateway (TLS, rate limits), gateway
- Group: Services
- Orders, service
- Payments, service
- Inventory, service
- Data tier: Databases
- Orders DB, database
- Payments DB, database
- Inventory DB, database
Connections:
- Web app to API gateway
- API gateway to Orders: POST /orders
- Orders to Payments: charge
- Orders to Inventory: reserve items
- Orders to Orders DB
- Payments to Payments DB
- Inventory to Inventory DB
3. A sign-in sequence
A sequence diagram reads top to bottom, one line per message. --> is a reply. An alt block shows two outcomes.
Ask your agent:
text
Use Plotwork to draw a sequence diagram of signing in with an identity provider. The user clicks Sign in in the web app, the app redirects to the identity provider, the user enters credentials, the provider returns an authorization code, and the app exchanges it for an access token. Then the app calls the Orders API. If the token is expired the API answers 401 and the app refreshes it.
Plotwork
sequence "Sign in with an identity provider" desc="A web app sends the user to an identity provider, receives a code, and trades it for tokens."
actor user person "User"actor app client "Web app"actor idp service "Identity provider"actor api service "Orders API"
user -> app : "Click Sign in"app -> idp : "Redirect with client id"idp -> user : "Ask for credentials"user -> idp : "Credentials"idp --> app : "Authorization code"app -> idp : "Exchange code for tokens"idp --> app : "Access token"
alt "token is valid" { app -> api : "GET /orders with token" api --> app : "200 orders"} else "token expired" { api --> app : "401" app -> idp : "Refresh token"}Participants:
- User, person
- Web app, client
- Identity provider, service
- Orders API, service
Steps:
-
- User to Web app: Click Sign in
-
- Web app to Identity provider: Redirect with client id
-
- Identity provider to User: Ask for credentials
-
- User to Identity provider: Credentials
-
- Identity provider to Web app (dashed): Authorization code
-
- Web app to Identity provider: Exchange code for tokens
-
- Identity provider to Web app (dashed): Access token
- alt: token is valid
- 8. Web app to Orders API: GET /orders with token
-
- Orders API to Web app (dashed): 200 orders
- else: token expired
- 10. Orders API to Web app (dashed): 401
-
- Web app to Identity provider: Refresh token
4. A shop database
A schema diagram draws tables with their columns. pk marks a primary key, fk a foreign key, and a line below the tables joins one column to another.
Ask your agent:
text
Use Plotwork to draw the database of an online shop: customers (id, email, created_at), products (id, name, price in cents), orders (id, customer, placed_at, status), and order_items (id, order, product, quantity). Orders belong to customers, and each order item points at an order and a product.
Plotwork
schema "Online shop" desc="Customers place orders. An order has many items, and each item points at a product."
table customers sub="People who buy" { id uuid pk email text unique created_at timestamptz}
table products { id uuid pk name text price int note="In cents"}
table orders { id uuid pk customer_id uuid fk placed_at timestamptz status text}
table order_items { id uuid pk order_id uuid fk product_id uuid fk quantity int}
orders.customer_id -> customers.idorder_items.order_id -> orders.idorder_items.product_id -> products.idTables:
- customers
- id uuid (primary key)
- email text (unique)
- created_at timestamptz
- products
- id uuid (primary key)
- name text
- price int: In cents
- orders
- id uuid (primary key)
- customer_id uuid (foreign key)
- placed_at timestamptz
- status text
- order_items
- id uuid (primary key)
- order_id uuid (foreign key)
- product_id uuid (foreign key)
- quantity int
Relations:
- orders.customer_id references customers.id (many to one)
- order_items.order_id references orders.id (many to one)
- order_items.product_id references products.id (many to one)
5. A serverless app on AWS
Cloud diagrams add icon=aws:... to a node, and type=account and type=region to groups. Ask your agent to choose the icons: it calls map_icons for every product name and never guesses.
Ask your agent:
text
Use Plotwork to draw a serverless image resizer on AWS. An upload to an S3 bucket triggers a Lambda function that resizes the image, writes it to a second S3 bucket, and sends logs to CloudWatch. Put it all in an AWS account and the eu-west-1 region.
Plotwork
flow "Serverless image resizer on AWS" desc="An upload to S3 triggers a Lambda function that resizes the image, writes it to a second bucket, and logs to CloudWatch." direction=down provider=aws
node user client "Uploader"
group aws "AWS account" type=account { group region "eu-west-1" type=region { node uploads storage "Uploads" icon=aws:s3 node resize function "Resize image" icon=aws:lambda sub="Node.js" node resized storage "Resized images" icon=aws:s3 node logs service "Logs" icon=aws:cloudwatch }}
user -> uploads : "PUT image"uploads --> resize : "object created"resize -> resized : "write thumbnail" role=dataresize --> logs : "metrics and logs"Nodes:
- Uploader, client
- Account: AWS account
- Region: eu-west-1
- Uploads, storage
- Resize image (Node.js), function
- Resized images, storage
- Logs, service
- Region: eu-west-1
Connections:
- Uploader to Uploads: PUT image
- Uploads to Resize image (dashed): object created
- Resize image to Resized images (stored data line): write thumbnail
- Resize image to Logs (dashed): metrics and logs
For Azure and Google Cloud, replace aws: with azure: or gcp: and the product name. Cloud examples has a complete diagram for each, and Cloud architecture explains accounts, regions, networks, and subnets.
6. A release pipeline
Status icons (status:success, status:warning, status:error) show how each step ended, which suits a pipeline, a runbook, or an incident timeline.
Ask your agent:
text
Use Plotwork to draw a release pipeline. A merged pull request is built and tested. A passing build is deployed to staging. Someone approves it, and it goes to production. If they do not approve, the release is held. Show each step with a success icon, and the held end with a warning.
Plotwork
flow "Release pipeline" desc="A merged pull request is built and tested. A passing build is deployed to staging, then to production after approval." direction=down
node pr step "Merged pull request"node build step "Build" icon=status:successnode test step "Test" icon=status:successnode staging step "Deploy to staging" icon=status:successnode approve decision "Approved?"node prod terminal "Production" icon=status:successnode hold terminal "Held" icon=status:warning
pr -> buildbuild -> testtest -> stagingstaging -> approveapprove -> prod : "yes"approve -> hold : "no"Nodes:
- Merged pull request, step
- Build, step
- Test, step
- Deploy to staging, step
- Approved?, decision
- Production, terminal
- Held, terminal
Connections:
- Merged pull request to Build
- Build to Test
- Test to Deploy to staging
- Deploy to staging to Approved?
- Approved? to Production: yes
- Approved? to Held: no
7. Numbered steps in a sequence
Add numbered=on to the header and every message gets a numbered badge, so people can say "step 4" aloud. Write step=off on a message to leave its badge out.
Ask your agent:
text
Use Plotwork to draw how a password reset works as a sequence with numbered steps. A user asks the web app for a reset, the app asks the Auth API, the API has the email service send a link, the user opens the link and chooses a new password, and the API confirms.
Plotwork
sequence "Password reset" numbered=on desc="A user asks for a reset link, receives it by email, and chooses a new password. Each message carries its step number."
actor user person "User"actor app client "Web app"actor api service "Auth API"actor mail service "Email"
user -> app : "Forgot password"app -> api : "Request reset"api -> mail : "Send reset link"mail --> user : "Email arrives"user -> app : "Choose new password"app -> api : "Set password"api --> app : "Password changed"Participants:
- User, person
- Web app, client
- Auth API, service
- Email, service
Steps:
-
- User to Web app: Forgot password
-
- Web app to Auth API: Request reset
-
- Auth API to Email: Send reset link
-
- Email to User (dashed): Email arrives
-
- User to Web app: Choose new password
-
- Web app to Auth API: Set password
-
- Auth API to Web app (dashed): Password changed
8. A data flow that moves
Add animate=on to the header and every line with an arrowhead gets dashes that travel toward it. Write animate=off on a line to keep it still. The motion shows when a browser or GitHub shows the SVG as an image, and it is off for readers who ask for reduced motion.
Ask your agent:
text
Use Plotwork to draw how page views flow from a website to a warehouse: a Collector, an Event stream, and a Processor in between. Animate the lines, except the acknowledgement the Processor sends back to the Collector.
Plotwork
flow "Clickstream into analytics" animate=on direction=down desc="Page views travel from a website through a collector and a stream to a processor, which loads them into a warehouse. The acknowledgement is drawn still."
node site client "Website"node collector gateway "Collector"node stream queue "Event stream"node processor function "Processor"node warehouse database "Warehouse"
site -> collector : "page view"collector -> stream : "append"stream -> processor : "read" role=dataprocessor -> warehouse : "load"processor --> collector : "ack" animate=offNodes:
- Website, client
- Collector, gateway
- Event stream, queue
- Processor, function
- Warehouse, database
Connections:
- Website to Collector: page view
- Collector to Event stream: append
- Event stream to Processor (stored data line): read
- Processor to Warehouse: load
- Processor to Collector (dashed): ack
Share what you made
| You want | Do |
|---|---|
| A picture file | Ask your agent: "Save this diagram as SVG files for light and dark." |
| The diagram in a README | Put the text in a diagram fence and ask your agent: "Render the diagrams in README.md." See Markdown and GitHub. |
| A link | On the hosted server, ask: "Publish this and give me the link." See Hosted diagrams. |
| A private copy for your team | Ask: "Publish this to the Platform organisation." See Organisations. |
See also
| Doc | Why |
|---|---|
| Quick start | Connect an agent and draw a first diagram |
| Writing diagrams | The language, kind by kind |
| Prompts and recipes | More requests and the tool each leads to |
| Cloud examples | Complete Azure, AWS, and Google Cloud diagrams |
| Architecture patterns | Checked, ready-made diagrams to start from |