Orrery

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](https://sagargupta.online/orrery/): every example in light and dark, with its spec and downloads.

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 main path in order, lighting each line behind it, 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,300 icons: AWS (810), Azure (636), Google Cloud (233), Kubernetes (40), GitHub Octicons (408) and IBM Carbon (2,783), plus 5,558 tech logos, 6,305 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.
• Data models, sequences and roadmaps. kind: er draws tables with typed, keyed rows and crow's foot relationships that meet the rows they join, and orrery import sql starts one from your CREATE TABLE statements. kind: sequence draws a call flow message by message, with replies dashed, activation bars and loop or alt fragments, played in order. kind: timeline draws a roadmap by month, quarter or year: lanes, status-styled bars, milestones, dependency arrows and a today marker.
• Automatic layout you can steer. 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; when you want a say, rank: first, align: , cols: 2 on a group and layout: { aspect: 4:3 } pin a node's place in the flow, line nodes up, grid a group's children and keep a figure compact enough to read in a README.
• One spec, many figures. views: draws an overview and its details from one source (render --view all), so they cannot drift apart; classes: share presets, include: pulls in a frame every figure shares, and tags: color and restyle what they mark, with a legend row each.
• Diagrams that stay true to the code. orrery import starts a spec from Terraform, CloudFormation or CDK output, Docker Compose, Kubernetes manifests or Mermaid, with every node's evidence: (the file, line and identifier it came from). orrery verify fails when a piece of evidence no longer exists, and --link makes each node a commit-pinned link to its code. orrery diff shows what changed between two versions as a colored picture, and the GitHub Action posts it, with the review, on every pull request.
• Diagrams that move. Animated SVG by default: packets travel every edge at one speed, the main path plays 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 each icon in a muted share of its own vendor color, 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.
• Eight 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, .drawio.svg (one file that shows as an image anywhere and opens as an editable diagram in draw.io), a TSX component for React sites, a standalone HTML viewer with dark mode, pan and pinch zoom, Mermaid text for wikis that draw only Mermaid, and a sequence diagram of the main path. Every SVG and PNG carries its own spec, so orrery import picture turns a picture back into an editable diagram. orrery doc puts the figures into a design document as HTML, Markdown or Word.
• 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, a validator whose every finding names the subject and the fix, an MCP server for clients without skills, and agents that plan a diagram from your code and check it against it.
• 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.

As an MCP server, for any client that speaks the Model Context Protocol (tools: authoring guide, validate, render, review, icon search, templates, patch candidates, draw.io link):

{ "mcpServers": { "orrery": { "command": "npx", "args": ["-y", "@sagargupta1610/orrery", "mcp"] } } }

That block goes in .mcp.json for Claude Code, ~/.gemini/settings.json for Gemini CLI, .cursor/mcp.json for Cursor and .kiro/settings/mcp.json for Kiro; Codex takes [mcp_servers.orrery] with command = "npx" and args = ["-y", "@sagargupta1610/orrery", "mcp"] in ~/.codex/config.toml. orrery mcp install writes that entry for you (claude-code, claude-desktop, cursor, vscode, gemini, codex or kiro, in the project or with user for every project), keeping every other server in the file. Each release publishes the server to the MCP Registry as io.github.Sagargupta16/orrery and attaches an .mcpb bundle for one-click install in Claude Desktop. In hosts that support MCP Apps, a rendered diagram opens in an inline viewer. orrery mcp --port 8765 serves the same tools over HTTP on 127.0.0.1, where specs are passed as text and nothing is read from or written to disk.

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 77 reference diagrams across AWS (from agents on Bedrock AgentCore to disaster recovery, threat detection, network inspection, migration and contact centers), 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](https://sagargupta.online/orrery/gallery/), or in examples/README.md with the command that renders each one. orrery init 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 diag