Systemathic

Design a system as a precise model — closed vocabularies, the contexts that use them, and explicit crossings between them — then verify it against rules and export it as a contract for implementers. See docs/motivation.md, the formal model in docs/foundation.md, and the tool's own design in docs/tool-design.md, which the tool verifies (pnpm check-self).

Build and test

Needs Node 22+, pnpm, and Python 3.11+ (verification rules are Python).

pnpm install

pnpm build

pnpm test

pnpm test:python

Use

The command line:

node packages/cli/dist/index.js check examples/game.systemathic.json

node packages/cli/dist/index.js verify examples/tool-design.systemathic.json examples/tool-design.rules.py

node packages/cli/dist/index.js export examples/game.systemathic.json md

node packages/cli/dist/index.js export examples/game.systemathic.json docs

The visual UI: start the host, then open http://127.0.0.1:4747.

pnpm serve examples/game.systemathic.json

The Explorer on the left holds the whole System; a click opens what it is in its editor — a Language's Entities, Relationships, Interactions and Axioms (or its diagram: drag between Entities to relate them), a Domain's scope and Transformations, a Transformation's mappings, a Mediation and its witness. Everything is edited in place, including each thing's description; the Documentation view reads the whole System as one document, and downloads it as Markdown. Ctrl K goes anywhere or runs any command; Ctrl Z / Ctrl Shift Z undo and redo your own edits; Ctrl S saves; Ctrl J shows the Problems, History and Verification. The verification script is edited in the UI too — Python, with problems as you type, completion and documentation — or in any editor: it is the .rules.py file beside the System.

In the browser alone, with nothing to install and no server: the static site is the same UI with its host built in. Systems are kept in the browser, files are opened from and downloaded to the computer, and rules run in Python compiled to WebAssembly (Pyodide), in a Web Worker.

pnpm build:static

packages/ui/dist-static is the site; pnpm dev:static runs it locally. Pushes to main deploy it through Site Manager (.github/workflows/ci.yml, with vars.SSMA_DEPLOY_URL and secrets.SSMA_DEPLOY_TOKEN).

An LLM, over MCP: register node packages/mcp/dist/main.js as a stdio MCP server. It joins the host if one is running (or SYSTEMATHIC_HOST), so the model and the UI edit the same System and see each other's edits; otherwise it hosts the Systems itself on port 4747.

Layout

Path	What
schema/	The Systemathic Languages, as data: the single source of truth
packages/core	Kernel, Contexts, Operations and Std: the instance graph, the logic, deletion
packages/tool, tool-json	Systems as the tool keeps them, and the file format (docs/format.md)
packages/editing, editors	Shared edit sessions and History; one editor per concept
packages/diagnoser, verifier, python-host	Structural errors, rule verification, and the Python rule host
packages/perspectives, exporter, catalog	Points of view, specifications, and importable packages
packages/host, host-node, host-browser	Where Systems live: the Host, in a local process or in a browser tab
packages/pyodide-host	Rule scripts run in WebAssembly, for the browser
packages/cli, mcp, ui	The clients
python/systemathic	systemathic.core and systemathic.std for rule scripts
catalog/	The standard packages (generated by scripts/build-catalog.ts)
examples/	The game example, broken examples, and the tool's own design