Diagram conventions

Diagrams share the site’s Paper and Charcoal appearances. Their visual language comes from Fieldnotes: ink rules, deliberate spacing, local type, and a restrained rust accent. A diagram explains one relationship or question at a time.

These seven examples demonstrate the documentation design. They are architectural illustrations, including intended stages, rather than verified instructions for a released engine. Technology labels are illustrative, not a compatibility matrix. Product behavior remains owned by the canonical engine sources.

Visual vocabulary

Treatment	Meaning	Source role
Paper fill, square ink outline	Ordinary stage, artifact, or participant	Default
Solid ink, paper label	Kernel responsibility, when ownership is the subject	core
Diagonal hatch, paper-backed label	Extension responsibility	extension
Rust outline and light tint	The single focal point of this figure	focus
Dashed outline and an explicit boundary label	External participant	external

Rust means “look here.” It does not encode success, failure, or a module category. Most diagrams need no focus; use at most one. State names, arrow labels, and captions carry meaning without relying on color. Connectors use ink and native arrowheads. A dashed sequence return remains distinct from a solid call.

Use Bricolage Grotesque for diagram labels. Compiler annotation rails use Martian Mono. Captions use Newsreader. Keep diagram labels at least 14 displayed pixels; the component provides local scrolling and a full-size view instead of shrinking a wide graph until its labels become unreadable.

Seven examples

Fig. 01 / The compiler's responsibilities

Flowchart / annotation rail

Extensions supply forms. The kernel owns composition. The rust stage is the subject of this view.

Stored inputs pass through parsing and model checks, extension lowering, kernel composition, later checks, and plan publication. This includes intended architectural stages.

Copy MermaidDownload sourceDownload SVGOpen full-size

Diagram loading. The description and source are available below.

Mermaid source

flowchart TB
  accTitle: The compiler's responsibilities
  accDescr: Stored inputs pass through parsing, binding, model rules, extension lowering, kernel composition, later checks, and plan publication. This is the architectural model, including intended stages.
  parse["Parse and bind"]
  model["Model rules"]
  lower["Extension lowerers"]
  compose["Rasterize and compose"]
  checks["Post-composition and diff"]
  rules["Cell and behavior rules"]
  writer["Publish plan directory"]
  parse --> model --> lower --> compose --> checks --> rules --> writer
  class parse,model,checks,rules,writer core
  class lower extension
  class compose focus
  %% rail parse | Read designs and resolve names
  %% rail model | Validate the bound model
  %% rail lower | Return forms in dependency order
  %% rail compose | Resolve forms into intended cells
  %% rail checks | Compare against stored inputs
  %% rail rules | Record findings about the result
  %% rail writer | Publish a reviewable artifact

Close full-size view

Fig. 02 / The plan is the handoff

Flowchart / artifacts

Rendering and applying read the plan. Reviewing a rendering does not authorize an apply.

Design files produce an immutable plan. One branch renders it for inspection; another reads it for applying through the sync mod. Other compilation inputs and transaction details are omitted.

Copy MermaidDownload sourceDownload SVGOpen full-size

Diagram loading. The description and source are available below.

Mermaid source

flowchart TB
  accTitle: The plan is the handoff
  accDescr: Design files compile into an immutable plan. Rendering reads the plan for inspection. Applying reads it and sends a plan transaction to the sync mod.
  design@{ shape: doc, label: "Design files" }
  plan@{ shape: doc, label: "Immutable plan" }
  views["Rendered views"]
  apply["ae apply"]
  sync_mod["Sync mod"]
  design -->|ae plan| plan
  plan -->|ae render| views
  plan -->|reads| apply
  apply -->|plan transaction| sync_mod
  class apply focus
  class sync_mod external

Close full-size view

Fig. 03 / Arrows point to the provider

Flowchart / dependencies

A dependency arrow runs from the consumer to its provider. The edge label makes the convention explicit.

The engine depends on extension-api and types; extension-api also depends on types. This is a selected subset, not the complete module table.

Copy MermaidDownload sourceDownload SVGOpen full-size

Diagram loading. The description and source are available below.

Mermaid source

flowchart TB
  accTitle: Selected engine dependencies
  accDescr: The engine depends on extension-api and types. Extension-api also depends on types. Arrows point to the dependency. Other permitted dependencies are omitted.
  engine["engine"]
  api["extension-api"]
  types["types"]
  engine -->|depends on| api
  engine -->|depends on| types
  api -->|depends on| types

Close full-size view

Fig. 04 / Lowering sits inside compilation

Sequence

Lowerers return forms to the engine. They do not write world cells.

The CLI asks the engine to plan. The engine invokes extensions in dependency order, receives forms, finishes compilation, and publishes the plan directory.

Copy MermaidDownload sourceDownload SVGOpen full-size

Diagram loading. The description and source are available below.

Mermaid source

sequenceDiagram
  accTitle: Lowering inside compilation
  accDescr: The CLI asks the engine to plan. The engine calls extension lowerers in dependency order. Extensions return forms. The engine completes later compilation stages and writes the plan to site files.
  participant cli as ae plan
  participant engine as Engine
  participant extensions as Extensions
  participant site as Site files
  %% role engine core
  %% role extensions extension
  cli->>engine: Plan site
  engine->>extensions: Lower in dependency order
  extensions-->>engine: Forms
  engine->>engine: Compose, diff, check rules
  engine->>site: Publish plan directory

Close full-size view

Fig. 05 / A receipt records the known outcome

State diagram

A prepared receipt records a known outcome. A later completed rollback can mark a done receipt as rolled_back.

Prepared can become done when completion is reported or failed when failure is recorded. Done becomes rolled_back only after a later rollback completes. Abbreviated arrows omit the full transaction conditions.

Copy MermaidDownload sourceDownload SVGOpen full-size

Diagram loading. The description and source are available below.

Mermaid source

stateDiagram-v2
  accTitle: Receipt states
  accDescr: A receipt starts prepared. It may become done or failed. A done receipt becomes rolled_back when a completed later rollback undoes it. The caption defines the abbreviated transition conditions.
  direction TB
  [*] --> prepared: Receipt prepared
  prepared --> done: Done reported
  prepared --> failed: Failure recorded
  done --> rolled_back: Rollback done
  class rolled_back focus

Close full-size view

Fig. 06 / The engine meets the server at a boundary

C4 / reviewed exports

The engine connects the CLI, extension inputs, site artifacts, and sync mod. The server boundary is this view's focus.

The CLI calls the engine. The engine exchanges snapshots and transactions with the sync mod, uses extension and block-pack inputs, and reads and writes site files. The technology labels reproduce the approved design example, not a release support promise.

Copy MermaidDownload sourceDownload SVGOpen full-size

Diagram loading. The description and source are available below.

Mermaid source

C4Container
  Container(cli, "ae CLI", "Java 25", "Commands and output")
  Container(engine, "Engine", "Java 25", "Compile, render, apply client")
  Container(mod, "Sync mod", "Fabric, Java 17", "Snapshots and transactions")
  Container(ext, "Extensions and block packs", "Jars and JSON", "Element kinds and block facts")
  ContainerDb(site, "Site directory", "Files in git", "Designs, plans, receipts, index")
  Rel(cli, engine, "calls")
  Rel(engine, mod, "snapshots and transactions", "HTTP JSON")
  Rel(engine, ext, "plan loads code; apply reads pack data")
  Rel(engine, site, "reads and writes")
  UpdateLayoutConfig($c4ShapeInRow="3", $c4BoundaryInRow="1")
  UpdateElementStyle(engine, $bgColor="AE_INK", $fontColor="AE_PAPER", $borderColor="AE_INK")
  UpdateElementStyle(mod, $bgColor="AE_TINT", $fontColor="AE_INK", $borderColor="AE_RUST")
  %% Relationship offsets are specific to this view and renderer.
  UpdateRelStyle(cli, engine, $textColor="AE_INK", $lineColor="AE_INK", $offsetX="-15", $offsetY="-16")
  UpdateRelStyle(engine, mod, $textColor="AE_INK", $lineColor="AE_INK", $offsetX="-92", $offsetY="-86")
  UpdateRelStyle(engine, ext, $textColor="AE_INK", $lineColor="AE_INK", $offsetX="-150", $offsetY="28")
  UpdateRelStyle(engine, site, $textColor="AE_INK", $lineColor="AE_INK", $offsetX="45", $offsetY="28")

Close full-size view

Fig. 07 / A blocking finding gates apply

Flowchart / decision

A published plan can contain a blocking finding. Publishing it does not make it eligible to apply.

If a blocking finding exists, apply is refused. Otherwise the remaining apply checks continue. This figure shows one gate, not the whole apply procedure.

Copy MermaidDownload sourceDownload SVGOpen full-size

Diagram loading. The description and source are available below.

Mermaid source

flowchart TB
  accTitle: Blocking findings gate apply
  accDescr: A plan with a blocking finding can be published. If a blocking finding is present, apply is refused. Otherwise the other apply checks continue. This is not the whole apply procedure.
  plan["Published plan"]
  blocking{"Blocking finding?"}
  refuse["Apply refused"]
  continue_checks["Continue apply checks"]
  plan --> blocking
  blocking -->|Yes| refuse
  blocking -->|No| continue_checks
  class refuse focus

Close full-size view

Author a figure

Keep one .mmd source in src/diagrams/. Import it with ?raw from an MDX article and pass it to the shared Diagram.astro component. Supply a unique page-local id, a title, a caption that explains the implication, and a plain-text summary that conveys the relationships without the drawing. Give the family in kind. Keep source free of HTML, links, initialization directives, and local color styles. The shared renderer uses strict security and SVG text.

In flowcharts, assign the semantic classes with class compose focus or class lower extension. Keep the underlying shape meaningful: documents are artifacts, diamonds are questions, and rectangular stages are actions. Use accTitle and accDescr in the Mermaid source as well as the figure description.

For a simple top-to-bottom pipeline, declare every stage on its own line as parse["Parse and bind"] and add %% rail parse | Read designs and resolve names. The adapter gives these stages 280 by 56 geometry, left-aligned labels, 24-pixel rank gaps, and a separate annotation rail. Use this extension only for a single unbranched chain of rectangular stages, with one short note per stage.

In sequence diagrams, declare participants with aliases, then add %% role engine core or %% role extensions extension. The adapter applies ink or hatching to those participants. State diagrams retain centered labels; the pipeline’s left alignment does not apply to states.

The source download contains the semantic Mermaid definition. The Fieldnotes theme and SVG adapter are part of its rendering environment; another Mermaid viewer will show the relationships but may not reproduce this treatment. SVG downloads retain the current appearance. They contain live text; install the Fieldnotes fonts when using them outside this site.

C4 figures use a reviewed Paper/Charcoal export pair and their matching source. Changes require reviewing both exports; the site does not silently reflow their relationship labels. The contributor snapshot records the provenance and refresh procedure in design/fieldnotes/README.md.