Module: Hecks::Projections::Diagrams

Extended by:
Hecks::Projector::Target
Defined in:
lib/hecks/projections/diagrams.rb

Overview

A DOMAIN'S OWN SHAPE, PROJECTED AS MERMAID DIAGRAMS — the same trick Projections::Reference/DocsProjector already play for prose, one level further: a diagram generated FROM the declaration can't drift from it the way a hand-drawn one inevitably does, because there is no second copy to forget to update.

MERMAID, NOT GRAPHVIZ (the two considered) — every diagram type below has a Mermaid form purpose-built for exactly what the underlying construct already is (a lifecycle IS a state machine, has_many/belongs_to already speaks in cardinality, emits/trigger already IS a directed graph), and the output is plain text that renders natively wherever this project's own docs already live — GitHub markdown, this repo's generated docs, Claude Artifacts — with no build step and no external binary. Graphviz's DOT format needs an actual render step (a dot binary, or a WASM port) to become anything viewable, which is a real dependency this repository's own discipline (see rust/parser's Cargo.toml: "no dependency earns its way past std") would rather not take just to draw a diagram.

FOUR DIAGRAM KINDS, one file each per domain except lifecycles (one per lifecycle-bearing construct, since that's how a reader actually reaches for it — looking at ONE aggregate's states, not every aggregate's at once):

<Name>_lifecycle.mmd  stateDiagram-v2  one per lifecycle
relationships.mmd     erDiagram        the whole domain's has_many/
                                     has_one/belongs_to/reference_to
dispatch.mmd          flowchart        the whole domain's command
                                     emits -> policy trigger chains
roles.mmd             flowchart        every role that issues a
                                     command, wired to every
                                     command it issues
ports.mmd             flowchart        every port operation, which
                                     aggregate exposes it, which
                                     aggregate it routes to: (if
                                     any), and what it emits
read_models.mmd       flowchart        every read_model, and every
                                     aggregate it's assembled
                                     from — the read-side
                                     complement to relationships.mmd
<Name>_surface.mmd    flowchart        one per aggregate/entity that
                                     declares at least one command
                                     or query — everything you can
                                     DO to it and ASK about it,
                                     in one place

CONSTRUCT NAMES (aggregate/entity/command/event) ARE USED BARE, UNSANITIZED, as Mermaid node/entity ids — safe because this language's own word grammar only ever admits simple CamelCase/ snake_case identifiers there (confirmed: no space or punctuation appears in any real aggregate/command/event name across the corpus this projects from). A role: STRING IS FREE TEXT, though — the real corpus already has "Back office"/"Vault officer"/"Branch clerk" — so roles.mmd is the one diagram here that sanitizes a name into an id (role_id) while keeping the real string as the node's own displayed label.

Class Method Summary collapse

Methods included from Hecks::Projector::Target

projection_declares, projection_emits, projection_key, projection_requires, projects_as

Class Method Details

.call(bluebook:, options: {}) ⇒ Object 



70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
 
# File 'lib/hecks/projections/diagrams.rb', line 70

def call(bluebook:, options: {})
  files = {}

  holders_with_lifecycle(bluebook).each do |holder|
    files["#{holder.hecks_name}_lifecycle.mmd"] = lifecycle_diagram(bluebook, holder)
  end

  if (diagram = relationship_diagram(bluebook))
    files["relationships.mmd"] = diagram
  end

  if (diagram = dispatch_diagram(bluebook))
    files["dispatch.mmd"] = diagram
  end

  if (diagram = roles_diagram(bluebook))
    files["roles.mmd"] = diagram
  end

  if (diagram = ports_diagram(bluebook))
    files["ports.mmd"] = diagram
  end

  if (diagram = read_model_diagram(bluebook))
    files["read_models.mmd"] = diagram
  end

  holders(bluebook).each do |holder|
    next if holder.commands.empty? && holder.queries.empty?

    files["#{holder.hecks_name}_surface.mmd"] = surface_diagram(bluebook, holder)
  end

  files
end

.command_node(aggregate_name, command_name) ⇒ Object 



236
237
238
 
# File 'lib/hecks/projections/diagrams.rb', line 236

def command_node(aggregate_name, command_name)
  %(cmd_#{aggregate_name}_#{command_name}(["#{aggregate_name}.#{command_name}"]))
end

.dispatch_diagram(bluebook) ⇒ Object

A COMMAND NODE, STADIUM-SHAPED ((["..."])); AN EVENT NODE, HEXAGONAL ({{"..."}}) — one visual vocabulary for "a thing someone does" versus "a fact that happened", matching the language's own verb/event distinction. Command ids are qualified by their owning aggregate (cmd_Order_Purchase) since two aggregates may share a command name; event ids are bare (evt_PizzaCreated) since an event is this domain's own addressing key, the same way policy.on_event reaches it.



196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
 
# File 'lib/hecks/projections/diagrams.rb', line 196

def dispatch_diagram(bluebook)
  lines = []

  holders(bluebook).each do |holder|
    holder.commands.each do |command|
      command.emits.each { |event| lines << emits_edge(holder, command, event) }
    end
  end

  bluebook.policies.each { |policy| lines << trigger_edge(policy) }

  lines.compact!
  return nil if lines.empty?

  subject = "#{bluebook.name}'s own declared commands' emits and policies' on/trigger"
  "#{header(bluebook.name, subject)}flowchart LR\n#{lines.uniq.join("\n")}\n"
end

.emits_edge(holder, command, event) ⇒ Object 



214
215
216
 
# File 'lib/hecks/projections/diagrams.rb', line 214

def emits_edge(holder, command, event)
  %(    #{command_node(holder.hecks_name, command.hecks_name)} -->|emits| #{event_node(event)})
end

.event_node(event_name) ⇒ Object 



240
 
# File 'lib/hecks/projections/diagrams.rb', line 240

def event_node(event_name) = %(evt_#{event_name}{{"#{event_name}"}})

.header(chapter_name, subject) ⇒ Object

chapter_name DRIVES THE RE-RUN HINT ALWAYS — that's the one argument bin/project_diagrams actually takes, regardless of which single aggregate/entity subject happens to name. Passing the wrong one here once already produced a real, committed Order_lifecycle.mmd telling a reader to run bin/project_diagrams <domain-path> Order — a chapter name Hecks.boot has never heard of.



127
128
129
130
131
132
 
# File 'lib/hecks/projections/diagrams.rb', line 127

def header(chapter_name, subject)
  <<~HEADER
    %% GENERATED by bin/project_diagrams from #{subject} — DO NOT EDIT BY HAND.
    %% Re-run `bin/project_diagrams <domain-path> #{chapter_name}` after any change.
  HEADER
end

.holders(bluebook) ⇒ Object

AN ENTITY CAN CARRY ITS OWN LIFECYCLE, RELATIONSHIP, OR COMMAND TOO — its own lifecycle/reference_to/command block, addressed through its holding aggregate the same way DocsProjector already treats an aggregate and its entities alike. Walking both here means a domain's entity gaining any of these needs no change to this file.



114
115
116
 
# File 'lib/hecks/projections/diagrams.rb', line 114

def holders(bluebook)
  bluebook.aggregates.flat_map { |aggregate| [aggregate, *aggregate.entities] }
end

.holders_with_lifecycle(bluebook) ⇒ Object 



118
 
# File 'lib/hecks/projections/diagrams.rb', line 118

def holders_with_lifecycle(bluebook) = holders(bluebook).select(&:lifecycle)

.lifecycle_diagram(bluebook, holder) ⇒ Object

── lifecycle -> stateDiagram-v2 ─────────────────────────────────



136
137
138
139
140
141
142
143
144
145
146
147
148
 
# File 'lib/hecks/projections/diagrams.rb', line 136

def lifecycle_diagram(bluebook, holder)
  lifecycle = holder.lifecycle
  edges = lifecycle.transitions.flat_map do |command_name, transition|
    Array(transition.from).map { |from_state| "    #{from_state} --> #{transition.target}: #{command_name}" }
  end

  subject = "#{holder.hecks_name}'s own declared lifecycle (field: #{lifecycle.field})"
  <<~MERMAID
    #{header(bluebook.name, subject)}stateDiagram-v2
        [*] --> #{lifecycle.default}
    #{edges.join("\n")}
  MERMAID
end

.port_edges(holder, port, operation) ⇒ Object 



311
312
313
314
315
316
317
 
# File 'lib/hecks/projections/diagrams.rb', line 311

def port_edges(holder, port, operation)
  op = port_operation_node(holder.hecks_name, port.name, operation.hecks_name)
  edges = ["    #{holder.hecks_name}[(#{holder.hecks_name})] -.->|exposes| #{op}"]
  edges << "    #{op} -->|to: #{operation.to}| #{operation.to}[(#{operation.to})]" if operation.to
  operation.emits.each { |event| edges << "    #{op} -->|emits| #{event_node(event)}" }
  edges
end

.port_operation_node(aggregate_name, port_name, operation_name) ⇒ Object 



319
320
321
322
 
# File 'lib/hecks/projections/diagrams.rb', line 319

def port_operation_node(aggregate_name, port_name, operation_name)
  id = "op_#{aggregate_name}_#{port_name}_#{operation_name}"
  %(#{id}[/"#{port_name}.#{operation_name}"/])
end

.ports_diagram(bluebook) ⇒ Object

A PORT OPERATION IS A BOUNDARY TRANSLATION, NOT A VERB OR A FACT — its own reference page says so plainly ("the builder behind it defines no given or sets, so an operation cannot read aggregate state or mutate a record itself"), so it gets a third shape, a trapezoid, beside dispatch.mmd's stadium/hexagon vocabulary. An aggregate drawn as a to: target is a cylinder — state landing somewhere, the same reason a data store gets one in an ordinary flowchart.

TWO EDGE KINDS PER OPERATION: a dotted "exposes" edge from the aggregate the port hangs off (always present — a port always belongs to exactly one aggregate), and a solid "to:" edge to whichever aggregate the operation itself names as its receiver (present only when to: is declared — PR #351's own real addition; before it, this data didn't exist to draw at all). emits reuses dispatch.mmd's own event_node unchanged — the same fact, reached from a different direction.

bluebook.aggregates, NOT the shared holders — unlike a lifecycle/relationship/command, a port belongs to an AGGREGATE only; an entity has no ports method at all (confirmed: calling it raises, it isn't just always empty), so walking entities here the way every other diagram in this file does would crash on the first entity-bearing domain.



300
301
302
303
304
305
306
307
308
309
 
# File 'lib/hecks/projections/diagrams.rb', line 300

def ports_diagram(bluebook)
  lines = bluebook.aggregates.flat_map do |holder|
    holder.ports.flat_map { |port| port.operations.map { |operation| port_edges(holder, port, operation) } }
  end.flatten

  return nil if lines.empty?

  subject = "#{bluebook.name}'s own declared port operations (which aggregate exposes each, its to:, and its emits)"
  "#{header(bluebook.name, subject)}flowchart LR\n#{lines.uniq.join("\n")}\n"
end

.query_node(aggregate_name, query_name) ⇒ Object 



408
409
410
 
# File 'lib/hecks/projections/diagrams.rb', line 408

def query_node(aggregate_name, query_name)
  %(qry_#{aggregate_name}_#{query_name}{"#{aggregate_name}.#{query_name}"})
end

.read_model_diagram(bluebook) ⇒ Object

THE READ-SIDE COMPLEMENT TO relationships.mmd — that diagram shows how aggregates reference each other for WRITES (has_many/belongs_to/reference_to); this shows how a read_model ASSEMBLES data for READS, from aggregate_heads — the same list where/group_by/order_by all operate over, and the one fact every read_model has regardless of whether it's rooted (reference_target) or gathers heads with no root at all (a rootless read model, real in the corpus: AccountsByKind).

A READ MODEL IS A SUBROUTINE SHAPE ([[...]], "a predefined process") — a fourth shape, beside ports.mmd's trapezoid and dispatch.mmd's stadium/hexagon: not a verb, not a fact, not a boundary translation, but a standing, reusable view. Every aggregate it draws from is a cylinder — the same "state lands somewhere" shape ports.mmd's to: target already uses, and the same bare id, so an aggregate feeding several read_models (real in banking: Account feeds four) merges into one node across the whole diagram.

THE LABEL NAMES THE SHAPE OF THE ANSWER, NOT JUST THE NAME — (count)/(median: field) for the two real aggregations in the corpus, nothing appended for an ordinary row-returning read_model. Still MVP scope: where/group_by/order_by aren't drawn at all yet — real facts, not invented, just not this diagram's job yet.



352
353
354
355
356
357
358
 
# File 'lib/hecks/projections/diagrams.rb', line 352

def read_model_diagram(bluebook)
  lines = bluebook.read_models.flat_map { |read_model| read_model_edges(read_model) }
  return nil if lines.empty?

  subject = "#{bluebook.name}'s own declared read_models and the aggregates each is assembled from"
  "#{header(bluebook.name, subject)}flowchart LR\n#{lines.uniq.join("\n")}\n"
end

.read_model_edges(read_model) ⇒ Object 



360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
 
# File 'lib/hecks/projections/diagrams.rb', line 360

def read_model_edges(read_model)
  shape = read_model.to_h
  node = %(rm_#{shape[:name]}[["#{read_model_label(shape)}"]])
  Array(shape[:aggregate_heads]).map do |head|
    # QUOTED, NOT BARE — an edge label containing `[` or `]`
    # (`accounts[]`, marking the "many" side) breaks Mermaid's own
    # `|label|` parser outright if left unquoted: it reads the
    # `[` as the START OF A NEW NODE SHAPE mid-label, not text.
    # Confirmed live against the real parser before this quoting
    # existed — every OTHER edge label in this file happens to be
    # a bare word or already-quoted string, so this is the one
    # spot that needed it.
    label = head[:many] ? "#{head[:as]}[]" : head[:as]
    %(    #{head[:aggregate]}[(#{head[:aggregate]})] -->|"#{label}"| #{node})
  end
end

.read_model_label(shape) ⇒ Object 



377
378
379
380
381
382
 
# File 'lib/hecks/projections/diagrams.rb', line 377

def read_model_label(shape)
  return "#{shape[:name]} (count)" if shape[:count]
  return "#{shape[:name]} (median: #{shape[:median_field]})" if shape[:median_field]

  shape[:name]
end

.relationship_diagram(bluebook) ⇒ Object

STANDARD CROW'S-FOOT READING, the same convention every ORM's own ERD generator (Rails' erd gem included) already uses: has_many/has_one are read from the OWNING side — one Holder relates to many/one Target. belongs_to/reference_to are read from the TARGET's side instead — one Target can be pointed at by MANY Holders — because a bare reference carries no promise about how many holders point back at it; "many" is the honest default absent a declared uniqueness rule this language doesn't expose. optional? only ever softens the side that can genuinely be absent (a nilable reference, an empty has_one) — never the crow's-foot "many" marker, which is a structural fact independent of any one instance's optionality.



164
165
166
167
168
169
170
171
172
 
# File 'lib/hecks/projections/diagrams.rb', line 164

def relationship_diagram(bluebook)
  edges = holders(bluebook).flat_map do |holder|
    holder.attributes.select(&:reference?).map { |attribute| relationship_edge(holder, attribute) }
  end
  return nil if edges.empty?

  subject = "#{bluebook.name}'s own declared reference_to/belongs_to/has_many/has_one attributes"
  "#{header(bluebook.name, subject)}erDiagram\n#{edges.join("\n")}\n"
end

.relationship_edge(holder, attribute) ⇒ Object 



174
175
176
177
178
179
180
181
182
183
184
 
# File 'lib/hecks/projections/diagrams.rb', line 174

def relationship_edge(holder, attribute)
  target = attribute.type.target_name
  case attribute.relationship
  when "has_many"
    %(    #{holder.hecks_name} ||--o{ #{target} : "#{attribute.name}")
  when "has_one"
    %(    #{holder.hecks_name} ||--#{attribute.optional? ? 'o|' : '||'} #{target} : "#{attribute.name}")
  when "belongs_to", "reference_to"
    %(    #{target} #{attribute.optional? ? '|o' : '||'}--o{ #{holder.hecks_name} : "#{attribute.name}")
  end
end

.role_edge(holder, command) ⇒ Object 



261
262
263
 
# File 'lib/hecks/projections/diagrams.rb', line 261

def role_edge(holder, command)
  %(    #{role_node(command.role)} -->|issues| #{command_node(holder.hecks_name, command.hecks_name)})
end

.role_id(role_name) ⇒ Object

A ROLE NAME IS FREE TEXT ("Back office", "Vault officer") — unlike every other name this file uses as a bare id, this one has to be sanitized to become a legal Mermaid identifier. The real string still appears as the node's own label (role_node); only the id is mangled.



272
 
# File 'lib/hecks/projections/diagrams.rb', line 272

def role_id(role_name) = "role_#{role_name.to_s.gsub(/[^A-Za-z0-9]+/, '_')}"

.role_node(role_name) ⇒ Object 



265
 
# File 'lib/hecks/projections/diagrams.rb', line 265

def role_node(role_name) = %(#{role_id(role_name)}((#{role_name})))

.roles_diagram(bluebook) ⇒ Object

WHO ISSUES WHAT, ACROSS THE WHOLE DOMAIN — data no existing projection draws at all today (the reference pages' own command_entry only ever prints a command's role as a single line of prose, never assembled across commands). A command with no declared role draws nothing — there is no fact to state. Circle-shaped so a role reads as "who" beside dispatch.mmd's stadium ("what someone does") and hexagon ("what happened").



251
252
253
254
255
256
257
258
259
 
# File 'lib/hecks/projections/diagrams.rb', line 251

def roles_diagram(bluebook)
  lines = holders(bluebook).flat_map do |holder|
    holder.commands.select(&:role).map { |command| role_edge(holder, command) }
  end
  return nil if lines.empty?

  subject = "#{bluebook.name}'s own declared command roles"
  "#{header(bluebook.name, subject)}flowchart LR\n#{lines.uniq.join("\n")}\n"
end

.surface_diagram(bluebook, holder) ⇒ Object

"WHAT CAN I DO TO THIS, WHAT CAN I ASK ABOUT IT" — one file per holder, unlike every other diagram here: dispatch.mmd already shows a command's own onward reaction chain, but never an aggregate's own FULL command/query menu in one place, and roles.mmd shows who issues a command without saying what else that same aggregate answers. This is the one diagram meant to be read starting from the aggregate, not from a verb or a fact.

A QUERY IS A DIAMOND — a fifth shape, beside dispatch.mmd's stadium/hexagon, ports.mmd's trapezoid, and read_models.mmd's subroutine: a question with an answer, not a verb that changes anything. Command edges are solid ("does"); query edges are dotted ("asks") — the same solid/dotted split ports.mmd already uses for "routes to:" versus "exposes".



400
401
402
403
404
405
406
 
# File 'lib/hecks/projections/diagrams.rb', line 400

def surface_diagram(bluebook, holder)
  lines = holder.commands.map { |command| "    #{holder.hecks_name}[(#{holder.hecks_name})] -->|does| #{command_node(holder.hecks_name, command.hecks_name)}" }
  lines += holder.queries.map { |query| "    #{holder.hecks_name}[(#{holder.hecks_name})] -.->|asks| #{query_node(holder.hecks_name, query.hecks_name)}" }

  subject = "#{holder.hecks_name}'s own declared commands and queries"
  "#{header(bluebook.name, subject)}flowchart LR\n#{lines.uniq.join("\n")}\n"
end

.trigger_edge(policy) ⇒ Object

on_event IS SOMETIMES AGGREGATE-QUALIFIED ("Account.AccountFrozen") AND SOMETIMES BARE ("CustomerSuspended") in the real corpus — emits never is, so this always matches against the bare tail, the same normalization a reader has to do by eye today.

A TRIGGER CROSSING INTO ANOTHER DOMAIN (policy.target_domain) still draws — the target command just has no incoming emits edge of its own here, which honestly shows "dispatch continues elsewhere" rather than silently dropping the edge. The label names which domain, so that's not a dead end on the page either.



229
230
231
232
233
234
 
# File 'lib/hecks/projections/diagrams.rb', line 229

def trigger_edge(policy)
  bare_event = policy.on_event.to_s.split(".").last
  aggregate_name, command_name = policy.trigger_command.to_s.split(".", 2)
  label = policy.target_domain ? "triggers in #{policy.target_domain}" : "triggers"
  %(    #{event_node(bare_event)} -->|#{label}| #{command_node(aggregate_name, command_name)})
end