Weavr - Event Modeling Editor

"Model Event Sourcing systems and DDD architectures directly in your browser without a server."

Weavr is an Event Modelling tool with a real-time, peer-to-peer feature for collaboration with your team. It provides a canvas to design and document business processes with your team, all directly within the browser.

This version is serverless and collaborative. Changes are synchronized in real-time between all users looking at the same model.

What is Event Modeling?

Event Modeling is a method of describing a system by illustrating the information that changes within it over time. It focuses on a single, comprehensive diagram that captures Screen, Command, Internal Event, Read Model and External Event elements, providing a clear and complete blueprint for development.

Key Features

• Real-Time Collaboration: Share your model's unique URL with colleagues to have them instantly join your session. All changes are synchronized in real-time across all participants.
• Serverless & P2P: Built with gun.js, this tool runs without a central server. Browsers communicate directly with each other to share data, ensuring privacy and simplicity.
• Intelligent Canvas: The canvas understands the rules of Event Modeling. It provides real-time visual feedback, highlighting valid and invalid connections as you model, guiding you toward a correct design.
• Core Event Model Elements: Add and connect essential components: Screen, Command, Internal Event, Read Model and External Event elements.
• Import & Export: Save your model to a local JSON file for backup, and import it back into any session to continue your work or overwrite a collaborative model.
• Intuitive Interface: Drag-and-drop nodes, create links easily, and edit properties in a dedicated panel.

Why Weavr?

Unlike generic whiteboard tools (Miro, LucidChart) or enterprise modeling heavyweights, Weavr is purpose-built for Domain-Driven Design.

Feature	Weavr	Generic Whiteboards	Enterprise Tools
DDD Syntax	Enforced (prevents invalid links)	None (draw anything)	Complex / Rigid
Privacy	Local-First / P2P (Your data)	Cloud (Their data)	Cloud / On-Prem
Cost	Free & Open Source	Subscription	Expensive
Collaboration	Real-Time P2P	Real-Time Cloud	Often Desktop / Slow

How to Use

1. Open the Application: Simply navigate to the application's URL. You will be automatically placed in a new, unique model session.
2. Collaborate:
   • Click the Share button in the header. This copies the unique URL for your model to your clipboard.
   • Send this link to your colleagues. When they open it, they will join you on the same canvas, and you will see each other's changes live.
3. Add Elements: Use the floating + button in the bottom-right corner to add elements like Screen, Command, Internal Event, Read Model and External Event elements to the canvas.
4. Arrange the Canvas:
   • Click and drag elements to position them. The canvas uses a grid for easy alignment.
   • Pan by clicking and dragging the canvas background.
   • Zoom using your mouse wheel.
5. Create Relationships:
   • Hover over an element to reveal four connection handles.
   • Click and drag from a handle to another element. The canvas will give you instant feedback: indicating potential target elements in green if the connection is valid according to Event Modeling rules, and red if it is not. Invalid links cannot be created.
6. Edit Properties:
   • Single-click an element or a link to select it and open the Properties Panel on the right. Here you can edit its name, description, and (for Triggers) its stereotype.
   • Double-click an element or link to focus the input field in the panel for quick editing.
7. Save and Load:
   • Use the Export button to download the entire model as a .json file.
   • Use the Import button to load a model from a .json file, replacing the current content of your canvas for all collaborators.

Keyboard Shortcuts

Key	Action
A or N	Toggle the 'Add Element' toolbar
1 - 5	Add specific element (when toolbar is open)
Arrow Keys	Move selected element(s)
Tab	Cycle through elements on the canvas
Shift + Tab	Cycle backwards through elements
Enter	Open properties panel for selected element
Esc	Close properties panel / Deselect all
Delete / Backspace	Delete selected element(s) or link

Running Locally

This project uses Vite for a modern, fast development experience.

1. Clone the repository.

   git clone https://github.com/rolfmadsen/weavr.git
   cd weavr

2. Install dependencies:

   npm install

3. Choose NodeJS version:

   nvm use 22

4. Run the development server:

   npm run dev

5. Build the application

   npm run build

6. Run the test suite

   npm test

Configuration

Analytics (Optional)

This project uses Plausible.io for privacy-first analytics.

To configure analytics for your own domain, set the following environment variable in your .env file or deployment platform:

VITE_PLAUSIBLE_DOMAIN=your-domain.com

If not set, it defaults to weavr.dk. Analytics are automatically enabled, but you can see them working on localhost.

Tracked Events

Weavr tracks the following custom events to understand feature usage:

Feature	Event Name	Properties
Add Element	Node.Added	type, id
Add Slice	Slice.Added	title
Undo / Redo	History.Undo, History.Redo	-
Auto Layout	Layout.Requested	method: 'MANUAL'
Export Model	Export.Started	format, nodeCount
Import / Merge	Import.Started	`type: 'OPEN'
Documentation	Documentation.Generated	fileSize
Unpin Node	Node.Unpinned	id
Pin/Unpin Select	Selection.Pinned, Selection.Unpinned	count
Filter	Filter.ElementSelected, Filter.SlicesChanged	type, hiddenCount
Share Link	Share.Clicked	-
Rename Model	Model.Renamed	-
Data Dictionary	Definition.Added, .Updated, .Deleted	name, id
Minimap	Minimap.Navigated	-

Enterprise Features

Weavr includes advanced features to support enterprise-grade Event Modeling:

1. Slice Chapters (Structuring Large Models)

Group slices into logical "Chapters" (e.g., "Checkout", "Inventory") to improve navigation in large systems.

• Usage: Select a slice and enter a Chapter name in the properties panel.

2. GDPR & PII Attributes

Support "Data Minimalism" and "Crypto-Shredding" patterns.

• Usage: Toggle the "Lock" icon in the Data Dictionary to mark attributes as PII.
• Documentation: PII fields are explicitly flagged in generated documentation.

3. Strict Mode Validation (Translation Pattern)

Prevents "External Data Leaks" by enforcing the Translation Pattern.

• Rule: External Event -> Read Model is Forbidden.
• Solution: Use External Event -> Automation -> Command to translate external data.

4. Actor Management

Define and manage Actors (Users/Personas) and associate them with specific screens or automations.

• Actors Sidebar: A dedicated tab to Create, Read, Update, and Delete actors. Syncs in real-time.
• Association: Link an Actor to a Screen or Automation via the Properties Panel.
• Smart Creation: Create new actors directly from the properties dropdown while modeling.