Skip to content

Why Moment

Jump to bottom
Claude edited this page Apr 1, 2026 · 1 revision

Why Moment: Test Your Domain Before Writing Code

The Problem

Every software team faces the same expensive risk: you don't know your domain design is wrong until you've built it.

Traditional development flows discovery → design → implementation → testing → "oh, the event schema doesn't work" → rework. The feedback loop is measured in weeks. By the time you discover that your OrderPlaced event is missing the shipping address, or that the fulfillment context can't consume the inventory event, you've already written thousands of lines of code around the wrong contract.

Domain-Driven Design promised to solve this. But in practice, DDD artifacts stay in Miro boards and wiki pages. The bounded context map is a diagram, not a testable specification. The event storming output is sticky notes, not machine-readable contracts. There's no feedback loop between the design and the code.

What Moment Does

Moment is a specification-first domain modeling tool. You describe your domain in .moment files — bounded contexts, aggregates, commands, events, value objects, invariants, policies, sagas, and temporal flows — and Moment generates testable artifacts from that specification.

Artifact Purpose
TypeScript interfaces Type-safe contracts for every aggregate, command, event, and value object
Test scaffolds (.spec.ts) Per-aggregate and per-flow test structure with assertion points
Gherkin features (.feature) BDD scenarios derived from temporal flows with contract assertions
Specification documents Markdown documentation of context inventories and relationships
Visualization envelope JSON data for rendering context maps and temporal timelines
Simulation scenarios Facet-compatible event chains with causation, payloads, and expected paths
Drift reports Detect when implementation diverges from specification

The Key Insight: Generated Artifacts Are Testable

This isn't documentation generation. Every artifact Moment produces is executable against your domain.

Before a single line of implementation code:

  1. Schema contracts are locked. The TypeScript interfaces define exactly what OrderPlaced contains. Every consumer of that event codes against the same contract.

  2. Crossing contracts are validated. When OrderPlaced crosses from Ordering to Fulfillment, the crosses-to contract specifies exactly which fields are [required]. If Fulfillment needs shippingAddress and it's not in the contract, you know now, not after deployment.

  3. Temporal sequences are simulated. moment simulate walks the entire flow — check-in → triage → diagnosis → treatment → billing → discharge — producing a 28-event chain with causation IDs, branch decisions, and payload data.

  4. Branch paths are enumerated. Every [branch] moment with when blocks produces test cases for each path — all derived from the specification, all testable.

The Moment → Facet Pipeline

Moment produces the specification artifacts. Facet consumes them and runs the full domain simulation.

.moment file
  → Moment CLI
    → Simulation Scenario (JSON)
      → Facet Simulation Engine
        → Event-by-event execution
          → Pass/fail per scenario
            → Visualization dashboard

What Facet Executes

Facet takes Moment's simulation output and:

  1. Walks the expected path node by node
  2. Evaluates branch decisions with the specified conditions
  3. Validates event payloads against schema contracts
  4. Tracks causation chains — does each event correctly reference its cause?
  5. Reports pass/fail per scenario with precise divergence points
  6. Visualizes results — which moments passed, which failed, where the flow broke

The Value

Before Moment + Facet: "We think the domain works" → build for months → discover contract mismatches → expensive rework.

After Moment + Facet: "We know the domain works" → test every temporal path → validate every schema crossing → implement with confidence.

The .moment file is the single source of truth. Change the specification, regenerate, re-simulate. The feedback loop is seconds, not weeks.

Who This Is For

  • Domain architects who model bounded contexts and need testable specifications
  • Engineering teams who want type-safe contracts before implementation begins
  • QA teams who need Gherkin scenarios derived from the domain, not invented from tickets
  • Platform teams who need to validate event schemas across service boundaries

What Makes Moment Different

Traditional DDD Tooling Moment
Diagrams in Miro/Lucidchart Machine-readable .moment specs
Sticky notes from event storming Formal event declarations with typed fields
Context maps as pictures Executable crossing contracts with [required] fields
Manual test creation Auto-derived test suites from temporal flows
No schema validation moment sync status detects drift
No simulation moment simulate produces full event chains
Design docs rot moment generate regenerates from source of truth

Clone this wiki locally