# ack: how to write a sequence diagram that runs on real time

You are writing a diagram in **ack**, a small text format for sequence diagrams where time is real.
The user pastes your answer into ack (ack.fin1te.com or a self-hosted copy). There, links between
participants have latency, work takes time, arrows slant in proportion to latency, a playhead sweeps
down and packets travel along the arrows. Viewers can click any message to drop it and watch the
flow re-run with timeouts, retries and hangs. Write for that: realistic latencies and durations matter.

Reply with a single fenced block tagged `ack` and nothing inside it except ack text.
On a web page that loads `<script src="https://ack.fin1te.com/embed.js" async></script>`, every such block
renders as the live diagram.

## 1. Shape of a file

```ack
title TLS 1.3 through a CDN edge
kicker One round trip before the request goes out
summary Optional paragraph shown above the figure in present mode.

client actor "Browser" "Mumbai" icon=laptop
edge service "Edge" "BOM" icon=cdn
origin service "Origin" "us-east-1" icon=server

link client edge 20ms        # one-way latency, so a 40 ms round trip
link edge origin 95ms

client -> edge "ClientHello + key share"
edge -> client "ServerHello, cert, Finished"
client -> edge "Finished + GET /"
edge does 2ms "cache miss"
edge -> origin "GET /"
origin does 30ms "render"
origin -> edge "200 OK"
edge -> client "200 OK" ttfb

step "The handshake costs one round trip" 1-2
```

One statement per line. `#` starts a comment. Statements run in order.

## 2. The time model

Every participant has a clock, starting at 0.

- A message leaves at the sender's current time and arrives one link latency later.
  The receiver's clock becomes the later of its own clock and the arrival.
- Sending does not move the sender's clock, so two sends in a row leave together (pipelining).
  A reply moves the requester's clock, because the requester was waiting for it.
- `does <duration>` advances that participant's clock and draws an activation bar.
- `waits <duration>` advances the clock with nothing drawn but a bracket (think time, a sleep).
- Receiving is a blocking wait. If a message is lost, its receiver waits forever, and so does
  everything that depends on it. ack greys those parts out and says who needs a timeout.
- Long idle stretches (timeouts, backoff, think time) fold into a marked break so diagrams stay compact.

## 3. Participants

```
<id> <kind> "<Label>" "<subtitle>" [icon=<name>] [tone=<tone>]
```

- `id`: letters, digits, `_ . -`, starting with a letter. Used everywhere else. Not a keyword.
- `kind` (sets the header look): `actor` (people, browsers, clients), `service` (the default),
  `store` (databases, caches, disks), `queue` (Kafka, SQS, streams), `control`, `external` (third parties).
- Label 1 to 3 words; subtitle short: a place, a technology, a role (`"us-east-1"`, `"PostgreSQL 16"`).
- `participant a "A"` and `actor a "A"` also work. Participants appear left to right in declaration order,
  so declare them in the order a request travels.

## 4. Links

```
link <a> <b> <one-way latency> [<bandwidth>]
link client server 40ms              # 80 ms round trip
link client server rtt=80ms          # same thing
link client server 20ms 100Mbps      # bandwidth: messages with size= take transmission time
latency 10ms                         # default for pairs without a link line
```

Links are symmetric. Use real numbers: same rack 0.1ms, same AZ 0.3 to 0.5ms, cross-AZ 1ms,
same city 2 to 10ms, across a continent 30 to 40ms, Mumbai to Virginia about 95ms one way.

## 5. Messages

```
a -> b "label"            request (solid)
b --> a "label"           reply (dashed); timing is identical, it only reads differently
a -x b "label"            lost on the way: never arrives
a -> b : label text       colon form, rest of the line is the label
a -> a "local call"       to itself, takes no time
```

Attributes after the label, any order:

- `size=14KB` payload size; with a link bandwidth it adds transmission time, and back-to-back
  messages on the same link queue behind each other.
- `timeout=500ms` the sender waits this long for the reply (the next message back from the receiver).
- `retries=3` resend up to 3 times after a timeout. Needs `timeout=`.
- `backoff=100ms` wait between attempts; `backoff=100ms*2` doubles each time; `cap=2s` caps it;
  `jitter` (or `jitter=equal`) randomises it, deterministically, so the diagram always plays the same.
- `idempotent` the receiver deduplicates retries (an idempotency key): a retry after it already did
  the work returns the stored reply instead of doing it again. Without it, ack flags work done twice.
- `drop=1` lose only attempt 1 (or `drop=1,2`). `-x` loses every attempt.
- `ttfb` or `mark="first byte"` puts this message's arrival time in the summary.

A timeout covers everything from the request to its reply: on retry, all of it runs again.

## 6. Work, waits and notes

```
db does 4ms "index scan"
user waits 3s "reads the page"
note api "Pool of 20 connections"
note client server "Spans both lifelines"
```

## 7. Blocks

```
loop 3 "per item" {
  app -> db "SELECT … WHERE id = $1"
  db --> app "1 row"
}

par {
  browser -> cdn "GET app.js"
  cdn --> browser "app.js"
} and {
  browser -> cdn "GET app.css"
  cdn --> browser "app.css"
}

alt "cache hit" {
  cache --> app "value"
} else "cache miss" {
  cache --> app "miss"
  app -> db "SELECT"
  db --> app "row"
}

opt "refresh the token" { … }
group "Handshake" { … }
```

- `loop N` repeats its body N times (up to 500).
- `par` branches start together; after the block everyone carries on once all branches are done.
- `alt` runs one branch at a time. The first runs by default and viewers can click the others.
  `opt` is an alt with one branch that viewers can switch off.

## 8. Steps and races

`step "caption" 1-3 5` lights up messages by the numbers drawn on the diagram (and participants by id)
and plays to the end of them in present mode. 3 to 6 steps, one plain sentence each.

Two diagrams separated by a line of `---` race side by side on the same time scale: TLS 1.2 against 1.3,
N+1 queries against one batched query. Give each its own `title`; keep the participants the same.

## 9. Icons

<!-- icons -->
- clients: user, users, browser, mobile, laptop, desktop, tenant, email, webhook, payment, bank, shop, cart
- compute: server, vm, container, pod, k8s, function, lambda, worker, cron, job, code, terminal, api, service
- data: db, cache, table, warehouse, bucket, disk, stream, queue, topic, search, file, lake, ledger, kafka
- network: network, router, switch, lb, gateway, firewall, dns, internet, cdn, vpn, tunnel, nat, region, cloud, wifi, antenna, satellite, edge
- security: shield, auth, lock, key, secrets, iam, identity, admin
- ai: llm, agent, model, tool, vector, gpu, mcp, chat
- observability: metrics, logs, traces, alert, monitor
- devops: git, ci, registry, deploy, config, event
- time: clock, timer, timeout
<!-- /icons -->

## 10. Style that makes it good

1. Real latencies and durations. The point of ack is that the numbers are true; say where they come from in the kicker.
2. 3 to 6 participants, 6 to 25 messages. Split bigger flows into two diagrams, or race two versions.
3. Declare participants in the order the request travels, left to right.
4. Labels are what is on the wire: `"GET /orders"`, `"SYN-ACK"`, `"COMMIT"`, `"201 Created"`. Short.
5. Put a `does` wherever real work happens (a query, a signature, a render), so the bars show where time goes.
6. Replies use `-->`. Give requests that can fail a `timeout=`, and `retries=` with `backoff=` when retrying is the point.
7. Plain language, no marketing words.

## 11. Before you answer, check

- Every participant is declared, every link has a unit (`20ms`, not `20`).
- Every `{` has a `}`. `timeout=` requests have a reply later in the same block.
- Output is one ```ack block.