As the saying goes, pictures paint a thousand words. This is definitely true when it comes to trying to understand, communicate and investigate complex software systems. A good design diagram is one that encompasses enough descriptive information without distracting its viewers with unnecessary detail. There's a delicate balance to take here and it's sometimes difficult to know upfront how much detail your target audience needs.

So, how can we improve diagrams? One approach is to take our static block diagrams and animate them, telling a story. Take a look at the content created by the Manim Community and the original's 3Blue1Brown videos. These videos are all generated from fragments of Python code, with the support of a large collection of community plugins.

While these videos are super impressive, and a big improvement over a single static diagram, they need to assume what their target audience is interested in understanding. One approach that tackles this issue is to present the viewer with an interactive mini-simulator. What better way to understand concepts and test scenarios than to provide a toy version of the real world system. This is what Bartosz Ciechanowski has done with his blog, each entry explains a core concept (mostly about physics) with a series of fully interactive mini-simulator toys.

Wouldn't it be great if system design and architecture diagrams were more like these examples. Bartosz's work is super impressive, but it's clear that each entry must have taken some time. Most teams don't have time to put a few rectangle blocks into a slide deck, so I'm not sure how feasible it would be to replicate their entire system behavior in the browser. But... large complex software systems are modular, and the core primary behavior can be simple enough. At least enough to warrant experimenting with the idea.

What is P5?

There are some great tools and libraries available to make this task easier. If I were to host interactive min-simulators, what would I need?

• This blog is created using NextJS, and is a mixture of server side rendered static content and client side components. Something hostable in NextJS as a React component.
• Articles and content are written using Markdown, so being able to embed these diagrams into the content would be great.
• Plus, naturally they would need to work on all devices.

So, there are a few widely used open-source tools and libraries that can help here: - The Manim tool stack above is written in Python, which then generates video files - that's useful, but not really interactive. Jazon Jiao started a JavaScript version of Manim called Manim.JS, he has some great videos on his channel generated from this code. That's great, but we need interaction rather than canned videos. But, the underlying technology for Manim.js does work in the browser - something called P5.js.

P5.js is part of the Processing Foundation, with the goal of teaching how to code, and a software "sketchbook". In fact, a Sketch is what P5 calls each interactive code 'applet'. More importantly, it has an active community and a huge amount of libraries, plus a React binding. Great!

Here's a quick demo, a slightly updated version of the Connected Particles tutorial.

Hosting P5 Sketches - Technical Notes

Most of the hard work has been done already by the P5.js community. There are a few gotchas, especially related to Markdown rendering, mobile, and NextJS hybrid client/server side rendering.

Embedding A Sketch in Markdown

There were plenty of possible solutions to this one. One obvious one was to use MDX (this allows any ad-hoc React component to be rendered inside Markdown), and then simply use the P5JS React wrapper. This was tempting, but hosting MDX has an impact on the entire tool chain (NextJS config for WebPack, TypeScript and ESLint). I opted for a simpler solution by using the Markdown Directive syntax.

Here's what it looks like in an .md document:

:P5Sketch{height=300px sketch="my-sketch"}

This feels more extensible than just hosting a React component, and opens the door to hosting more descriptive content when using the container syntax of a directive:

Maybe eventually we could attempt to render something like Mermaid graph format

:::P5Sketch{height=300 sketch="graph" }
A[Square Rect] -- Link text --> B((Circle))
A --> C(Round Rect)
B --> D{Rhombus}
C --> D
:::

Getting ReactMarkdown to process custom directives was fairly straight forward:

import directive from "remark-directive";
import { visit } from "unist-util-visit";
import { P5Sketch } from "@/client-components/Sketch";

function reactMarkdownRemarkDirective() {
    const nodeTypes = ["textDirective", "leafDirective", "containerDirective"];
    return (tree: Root) => {
        visit<Root, string[]>(tree, nodeTypes, (node: any) => {
            node.data = {
                hName: node.name,
                hProperties: node.attributes,
                ...node.data,
            };
            return node;
        });
    };
}

return (
    <ReactMarkdown
        remarkPlugins={[directive, reactMarkdownRemarkDirective]}
        components={{P5Sketch}}
    >
        {content}
    </ReactMarkdown>);

Resizing the Sketch Canvas

Most P5 sketches are explicit about their canvas size. This is because they're mostly small coding projects and don't need to be too concerned about working on different screen sizes. There are some P5 libraries that address this (p5-flex being one example). I simply added a size observer into the React hosting code and propagated the detected size into the Sketch code. The size observer returns a tuple: - an HTML reference for use by the wrapping element and the size of that element. Note that the width and height here are set on the container and passed down from the markdown directive.

const [wrapperRef, size] = useSizeRef<HTMLDivElement>();
return (<div ref={wrapperRef} style={{ width, height }}/>);

Now we just need to pass that observed size down into the Sketch. Unfortunately, there's currently no simple way to pass ad-hoc arguments to a Sketch. But we have access to the P5 Sketch Canvas instance, so we can simply inject properties into that. We can also invoke the function resizeCanvas on the Canvas object to resize the content dynamically.

useEffect(() => {
    if (size && canvasInstanceRef.current && wrapperRef.current) {
        // .size is not part of the type definition, so nasty casting here
        canvasInstanceRef.current.size = size;
        canvasInstanceRef.current.resizeCanvas?.(size.width, size.height);
    }
}, [size, wrapperRef]);

The properties above should be available to be used before the Sketch setup function is called, so this should work:

canvas.setup = () => {
    canvas.createCanvas(canvas.size?.width ?? 400, canvas.size?.height ?? 400);
};

NextJS Server and Client

One complexity with the new React server side component model is that you have to be fully aware of a component's dependencies on the browser environment. For P5, it's simple - it has to run on the client, it's animated and interactive. We can take care of this in the React wrapper by forcing all P5 dependencies and sketches into client rendering mode:

"use client";
import dynamic from "next/dynamic";

const P5WrapperReact = dynamic(() => import("./P5WrapperReact").then((mod) => mod.P5WrapperReact), { ssr: false });

Touch Interaction

One last tweak relates to how the above demo works on phones. When interacting with a Sketch on a phone you don't really want the containing page to scroll around. This can be fixed by disabling these events from propagating to the parent page using CSS on the P5 containing element:

<div ref={wrapperRef} style={{ width, height, touchAction: "none" }}/>