Chartado diagram language

Your first diagram

API Gateway -> Lambda -> DynamoDB

Three services in a row at columns 0, 1 and 2, wired targets: [1], [2], []. One flow, rooted at the first service.

Name things whatever you call them

Order API -> Checkout Function -> Orders Table

The same three-box shape in your own vocabulary. Names render exactly as typed. The icons still resolve to API Gateway, Lambda and DynamoDB because the parser found the keywords api, function and table inside them.

Fan-out: send to everything at once

API Gateway -> Lambda -> SNS -> {Lambda Emailer, SQS Archive}

Braces make SNS a fan-out source: it gets targets: [3, 4] and isFanOutSource: true. Both entries land in column 3 with rows 0 and 1 and totalRows: 2, so they stack. The animation sends a message down both arrows at the same time.

Choice: take one path, not all of them

API Gateway -> Lambda -> |DynamoDB, SQS| -> EventBridge

Pipes make Lambda a choice source: isChoiceSource: true, targets: [2, 3]. DynamoDB and SQS are flagged isChoiceTarget and share column 2. The segment after the closing pipe rejoins, so both branches target EventBridge. Same shape as the fan-out above, different meaning at playback.

A response coming back

API Gateway -> Lambda -> DynamoDB
API Gateway <- Lambda <- DynamoDB

Line two names the same three services, so no new boxes are created — the result is still 3. Because the second line runs against the direction of the first, it becomes a second flow: flows[0] carries the outbound connections and flows[1] the return. You get a request animation and a response animation over one set of boxes.

What the public editor already shows you

API Gateway -> Lambda -> SNS
SNS -> {Lambda Emailer, Lambda Analytics, SQS Archive}

This is the prompt the live editor loads with, so you can read it here and then watch it move there. SNS is written on both lines and reused rather than duplicated: 6 services, one flow. Line two turns the existing SNS box into a fan-out source with three targets in column 3.

One service

Lambda

The smallest valid diagram. One service, column 0, no targets, and a single flow with no connections. That is the whole document.

Multi-word names

Order API -> Order Queue -> Order Worker -> Orders Table

Spaces inside a name are ordinary and no quoting is needed. Columns are 0, 1, 2, 3. The icon is picked by a case-insensitive keyword search inside the name, which is why Order Queue renders as SQS and Orders Table as DynamoDB, while Order Worker falls back to the generic icon.

Whitespace is trimmed at the edges

  Lambda    Producer  ->  SNS Topic  

Leading and trailing spaces on the line and around each arrow are removed. Spaces inside a name are not: this box is named Lambda Producer, keeping all four interior spaces exactly as typed.

Spaces around the arrow are optional

Lambda->SQS

Exactly the same result as Lambda -> SQS. Tabs work too. Space around arrows is for your eyes only.

The same name twice on one line makes two boxes

Lambda -> SQS -> Lambda

Three boxes, not two, and not a cycle back to the first. Within a single line the parser appends a new service per segment and never looks up an existing one by name. Name-based reuse only starts on the second and later lines — see multiple lines.

Fan out to three targets

SNS -> {Lambda A, Lambda B, SQS}

Four services. SNS sits at column 0 with targets: [1, 2, 3]. The three targets share column 1 with rows 0, 1, 2 and totalRows: 3. All three edges carry isFanOut: true and a fanOutIndex equal to the entry’s row.

Rejoin after the fan-out

SNS -> {Lambda A, Lambda B} -> SQS

Anything after the closing brace receives from every branch: Lambda A and Lambda B both get targets: [3]. SQS lands at column 2 and has no row or totalRows — continuations are not part of the row group.

Fan out from a fan-out target, on a new line

EventBridge -> {Lambda Orders, Lambda Billing}
Lambda Orders -> {SQS Orders, DynamoDB Orders}
Lambda Billing -> {SQS Billing, DynamoDB Billing}

This is how you get a second level. Braces do not nest, so each later line names an existing service and fans out from it. Lambda Orders and Lambda Billing end up flagged both isFanOutTarget and isFanOutSource. Row numbering restarts per group: SQS Orders and SQS Billing are both row 0 of totalRows: 2 at column 2.

A chain inside one branch

SNS -> { (SQS -> Lambda), DynamoDB }

The parenthesised chain is one entry, so there are two rows, not three. SQS and Lambda both carry row 0, DynamoDB carries row 1, and all three carry totalRows: 2. SNS targets only the head of each entry: targets: [1, 3].

Branches of different lengths

SNS -> { (SQS -> Lambda -> DynamoDB), S3 }

Branches do not have to be the same length. The chain spans columns 1, 2 and 3 on row 0; S3 stays at column 1 on row 1. totalRows is 2 for every service in the group.

Several chains, then a continuation

SNS -> { (SQS -> Lambda), (Kinesis -> Firehose), DynamoDB } -> S3

Three entries, three rows. S3 receives from the terminal of each branch — Lambda, Firehose and DynamoDB — not from the entries’ heads. Its column is the group’s starting column plus the length of the longest branch, so it sits at column 3 whatever the shorter branches do.

Extend one branch on a later line

SNS -> { (SQS -> Lambda), DynamoDB }
DynamoDB -> Athena

Naming a fan-out target on a later line appends to that branch. Athena lands at column 2 and inherits row 1 of totalRows: 2 from DynamoDB, keeping it on the same horizontal track. Do not combine this with a continuation after the closing brace on the first line: the later line replaces the branch’s targets rather than adding to them, and the edge into the continuation disappears. Pick one or the other.

A choice in one line

Lambda -> |DynamoDB, SQS| -> EventBridge

The minimal choice. Lambda is the choice source with targets: [1, 2]. DynamoDB (row 0) and SQS (row 1) both carry isChoiceTarget and totalRows: 2, and both target EventBridge. Branches share column 1, the source is column 0, the join is column 2.

A choice with no continuation

Lambda -> |DynamoDB, SQS, SNS|

You do not have to rejoin, and the number of branches is not fixed. Nothing follows the closing bar, so all three branches end with targets: []. This is a complete, valid diagram.

Branches that continue on their own lines

Validator -> |Authorize, Reject| -> CloudWatch
Authorize -> Process -> DynamoDB -> CloudWatch
Reject -> SQS -> SNS -> CloudWatch

Lines 2 and 3 start with names that already exist as choice targets, so they extend those branches instead of starting new flows. CloudWatch is named three times and exists exactly once. Eight services, one flow. Process and DynamoDB inherit row 0 from Authorize; SQS and SNS inherit row 1 from Reject. Note that the -> CloudWatch on line 1 is overridden: Authorize ends up targeting Process, not CloudWatch.

Branches that never rejoin

API -> |Process, Reject|
Process -> DynamoDB -> SNS
Reject -> Dead Letter

Branches are not required to converge. Six services, one flow, two dead ends: SNS and Dead Letter both finish with targets: [].

Three-way routing with unequal branch lengths

Order API -> |Approve, Review, Decline| -> Audit Log
Approve -> Charge Card -> Ship Order -> Audit Log
Review -> Manual Queue -> Audit Log
Decline -> Notify Customer -> Audit Log

Branches may be different lengths. The long branch reaches column 3, the short ones stop at column 2, and all three land on the single Audit Log service. Nine services, one flow. Branch-line order does not matter: rows follow the order written on the choice line.

Naming the join only on the branch lines

Validator -> |Authorize, Reject|
Authorize -> Process -> CloudWatch
Reject -> SQS -> CloudWatch

Where you first name the join changes the layout. Here CloudWatch is created by the Authorize branch line, so it inherits row 0 of totalRows: 2 and is flagged isBranchContinuation — it renders in the top lane rather than centred. Name the join on the choice line instead and it is created outside any branch, with row and totalRows undefined, and renders centred against the group. The edges are the same either way; the layout is not.

Fan-out on one branch

Validator -> |Authorize, Reject| -> CloudWatch
Authorize -> {Process, Archive}
Reject -> CloudWatch

A branch line can fan out. Authorize becomes both isChoiceTarget and isFanOutSource, targeting Process and Archive. The Reject branch still reaches CloudWatch. Note that Authorize no longer targets CloudWatch: the fan-out replaced that edge.

Fan-out after a choice, on the same line

Lambda -> |DynamoDB, SQS| -> {SNS, EventBridge}

A { } immediately after a choice attaches to every branch, not just the last one: both DynamoDB and SQS become isFanOutSource and both target the same two services. The reverse order is not symmetric — see the block below.

Nested choice on a branch line

API Gateway -> SQS -> EventBridge -> |Lambda SES, Lambda Store|
Lambda Store -> DynamoDB -> Lambda Miloljub -> S3
Lambda SES -> EventBridge 2 -> |Lambda Check, Lambda Two| -> SES

A branch line can open its own choice. EventBridge 2 is created on the Lambda SES branch and is simultaneously isChoiceTarget, isBranchContinuation and isChoiceSource, with Lambda Check and Lambda Two below it, both rejoining at SES. Twelve services, one flow. Nesting is verified three levels deep.

A repeated name is the same service

API Gateway -> Lambda
Lambda -> DynamoDB

Three services, not four. Line two starts with a name that already exists, so it continues from the existing Lambda instead of creating a second one. DynamoDB lands at column 2. Contrast with Lambda -> SQS -> Lambda on a single line, which really does draw two Lambdas. Line two is a fresh chain rather than a branch continuation, so it becomes a second flow: the arrow into DynamoDB animates after the arrow into Lambda, and Lambda’s own targets stays empty.

A line that shares no name draws a separate diagram

A -> B -> C
D -> E

This is how you put two unrelated pipelines on one canvas. Line two names nothing that already exists, so it joins the picture only in the sense of sharing the canvas: there is no connection of any kind between the two groups. D restarts at column 0 alongside A, and the second chain animates only after the first has finished.

Reuse is case-sensitive

Order API -> |Approve, Decline| -> CloudWatch
Approve -> cloudwatch

Won’t work as a rejoin. cloudwatch is not CloudWatch, so you get five services with two separate boxes that look like the same thing. Name lookup uses exact string equality. If a branch refuses to converge, check the capitalisation first.

A second entry point converging on an existing service

API Gateway -> Lambda -> DynamoDB
EventBridge -> Lambda

The smallest fan-in. Line two introduces a new service that feeds an existing one, so the result is a single flow with two roots — API Gateway and EventBridge — and a message from either entry point continues downstream through Lambda to DynamoDB. EventBridge already lands adjacent to Lambda, so it is not flagged isConvergentSource and nothing moves. It does share column 0 with API Gateway, so both pick up a row and stack.

More than one converging line

A -> B -> C -> D
E -> C
F -> D

There is no limit on how many entry points converge. E and F each land one column left of the service they feed — column 1 and column 2, not column 0 — and both are flagged isConvergentSource. E shares column 1 with B and F shares column 2 with C, so each of those pairs stacks as rows 0 and 1. Still one flow, now with three roots: A, E and F all start moving at once.

Line order does not change the columns

E -> C
A -> B -> C -> D

The same diagram as A -> B -> C -> D followed by E -> C, written the other way round. Every column is identical: A at 0, B and E at 1, C at 2, D at 3. Writing the converging line first does not push the main chain rightwards and does not leave E stranded at column 0. Only which of B and E is row 0 follows the order you wrote.

Convergence carries through the chain

A -> B -> C
D -> E -> C
F -> E

Line two converges on C. Line three converges on E, which line two had only just created — and that is enough to pull it into the same picture. All three entry points end up in one flow with three roots. A, D and F share column 0 and stack as rows 0, 1 and 2 of totalRows: 3; B and E share column 1. Nothing here is flagged isConvergentSource, because every source already sits directly in front of its target.

An agent calling a tool and coming back

User -> Agent -> LLM -> |Tool, Response|
Tool -> Agent

Line two adds no boxes. It draws two arrows, not one: Tool back to LLM, then LLM back to Agent, retracing the forward route. They live in a second flow, so the outbound pass finishes first and the return then plays over the same boxes. Writing Tool -> Agent and expecting a single long arrow is the surprise this section exists for.

The return is as long as the path it retraces

A -> B -> C -> D -> E
E -> B

Three hops back, not one: E to D, D to C, C to B. The expansion follows the forward route exactly, so a longer chain gives a longer return. No new services and no new columns — only a second flow.

Neighbours stay a single arrow

A -> B -> C
B -> A

The exception. A and B are adjacent, so there is no intermediate service to route through and the second flow holds exactly one arrow, B back to A. This is also how you draw a plain request-and-response pair over two boxes.

A one-hop loop back from a branch stops the animation

Validator -> {Authorize, Reject}
Authorize -> Validator

Won’t work, and it fails without warning. A line starting from a service inside { } or | | continues that branch, so its edge is written into targets and stays in flow 0 — it does not become a return flow. Here that closes a cycle, and a flow whose every arrow has an arrow feeding it has no arrow to start from: the diagram draws, and then nothing moves at all. Contrast A -> B / B -> A, where B is an ordinary service and you get two working flows. Loop back to a service two or more hops away, or loop back from outside a branch.

Reverse arrow

API Gateway <- Lambda <- DynamoDB

Identical to DynamoDB -> Lambda -> API Gateway: same services in the same order, same columns, same connections. DynamoDB is column 0 and API Gateway is column 2.

Mixing arrow directions reverses the whole line

Client -> API Gateway <- Lambda

Won’t work as a round trip. One <- anywhere on the line reverses every segment on that line, so the result is the chain Lambda → API Gateway → Client — the opposite of what the text reads like. There is no bidirectional edge in the language.

Prefix a service with its namespace

User:Browser -> API Gateway -> Lambda -> DynamoDB

User:Browser renders as a Browser and is named Browser — the prefix is stripped from the label. The other three segments need no prefix: the bare-name search finds api in the AWS list, then lambda, then dynamodb. Mixing prefixed and unprefixed segments on one line is normal.

Without a prefix, AWS wins the tie

API -> Memory

A bare name is tried against the three lists in order — AWS, then User, then AI — and the first list containing a match wins. api is a keyword in both AWS (API Gateway) and AI (Tool), so API becomes an API Gateway. Memory matches nothing in AWS or User, so the search falls through to AI.

Force the AI vocabulary with a prefix

AI:API -> AI:Memory

Same two names, one prefix. AI:API now searches only the AI list and becomes a Tool instead of an API Gateway. This is the case a namespace is actually for: overriding a keyword collision.

An unregistered namespace silently goes generic

AWS:Lambda -> SNS -> Google:Functions

Won’t work. Google is not one of the three registered namespaces, so no keyword list is searched at all and the box renders as the generic grey dot labelled Service. It is not an error and there is no warning — the service is still created, still named Functions, still connected. Without the prefix, bare Functions would have matched the AWS keyword function and drawn a Lambda.

Namespaces are case-sensitive

aws:Lambda -> AWS:Lambda

Won’t work: aws: is not AWS:. The first box falls back to generic grey; the second is a proper orange Lambda. Both are named Lambda — and because this is a single line, they really are two separate boxes. This is the single most likely reason a box came out grey when you expected an icon.

A name identifies a box; a namespace does not

AWS:Lambda -> SQS
AI:Lambda -> DynamoDB

Three services, not four. Line two’s AI:Lambda resolves to the name Lambda, which already exists, so it merges into the box created on line one and keeps that box’s AWS namespace and its icon. There is no way to have two different boxes both named Lambda across lines.

Coordinates parse and are stored

Lambda [0.5, 0.7] -> SQS [0.8, 0.7]

Two services named Lambda and SQS, each carrying a coordinates object. The bracketed text is not part of the name and is not drawn.

Coordinates do not move anything

Lambda [0.9, 0.9] -> SQS [0.1, 0.1]

Won’t work as positioning. Lambda claims x 0.9 and SQS claims x 0.1, so you might expect SQS on the left. It is not: Lambda stays at column 0 and SQS at column 1, and the rendered pixel positions are identical to a plain Lambda -> SQS. Layout is decided by arrow order alone.

Namespace and coordinates combined

AWS:Lambda [0.2, 0.3] -> AWS:SQS [0.5, 0.3]

Prefix first, brackets last, both stripped from the name. The icons come from the AWS list; the coordinates change nothing on screen. Given that, the only reason to write them today is to carry a note you intend to use later.

Brackets swallow everything after them

My [x] Lambda

Won’t work as a name. This is one box named My, not My Lambda. Everything from the first [ onward is discarded, so the trailing word is thrown away with it — and with it the keyword that would have made this a Lambda box. It renders generic grey. Keep brackets at the end of a name or leave them out.

An AI pipeline needs no prefixes at all

User -> Agent -> LLM -> Vector DB

Every name here is found by the bare-name search. User matches the AI keyword user and renders as Human — note that the User namespace does not contain the word user. Agent gives AI Agent, LLM gives LLM, Vector DB gives Vector DB.

Keywords work inside ordinary business names

Order Table -> Audit Stream -> Search Index

This is the mechanism working for you: table gives DynamoDB, stream gives Kinesis, search gives an AI Tool. You get sensible icons without naming AWS services at all.

A whole word can still hide in a name

Webhook -> Responses -> User Service

A keyword only matches a whole word, so a short keyword can no longer hide inside a longer one — Webhook is not a Browser and Approved is not a phone. What still catches people is a keyword that is actually one of the words: User Service renders a Human because user is a word in it, and Order Queue renders an SQS queue. If a name comes out wrong, look for a keyword among its words, then rename the box or force the namespace.

Prose is a service name

!!! total garbage ###

One box, named after your text, at column 0. No error, no warning, and it passes the editor’s pre-parse check. Anything you type that contains no arrow does this, including an English sentence.

=> is not an arrow

Lambda => SQS

Won’t work. One service named Lambda => SQS. The only two arrows are -> and <-. A Unicode → and a spaced - > fail the same way.

A near-miss arrow is worse than a wrong one

Lambda --> SQS

Won’t work, and this half-works, which is why it is easy to miss. The parser matches the -> at the end and keeps the leading hyphen as part of the name, producing a service called Lambda -. The connection is made, so the diagram looks nearly right; only the label is wrong.

There is no comment syntax

# this is a note
API Gateway -> Lambda

Won’t work. The heading becomes a stray box at column 0 in its own flow. // behaves the same way, and a trailing comment welds itself onto the last service name on the line. There is no comment stripping anywhere in the parser.

There are no edge labels, and quoting damages a name

A -> "publishes" -> B

Won’t work. There is no syntax for putting text on an arrow; the label becomes its own box, and the quote characters are kept and drawn. Names never need quoting — whitespace is already trimmed — and quoting actively damages the label.

Square brackets around a name produce an invisible box

API Gateway -> [Lambda] -> DynamoDB

Won’t work, and this is the worst outcome on the list. Square brackets are the coordinate syntax, not a label syntax, so the middle service ends up with an empty name: a real, connected, unlabelled box in the middle of your diagram.

A colon anywhere creates a namespace

Step 1: Validate -> Step 2: Persist

Won’t work as labels. These are not boxes called Step 1: Validate and Step 2: Persist. The first colon splits each segment, so the names are Validate and Persist, in namespaces Step 1 and Step 2. Neither is registered, so both render generic grey.

A chain in braces without parentheses

SNS -> { SQS -> Lambda, DynamoDB }

Won’t work. The arrow is swallowed into the name and you get a single box labelled SQS -> Lambda. Parentheses are mandatory for a chain inside a group.

Braces do not nest

SNS -> { {Lambda A, Lambda B}, SQS }

Won’t work. The group is split on every comma and the inner braces are ignored, so they end up glued to the names. Watch for a box called {Lambda A — that is the tell. Use a second line for a second level.

Parentheses do not build chains inside | |

Lambda -> |(A -> B), C| -> D

Won’t work, even though the same notation does work inside { }. There is no A and no B and no internal edge — just one branch literally named (A -> B). Put the chain on its own branch line.

Coordinates inside a choice are torn in half

Lambda -> |A [0.1, 0.2], B [0.3, 0.4]|

Won’t work. Coordinates survive inside a fan-out but not inside a choice: the contents of the bars are split on every comma with no bracket awareness, so two branches become four and totalRows becomes 4.

Two choices on one line chain through

A -> |B, C| -> |D, E|

Works. Every terminal of the first choice becomes a choice source for the second, so B and C each branch to D and E. This used to drop the first choice entirely, orphaning B and C; that was fixed, and a test now pins it.

Two fan-outs on one line chain through

SNS -> {Lambda A, Lambda B} -> {SQS, DynamoDB}

Works, in the same way as the line above. Every terminal of the first fan-out becomes a fan-out source for the second, so Lambda A and Lambda B each fan out to SQS and DynamoDB. This used to overwrite the source and orphan both Lambdas; that was fixed, and a test now pins it.