Skip to content

Architecture decisions ​

These records describe the architecture of bpmn-to-code as it is today, as a set of decisions: what was decided, what follows from it, and which alternatives were turned down and why. They are not a history. When a decision changes, its record is edited in place so that it stays true; what it said before is in git, and what changed for users is in the changelog.

Change a record in the same pull request that changes what it describes. Write a new one when a change introduces a decision that a contributor would otherwise have to rediscover: a new product surface, a new public contract, a constraint that is not visible from the code, or an alternative that was seriously considered and rejected. Conventions, commands and thresholds belong in the contributing guide and in Architecture, not here.

Every record has the same sections: Context, Decision, Consequences, Rejected alternatives.

  1. Product surfaces, distribution and uniform entry points: what is published, why core is not, and why every entry point behaves the same.
  2. Hexagonal core with a plugin facade: layers, wiring without a DI framework, and the rules Konsist enforces.
  3. BPMN reading stack, engine dialects and variable extraction: one parser for all engines, a dialect per namespace, explicit and directional variables.
  4. BPMN-aligned domain model: a sealed flow-node hierarchy with structural containment.
  5. One API per file, deterministic whole-run generation, generated-file ownership: naming by variantName, byte-identical output, and which files the generator may delete.
  6. Generated API shape: FlowNodes, Next, shared definition files and naming.
  7. Output languages: the language-neutral FlowGraph, rendered to every language from FreeMarker templates.
  8. Runtime library and process paths: the published support types and the compile-checked ProcessPath.
  9. Process JSON contract: a schema-versioned, BPMN-aligned public format. Superseded by record 13.
  10. Validation: the rule model, mandatory rules, and the three places validation runs.
  11. Compatibility and stability policy: the public contracts, what may break when, and the JDK floor.
  12. Web application: a stateless entry point with a static frontend, and its operating constraints.
  13. Process JSON deprecation: why the JSON output is deprecated in 6.x and removed in 7.0.
  14. Command-line tool: an entry point outside build tools, configured by flags only.
  15. Agent skills: one skill per task, engine knowledge in resources per style and language, bpmn-cli as a plugin dependency.