Skip to content
Back to search

Cosmogony

Event Storming whiteboard with an MCP server that lets AI agents read and edit the canvas.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/abner-tungchi--cosmogony/badge.svg)](/listings/abner-tungchi--cosmogony)

HTML

<a href="/listings/abner-tungchi--cosmogony"><img src="/api/listings/abner-tungchi--cosmogony/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Install

npm install
cd mcp-server && npm install

Start the dev environment

# Terminal 1 — frontend (Vite :5173)
npm run dev

# Terminal 2 — MCP server (:3333)
cd mcp-server
npm run dev

Open http://localhost:5173/ to use it.

Build

npm run build               # frontend
cd mcp-server && npm run build   # MCP server

MCP setup (so Claude Code can connect)

Add to Claude Code's `.mcp.json`:

{
  "mcpServers": {
    "event-storming": {
      "command": "node",
      "args": ["/path/to/mcp-server/dist/index.js"]
    }
  }
}

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 316 lines
  1. **English** | [繁體中文](README.zh-TW.md)
  2. # Cosmogony
  3. > Every software system is a universe being born.
  4. We don't just write code — we bring a universe into existence. Each domain has its own laws of physics: invariants that must hold, rules that cannot be broken, and boundaries that define where one world ends and another begins.
  5. Event Storming is the act of cosmogony itself — the process by which we observe the primordial chaos of business requirements and discover the fundamental forces that give them structure. Events are the elementary particles. Commands are the forces that act upon them. Aggregates are the celestial bodies that emerge when those particles coalesce under the gravity of business rules.
  6. Just as the universe was not designed but emerged from a set of initial conditions and fundamental laws, a well-modeled domain is not invented — it is discovered. Cosmogony is the tool for that discovery.
  7. ---
  8. An **Event Storming whiteboard tool** for **Domain Experts** and **AI** to collaborate on. It supports humans drawing Event Storming diagrams on a canvas, and also lets AI manipulate the canvas directly through MCP tools. Diagrams can finally be exported as a **Spec Bundle** (JSON) that AI can consume to produce executable code.
  9. ---
  10. ## Table of Contents
  11. - [1. Project Goals](#1-project-goals)
  12. - [2. Core Concepts](#2-core-concepts)
  13. - [2.1 DomainEvent-Centric Design](#21-domainevent-centric-design)
  14. - [2.2 Aggregate and Invariant](#22-aggregate-and-invariant)
  15. - [2.3 Read Model](#23-read-model)
  16. - [2.4 Spec Bundle Export](#24-spec-bundle-export)
  17. - [3. 12 Element Types](#3-12-element-types)
  18. - [4. Architecture](#4-architecture)
  19. - [5. Quick Start](#5-quick-start)
  20. - [6. Key Features](#6-key-features)
  21. ---
  22. ## 1. Project Goals
  23. **Event Storming** is a visual collaboration method for exploring complex business domains. By placing sticky notes, domain experts and engineers jointly figure out:
  24. - **What happened** (DomainEvent)
  25. - **Who triggered it** (Actor / Command)
  26. - **Which entity handles it** (Entity / Aggregate)
  27. - **What rules apply** (Policy / Invariant)
  28. What makes this tool different:
  29. 1. **Not only for humans** — AI (Claude) can manipulate the canvas directly through the **MCP** protocol
  30. 2. **Exportable as structured Spec** — AI can read it and produce executable DDD/CQRS code
  31. 3. **Lightweight workshop spirit** — does not force users to fill in too many fields, supports progressive refinement
  32. **Who is it for?**
  33. - Domain Experts: clarify business processes, align with engineers
  34. - Architects / senior engineers: do DDD modeling
  35. - AI agents (Claude): auto-model or assist implementation
  36. ---
  37. ## 2. Core Concepts
  38. ### 2.1 DomainEvent-Centric Design
  39. In traditional Event Storming, Command, Event, and Entity are usually independent sticky notes. This tool uses a group design **anchored on DomainEvent**:
  40. ```
  41. DomainEvent (orange) ← Group anchor
  42. ├── commandId → Command (blue)
  43. │ └── informationForCommandId → Information (green)
  44. └── entityId → Entity (yellow) or Aggregate (gold border)
  45. ```
  46. - **DomainEvent is the group anchor** — dragging it moves the whole group together
  47. - **Command / Information / Entity are satellite notes**, carrying `groupEventId` pointing to the parent DomainEvent
  48. - **Collapsible into a Chip**: when the canvas gets crowded, the entire group can collapse into a 40px orange mini-card
  49. > 💡 **Why this design?**
  50. > The original 4-in-1 Bundle card locked four cells together, but in practice Command and Entity are shared across multiple DomainEvents. After switching to DomainEvent-Centric, the same Entity can be referenced by multiple DomainEvents, and Commands can be reused.
  51. ---
  52. ### 2.2 Aggregate and Invariant
  53. **Aggregate** is the "consistency boundary" in DDD, responsible for protecting business rules from being violated.
  54. In this tool:
  55. - **Once an Entity is marked as Aggregate Root**, the note **transforms directly into an Aggregate** (no new note is created)
  56. - Aggregate has a gold border + an `AR` badge in the upper-right corner
  57. - Multiple DomainEvents can share the same Aggregate via `entityId`
  58. **Aggregate Detail Panel** lets you define the full spec.
  59. #### Aggregate Spec Fields
  60. - **Identity**: the Aggregate's identity field (e.g. `orderId`), with a derived type suggestion (`OrderId`)
  61. - **State**: list of properties held by the Aggregate (name / type / required)
  62. - **Invariants**: business invariants (rules), grouped into three visual bands:
  63. - **CONFIRMED**: rules explicitly authored by the user (solid border, no fill)
  64. - **NEEDS REVIEW · AI-inferred**: candidate rules inferred by AI (dashed border, light yellow fill)
  65. - Each card carries `source.agent` / `source.rationale` (origin and reasoning)
  66. - Comes with three actions: `Approve` / `Edit` / `Reject`
  67. - **Rejected**: rejected rules (gray strikethrough, collapsible)
  68. #### Full Invariant Structure
  69. Each invariant contains:
  70. - `name`: semantic identifier (camelCase, e.g. `checkCancellable`), maps to the generated method name
  71. - `title`: human-readable label (e.g. "Shipped orders cannot be cancelled")
  72. - `applicability`: when this rule applies (optional, e.g. `customerStatus == .established`)
  73. - `rules`: **multiple conditional rules**, each with `when` + `rule`
  74. - `when`: condition (e.g. `status == .shipped`, or reserved keyword `always` / `never`)
  75. - `rule`: the behavior or state when violated (natural language or expression)
  76. - `errorCode`: error identifier when violated (e.g. `orderAlreadyShipped`)
  77. - `relatedState`: which state fields this rule touches
  78. > 💡 **Why is Invariant so complex?**
  79. > Because AI needs this information to produce stable code: `name` → method name, `applicability` → guard condition, `rules[].when` → if/switch branches, `errorCode` → which error to throw. Without these, AI generates different code every time.
  80. ---
  81. ### 2.3 Read Model
  82. **Read Model** represents the Query side of CQRS — describing "how to query data", separated from the Command side (Aggregate).
  83. It is rendered on the canvas as a **4-in-1 card**:
  84. ![Remodel Card](assets/screenshots/05-remodel-card.png)
  85. Three colored cells:
  86. | Cell | Color | Meaning | Example |
  87. |------|------|------|-----|
  88. | Left (Parameters) | Mint green | Query parameters | `customerId: CustomerId, from: Date` |
  89. | Middle (Func Name) | Blue-gray | Query function name | `getOrderSummary` |
  90. | Right (Return Type) | Mint green | Return data structure | `OrderSummaryDto[]` |
  91. **Detail Panel** uses a structured editor (not plain text):
  92. - **Parameters**: table editor (name / type / required)
  93. - **Return Type**:
  94. - `shape`: dropdown (object / array / primitive)
  95. - `fields`: each field has name / type / nullable / **dtoSpecRef** (can reference a Dto)
  96. - The sub-note content on the canvas is **auto-generated from the structured data** (edit a field → canvas updates live)
  97. #### Source Events (optional)
  98. A Read Model can be linked to DomainEvents, indicating "data is projected from these events". Expand the Source Events section to manage them.
  99. ---
  100. ### 2.4 Spec Bundle Export
  101. The end goal of the tool is to produce a **Spec Bundle**: a JSON document AI can consume to produce executable DDD/CQRS code.
  102. Two formats are supported:
  103. - **Markdown**: for humans to review (sections include DomainEvents / ReadModels / FlowPaths)
  104. - **JSON**: for AI to process (structured, includes derived fields)
  105. ### Bundle Structure
  106. ```json
  107. {
  108. "manifestVersion": 1,
  109. "bundleId": "...",
  110. "context": "OrderManagement",
  111. "aggregates": [AggregateSpec, ...],
  112. "useCases": [UseCaseSpec, ...],
  113. "readModels": [ReadModelSpec, ...],
  114. "dtos": [DtoSpec, ...]
  115. }
  116. ```
  117. ### Four Spec Types
  118. | Spec Type | DDD Concept | Question Answered |
  119. |-----------|------------|-------------|
  120. | **AggregateSpec** | Aggregate (consistency boundary) | What state does this Aggregate hold? What invariants? |
  121. | **UseCaseSpec** | Command + DomainEvent | Who initiates the action? What is the input? What event is produced? |
  122. | **ReadModelSpec** | Query / Projection | What data to query? What input/output format? |
  123. | **DtoSpec** | Data Transfer Object | What does the data structure look like? |
  124. ### Authored vs Derived (`_suggested_` prefix)
  125. To prevent AI from treating derived fields as user-asserted facts, every **name-derived** field in the Spec is prefixed with `_suggested_`:
  126. ```json
  127. {
  128. "aggregate": "Order", // ✅ Authored by the user, AI must trust
  129. "_suggested_aggregateId": "OrderId", // ⚠️ Naming derivation hint, AI may adjust per framework
  130. "_suggested_method": "Order.cancel", // ⚠️ Same as above
  131. "_suggested_repository": "OrderRepository" // ⚠️ Same as above
  132. }
  133. ```
  134. ---
  135. ## 3. 12 Element Types
  136. | Type | Color | Description |
  137. |------|------|------|
  138. | `DomainEvent` | orange | A domain event that has happened (group anchor) |
  139. | `Command` | blue | User intent / command (satellite note) |
  140. | `Information` | green | Input parameters of a Command (satellite note) |
  141. | `Entity` | yellow | The entity being operated on (satellite note) |
  142. | `Aggregate` | gold border | Aggregate Root (transformed from a marked Entity) |
  143. | `Actor` | light yellow | User / external role |
  144. | `Policy` | purple | Business rule / policy |
  145. | `ExternalSystem` | pink | External system |
  146. | `ReadModel` | dark green | Query view (legacy, replaced by Remodel 4-in-1) |
  147. | `Hotspot` | red | Issue point that needs discussion |
  148. | `Diamond` | pink | Decision diamond |
  149. | `Dto` | light green | Data transfer object (supports structured field definitions) |
  150. ---
  151. ## 4. Architecture
  152. ### Frontend — React + TypeScript (Vite)
  153. - **React** + **TypeScript**: component-based architecture, types flow through the whole project
  154. - **Vite**: lightning-fast HMR
  155. - **Zustand + immer**: state management with `persist` middleware (localStorage, currently v21) and version migration
  156. - **dnd-kit**: drag-and-drop sorting
  157. ### Backend — Node.js + TypeScript + Express
  158. - **Express**: lightweight HTTP server, exposes `/api/board` (POST), `/api/events` (SSE)
  159. - **MCP SDK** (`@modelcontextprotocol/sdk`): the protocol for AI to manipulate the canvas
  160. - **SSE** (Server-Sent Events): real-time push from MCP server to React
  161. ### Why share TypeScript between frontend and backend
  162. A single set of type definitions flows through the whole stack — MCP server and React speak the same language, reducing data-format conversion errors.
  163. ---
  164. ## 5. Quick Start
  165. ### Install
  166. ```bash
  167. npm install
  168. cd mcp-server && npm install
  169. ```
  170. ### Start the dev environment
  171. ```bash
  172. # Terminal 1 — frontend (Vite :5173)
  173. npm run dev
  174. # Terminal 2 — MCP server (:3333)
  175. cd mcp-server
  176. npm run dev
  177. ```
  178. Open http://localhost:5173/ to use it.
  179. ### Build
  180. ```bash
  181. npm run build # frontend
  182. cd mcp-server && npm run build # MCP server
  183. ```
  184. ### MCP setup (so Claude Code can connect)
  185. Add to Claude Code's `.mcp.json`:
  186. ```json
  187. {
  188. "mcpServers": {
  189. "event-storming": {
  190. "command": "node",
  191. "args": ["/path/to/mcp-server/dist/index.js"]
  192. }
  193. }
  194. }
  195. ```
  196. ---
  197. ## 6. Key Features
  198. ### 6.1 FlowPath Filtering
  199. Assign DomainEvents to a FlowPath (a named flow). When filtering is enabled, elements not on the path are dimmed, making it easier to focus on a single flow.
  200. ### 6.2 Group Collapse (Chip)
  201. When the canvas gets crowded, an entire DomainEvent group can be collapsed into a 40px Chip:
  202. - **Double-click** to expand
  203. - **Single-click** to select
  204. - Supports Link Mode connections
  205. ### 6.3 Link Mode
  206. With Link Mode enabled, you can drag an arrow between any two elements to express a semantic relationship (Actor → Command, Event → Policy, etc.).
  207. ### 6.4 MCP Integration (AI manipulates the canvas directly)
  208. AI (e.g. Claude Code) can use 40 MCP tools to directly:
  209. - Create / modify / delete notes and Remodels
  210. - Link elements
  211. - Batch-create a complete Event Storming flow
  212. - Assign FlowPath and Phase
  213. This lets AI play the role of "co-modeler" rather than just summarizing afterwards.
  214. ### 6.5 Dto Structured Fields + Nested References
  215. Dto notes support structured field definitions and can reference other Dtos (e.g. `OrderSummaryDto.lines: OrderLineDto[]`).
  216. The **REF picker** lists every Dto note on the current board (excludes itself, preventing circular references).
  217. ---
  218. ## License
  219. [MIT](LICENSE)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.