A small language and CLI

Event Modeling in HCL

.em.hcl is a language for writing Event Models in HCL.

The emhcl tool validates, formats, and renders these models.

See an example Install the CLI

A small example

Event Model showing Add Pet Form flowing to Add Pet and then Pet Added.
bounded_context "pet_management" { event "pet_added" { } } state_change "add_pet" { screen "add_pet_form" { to = [command.add_pet] } command "add_pet" { to = [event.pet_management.pet_added] } }
emhcl validate model.em.hcl emhcl diagram model.em.hcl -o model.html

What the tool does

Validate

Checks references, workflow rules, scenarios, and model structure. A model is one .em.hcl file or a folder of them.

Format

Keeps .em.hcl files consistent. Formats one file at a time, including files that belong to a folder model.

Render

Produces a self-contained HTML Event Model with switchable Model, Compact, Storming (Event Storming-like), and Context Map views.

Convert

Imports and exports slice-based Event Modeling JSON. Warns about each detail that the other format cannot hold.

Why it exists

Start with the business process without software. Identify who acts, what facts they record, and what information they need. Then describe that flow in HCL.

Event Models needed to live beside the code, pass code review, and work with automated checks. HCL fits this need. The validator produces a typed model for documentation and coding-agent workflows.

A valid file does not prove that the business process is complete. Review field origins, missing decisions, failure paths, and scenarios with domain experts. See the method and core concepts.

Examples

The tool generates each diagram from the .em.hcl source in the repository.

Minimal

This example has one Event and one State Change.

Open example →

Course subscriptions

This example covers Translation, State Changes, and State Views for course enrollment.

Open example →

Appointments & weather

This example shows all four workflow patterns.

Open example →
All examples

Why HCL?

HCL lets an Event be an event block instead of an object with kind: event. HCL also has traversal expressions, and the .em.hcl validator checks them as references.

The cost is more custom tooling. YAML is easier to adopt, and JSON has a broader interchange ecosystem. This project accepts that cost.

More about the choice

About this project

This project builds on Event Modeling and on work by Adam Dymitruk, Martin Dilger, EmLang, ESDM, and others in the Event Modeling community.

.em.hcl is not a new Event Modeling method. It is one text format with a validator, formatter, and renderer.

Project status

Status: experimental
Current spec: v0.4.0
CLI: v0.9.0

Syntax can still change before 1.0.

Try the example

Install the CLI. Validate a small model. Open the generated diagram.

Get started GitHub