A standalone visualization server for com.fulcrologic/statecharts. Renders interactive statechart diagrams in the browser, with simulation and live session monitoring.
The visualizer is designed to run from your project directory so your chart namespaces are already on the classpath. Add it as an inline dependency:
clj -Sdeps '{:deps {com.fulcrologic/statecharts-visualizer {:mvn/version "1.0.0"}}}' \
-M -m com.fulcrologic.statecharts.visualizer.standalone \
--namespaces my.app.chartsThen open http://localhost:8080 in your browser.
Add the visualizer as a dev alias in your project's deps.edn:
{:aliases
{:viz {:extra-deps {com.fulcrologic/statecharts-visualizer {:mvn/version "1.0.0"}}
:main-opts ["-m" "com.fulcrologic.statecharts.visualizer.standalone"
"--namespaces" "my.app.charts,my.app.other-charts"]}}}Then start it with:
clj -M:vizScans Clojure namespaces for public vars that contain statechart definitions (maps with ::sc/elements-by-id). Your
namespaces must be on the classpath.
clj -M -m com.fulcrologic.statecharts.visualizer.standalone \
--namespaces my.app.charts,my.app.other-chartsThis is the primary mode for exploring charts during development.
Proxies all Pathom queries to an existing Fulcro/Pathom server that already has statechart resolvers wired in. The viz UI runs locally but data comes from your running app.
clj -M -m com.fulcrologic.statecharts.visualizer.standalone \
--remote http://localhost:3000/apiUse this when your app is already running and you want to inspect live sessions.
Starts an empty server that accepts chart definitions pushed over HTTP. Useful for babashka scripts and other external tooling.
clj -M -m com.fulcrologic.statecharts.visualizer.standaloneThen push charts via POST:
curl -X POST http://localhost:8080/api/chart \
-H "Content-Type: application/edn" \
-d '{:key :my-chart :definition {... chart EDN ...}}'Charts registered via POST support diagram rendering only (no simulation), since functions cannot be serialized over HTTP.
| Flag | Default | Description |
|---|---|---|
--port PORT |
8080 | HTTP server port |
--namespaces NS |
— | Comma-separated namespace symbols to scan for chart vars |
--remote URL |
— | URL of existing Pathom API to proxy to |
--help |
— | Print usage and exit |
--namespaces and --remote are mutually exclusive. If neither is given, the server starts in POST-only mode.
Select any chart and step through it interactively in the browser:
- Toggle guard conditions on/off to explore different paths
- Send events and watch state transitions animate in real time
- Reset to initial configuration at any time
The simulator uses a custom execution model where guards are toggleable booleans and other executable content (scripts, assigns) is a no-op.
In remote proxy mode, connect to a running session by ID to:
- View the current active state configuration
- Send events to the live session
- Watch state changes as they happen
Charts can include UML-style labels for richer diagrams:
(require '[com.fulcrologic.statecharts.elements :refer [state transition script on-entry]])
(state {:id :processing}
(on-entry {}
(script {:expr some-fn :diagram/label "validate input"}))
(transition {:event :done :target :complete
:cond guard-fn
:diagram/condition "input valid?"})):diagram/labelonscriptelements displays as entry/exit activities:diagram/conditionon transitions displays as guard labels
The visualizer is a thin server layer on top of resolvers that ship with the main com.fulcrologic/statecharts library:
statecharts-visualizer (this artifact)
├── standalone.clj — CLI entry point
├── server.clj — Ring/Jetty HTTP server
├── pathom.clj — Pathom parser setup
└── proxy.clj — Remote Pathom proxy
com.fulcrologic/statecharts (dependency)
├── visualization/server/resolvers.clj — Pathom resolvers
├── visualization/simulator.cljc — Simulation engine
├── visualization/visualizer.cljs — SVG rendering (pre-compiled)
└── visualization/elk.cljs — ELK layout engine (pre-compiled)
The pre-compiled CLJS visualization UI is served from resources/public/viz/ on the classpath.
MIT