Open source · MIT · v0.8.0
Architecture diagrams drawn to each vendor's own rules.
Write a short YAML spec. orrery lays it out with ELK, draws it with the official AWS, Azure, Google Cloud, Kubernetes, GitHub and IBM icons, and renders animated SVG, PNG, editable draw.io, React and HTML.
- official icons
- 18,209
- official icons
- icon packs
- 10
- icon packs
- reference diagrams
- 40
- reference diagrams
- output formats
- 5
- output formats
Install
One skill, every agent.
The CLI, the layout engine, the PNG renderer, the fonts and the four cloud packs ship inside the skill, so it runs with no install step. Pick the place you work.
Claude Code plugin
The skill, three reviewer agents and the /orrery:review loop.
> /plugin marketplace add Sagargupta16/orrery> /plugin install orrery@orreryAny Agent Skills client
Codex, Cursor, Kiro, Copilot and the rest of the skills CLI's agents.
$ npx skills add Sagargupta16/orreryGitHub CLI
Installs from the latest release into the agent you pick.
$ gh skill install Sagargupta16/orrery orreryGemini CLI
An extension that loads the orrery skill.
$ gemini extensions install https://github.com/Sagargupta16/orreryJust the CLI, from npm
No clone, no agent. Node.js 22 or newer.
$ npx @sagargupta1610/orrery render diagram.yaml -f all --theme bothFrom spec to picture
The YAML is the whole input.
# yaml-language-server: $schema=../references/diagram.schema.json
# Starter template: rename the nodes, keep the shape. Render with `orrery render diagram.yaml`.
title: Web app on AWS
subtitle: A container service behind a load balancer, with a database, a cache and file storage
direction: right
# A little extra spacing keeps the line to the bucket clear of the VPC border.
layout: { spacing: 1.15 }
groups:
aws: { type: aws:cloud }
region: { type: aws:region, in: aws }
vpc: { type: aws:vpc, in: region }
nodes:
users: { icon: aws:users, label: Users }
alb: { icon: aws:alb, label: Application Load Balancer, in: vpc }
app: { icon: aws:fargate, label: Web service, note: Amazon ECS on AWS Fargate, badge: x3, in: vpc }
db: { icon: aws:aurora, label: Orders database, note: Amazon Aurora PostgreSQL, in: vpc }
cache: { icon: aws:elasticache, label: Session cache, note: Amazon ElastiCache for Valkey, in: vpc }
files: { icon: aws:s3, label: Uploads, note: Amazon Simple Storage Service, in: region }
edges:
- users -> alb: HTTPS
- alb -> app
# Label all sibling edges or none: a labeled edge takes one extra column.
- app -> db, cache, filesSVG
Animated by default: one story plays along the edges, numbered steps in order.
PNG
A still frame at 2x for slides and docs that strip SVG.
draw.io
Every node, group and edge stays editable in diagrams.net.
React TSX
A typed component with ids made unique through useId().
HTML viewer
One file with both themes, zoom and PNG and SVG export.
How it works
Five steps, all of them checkable.
- 01
Write the spec
Nodes with official icon ids, nested groups, labelled edges. Or let your agent write it.
- 02
Validate
Spec errors stop the render, layout warnings do not; every diagnostic carries its fix.
- 03
Lay out
ELK places nested boundaries, routes edges at right angles and keeps the order you wrote.
- 04
Render
Animated SVG, a still PNG, editable draw.io, a React component and an HTML viewer.
- 05
Review
Measured at the width people see it, then judged against each vendor's own rules.
What you get
Correct first, then beautiful.
Official icons, current releases
The cloud packs are rebuilt from each vendor's own download and pinned by SHA-256; the logo and glyph sets load from their npm libraries. Renovate's monthly pull request moves all of them to the newest release.
Each vendor's conventions
AWS groups follow the Architecture Icons deck, Google Cloud frames are measured from Google's own diagrams, Azure uses filled arrowheads, and C4 views use C4 notation. Every value cites its source.
Validation with the fix
A typo in an icon id comes back with the id you meant.
$ orrery validate orders.yaml
error DG101 node "fn" uses unknown icon "aws:lamda"
fix: use icon "aws:lambda"
fix: run `orrery icons search lamda`
error DG108 unknown key "lable" in node "db"
fix: rename "lable" to "label"
failed: 2 error(s), 0 warning(s)A review board that measures before it judges
orrery review scores six dimensions at the width readers see the diagram. In Claude Code, /orrery:review adds three reviewer agents for vendor conventions, the story the arrows tell, and legibility, and keeps a patch only when the score rises.
$ orrery review gitops-0.2.yaml --width 880
review gitops-0.2: 1964x786 in a 880px column
score 85.3/100 FAIL
blocker quality.label-size node labels render
at 5.82px at this width
fix: use direction: downAnimated by default
animate: packets sends a packet along every edge, flow moves the dashes, none keeps it still. GitHub keeps the motion in README images.
Fits where the diagram goes
Light and dark renders from one spec, a legend for every line style you use, warnings when a diagram is too wide to read in a README column, and byte-identical output for the same spec, so diffs stay clean.
Gallery
Every kind of diagram.
GitOps delivery with Argo CD
GitOps with Argo CD: a pull request runs GitHub Actions, which pushes the image to ghcr.io and bumps its tag in the config repository; Argo CD syncs the staging cluster automatically and production on a manual sync, with Prometheus and Grafana monitoring production.
AI coding agent on the Model Context Protocol
an AI coding agent on the Model Context Protocol: the MCP host runs one MCP client per server, stdio to a local filesystem server, Streamable HTTP with OAuth to remote GitHub and Postgres servers, Claude choosing each tool, and OTLP traces to Grafana Cloud.
Three-tier web application on AWS
a VPC across two Availability Zones with public, web and data subnets, NAT gateways, an ALB, and one Auto Scaling group drawn across both zones with `around:`; zone B writes to the primary database in zone A.
Hub-spoke network on Azure
a hub-spoke network on Azure: on-premises reaches the hub's ExpressRoute and VPN gateways and Azure Firewall, which forwards over the peerings to the spokes, with Bastion in the hub, AKS in one spoke and VMs with a private endpoint to Azure SQL in the other, Private DNS and Log Analytics.
GKE application platform on Google Cloud
a GKE platform in Google Cloud's frames (cloud, project, region, cluster): Cloud Build pushes each image to Artifact Registry and releases it through Cloud Deploy to two namespaces, next to Memorystore, Secret Manager and Cloud SQL, with Cloud Logging and Cloud Monitoring.
Web application on Red Hat OpenShift on IBM Cloud
IBM Cloud Internet Services in front of a static site in Cloud Object Storage and a three-zone Red Hat OpenShift cluster, with App ID and services reached through Virtual Private Endpoints.
Icon packs
18,209 icons in 10 packs.
Search them from the CLI with orrery icons search load balancer, or use one of 482 short names such as aws:sqs or k8s:deploy.
| Pack | Source | Icons | Version | Ships |
|---|---|---|---|---|
| aws | AWS Architecture Icons | 810 | 2026-07-31 | bundled |
| azure | Azure Architecture Icons | 636 | V24 | bundled |
| gcp | Google Cloud Icons | 233 | May 2026 icon guide | bundled |
| k8s | Kubernetes Icons | 40 | kubernetes/community@70a4bb2 | bundled |
| github | GitHub Octicons | 399 | @primer/octicons 19.40.0 | npm @primer/octicons |
| ibm | IBM Carbon icons | 2,776 | @iconify-json/carbon 1.2.28 (Carbon 11.89.0) | npm @iconify-json/carbon |
| logos | SVG Logos (gilbarbara/logos) | 2,151 | @iconify-json/logos 1.2.16 | npm @iconify-json/logos |
| si | Simple Icons | 3,351 | simple-icons 16.35.0 | npm @iconify-json/simple-icons |
| tabler | Tabler Icons | 6,286 | @iconify-json/tabler 1.2.42 (Tabler Icons 3.49.0) | npm @iconify-json/tabler |
| ph | Phosphor Icons | 1,527 | @iconify-json/ph 1.2.2 (Phosphor 2.1.1) | npm @iconify-json/ph |
Ask your agent for a diagram.
"Draw the architecture of this repo." "A three-tier web app on AWS across two Availability Zones." "Turn this Mermaid flowchart into a Google Cloud diagram."