orrery

Animated architecture and system design diagrams with official AWS, Azure, Google Cloud, Kubernetes, GitHub and IBM icons. One YAML spec in; SVG, PNG, editable draw.io, a React component and an HTML viewer out. sagargupta.online/orrery: every example in light and dark, with its spec and downloads.

imageCI imageVersion imageIcons imageLicense

The diagram above is docs/hero.yaml: 40 lines of YAML, laid out and rendered by orrery in its default stage skin: the groups light, then the tiles, then a packet with a comet tail runs the numbered steps in order, lighting each line behind it, and every step badge pops as its packet leaves, on a loop. Every picture in this README is the stage skin; skin: classic (or --skin classic) draws the same layout in each vendor's own diagram style, with a packet along every edge. GitHub keeps the animation; the PNG of the same spec is a still frame.

What you get

• Official, current icons only. 18,209 icons: AWS (810), Azure (636), Google Cloud (233), Kubernetes (40), GitHub Octicons (399) and IBM Carbon (2,776), plus 5,502 tech logos, 6,286 neutral symbols and Phosphor (1,527) in six weights for system design and business flows; your own SVGs work too, as local: icons drawn and checked with orrery icons new and icons check. The cloud packs are rebuilt from each vendor's own download, pinned by checksum. Google Cloud products get the icon Google's 2026 guide assigns them; deprecated sets and unofficial redraws of cloud icons are left out.
• Official conventions. AWS groups follow the AWS Architecture Icons deck (borders, dashes, corner tiles, label placement, open arrowheads, numbered callouts); Google Cloud and Azure groups are measured from their own reference diagrams. Every value cites its source in styles.md.
• Business flows too. kind: turns the same spec into an ISO 5807 flowchart, a BPMN 2.0 process with pools, lanes and message flows, a UML state machine, an org chart, a two-sided mind map or a customer journey map with an emotion curve. In the stage skin a process plays as a BPMN token: it splits at parallel gateways, waits at the join and follows the yes branch.
• Automatic layout. The Eclipse Layout Kernel places nested boundaries, routes edges at right angles, joins fan-in and fan-out into trunks and keeps the order you wrote unless that would cross edges. No coordinates to write.
• Diagrams that move. Animated SVG by default: packets travel every edge at one speed, numbered steps play as a story, line styles stay as drawn. animate: flow for marching dashes, --static for a still file.
• Two skins, one layout. The default stage skin draws every diagram as an animated scene, dark by default: a hairline grid with one tint, ink tiles with monochrome icons, mono caps labels, dim wires and one story that plays along them. skin: classic (or --skin classic) follows each vendor's own diagram style instead, for docs that must match the AWS, Azure or Google Cloud deck. Every position stays the same; dark and light.
• Five outputs from one spec. SVG for READMEs and docs, PNG for slides and chat (3x by default, sharp when zoomed), .drawio you can keep editing, a TSX component for React sites, and a standalone HTML viewer with dark mode, pan and pinch zoom.
• Made for agents. A skill with a fast path and authoring rules, a JSON Schema, 482 short aliases (aws:s3, azure:aks, k8s:deploy, and business names such as generic:invoice and generic:approval), ranked icon search, and a validator whose every finding names the subject and the fix.
• No install. The CLI, layout engine, PNG renderer, fonts and the official cloud packs ship in the skill folder (9 MB). Logo and glyph sets are not copied in: they load from their own npm libraries the first time a diagram uses them, verified by checksum and cached. Node.js 22 or newer is all it needs.

How it works

Install

Claude Code plugin:

/plugin marketplace add Sagargupta16/orrery
/plugin install orrery@orrery

Any agent that reads Agent Skills (Codex, Cursor, Gemini CLI, Kiro and others):

npx skills add Sagargupta16/orrery
gh skill install Sagargupta16/orrery orrery              # GitHub CLI, any supported agent
gemini extensions install https://github.com/Sagargupta16/orrery   # Gemini CLI extension

Only the CLI, from npm:

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

Or from a clone: node orrery/skills/orrery/scripts/orrery.mjs doctor.

Quick start

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"). It writes a spec, validates it, renders it and checks the picture. Or write one yourself:

title: Orders API
direction: right
groups:
  cloud:  { type: aws:cloud }
  region: { type: aws:region, label: eu-west-1, in: cloud }
nodes:
  users: { icon: aws:users, label: Customers }
  api:   { icon: aws:api-gateway, in: region }
  fn:    { icon: aws:lambda, label: Create order, in: region }
  table: { icon: aws:dynamodb, label: Orders, in: region }
edges:
  - users -> api: HTTPS
  - api -> fn -> table

node skills/orrery/scripts/orrery.mjs render orders.yaml -f svg,png

Labels default to the official service names, so { icon: aws:lambda } reads "AWS Lambda". Edges use arrows: -> solid, --> dashed, ..> dotted, ==> thick, <-> both ways, a -> b, c to fan out. The full format is in spec.md.

Examples

aws-three-tier: a VPC across two Availability Zones with public, web and data subnets and an Auto Scaling group drawn across both zones, in the AWS deck's own group styles.

That is one of 40 reference diagrams across AWS, Azure, Google Cloud, IBM Cloud, Kubernetes, AI and ML, data platforms, CI/CD, C4, system design and business flows (flowcharts, a BPMN process, swimlanes, a state machine, an org chart, a mind map and a customer journey), each rendered from a spec in skills/orrery/examples and checked against the renderer by CI. Browse them all in light and dark, with each spec and every output to download, at sagargupta.online/orrery/gallery, or in examples/README.md with the command that renders each one. orrery init <name> copies any of them as a starting point.

Validation that tells you the fix

$ orrery validate orders.yaml
error DG101 node "fn" uses unknown icon "aws:lamda" {"node":"fn","icon":"aws:lamda"}
      fix: use icon "aws:lambda"
      fix: run `orrery icons search lamda`
error DG108 unknown key "lable" in node "db" {"where":"node \"db\"","key":"lable"}
      fix: rename "lable" to "label"
failed: 2 error(s), 0 warning(s)

Spec errors (DG1xx) stop the render; composition warnings (DG2xx: an edge through a node, colliding labels, a diagram too wide to read) keep it going unless --strict is set. render --json writes every file atomically and prints a receipt with the size and SHA-256 of each output.

A review board that measures before it judges

orrery review looks at the diagram at the width readers see it (880 px for a README column) and scores six dimensions: official conventions, layout, grid, arrows and flow, overlap, and size and quality.

$ git show v0.2.1:skills/orrery/examples/gitops-kubernetes.yaml > gitops-0.2.yaml
$ orrery review gitops-0.2.yaml --width 880
review gitops-0.2: 1964x786 in a 880px column, seen at 880x352 (scale 0.45, light)
score 85.3/100  FAIL (pass = no blocker or major and score >= 85)
...
blocker quality.label-size node labels render at 5.82px at this width (1964px canvas shown at 0.45x)
        fix: use direction: down so the diagram is narrower

The review loop took that diagram to 98.5 and passing: it now runs top to bottom, so its labels show at full size in the README column.

In Claude Code, /orrery:review <spec> runs the full loop. Code measures everything that can be counted: overlaps, crossings, alignment, text size and contrast at display width. Three read-only agents run in parallel and judge what cannot be counted:

• conventions-reviewer checks the vendor's own rules, quoted from the AWS deck, Azure Well-Architected, Google's icon guide and the C4 notation.
• flow-reviewer checks the story the arrows tell.
• legibility-reviewer reads the PNG at display size.

A finding counts only if it cites a measured value or a vendor rule. Each round applies one to three spec patches, and a round is kept only when the score goes up and no hard count does; the loop stops after three rounds or two without progress. Vision models are weak at counting overlaps and intersections, so they never decide those. The rubrics live in references/review, so the same passes run inline anywhere the skill is installed without subagents.

Commands

Icon packs

Bundled packs exist only as vendor downloads, so they ship with the skill and work offline. The npm sets load at render time from a local node_modules, the user cache or jsDelivr, checked against a pinned SHA-256; orrery icons fetch caches them ahead of time, and icons.md has the details. Renovate's monthly dependency PR also checks the vendors' pages for new releases and carries the updated packs. Icons, logos and trademarks belong to their owners and are used under the terms listed in THIRD_PARTY_NOTICES.md; the AWS, Microsoft and Google terms allow them in architecture diagrams.

Community

Made a diagram with orrery? Share it in Show and tell. Questions go to Q&A, and requests for icons, examples, outputs or styles to Ideas. Found a bug? Open an issue. If orrery saved you a diagram, a star helps other people find it.

Development

pnpm install
pnpm lint
pnpm typecheck
pnpm test
pnpm build                       # src/ -> skills/orrery/scripts/orrery.mjs
pnpm gallery                     # re-render examples/ and docs/
node scripts/check-repo.mjs      # dashes, links, counts, doc snippets, gallery freshness
pnpm sync-icons                  # rebuild icon catalogs (--latest re-pins new vendor releases)
node scripts/pack-npm.mjs        # stage the npm package in out/npm (a GitHub release publishes it)

See CONTRIBUTING.md for how the pieces fit and SECURITY.md for reporting issues.

License

Code and docs: MIT. Icons, fonts and the vendored engines keep their own licenses: THIRD_PARTY_NOTICES.md.