> > > SpecTextToBpmnToolingAnalysis

Text-to-BPMN Tooling Analysis

Question

What tooling architecture should SOTER build to author process-oriented diagrams as text and render them without a graphical editor, without importing BPMN's ambiguity as the source format?

Context

The original problem was practical: SOTER needs a human-friendly, repository-friendly way to author process-oriented diagrams and render them without a graphical editor. This note standardizes an earlier dialogue about PlantBPMN-like tooling into a technical analysis and product direction.

The deeper conclusion is that SOTER should not merely clone BPMN tooling. It should own a semantic source model and treat BPMN as one possible projection, consistent with the position established in BpmnExecutableVsNonExecutableAnalysis.md.

Target requirements for the tooling:

Human-friendly syntax, closer to PlantUML, YAML, or Markdown than XML.
CLI rendering without a desktop GUI.
SVG, PNG, or HTML output.
Clickable elements and stable element IDs.
Preview inside VS Code.
Optional web preview for read-only users.
Manual editing must remain realistic.
The source files must remain suitable for Git review.

The long-term goal is not just "text to diagram." It is stable semantic authoring with deterministic visual projections.

Sources

PlantUML (architecture, syntax culture, CLI rendering model)
bpmn-js and Camunda Modeler (BPMN XML rendering and editing reference)
Mermaid, D2, Graphviz (text-based diagramming alternatives)

Findings

PlantUML is an excellent model for authoring diagrams as text, but it does not provide a full official BPMN notation comparable to the OMG BPMN standard. BPMN-like diagrams can be approximated with activity diagrams, but this is styling, not a formal BPMN model.
Forking PlantUML would be expensive: it is a mature Java codebase with its own parser, layout assumptions, renderer, and compatibility constraints. It is a good inspiration, not the best foundation for SOTER's first BPMN-oriented tooling.
Three candidate architectures were evaluated:

1. Extend PlantUML — advantages: existing CLI/server ecosystem, mature rendering pipeline, familiar syntax culture, existing documentation-tool integrations. Disadvantages: Java stack mismatch, high maintenance cost, BPMN layout is not a trivial activity-diagram variant, long-term fork burden, poor fit for SOTER's semantic model. Not recommended for the MVP.

2. Build a custom DSL to BPMN XML pipeline (custom DSL -> parser -> semantic model -> BPMN XML -> bpmn-js / Camunda / BPMN renderer) — advantages: real BPMN compatibility, reuse of bpmn-js for rendering, path to import/export with external tools, potential browser interactivity. Disadvantages: BPMN XML becomes a strong constraint, the DSL may drift toward BPMN instead of SOTER semantics, layout and round-tripping remain difficult. Useful later for interchange, but should not define the first authoring model.

3. Build a SOTER-native semantic DSL with projectors (Logos / SOTER model -> parser -> canonical semantic IR -> VGM layout model -> projector -> SVG / HTML / BPMN XML / Mermaid / PlantUML) — advantages: preserves SOTER's model-first philosophy, keeps BPMN as a projection rather than source truth, supports stable IDs and cross-diagram links, enables multiple notations from one model, fits a Python backend plus JS frontend stack. Disadvantages: requires a custom compiler pipeline, layout discipline, and VS Code/preview tooling over time.

Comparison of existing tools by role:

Tool	Role
Mermaid	Useful for quick Markdown-friendly diagrams, not full BPMN.
PlantUML	Inspiration for CLI-first text diagrams, not a base for the MVP.
D2	Useful inspiration for modern layout and text-based diagramming.
Graphviz	Useful backend for early layout experiments.
bpmn-js	Useful for BPMN XML rendering and future compatibility.
Camunda Modeler	Useful external reference for BPMN, not SOTER's source editor.
VS Code extensions	Useful shell for authoring, preview, and diagnostics.

Interpretation

Option 3 (SOTER-native semantic DSL with projectors) is the recommended direction: it is the only option that keeps BPMN as a projection rather than a source-of-truth format, matching the architectural position that BPMN must not become the authoritative definition of organizational reality.

The MVP should not be framed as a PlantUML fork. It should be a small SOTER projection tool with three commands:

pbpmn build — parses source files and produces rendered artifacts: SVG, HTML viewer output, optional PNG, diagnostics, and build metadata.
pbpmn index — builds a repository index of elements, stable IDs, names, files, relationships, references, backlinks, and render targets. The index can start as SQLite; source files remain the source of truth.
pbpmn serve — starts a local read-only viewer with rendered diagrams, clickable elements, element search, cross-diagram navigation, diagnostics, and links from visual nodes to source definitions.

The file system remains authoritative: source files -> parser -> index -> render output. The database is a projection, not the primary authoring store, keeping the workflow compatible with Git, code review, branches, and manual editing.

Stable IDs are mandatory. Content hashes and URLs are not enough because IDs must survive renames, edits, and file moves. Recommended policy: every top-level element receives a UUID (preferably UUIDv7 or UUIDv4), the UUID is stored explicitly in source metadata, human-readable names remain aliases rather than identity, the index maps names/aliases/files/UUIDs, and validation detects duplicate IDs and unresolved references. Example:

element PrepareOffer id=01J...
    type: Action
    in: [CustomerNeed]
    out: [OfferDraft]

For SVG output, each semantic element should render as a <g> group carrying the stable ID:

<g id="01J..." data-soter-kind="Action" data-soter-name="PrepareOffer">
  ...
</g>

This is better than linking only whole files, because the link target is the semantic element, not merely the diagram document. HTML output can add hover metadata, click navigation, source links, related elements, backlinks, and validation state.

VS Code integration should be incremental:

Phase 1 — CLI build, generated SVG/HTML, Live Preview or browser preview.
Phase 2 — a simple VS Code extension with syntax highlighting, diagnostics from CLI output, and a preview command.
Phase 3 — a language server with go-to-definition, references, rename support, hover cards, and semantic validation.

Manual editing remains feasible if the DSL is stable and restrained: keep definitions short, keep UUID metadata explicit but visually secondary, avoid mandatory verbose XML-like structures, support local aliases, validate aggressively, and provide formatter and linter commands. Manual editing becomes unrealistic only when the language forces users to manage layout, repeated IDs, or global wiring by hand.

Two distinct composition mechanisms are needed: include for composing one logical model from several physical files, and use/import for referencing another process or library without merging everything into the same logical module. This prevents accidental coupling between reusable definitions and process interfaces.

Impact on SOTER

This note sets the architectural decision for SOTER's diagram-authoring tooling: build a semantic authoring pipeline, not a BPMN clone. The first implementation should be a Python parser/compiler, a SQLite index, Graphviz or a simple layout for early rendering, SVG/HTML output, stable semantic IDs, optional BPMN XML export later, and VS Code support after CLI stabilization.

Do not fork PlantUML. Do not make BPMN XML the primary source format. Treat BPMN, SVG, HTML, Mermaid, and PlantUML as render targets. The durable value is not diagram rendering; it is stable semantic identity, repository-scale navigation, and deterministic projection from one source of truth.

Confidence

Medium. The architectural direction (native DSL with projectors) is well justified against alternatives, but the concrete MVP scope (pbpmn build / index / serve) has not yet been implemented or validated against real usage.

Follow-up

Prototype the pbpmn build command against a small set of real SOTER process definitions.
Decide on the canonical semantic IR schema before committing to a VGM layout model.
Revisit BPMN XML export scope once the native DSL and SVG/HTML projection are stable.