Skip to content

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
GitOps delivery to three clouds: GitHub Actions builds and signs, Argo CD syncs GKE, AKS and EKS, Cloudflare fronts them and Grafana watches
This diagram is 40 lines of YAML, drawn in the stage skin. Every SVG is animated by default.docs/hero.yaml

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@orrery

Any Agent Skills client

Codex, Cursor, Kiro, Copilot and the rest of the skills CLI's agents.

$ npx skills add Sagargupta16/orrery

GitHub CLI

Installs from the latest release into the agent you pick.

$ gh skill install Sagargupta16/orrery orrery

Gemini CLI

An extension that loads the orrery skill.

$ gemini extensions install https://github.com/Sagargupta16/orrery

Just the CLI, from npm

No clone, no agent. Node.js 22 or newer.

$ npx @sagargupta1610/orrery render diagram.yaml -f all --theme both

From spec to picture

The YAML is the whole input.

starter.yaml6 nodes
# 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, files
Web app on AWS: users, an Application Load Balancer and an ECS service with a database and a cache in a VPC, and an S3 bucket in the Region
orrery render starter.yaml -f all --theme both

How it works

Five steps, all of them checkable.

  1. 01

    Write the spec

    Nodes with official icon ids, nested groups, labelled edges. Or let your agent write it.

  2. 02

    Validate

    Spec errors stop the render, layout warnings do not; every diagnostic carries its fix.

  3. 03

    Lay out

    ELK places nested boundaries, routes edges at right angles and keeps the order you wrote.

  4. 04

    Render

    Animated SVG, a still PNG, editable draw.io, a React component and an HTML viewer.

  5. 05

    Review

    Measured at the width people see it, then judged against each vendor's own rules.

A YAML spec is validated, laid out by ELK, checked and rendered with the icon packs to SVG, PNG, draw.io, TSX and HTML

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.

aws 810azure 636gcp 233k8s 40github 399ibm 2,776logos 2,151si 3,351tabler 6,286ph 1,527

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: down

Animated 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 on Kubernetes: GitHub Actions, ghcr.io, a config repository and Argo CD syncing staging and production clustersGitOps on Kubernetes: GitHub Actions, ghcr.io, a config repository and Argo CD syncing staging and production clustersGitOps on Kubernetes: GitHub Actions, ghcr.io, a config repository and Argo CD syncing staging and production clustersGitOps on Kubernetes: GitHub Actions, ghcr.io, a config repository and Argo CD syncing staging and production clusters

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.

githubk8slogos16 nodes
AI coding agent on the Model Context Protocol: a developer prompts the agent loop in the MCP host, which asks Claude and calls tools through three MCP clients over stdio and Streamable HTTPAI coding agent on the Model Context Protocol: a developer prompts the agent loop in the MCP host, which asks Claude and calls tools through three MCP clients over stdio and Streamable HTTPAI coding agent on the Model Context Protocol: a developer prompts the agent loop in the MCP host, which asks Claude and calls tools through three MCP clients over stdio and Streamable HTTPAI coding agent on the Model Context Protocol: a developer prompts the agent loop in the MCP host, which asks Claude and calls tools through three MCP clients over stdio and Streamable HTTP

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.

logostabler15 nodes
Three-tier web application on AWS across two Availability ZonesThree-tier web application on AWS across two Availability ZonesThree-tier web application on AWS across two Availability ZonesThree-tier web application on AWS across two Availability Zones

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.

aws11 nodes
Hub-spoke network on Azure with ExpressRoute, a VPN backup, Azure Firewall, Bastion and two peered spokesHub-spoke network on Azure with ExpressRoute, a VPN backup, Azure Firewall, Bastion and two peered spokesHub-spoke network on Azure with ExpressRoute, a VPN backup, Azure Firewall, Bastion and two peered spokesHub-spoke network on Azure with ExpressRoute, a VPN backup, Azure Firewall, Bastion and two peered spokes

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.

azure13 nodes
GKE application platform on Google Cloud with Cloud Build, Artifact Registry, Cloud Deploy, Memorystore, Secret Manager and Cloud SQLGKE application platform on Google Cloud with Cloud Build, Artifact Registry, Cloud Deploy, Memorystore, Secret Manager and Cloud SQLGKE application platform on Google Cloud with Cloud Build, Artifact Registry, Cloud Deploy, Memorystore, Secret Manager and Cloud SQLGKE application platform on Google Cloud with Cloud Build, Artifact Registry, Cloud Deploy, Memorystore, Secret Manager and Cloud SQL

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.

gcpk8slogos12 nodes
Web application on Red Hat OpenShift on IBM Cloud across three zones in a VPCWeb application on Red Hat OpenShift on IBM Cloud across three zones in a VPCWeb application on Red Hat OpenShift on IBM Cloud across three zones in a VPCWeb application on Red Hat OpenShift on IBM Cloud across three zones in a VPC

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.

ibm20 nodes

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.

PackSourceIconsVersionShips
awsAWS Architecture Icons8102026-07-31bundled
azureAzure Architecture Icons636V24bundled
gcpGoogle Cloud Icons233May 2026 icon guidebundled
k8sKubernetes Icons40kubernetes/community@70a4bb2bundled
githubGitHub Octicons399@primer/octicons 19.40.0npm @primer/octicons
ibmIBM Carbon icons2,776@iconify-json/carbon 1.2.28 (Carbon 11.89.0)npm @iconify-json/carbon
logosSVG Logos (gilbarbara/logos)2,151@iconify-json/logos 1.2.16npm @iconify-json/logos
siSimple Icons3,351simple-icons 16.35.0npm @iconify-json/simple-icons
tablerTabler Icons6,286@iconify-json/tabler 1.2.42 (Tabler Icons 3.49.0)npm @iconify-json/tabler
phPhosphor Icons1,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."