Cheat sheets

Diagram, Chart and Infrastructure Explainers

Four local explainer projects. Run them, feed them, read their outputs and fix their errors.

  • Concepts and terms
  • Tasks and commands
  • Annotated code
  • Diagrams
  • Comparisons
  • Defaults and numbers
  • Troubleshooting
  • Questions and tips

Source

Four projects side by side#

FactorChart Storyboard BuilderDiagram Reading CompanionInfrastructure Plan ExplainerService Ownership Navigator
LanguagePython 3.10+Node 22.18 or newerPython 3.10+Node 22.18 or newer
Inputcsv, roles, periods, chartssvg, graphTerraform plan JSONcatalog, path
Outputschart-N.svg, chart-specs.json, storyboard.htmlgraph.json, analysis.json, report.htmlchange-brief.md, resource-impact.json, review.htmlhandoff.json, catalog.json, report.html
Review filenonethird argument, reviewed ordernonenone
Never doesInfer dates or causationRead meaning from SVG geometryApply a planSend notifications

From chart-storyboard-builder/README.md, solution/cli.py, diagram-reading-companion/README.md, solution/cli.ts, infrastructure-plan-explainer/README.md, solution/cli.py, service-ownership-navigator/README.md, solution/cli.ts

Run the reference#

CommandWhat it does
python3 cli.py samples/input.json --output demo-outputChart or infrastructure sample
node cli.ts sample.json outputDiagram or ownership sample
node cli.ts <input.json> <dir> <review.json>Diagram with your reviewed order
node cli.ts --helpPrints the argument line
python3 scripts/project_test.py <project> --all --solution --strictGrades the reference
python3 scripts/project_test.py <project> --init <dir>Makes a starter

From chart-storyboard-builder/README.md, infrastructure-plan-explainer/README.md, diagram-reading-companion/README.md, service-ownership-navigator/README.md, solution/cli.ts

Explain a real Terraform plan#

terraform show -json saved.plan > input.jsonsaved plan as JSON
python3 cli.py input.json --output reviewnever applies the plan
review/change-brief.md addresses with local anchors
review/resource-impact.json graph.edges and resources
review/review.html changes, edges, unresolved

From infrastructure-plan-explainer/README.md, solution/cli.py

Plan explainer pipeline#

1load_planaccepts only format major 1. It keeps actionsand masked before and after.2load_planshows sensitive values as [sensitive] andcomputed values as [unknown].3classifymaps each exact action sequence to one actionname.4impact_graphlinks references and depends_on by the longestaddress prefix.5impact_graphskips var, local, path, count, each, terraformand self.6explainwrites Markdown with one anchor per address andthe declared dependencies.

From infrastructure-plan-explainer/API.md, solution/main.py

Action sequences#

CommandWhat it does
["create"]create
["update"]update, in place
["delete", "create"]replace
["create", "delete"]replace
["delete"]delete
["read"], ["no-op"], ["forget"]read, no-op, forget
any other listunsupported action sequence

From solution/main.py, infrastructure-plan-explainer/API.md

Diagram companion#

svg, graphgraphordersaverenderclientsample.jsonsvg, graphprocessloadDiagram()node ids must be SVG idsprocessanalyzeGraph()order, branches, cyclesprocessreviewGraph()order, reviewedstoregraph.jsonreviewed manifeststorereport.htmlkeyboard walkthroughsvg, graphgraphordersaverenderclientsample.jsonsvg, graphprocessloadDiagram()node ids must be SVGidsprocessanalyzeGraph()order, branches,cyclesprocessreviewGraph()order, reviewedstoregraph.jsonreviewed manifeststorereport.htmlkeyboard walkthrough

From solution/main.ts, solution/cli.ts

Chart rules#

roles
group, value and unit name CSV columns and a display unit.
Reducers
sum, mean and count. Count uses nonblank values, unit records.
Grammar
bar for categories, line for ordered periods.
Blank value
it is missing, not zero. A line breaks there.
periods
set the order. An absent period plots as null.
Axis
always includes zero.
Annotation
needs a plotted point. The text gets the exact value and unit.

From chart-storyboard-builder/API.md, solution/main.py, chart-storyboard-builder/README.md

Ownership rules#

Last match wins
the last matching rule sets the effective owners.
Anchored
a pattern that starts with / or holds a / matches from the root.
Wildcards
* stays in one segment, **/ spans folders, ? is one character.
Directory
a trailing / matches the folder and all below it.
Service
the longest service root that holds the path.
Owners
@user or @org/team names only.
Runbook links
local links must point to a supplied runbook file.

From solution/main.ts, service-ownership-navigator/README.md

Defaults and limits#

SettingDefaultNote
reducersumPer chart in charts
grammarbarOr line
schema_version1Chart specs and plan brief
SVG size500000Characters at most
Rule sourceCODEOWNERSName in the evidence rows
Output folderoutputSecond argument of the Node CLIs
Chart width640Minimum SVG width in pixels

From solution/main.py, solution/cli.py, solution/main.ts, solution/main.ts, solution/cli.ts, solution/main.py

Error messages and fixes#

SymptomCauseFix
unsupported Terraform JSON format majorNot a terraform show -json fileExport the saved plan as JSON
periods omit data or duplicate a groupA data group is not in periodsList every group once
annotation needs a unique plotted pointNote on a blank or unknown groupAnnotate a point with a value
Node missing from SVG or duplicatedManifest id has no SVG idAdd the id to the SVG element
Unsupported SVG elementTag outside the safe subsetUse shapes, text, g, title, desc
Review order must contain every node exactly onceOld or partial orderList each node id one time
Earlier matching rules name different owners; last matching rule winsRules overlapCheck the last rule is right
Missing local runbook linkRunbook links a file not suppliedAdd the file to runbooks

From solution/main.py, solution/main.py, solution/main.ts, solution/main.ts

Worked examples#

What does W1 plot with sum?
18. Its rows hold 8 and 10.
What happens to W2 and W3?
W2 is blank and W3 is absent. Both plot as missing.
Why is the database a replace?
Its actions are delete then create.
What does the brief show for the password?
[sensitive], also inside arrays.
Who owns services/images/cache/store.ts?
@fictional/cache, from the last rule.
Where does the diagram branch?
At check, to share and clarify.

From samples/input.json, chart-storyboard-builder/README.md, samples/input.json, infrastructure-plan-explainer/README.md, solution/sample.json, solution/sample.json

Tips#

  • Graph edges are declared dependencies, not the provider execution order.
  • The plan tool does not predict outage time, cost or full execution order.
  • A reading order is a candidate for review, not a proof of pedagogy.
  • Chart SVGs carry title and desc and no JavaScript.
  • The ownership format is a local subset, not the full CODEOWNERS format.

From infrastructure-plan-explainer/README.md, infrastructure-plan-explainer/API.md, diagram-reading-companion/README.md, chart-storyboard-builder/API.md, service-ownership-navigator/README.md