recon_gen.common.handbook.diagrams

Diagram render pipeline for the unified mkdocs site.

Three diagram families:

L2-driven topology (render_l2_topology) — accounts + rails + chains laid out from the loaded L2Instance. Cuts: accounts (account-rail-account edges), chains (parent → child DAG over rails / transfer templates), layered (both, layered).
Per-app dataflow (render_dataflow) — which datasets feed which sheets, walked off the typed App tree. One per app’s reference page.
Hand-authored conceptual (render_conceptual) — reads a .dot file from docs/_diagrams/conceptual/. Used for the narrative concept pages where the diagram is a teaching aid that doesn’t derive from any L2 data (double-entry, escrow-with-reversal, sweep-net-settle, etc.).

All three return the DOT source string; the mkdocs-macros diagram(...) macro wraps it in <script type="text/x-graphviz"> inside a <figure> and stylesheets/qs-graphviz-wasm.js renders it client-side via @hpcc-js/wasm-graphviz. No system dot binary is invoked at build time (Phase T migration).

Functions

`render_conceptual`(name)	Render a hand-authored `.dot` file from the conceptual catalog.
`render_dataflow`(app_name)	Render which datasets feed which sheets for `app_name`.
`render_l2_account_focus`(l2_instance)	Render the first singleton Account with its parent edge (if any).
`render_l2_account_template_focus`(l2_instance)	Render the first AccountTemplate with its parent singleton.
`render_l2_chain_focus`(l2_instance)	Render the first Chain row with parent + every child labeled.
`render_l2_limit_schedule_focus`(l2_instance)	Render the first LimitSchedule as a (parent_role, rail) → cap.
`render_l2_rail_focus`(l2_instance)	Render the first Rail with its endpoint accounts.
`render_l2_topology`(l2_instance, kind, *[, name])	Render an L2 instance's structure as an inline SVG.
`render_l2_transfer_template_focus`(l2_instance)	Render the first TransferTemplate as a chain of leg rails.

recon_gen.common.handbook.diagrams.render_conceptual(name)[source]

Render a hand-authored .dot file from the conceptual catalog.

Reads docs/_diagrams/conceptual/<name>.dot and pipes it through Graphviz. KeyError if the named diagram doesn’t exist — surfaces in the mkdocs build with a clear “no such conceptual diagram” line.

Return type:: str
Parameters:: name (str)

recon_gen.common.handbook.diagrams.render_dataflow(app_name)[source]

Render which datasets feed which sheets for app_name.

Reads the typed App tree — every Visual exposes datasets() which returns the set of Datasets its field-well leaves reference. Resulting graph: dataset cylinders on the left, sheet boxes on the right, an edge from a dataset to every sheet that has at least one visual sourced from it. TextBox visuals (no field wells) are skipped via hasattr(visual, "datasets").

Return type:: str
Parameters:: app_name (str)

recon_gen.common.handbook.diagrams.render_l2_account_focus(l2_instance)[source]

Render the first singleton Account with its parent edge (if any).

Returns None if the instance has no singleton accounts. Caller (the mkdocs-macros entry) handles the fallback to spec_example.

Return type:: str | None
Parameters:: l2_instance (L2Instance)

recon_gen.common.handbook.diagrams.render_l2_account_template_focus(l2_instance)[source]

Render the first AccountTemplate with its parent singleton.

Return type:: str | None
Parameters:: l2_instance (L2Instance)

recon_gen.common.handbook.diagrams.render_l2_chain_focus(l2_instance)[source]

Render the first Chain row with parent + every child labeled.

Endpoint nodes are coloured by kind (rail vs template vs unresolved). Edge style + label match the same conventions as the full chains diagram (solid=required for singleton-children rows, dashed=xor for multi-children rows). Z.A: a multi-children row produces N edges from the same parent.

Return type:: str | None
Parameters:: l2_instance (L2Instance)

recon_gen.common.handbook.diagrams.render_l2_limit_schedule_focus(l2_instance)[source]

Render the first LimitSchedule as a (parent_role, rail) → cap.

Visual: a parent-role node on the left with a labeled edge to a “cap” node showing the daily flow ceiling. Conceptual rather than topological since LimitSchedules are configuration, not topology.

Return type:: str | None
Parameters:: l2_instance (L2Instance)

recon_gen.common.handbook.diagrams.render_l2_rail_focus(l2_instance)[source]

Render the first Rail with its endpoint accounts.

For TwoLeg, source + destination side-by-side with the rail edge between them. For SingleLeg, the leg-role account with a self-loop edge.

Return type:: str | None
Parameters:: l2_instance (L2Instance)

recon_gen.common.handbook.diagrams.render_l2_topology(l2_instance, kind, *, name=None)[source]

Render an L2 instance’s structure as an inline SVG.

kind="accounts" shows every Account as a node and every Rail as an edge between source-role-account and destination-role-account. Single-leg rails draw a self-loop on the leg-role account so they show up at all.

kind="account_templates" mirrors the accounts diagram but with AccountTemplate nodes (keyed by role) instead of singleton Accounts. Rails whose source_role / destination_role / leg_role reference a template’s role get edges to those template nodes; rails whose roles touch no template are excluded — this diagram is the “what does the template-shape graph look like?” view, not the full topology.

kind="chains" shows every Rail / TransferTemplate the chains table references, with parent → child edges (XOR groups rendered as a shared cluster). Required edges drawn solid; optional edges dashed.

kind="layered" lays the accounts diagram on top of the chains diagram in two ranks — the accounts row at the top, the chains row below.

kind="hierarchy" shows the parent → child rollup of singleton accounts and account templates. Each node is an Account or AccountTemplate; an edge points from a child to its parent (resolved by child.parent_role == parent.role). Singleton accounts have solid borders; account templates carry dashed borders since they’re a SHAPE, not an instance.

kind="transfer_template" requires a name kwarg naming one of the instance’s TransferTemplates. Renders that template as a parent node with each leg-rail as a child node, edge-labeled with the leg’s direction (Debit / Credit / Variable / two-leg). The template node carries its expected_net + transfer_key + completion so a reader gets the closure shape at a glance.

Return type:

str

Parameters:

l2_instance (L2Instance)
kind (Literal['accounts', 'account_templates', 'chains', 'layered', 'hierarchy', 'transfer_template'])
name (str | None)

recon_gen.common.handbook.diagrams.render_l2_transfer_template_focus(l2_instance)[source]

Render the first TransferTemplate as a chain of leg rails.

Each leg becomes a node labeled with its rail_name; edges connect them in declaration order. The template name + expected_net sit in the graph label.

Return type:: str | None
Parameters:: l2_instance (L2Instance)