Proposal

Current tools for event modeling are effectively just virtual whiteboards. Being able to embed event models in markdown would make them much more widely useful for documentation as well as brainstorming. See the event modeling cheat sheet for more explanation of the format.

Use Cases

• documenting the expected behavior of an application
• illustrating how data moves between multiple systems and what can cause it to be created

Screenshots

Syntax

Building blocks

Event models break down into several sections shown as swim lanes; triggers, commands and queries, and facts.

Triggers

Triggers come in two forms. They can either be automated, in which case they just need a name, or they can be manual, in which case they need a pattern and a role.

pattern "auditing records" {
   role auditor {
      auditUI["auditing UI"]
      flagErrors["Flag errors"]
   }
  role author {
    authorUI["author UI"]
    write["write records"]
    authorUpdateUI["Update UI"]
    update["update records"]
  }
}
processStale["mark unaudited records as good after X days"]

This would declare an "auditing records" pattern with two roles.

• The auditor role would have an "audit UI" trigger and a "flag errors" trigger.
• The author role would have 4 triggers.

Separately, processStale would be created as an automated trigger, outside the context of the pattern. The syntax here is chosen to be relatively similar to the syntax in flowcharts.

Queries and Commands

Queries and commands do not have any additional context, and so are easy to declare. All that is necessary is the keyword query or command before the name, to clarify which you are declaring.

query showRecords["show records"]
command flagErrors

Facts

Facts need to be stored in some system which are drawn on the diagram as swimlanes.

system records {
  goodRecord["a complete history of the world"]
  badRecord["how to spel gud"]
}
system audits {
  auditGood["ACHOTW approved"]
  auditBad["HTSG needs revision"]
}

Organization

Any of the chunks above could be placed in any order in a diagram block. They will be connected by edges declared similarly to flowchart graphs.

goodRecord & badRecord --> showRecords
flagErrors --> auditGood & auditBad

Unlike in flowcharts, only certain transitions are allowed. Any other transitions will lead to an error.

flowchart LR

fact --> query
command --> fact
trigger --> command
query --> trigger

Edges that reference undeclared variables will also lead to an error, as we can't know what kind a variable is or where to put it otherwise.

Variables will be placed on the graph in their appropriate section, with an X coordinate related to their rank in the graph. If two variables have the same rank, they will be placed in the order that they were declared. No two variables should have the same X coordinate.

Complete Example

eventModel

pattern "auditing records" {
   role auditor {
      auditUI["auditing UI"]
      flagErrors["Flag errors"]
   }
  role author {
    authorUI["author UI"]
    write["write records"]
    authorUpdateUI["Update UI"]
    update["update records"]
  }
}
processStale["mark unaudited records as good after X days"]

query showRecords["show records"]
command flagErrors

system records {
  goodRecord["a complete history of the world"]
  badRecord["how to spel gud"]
}
system audits {
  auditGood["ACHOTW approved"]
  auditBad["HTSG needs revision"]
}

goodRecord & badRecord --> showRecords
flagErrors --> auditGood & auditBad

Implementation

I will try and implement it myself.