Boxes with opinions: block, packet, treemap, and friends

Three ideas run the whole show. columns N sets the grid width; blocks fill it left to right, wrapping to new rows. A suffix like :2 makes a block span columns. And space (or space:2) is an invisible block - your alignment tool.

block-beta
  columns 3
  a["Sources"] b["Platform"] c["Consumers"]
  d["Batch lane"]:2 e["Stream lane"]
  space f["You choose the grid"] space

• Row wrapping is automatic: with columns 3, the 4th block starts row two. Count as you write.
• Spans eat columns: d["Batch lane"]:2 takes two cells, so only one cell remains in that row.
• Shapes carry over from flowcharts: x[("db")] cylinder, x(["pill"]), x{"decision"} all work here.
• Nesting: block:ID ... end makes a composite block containing its own mini-grid - a group border without a subgraph.

The classic use: a platform poster where column one is sources, column two is the platform, column three is consumers. Edges still exist (-->, with labels as a-- "text" -->b), but layout no longer reflows when you add one - the grid holds.

block-beta
  columns 3
  hdr["Nova data platform"]:3
  ev["App events"] ing["Ingestion"] bi["Dashboards"]
  crm["CRM export"] qa["Quality checks"] ml["ML features"]
  space dw[("Warehouse")] space
  ev --> ing
  crm --> ing
  ing --> qa
  qa-- "pass" -->dw
  dw --> bi
  dw --> ml
  style hdr fill:#FFD9E6,stroke:#D6246E

• Beta: current docs have started writing plain block; both block and block-beta parse in v11. This page uses block-beta, which works across all v11 releases.
• Arrows don't route politely. Edges draw fairly straight lines between cells - if they cross a block, rearrange the grid, not the edge.
• Never name a block end - it closes composite blocks. Same reserved-word trap as flowcharts.
• Miscounted rows are the #1 bug: a forgotten space shifts everything after it one cell left. When the poster looks drunk, count cells per row first.

Each line is start-end: "Field name" in bit positions; rows wrap every 32 bits automatically. Since v11.7 you can also write +8: "Field" and let mermaid count on from wherever the previous field ended - much kinder when a design is still moving.

---
title: "Nova event envelope (header)"
---
packet-beta
0-7: "Version"
8-15: "Event type"
16-31: "Tenant ID"
32-63: "Event timestamp"
64-95: "User ID hash"
96-111: "Payload length"
112-127: "Checksum"

• Ranges are inclusive: 0-7 is eight bits. Off-by-one here means your doc lies about the wire format.
• Auto-counting: +16: "Tenant ID" starts where the previous field stopped; you can mix +n and explicit ranges freely.
• Single bits: just 106: "ACK" - one number, no range. Great for flag bits.

• Beta: introduced v11.0 as packet-beta; current docs write plain packet. Both parse in v11 - this page sticks with the widely compatible form.
• Gaps are errors: fields must be contiguous. Skip bits 40-47 and the parser complains - pad with a "Reserved" field like real RFCs do.
• It only does layout, not meaning: no types, no endianness, no units. Put those in a table next to the diagram.
• Long labels squeeze: a 4-bit field with a 30-character name gets unreadable. Abbreviate, expand in prose.

Quoted names are nodes; indentation nests them; "Leaf": value sets the size. That's the whole grammar. Tag a node with :::class and style it with a classDef - handy for pointing at the elephant.

treemap-beta
"Nova warehouse (GB)"
    "Events domain"
        "Page views": 420:::hot
        "Clicks": 310
        "Sessions": 120
    "CRM domain"
        "Accounts": 80
        "Contacts": 60
    "ML features"
        "Feature store": 150
        "Training sets": 90

classDef hot fill:#D6246E,color:#FFEFF5,stroke:#8E1146;

• Parents don't take values - they sum their children. Give a parent its own number and the picture stops being trustworthy.
• valueFormat (frontmatter config) formats numbers with d3 specifiers: '$0,0' for cost treemaps, '.1%' for shares.
• Depth discipline: two levels read instantly, three is the ceiling. Deeper than that, link out to a second treemap.

• Genuinely new: the docs warn the syntax "may evolve in future versions". Fine for living docs; risky for anything you'll print and frame.
• Indentation is load-bearing - a leaf indented one level too far silently changes the hierarchy. Diff carefully.
• Tiny values vanish: a 2 GB slice next to a 420 GB slice renders as a sliver with no readable label. Group small stuff into "Other".
• No negatives - treemaps size by area, and negative area isn't a thing.
• Cousin worth knowing: a venn diagram type also exists in recent releases - even newer than treemap, so we mention it and move on. Watch the release notes.

Two building blocks. A requirement has an id, text, a risk (low, medium, high) and a verifymethod (analysis, inspection, test, demonstration). An element is anything real - a DAG, a test suite, a doc. Relationships connect them: {source} - <type> -> {destination} where type is one of contains, copies, derives, satisfies, verifies, refines, traces.

requirementDiagram

requirement freshness {
  id: "DQ-1"
  text: "Warehouse tables refresh within 60 minutes"
  risk: high
  verifymethod: test
}

functionalRequirement no_null_ids {
  id: "DQ-2"
  text: "Customer ID is never null after ingestion"
  risk: medium
  verifymethod: inspection
}

element quality_checks {
  type: "dbt test suite"
  docref: "nova/dbt/tests"
}

element ingestion_job {
  type: "Airflow DAG"
  docref: "nova/dags/ingest"
}

quality_checks - verifies -> freshness
ingestion_job - satisfies -> no_null_ids
freshness - traces -> no_null_ids

• Six requirement flavors: requirement, functionalRequirement, interfaceRequirement, performanceRequirement, physicalRequirement, designConstraint. For DQ work the first two carry most of the load.
• satisfies vs verifies is the useful distinction: the ingestion job SATISFIES the rule (it does the work); the test suite VERIFIES it (it proves the work happened).
• Quote free text - names, text and docrefs can go unquoted, but the parser fails if it smells a keyword. Quotes end the guessing.

• Layout is take-it-or-leave-it: big requirement webs get tangled. Split by domain (one diagram per data product) before you hit ten nodes.
• The enums are closed lists - risk: critical is a parse error. Map your own severity scale onto low/medium/high.
• The arrow is fussy: it's - satisfies -> with single hyphens, not the flowchart's -->. Muscle memory will betray you exactly once per session.
• It documents intent, not status - nothing turns red when a test fails. Pair it with your observability stack; this is the map, not the alarm.