You describe it. Lumagram draws it.
An architecture diagram is a picture of how the parts of a piece of software fit together — which piece talks to which. People draw them to explain a system to somebody new, to plan a change before making it, or to put a clear picture in a document.
Normally you would drag boxes around in a drawing tool and lose an afternoon nudging them into line. Here you write one sentence per connection, press a button, and the finished picture appears — evenly spaced, with the arrows routed for you and the right logos already attached.
Visitors -> Website -> Database
Visitors
Website
DatabaseThree ordinary words and two arrows. Nothing was installed, nothing was positioned by hand, and no account was created.
You do not need to be technical
Nothing here assumes you know what a load balancer is. Type plain words — Website, Payments, Customers — and you get labelled boxes. Lumagram quietly tries to match each name against a library of 7,800+ official logos, so Databasetends to arrive wearing a database icon. When it doesn't recognise a word, you simply get a clean labelled box, which is a perfectly good diagram.
Any term you don't recognise in this page is explained in plain English in the glossary, and section 07 has finished examples you can paste in and edit.
It runs in this browser
There is nothing to download and nothing to set up. The page you are reading and the studio are the whole product.
Nothing is uploaded
Your diagram never leaves your machine. The draft is saved in this browser, so closing the tab does not lose your work.
The text is the file
Your diagram is a few lines of plain text. Copy them into a document or a repo; anyone who pastes them back sees exactly what you saw.
One arrow is a valid diagram.
Open the studio and type into the left pane. Hit Generate diagram (or ⌘/Ctrl + Enter) and the canvas lays itself out — your draft autosaves in the browser, so there is nothing to save. Everything below is optional sugar on top of this one line.
Users -> API -> Postgres
APIPostgresThree names and two arrows. No icons were requested, so the compiler fuzzy-matched each name against the catalog and found marks for all three.
Note what you did not have to write: no node declarations, no icon ids, no positions, no layout hints. A name that appears in an arrow becomes a node, and the layout engine decides where it goes. Everything in the rest of this page is optional detail layered on top of that one line.
Open the studio
No account, no project to create. The editor is the landing state, and your draft autosaves in this browser.
Type an arrow
Left pane, Builder tab. Hit Generate diagram — or ⌘/Ctrl + Enter — and the layout engine does the rest.
Export PNG
Download PNG in the top bar. You get the frame as shown, no watermark.
Naming a thing creates it.
Any word that appears in an arrow becomes a node. To attach an icon, put a nickname in parentheses — resolution is fuzzy across 7,800+ icons, so rds, database and db land on the same official mark, while postgres or github pick their own logos. Prefer an exact pick? Name [icon: x] is explicit. Icons that would vanish on a dark canvas swap to generated dark variants automatically, so exports follow your theme.
Users (users)
CDN (cloudfront)
Public ALB (alb)
Store [icon: rds]
Users -> CDN -> Public ALB -> Store
Usersusers
CDNcloudfront
Public ALBalb
StorerdsEvery edge form, in one table.
Chain as many hops as you like on one line. Edges are counted in the order you wrote them — flip on Step numbers in the studio to print that order on every arrow, which is usually the order a request actually travels.
- A -> B
- Solid directed edge. Chain freely: A -> B -> C -> D.
- A -> B : label
- Labels the edge — everything after the first colon outside brackets.
- A --> B
- Dashed — conventionally async, queued, or best-effort.
- A ..> B
- Dotted — telemetry, logs, side channels.
- A <-> B
- Bidirectional, arrowheads both ends. <> works too; <--> is the dashed form.
- A <- B
- Reversed — the arrowhead points back at A. <-- is the dashed form.
- A -> B, C, D
- Fan-out: one source, several targets. Comma lists work on the source side too.
- A -> B -> A
- Cycles are legal; ELK routes around the loop.
The two forms that need more than one edge to show — fan-out and a labelled chain — look like this once compiled:
Route53 (route53) -> ALB (alb)
ALB -> EC2 (ec2), Lambda (lambda)
EC2 -> RDS (rds) : write
Route53ALB
EC2RDS
LambdaLine 2 fans one source out to two targets with a comma list — ALB reaches both branches, and only the EC2 branch continues to the database.
Real containers, nested as deep as you need.
Groups are layout objects, not decoration — ELK sizes and routes around them, so a subnet inside a VPC inside a region behaves the way it does in the console. Arrows can even point at a group itself.
region us-east-1 {
vpc prod {
subnet public {
ALB (alb)
}
subnet private {
EC2 (ec2) -> RDS (rds)
}
}
}
ALB -> EC2vpcsubnetregionazaccountcloudclustersggroup
Any other word before the brace makes a generic container. Edges may cross container walls freely — reference a node by name from anywhere in the file. Indentation is cosmetic; the braces are what nest.
That file compiles to genuinely nested boxes — a subnet inside a VPC inside a region — and the arrow from the public subnet to the private one crosses a container wall without any extra syntax:
ALBEC2RDSContainers are sized by their contents, so adding a node grows the box around it. The ALB → EC2 edge crosses two subnet boundaries and ELK routes around them.
Make one flow the point of the picture.
- A -> B [red]
- Named color on one line's arrows — red, orange, amber, yellow, green, teal, cyan, blue, indigo, violet, purple, pink, gray, black.
- A -> B [#ff8800]
- Any hex works too.
- A -> B : label [color: blue]
- Eraser-style color attribute on a labeled edge.
- Risky DB [icon: rds, color: red]
- Tints a node's box and label without touching its icon.
- # comment
- Ignored. // and %% work too, so pasted files stay valid.
Spotlighting is a canvas gesture, not syntax: click a node to fade everything but its connections, click an arrow to isolate it, and use the Flows legend when arrows carry multiple colors. Exporting while focused captures exactly that view.
Colour is how you separate two paths through the same boxes. Here the read path and the write path share a load balancer, and the backup edge is deliberately pushed into the background:
ALB (alb) -> EC2 (ec2) : read [blue]
EC2 -> Redis (redis) : hit [blue]
EC2 -> RDS (rds) : write [green]
RDS --> S3 (s3) : nightly backup [gray]
RedisRDS
S3Same nodes, three colour-coded stories. Because the colours are per-line, the diagram stays readable even when one topology serves several flows.
Start from something that already works.
Each of these is a whole diagram, not a fragment. Copy one into the studio, press Generate diagram, then change the words to match your own system. Renaming Website to Booking portal is a perfectly good way to learn this.
The most common shape there is. Someone visits your site, the site reads and writes data.
Visitors (users) -> Website (nextjs) -> Database (postgres)A cache remembers recent answers so the database is asked less often. Backups copy the data somewhere safe overnight.
Visitors (users) -> Website (nextjs)
Website -> Cache (redis) : fast lookups
Website -> Database (postgres) : everything else
Database --> Backups (s3) : nightly [gray]Two jobs handed to outside companies rather than built yourself — a login provider and a payments provider.
Visitors (users) -> App (nextjs)
App -> Login (auth0) : sign in [blue]
App -> Payments (stripe) : charge card [violet]
App -> Database (postgres)Braces draw a box around whatever is inside them. Useful for showing what runs where.
Visitors (users) -> Gateway (api)
cloud aws {
Gateway -> Worker (lambda)
Worker -> Store (s3)
}Notice the small differences between them: a colon adds a label to an arrow, two dashes make it dashed, square brackets set a colour, and braces draw a box around a group. Those four things cover most diagrams anyone needs.
Paste Mermaid or Eraser unchanged.
The parser sniffs the first few lines and switches dialect on its own — a flowchart or graph header means Mermaid. Useful when the diagram already lives in a README, or when you asked an LLM for Mermaid.
title Checkout path
Users (users) -> CDN (cloudfront)
vpc prod {
ALB (alb) -> EC2 (ec2) -> RDS (rds)
}
CDN -> ALB : https
EC2 --> CloudWatch : logs [gray]The default, and what every canvas edit writes back. Chains, fan-outs and nestable containers.
- A -> B : label
- Arrow with an optional label
- Name (service)
- Icon by fuzzy nickname
- vpc Prod { … }
- Nestable container
- A -> B [red]
- Per-edge color
- title …
- Diagram title
One real diagram, built line by line.
Everything above in one go. This is a three-tier checkout path inside a real account layout — a cloud, a region, a VPC, two subnets — written in the order you would actually type it. Each step below is the line added and what it does to the picture.
title Checkout pathA title is optional and never becomes a node — it just labels the frame on export.
Users -> CDN (cloudfront)Two nodes and the first edge. Users resolves on its own; CDN takes an explicit nickname so it gets the CloudFront mark rather than a guess.
cloud aws { region us-east-1 { … } }Containers open before anything needs to live in them. Nesting is by brace, not indentation — the indentation here is purely for humans.
subnet public { ALB (alb) }A public subnet holding just the load balancer. One node in a container is a perfectly normal thing to write.
ALB -> EC2 (ec2) -> RDS (rds) : sqlA chain inside the private subnet. The label attaches to the last hop only — EC2 → RDS — because a colon binds to the edge it follows.
EC2 ..> CloudWatch (cloudwatch) : metrics [gray]A dotted, greyed side channel. It crosses out of the subnet to a node declared at cloud level, which is legal — names are global.
Put together, the whole file is nine lines — and this is the complete source, not an excerpt:
title Checkout path
Users -> CDN (cloudfront)
cloud aws {
region us-east-1 {
vpc prod {
subnet public { ALB (alb) }
subnet private {
ALB -> EC2 (ec2) -> RDS (rds) : sql
}
}
}
EC2 ..> CloudWatch (cloudwatch) : metrics [gray]
}
CDN -> ALB : https
CloudWatchFour levels of nesting, five services, and two edges that cross container walls — from nine lines of text and no coordinates anywhere.
Two things worth noticing. The metrics edge is declared at cloud level but starts at a node buried two containers deep — names are global, so you never have to restructure the file to draw an edge. And nothing in the source says where anything goes; move a service between subnets by cutting one line, and the layout re-solves itself.
Edit either side. The text stays the source of truth.
Drag a node, draw an edge, double-click to rename — with Sync edits to text on (the default), the left pane rewrites itself so you can copy the result back into your repo. Export gives you exactly the frame you see.
Drag to fine-tune
Nodes snap to the grid and their arrows re-route live. Press L to lock the layout so panning can't move anything; ⌘/Ctrl + Z undoes.
Draw edges by hand
Hover a node and pull from its dot to another node; the matching arrow line appears in the source.
Double-click to rename
Double-click or right-click a label (or press F2) to rename, or an icon (i) to swap it. Renames propagate to every arrow referencing that node.
PNG export
Exports exactly the frame you see — theme-aware, no watermark. Select and press Backspace to delete anything first.
Everything the studio responds to.
None of these are required — you can do all of it with the buttons on screen. They are here because nobody guesses that L locks the canvas.
- ⌘ / Ctrl + Enter
- Draw the diagram from whatever is in the text box
- ⌘ / Ctrl + Z
- Undo the last change
- Double-click a name
- Rename that box
- F2
- Same as double-clicking — rename the selected box
- i
- Change the icon on the selected box
- Backspace
- Delete whatever is selected
- L
- Lock the layout so dragging the canvas cannot move things
- Shift + click
- Select several boxes, which reveals the align tools
- Drag from a box's dot
- Draw a new arrow to another box
Every word on this page, explained.
Cloud documentation is full of acronyms that everybody pretends to know. Here is what each one actually means, in ordinary language. You do not need any of it to draw a diagram — it is here for when you meet the words elsewhere.
- Box (node)
- One thing in your system — a website, a database, a person. Anything you name becomes one.
- Arrow (edge)
- A line between two boxes meaning "this talks to that". The arrowhead shows which direction.
- Group / container
- A box drawn around other boxes, to show they belong together or run in the same place.
- Cloud
- A company that rents you computers over the internet. The big three are Amazon (AWS), Microsoft (Azure) and Google (GCP).
- Region
- Which part of the world those rented computers physically sit in — for example London or Virginia.
- VPC
- Virtual Private Cloud. A fenced-off private network inside your cloud account, so your things can talk to each other but not to strangers.
- Subnet
- A smaller fenced area inside a VPC. Usually one for things the public may reach, one for things only you may reach.
- Load balancer
- Stands in front of several identical servers and spreads incoming visitors across them, so no single one is overwhelmed.
- CDN
- Content Delivery Network. Keeps copies of your images and pages in many countries so they load quickly wherever the visitor is.
- Cache
- A small, very fast store of recent answers, so the slow thing behind it gets asked less often.
- Queue
- A waiting line for jobs. Work is dropped in at one end and picked up later at the other, so nothing is lost at busy times.
- Icon nickname
- The short word in brackets, like (postgres). It is how you tell Lumagram which logo to put on a box.
- Syntax
- The rules for how you write the lines. Lumagram understands three sets of rules and works out which you are using.
- Layout engine
- The part that decides where every box goes and how the arrows bend, so you never position anything by hand. Ours is called ELK.
- PNG
- A picture file. The kind you can drop into a document, a slide deck or a chat message.
If something looks wrong, it is probably one of these.
- Do I need to know what any of these services are?
- No. Type ordinary words — Website, Database, Payments — and you get labelled boxes. The service nicknames in brackets only change which logo appears; the diagram works perfectly well without any of them.
- Nothing happened when I typed
- The picture is drawn when you ask for it, not as you type. Press Generate diagram, or ⌘/Ctrl + Enter.
- My icon didn't appear
- The nickname matched nothing, so the box kept a generic icon and a warning names the miss. Try the short, common name — ec2, alb, postgres — rather than a full product title. Or pick one by hand: double-click the icon and search.
- A word I used turned into a box by mistake
- Every name in an arrow line becomes a box, so a stray word makes a stray box. Delete the word, or start the line with # to turn it into a note the compiler ignores.
- Everything moved when I pressed Generate
- Generate re-runs the automatic layout, so anything you dragged by hand is recalculated. Do your hand-tidying last — or press L to lock the layout, and ⌘/Ctrl + Z to undo.
- My Mermaid file came out flat
- Only subgraph blocks become containers. Mermaid has no concept of a VPC, so add native vpc or subnet blocks after importing.
- The exported image is cut off
- Export captures the canvas exactly as shown. Press Fit view first so the whole diagram is in frame — or zoom into one area deliberately for a close-up.
- Is my diagram sent anywhere?
- No. Everything runs in your browser and your draft is saved in this browser only. Nothing is uploaded, and there is no account to create.
- How do I share it with someone?
- Download the PNG and send that, or copy the text of your diagram — the text is the whole thing, so anyone who pastes it into the studio sees exactly what you see.
Ask us. A person will answer.
If something here didn't make sense, if a diagram won't come out the way you pictured it, or if you just want to tell us what you think — write to us. Questions from people who don't consider themselves technical are especially welcome; they are usually the ones that show us where the documentation is wrong.
Support, questions, bug reports, feature requests, reviews and general inquiries all go to the same place.