A small language and CLI

Event Modeling in HCL

Keep an Event Model in git, validate it, and render it to HTML.

.em.hcl is an HCL-based language for Event Modeling.

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] } }
eventmodeling-hcl validate model.em.hcl eventmodeling-hcl diagram model.em.hcl -o model.html

What the tool does

Validate

Checks references, workflow rules, scenarios, and model structure.

Format

Keeps .em.hcl files consistent.

Render

Produces a self-contained HTML Event Model.

Why it was created

There was a need for Event Models that could live beside the code, survive code review, and be checked by tooling. HCL happened to fit the shape quite nicely.

The validated typed model can also feed documentation or coding-agent workflows.

Examples

Each diagram is generated from the .em.hcl source in the repository.

Minimal

One Event and one State Change.

Open example →

Course subscriptions

Translation, State Changes, and State Views for course enrollment.

Open example →

Appointments & weather

All four workflow patterns.

Open example →
All examples

Why HCL?

It allows an Event to be an event block rather than an object with kind: event. HCL also provides traversal expressions that the .em.hcl validator can check as references.

The downside is more custom tooling. YAML is easier to adopt, and JSON has a broader interchange ecosystem. For this project, HCL gives a good tradeoff.

More about the choice

About this project

This project builds on Event Modeling and 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 textual representation plus a validator, formatter, and renderer.

Project status

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

Syntax may still change before 1.0.

Try the example

Install the CLI, validate a small model, and open the generated diagram.

Get started GitHub