ESDM Viewer

See your event-sourced domain as a diagram while you write it.

ESDM Viewer turns a folder of *.esdm.yaml files into an interactive map of your domain -- bounded contexts, aggregates, commands, events, policies, read models and queries -- and adds full language support to the files themselves: completion, cross-file navigation, rename, hover and instant validation.

What is ESDM?

ESDM (Event Sourcing Domain Modeling) describes an event-sourced domain as plain YAML files, one element per file, referencing each other by name. Because the model is text, it lives in your repository next to the code, is reviewed in pull requests and versioned in Git.

A command that acquires a book, in a library domain:

apiVersion: schema.esdm.io/core/v1
kind: command
name: acquire
scope:
  domain: library
  boundedContext: cataloging
  aggregate: book
data:
  type: object
  properties:
    title: { type: string }
    author: { type: string }
    isbn: { type: string }
  required: [title, author, isbn]
publishes:
  - acquired

This extension understands those references. book and acquired are not just strings to it: you can jump to them, rename them, hover them, and you get a warning the moment one points at something that does not exist.

The language, its schemas and its CLI are documented at www.esdm.io.

Features

The diagram

• Interactive map of the whole workspace, rendered with Mermaid -- zoom, pan, click an element to see its details.
• Live reload -- every save re-renders the diagram.
• Jump to the source -- double-click any node to open the YAML that defines it.
• Search inside the diagram with step-through navigation.
• Export as SVG -- the full diagram or just one bounded context, one aggregate or all external systems; to a file or the clipboard.
• Follows your theme -- colors adapt to the active VS Code theme and recolor when you switch, without losing your zoom.

Writing the model

• Completion for kind: values and for references such as scope.aggregate, publishes, handles.event and emits.command, offering the elements that actually exist.
• Navigation and rename across files -- go to definition, find all references, and a rename that catches every reference workspace-wide while leaving descriptions, comments and same-named elements of another kind untouched.
• Hover, CodeLens, outline and symbols -- an element's kind, name and description on hover, a "N references" lens above every definition, and an ESDM tree in the Explorer with breadcrumbs and symbol search.
• Snippets and scaffolding -- one snippet per document kind, plus ESDM: New Domain to start a consistent model from scratch.
• Schema-driven completion and hover -- with the ESDM schemas in the project, the editor knows which fields a document kind may carry, which values they take and what they mean. ESDM: Update Schemas puts them there or brings them up to date.

Catching mistakes

• Reference warnings -- a name that resolves to nothing is underlined as you type, with no CLI involved.
• Duplicate warnings -- an element defined twice under one name is flagged at every definition, each pointing at the others.
• esdm lint results appear as normal VS Code problems, on save and while typing.
• Quick fixes -- create a missing element in a new file straight from the warning, or act on an unknown apiVersion.

Getting started

1. Install the extension.
2. Open a folder that contains *.esdm.yaml files. The extension activates on its own.
3. Run ESDM: Open Diagram from the Command Palette (Cmd/Ctrl+Shift+P).

No ESDM model yet? Open an empty folder and run ESDM: New Domain -- it scaffolds a small, self-consistent model you can grow from, together with the schemas that drive completion.

For an existing project without a schemas/ directory, ESDM: Update Schemas adds it. The extension offers this once per project, since without it field and value completion stay off.

All further commands are in the Command Palette under ESDM:.

Keyboard shortcuts

Requirements

• VS Code 1.85 or newer.
• The esdm CLI, but only for esdm lint and the schema commands. The extension downloads a pinned version on demand, so there is nothing to install by hand. Everything else -- the diagram, completion, navigation, rename, reference and duplicate warnings -- works without it.

Settings and troubleshooting

Every setting, and what to do when something does not work, is in docs/configuration.md. The settings are also listed in the VS Code settings UI under ESDM.

ESDM: Show Output Channel shows what the extension is doing; set esdm.logLevel to debug for the full trace.

Contributing

Build instructions, the architecture and the test setup are in docs/development.md.

License

MIT