Stadiæ

Stadiæ maintains an in-memory model of your diagram — states, choice-points, interfaces, messages, transitions — and re-emits PlantUML source from scratch on every edit. You never touch PlantUML syntax unless you want to; you edit behaviour. The server renders it; you see the result.

The domain is not decoration. The tool knows that a choice-point has exactly two branches (Yes / No), that an initial transition carries no message, that each source handles a given message at most once, that History and ANY are real pseudo-states with real semantics. Malformed diagrams cannot be saved, because they cannot be constructed.

'== States ==
state Advertising
state Connecting
state CP_Whitelisted as "Is Server\nWhitelisted?"

'== Transitions ==
[*]            --> Advertising
Advertising    --> CP_Whitelisted    : $RTx_ConnectReq
CP_Whitelisted --> Connecting        : $Logical_Yes
CP_Whitelisted --> Error             : $Logical_No

A Stadiæ file captures two levels of a design side by side: the device diagram — components as boxes, interfaces as lollipops, lines marking who talks to whom — and one state machine per component, describing its behaviour.

Interfaces and messages are the shared vocabulary that binds the two levels. Rename an interface and every component's state machine, every transition message, and every connection in the device diagram updates together. There is no way for the two levels to drift apart silently.

skinparam componentStyle rectangle

component Mesh {

'== Interfaces ==
() if_RTx as "RTx"
() if_Storage as "Storage"

'== Components ==
component Advertising
component Session

'== Handlers ==
node Radio as "RF\nRadio"

'== Connections ==
Advertising <- if_RTx
Session <- if_RTx
Session - if_Storage

'== Handler connections ==
Radio - if_RTx

}

Two floating buttons on the canvas control view navigation: ♦ Device at the top-left switches to the device diagram, and Component ▸ at the top-right (device view only, enabled when one Component is selected) enters the selected component's state machine. Stadiæ flags every transition that references an interface the component isn't connected to — an advisory amber !, not a block — so the two levels stay in sync without ceremony.

Every architect has tried the alternatives. Each one breaks in a different way once the diagram needs to live alongside the code.

A Stadiæ file holds a list of components, all sharing one set of interfaces and messages. This matches the reality of embedded systems: components are independent state machines, but they speak a common protocol.

{
  "format": "stadiae-v4",
  "deviceName": "Mesh",
  "interfaces": [ {"name":"RTx"}, {"name":"Data"} ],
  "messages":   [ {"interface":"RTx", "name":"ConnectReq"}, /* ... */ ],
  "components": [
    {
      "name": "Node",
      "displayName": "BLE Node",
      "description": "Connects to whitelisted servers, retries on failure.",
      "states":       [ {"name":"Advertising", "displayName":"Advertising"}, /* ... */ ],
      "choicePoints": [ {"name":"Whitelisted", "question":"Is Server\nWhitelisted?"} ],
      "transitions":  [
        {
          "source": "Advertising",
          "target": "CP_Whitelisted",
          "messages": [
            { "interface":"RTx", "name":"ConnectReq",
              "action": "Post ConnectReq to RTx; arm retry timer." }
          ],
          "connector": "Down", "length": 1
        }
      ]
    }
  ],
  "handlers": [
    { "name": "Radio", "displayName": "RF\nRadio" }
  ],
  "connections": [
    { "component":"Node", "interface":"RTx", "connector":"Right", "length": 1 }
  ],
  "handlerConnections": [
    { "handler":"Radio", "interface":"RTx", "connector":"Down", "length": 1 }
  ],
  "handlerCalls": [
    { "component":"Node", "handler":"Radio", "connector":"Right", "length": 1 }
  ],
  "activeComponentIndex": 0
}

Stadiæ is opinionated about file formats because your CI pipeline, your code review process, and your future self all are. Three exports, all text:

The action field on each transition row is where the behavioural description lives — "post ConnectReq to RTx; arm retry timer" — stored in the JSON save, surfaced in the Markdown export, omitted from PlantUML so the diagram stays uncluttered. Each component also carries a free-text description, edited live in a panel below the device catalogue. Behaviour and visualisation, separated.

Names in any prose field can be turned into cross-references by wrapping them in backticks — \`Idle\`, \`Card:Charge\`, \`Connection:ConnectReq:serverId\`, \`recomputeTotal()\`. The HTML spec resolves each one to a hyperlink to the named state, message, parameter, function, or whatever else the model knows about. Bare names use context (a backtick reference inside OrderManager's actions resolves to OrderManager's entities first); qualified names jump anywhere. Renames cascade automatically: rename an interface and every backtick reference to it across the model updates as one history step. Deletes leave references unresolved (warning style) so the holes are easy to spot. Live preview while editing: in the Device Specification, transition Action, local-function Steps, and Description panels, references render in styled monospace (with hover tooltips, just like the spec) when the field loses focus — so you can verify your references resolve without opening the spec preview. Press Esc to leave the field, hover the styled span to see the description.

Two panes. Rendered diagram on the left, the domain on the right. Everything a single click away.

The canvas isn't a dumb image. A second PlantUML rendering runs in parallel with every element painted in a unique colour. A click on the canvas samples the pixel, looks up the element, and selects it. Near-misses are silently ignored — clicking between two states doesn't blow away your selection.

Components, handlers, interfaces, and messages live in the device catalogue at the top of the right panel; all four are shared across the file. The Components list switches between components with one click — Node, Gateway, Session, whatever your subsystem contains. Each component has its own states, choice-points, transitions, and action notes, plus optional state variables, constants, and local functions in their own panels — all documentation-only fields that enrich the spec without touching the diagram. Handlers are device-level entities without a state machine — asynchronous edges to the outside world (radio, sockets, timers) that talk to components over interfaces or expose functions for components to call directly. Both interfaces and handlers dim in their lists when not connected to the active component, so you always see what's in scope at a glance.

Type definitions live one menu away under Device → Type definitions.... They're the device-wide reference of what each domain type means — a single name, a description, a free-text specification body. Parameter and state-variable type fields auto-link to their definition in the rendered spec when the cell text exactly matches a type name.

The save format is compact, stable JSON. The PlantUML export is deterministic. Both round-trip losslessly. What that means in practice:

A pull request can contain a state-machine change the same way it contains a code change. Your reviewer sees exactly what moved. No screenshots, no "open the Visio file and look at page 3", no tribal knowledge about who last touched the diagram.

In your CI: run plantuml node.stadiae.puml to render the current diagrams into artefacts, attach them to release notes, check them into a documentation site. Stadiæ is a participant in your engineering pipeline, not a detour from it.

stadiae.html is the entire program. Put it wherever you put other tools — a shared network drive, an internal wiki page, your Downloads folder. Open it in a browser.

System requirements: a modern browser and network reachability to a PlantUML server for rendering. Exports work offline regardless — the .puml file generation is local.

Source, detailed design document, user manual, and issue tracker live on GitHub: github.com/computerguided/stadiae.

Stadiæ renders diagrams by sending PlantUML source to a PlantUML server. By default it uses the public server at plantuml.com, which works out of the box and requires no setup. When that's not appropriate — because you work offline, because your network blocks external services, or because you want your diagrams never to leave your machine — point Stadiæ at a local PlantUML server instead.

// online (default)
"https://www.plantuml.com" + "/plantuml/png/" + encoded

// local
"http://127.0.0.1:8080" + "/plantuml/png/" + encoded

Choose between the two via File → PlantUML server…, or click the small plantuml: badge at the bottom-right of the canvas. The dialog has two radio options and a Base URL field that's only active when Local is selected; your choice is saved in the browser and persists across sessions.

Setting up a local PlantUML server on Linux takes a few minutes — step-by-step instructions are on GitHub: local_plantuml_server.md ↗. Once it's running, point Stadiæ at its base URL (default http://127.0.0.1:8080) and the canvas re-renders immediately from the local server.