# Examples to copy

> Page: https://docs.plotwork.dev/examples. Index of every page: https://docs.plotwork.dev/llms.txt

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](https://docs.plotwork.dev/git-graphs.md), [Gantt charts](https://docs.plotwork.dev/gantt-charts.md), [Class diagrams](https://docs.plotwork.dev/class-diagrams.md), [State diagrams](https://docs.plotwork.dev/state-diagrams.md), [Timelines](https://docs.plotwork.dev/timelines.md), [User journeys](https://docs.plotwork.dev/user-journeys.md), and [Mind maps](https://docs.plotwork.dev/mind-maps.md). |
| 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](https://docs.plotwork.dev/writing-diagrams.md), kind by kind, and the [language reference](https://docs.plotwork.dev/reference/language.md). |
| Where are cloud examples? | [Cloud examples](https://docs.plotwork.dev/cloud-architecture/examples.md) for Azure, AWS, and Google Cloud, and [Architecture patterns](https://docs.plotwork.dev/architecture-patterns.md) 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.id
```

## 1. 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.
```

**Diagram source**

```diagram
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:success
node deny  terminal "401 Unauthorized" icon=status:error

user  -> api   : "email and password"
api   -> db    : "look up user" role=data
db    -> check
check -> ok    : "yes"
check -> deny  : "no"
```

*Picture: How a login request is checked: 6 nodes, 5 connections. A user signs in through an API that checks the password against a database and answers with a session or an error.*

**Text description**

**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.
```

**Diagram source**

```diagram
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   -> gw
gw       -> orders  : "POST /orders"
orders   -> payments : "charge"
orders   -> stock    : "reserve items"
orders   -> ordersdb
payments -> paydb
stock    -> stockdb
```

*Picture: Online shop services: 8 nodes, 7 connections. 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.*

**Text description**

**Nodes:**

- 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.
```

**Diagram source**

```diagram
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"
}
```

*Picture: Sign in with an identity provider: 4 participants. A web app sends the user to an identity provider, receives a code, and trades it for tokens.*

**Text description**

**Participants:**

- User, person
- Web app, client
- Identity provider, service
- Orders API, service

**Steps:**

- 1. User to Web app: Click Sign in
- 2. Web app to Identity provider: Redirect with client id
- 3. Identity provider to User: Ask for credentials
- 4. User to Identity provider: Credentials
- 5. Identity provider to Web app (dashed): Authorization code
- 6. Web app to Identity provider: Exchange code for tokens
- 7. Identity provider to Web app (dashed): Access token
- alt: token is valid
  - 8. Web app to Orders API: GET /orders with token
  - 9. Orders API to Web app (dashed): 200 orders
- else: token expired
  - 10. Orders API to Web app (dashed): 401
  - 11. 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.
```

**Diagram source**

```diagram
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.id
order_items.order_id    -> orders.id
order_items.product_id  -> products.id
```

*Picture: Online shop: 4 tables, 3 relations. Customers place orders. An order has many items, and each item points at a product.*

**Text description**

**Tables:**

- 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.
```

**Diagram source**

```diagram
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=data
resize  --> logs   : "metrics and logs"
```

*Picture: Serverless image resizer on AWS: 5 nodes, 4 connections. An upload to S3 triggers a Lambda function that resizes the image, writes it to a second bucket, and logs to CloudWatch.*

**Text description**

**Nodes:**

- Uploader, client
- Account: AWS account
  - Region: eu-west-1
    - Uploads, storage
    - Resize image (Node.js), function
    - Resized images, storage
    - Logs, service

**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](https://docs.plotwork.dev/cloud-architecture/examples.md) has a complete diagram for each, and [Cloud architecture](https://docs.plotwork.dev/cloud-architecture.md) 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.
```

**Diagram source**

```diagram
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:success
node test    step     "Test"           icon=status:success
node staging step     "Deploy to staging" icon=status:success
node approve decision "Approved?"
node prod    terminal "Production"     icon=status:success
node hold    terminal "Held"           icon=status:warning

pr      -> build
build   -> test
test    -> staging
staging -> approve
approve -> prod : "yes"
approve -> hold : "no"
```

*Picture: Release pipeline: 7 nodes, 6 connections. A merged pull request is built and tested. A passing build is deployed to staging, then to production after approval.*

**Text description**

**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.
```

**Diagram source**

```diagram
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"
```

*Picture: Password reset: 4 participants. A user asks for a reset link, receives it by email, and chooses a new password. Each message carries its step number.*

**Text description**

**Participants:**

- User, person
- Web app, client
- Auth API, service
- Email, service

**Steps:**

- 1. User to Web app: Forgot password
- 2. Web app to Auth API: Request reset
- 3. Auth API to Email: Send reset link
- 4. Email to User (dashed): Email arrives
- 5. User to Web app: Choose new password
- 6. Web app to Auth API: Set password
- 7. 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.
```

**Diagram source**

```diagram
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=data
processor -> warehouse : "load"
processor --> collector : "ack" animate=off
```

*Picture: Clickstream into analytics: 5 nodes, 5 connections. 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.*

**Text description**

**Nodes:**

- 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](https://docs.plotwork.dev/markdown-and-github.md). |
| A link | On the hosted server, ask: "Publish this and give me the link." See [Hosted diagrams](https://docs.plotwork.dev/hosted-diagrams.md). |
| A private copy for your team | Ask: "Publish this to the Platform organisation." See [Organisations](https://docs.plotwork.dev/organisations.md). |

## See also

| Doc | Why |
|---|---|
| [Quick start](https://docs.plotwork.dev/quick-start.md) | Connect an agent and draw a first diagram |
| [Writing diagrams](https://docs.plotwork.dev/writing-diagrams.md) | The language, kind by kind |
| [Prompts and recipes](https://docs.plotwork.dev/agents/prompts.md) | More requests and the tool each leads to |
| [Cloud examples](https://docs.plotwork.dev/cloud-architecture/examples.md) | Complete Azure, AWS, and Google Cloud diagrams |
| [Architecture patterns](https://docs.plotwork.dev/architecture-patterns.md) | Checked, ready-made diagrams to start from |