How I Execute Diagrams As Code
2025-10-07
Very Brief Overview
I refuse to build a diagram editor, on the assumption that there’s something off-the-shelf that is “good enough” and someone probably spent more time on it than I’m willing to spend
So, I look for existing diagram editors that save diagrams out in a form that can be parsed, e.g. graphML, SVG, etc.
draw.io is what I currently use, I did use yEd at one time, I imagine that Excalidraw would work but haven’t pursued it
I pick and choose a small syntax from available figures in the chosen editor
akin to what was done with picking a few bits of English for creating text programming languages, e.g. “if”, “then”, “else”, “define”, “defer”, etc.
with draw.io:
rectangles with “container” flag set == Parts
rectangles without “container” flag == ports
arrows that begin at ports and end at ports
rhombuses == “gates” (top-level ports on the diagram)
Ignore everything else, everything else is a “comment”
I’m comfortable with electronics schematics, so node-and-wire seems natural to me
use an XML parser library, or, OhmJS to parse and reduce the .drawio file to JSON that contains only semantically interesting stuff (plethora of graphical information is discarded, retain rectangles and connection info)
App == main.py + Leaf parts written in python code + kernel0d.py ...
inhales JSON and creates a dictionary of Parts
2 kinds of Parts:
recursive Container Parts,
raw code Leaf Parts
Kernel loads the system by recursive instantiation of Parts,
main.py execs the app, i.e. runs the diagram+Leaves
this system allows fan-out (output from one port goes to more than one port), so debugging the code becomes easier-than/different-from debugging function-based code - more like using a voltmeter to tap into parts of the system
edit/transmogrify/load/run cycle is fast enough to allow probing various parts of the data flows in arrows (wires) without too much ceremony - I find this to be simpler and more effective than single-stepping text code
simple examples of this: arith and helloworld (https://github.com/guitarvydas/arith and https://github.com/guitarvydas/pbp-dev/tree/main/examples/helloworld resp. (examine pbp-dev repo for other tools and examples))
not-so-simple example: the kernel itself is written as a diagram that invokes OhmJS parts (https://github.com/guitarvydas/pbp-dev/tree/main/kernel) and creates kernel0d in 3 languages (Python, node JS, Common Lisp)
See Also
Email: ptcomputingsimplicity@gmail.com
Substack: paultarvydas.substack.com
Videos: https://www.youtube.com/@programmingsimplicity2980
Discord: https://discord.gg/65YZUh6Jpq
Leanpub: [WIP] https://leanpub.com/u/paul-tarvydas
Twitter: @paul_tarvydas
Bluesky: @paultarvydas.bsky.social
Mastodon: @paultarvydas
(earlier) Blog: guitarvydas.github.io
References: https://guitarvydas.github.io/2024/01/06/References.html