Event Modeling as the design foundation

2026-03-01 20:59:24.126Z2026-03-01 22:32:48.212Z

Event Modeling is the design methodology at the heart of
NEXUS. Before any code is written, the system is modeled
as a sequence of events on a timeline. This is not optional
overhead — it is the foundation from which everything else
is built.

What Event Modeling Is

Event Modeling was created by Adam Dymetrik. It is a
methodology for designing software systems by mapping out
the events that flow through them — the things that happen,
in the order they happen — always expressed as a timeline.
The left-to-right temporal layout is not incidental. It is
the core structure that makes the model readable as a story
of what happens in the system.

An Event Model is a timeline showing four elements:

Commands — the mechanism of intent. A function that
represents something being asked of the system. A user
clicks a button, a process posts to an API, an AI agent
issues an instruction. The command carries the intent and
the input. Given the same input, a correctly designed
command produces the same result — it is deterministic
and repeatable, though it may contain logic and branch
across multiple paths.

Events — immutable facts that have occurred. Not
functions — facts. Something happened and is permanently
recorded. Events are the only source of truth in the
system. They are never updated or deleted, only
appended. A command produces an event. Ideally one
event per command — multiple events from a single
command is an anti-pattern worth examining carefully.

Projections — the mechanism of derived state. A
function that takes one or more events and produces
a view of current state for a consumer. Like commands,
projections are deterministic and repeatable — given
the same events in the same order, a projection always
produces the same result. Projections are never the
source of truth. They are always derived from events.
The events don't have to be the most recent — a
projection can draw from any point in the event
history.

Note: Projections are also called Read Models in CQRS
literature and Views in some frontend contexts. NEXUS
uses Projection because it is mechanistically honest —
it describes how the thing comes to exist, not just
what it's used for. See: The Command / Event /
Projection triad.

The UI/IO layer — the boundary of the system.
Where external signals originate and where projections
are consumed. Colloquially called "UI" or "screens"
but this understates what this layer actually
represents. Any actor can occupy this layer: a human
clicking a button, a CLI entry, an API post, an
external process, an AI agent, or any IO boundary
between the system and the outside world. This layer
initiates commands and receives projections. It is
where decisions and choices happen — not inside the
system, but at its boundary.

NEXUS treats this layer explicitly as the IO boundary
of the system — where external communication happens.
See: The UI/IO boundary layer.

The Two Fundamental Slices

A slice is a vertical cut through the timeline connecting
the layers. There are exactly two fundamental slice types.
All more complex patterns decompose into these two:

Command slice — UI/IO layer initiates a command,
command produces an event. The flow is: something
external wants something to happen → the system
records that it happened.

Projection slice — one or more events feed a
projection, projection informs the UI/IO layer.
The flow is: something happened in the system →
a consumer is informed of the derived state.

Complex patterns are compositions of these two
fundamentals across multiple slices — not new slice
types. Recognizing this simplifies the model and
keeps analysis tractable.

See: Slice patterns — the two fundamentals and
how they compose.

External Events

NEXUS takes a clear position on external events: there
are none at the event layer. Events in NEXUS are always
internal — facts produced by commands within the system.

External signals — from other systems, external
processors, third-party services — enter through the
UI/IO boundary layer. They trigger commands. Those
commands produce internal events. The external signal
never becomes an event directly. This keeps the event
layer clean and fully owned.

Swim Lanes

Swim lanes are horizontal lanes within a layer that
separate different actors or systems. They mean
different things depending on where they appear:

UI/IO layer swim lanes — actor and persona
boundaries. A lane for a generic user, a lane for
an admin, a lane for a REST API consumer, a lane
for an external processor, a lane for an AI agent.
Each lane shows what that actor initiates or receives.

Event layer swim lanes — system boundaries within
your controlled domain. When the model spans multiple
systems you own or build, each system gets a lane
showing which events it owns. These are internal
boundaries — all systems are within your domain —
but the lane makes ownership explicit.

See: Swim lanes — actor boundaries and system
boundaries.

Why NEXUS Uses Event Modeling

Event Modeling produces artifacts that are:

Unambiguous — the model either covers a scenario
or it doesn't. Gaps are visible in the timeline.
A missing projection means something produces events
that nothing consumes. A missing command means
something is expected to happen with no mechanism
to trigger it. These gaps are structural and
observable, not hidden in prose.

Implementation-ready — the event model maps
directly to code. Commands become command handlers.
Events become event types. Projections become query
handlers. The design is the specification. There is
no translation layer between design and
implementation — only rendering.

Language-agnostic — Commands, Events, and
Projections are concepts, not code. A complete,
well-formed Event Model describes what the system
does at a semantic level independent of any
implementation language. The same model can be
rendered into F#, JavaScript, Haskell, or Kotlin
by changing the target language passed to the AI
implementation layer. NEXUS currently targets F#
but the methodology does not require it.

See: Language-agnostic design — one model, many
implementations.

AI-actionable — a complete Event Model gives
an AI system the context it needs to implement
correctly. The design does the thinking; AI does
the building. The completeness requirements of a
good Event Model align exactly with what AI needs
— unambiguous inputs, deterministic functions,
clear outputs.

Reversible — existing software can be analyzed
to derive its implicit Event Model, making the
design that was buried in code explicit and
actionable. This enables reimplementation in a
new language, contribution of the model back to
the original project, and discovery of gaps and
broken paths the original authors may not be
aware of.

See: Reverse engineering existing software with
Event Modeling.

How NEXUS Extends Event Modeling

NEXUS builds on Adam Dymetrik's methodology with
several additions:

Paths as first-class artifacts — a path is a
named, purposeful journey through the event model
from a specific actor's perspective. Paths make
intent explicit within the model. They also enable
path playback — replaying a specific user's actual
event sequence to observe exactly what happened,
making bug tracing a matter of observation rather
than reconstruction.

See: Paths as first-class artifacts.

Spec topics linked to model elements — specific
slices of the event model become Spec topics in
LOGOS with their own workflow states. The model
element and the spec are linked — the spec is not
a separate document, it is the model element made
into an actionable artifact.

AI as the implementation layer — the event
model is designed to be consumed by AI code
generation. The language-agnostic nature of a
complete model means AI can render it into any
target language from the same design source.

The Tool

Penpot is the current tool for creating Event Models
within NEXUS — an open source, self-hostable design
tool that produces the visual timeline artifact.
The model lives in Penpot; the link to it lives in
LOGOS; the conversations that shaped it live in
LOGOS alongside that link.