Architecture decisions¶
This section records the significant decisions about IronLAB's design as a numbered chain of architecture decision records (ADRs). Each record states the context in which the decision was made, the decision itself, and its consequences, and links to the records it relates to. The discussion from which most of these decisions emerged is in the background section, and the resulting structure is summarised in the architecture reference.
Records that have been released on the main branch are never modified. A decision that changes is recorded in a new ADR that names the record it supersedes, and this index shows the earlier record as superseded.
| ADR | Decision | Status |
|---|---|---|
| 0001 | Figures are a retained IR with stable node identifiers whose Rust types are the source of truth; .fig files use Protocol Buffers, with JSON as a secondary format and both schemas generated. |
Accepted |
| 0002 | The viewer is built with egui and eframe, using only Rerun-family user-interface crates plus rfd. |
Superseded by 0016, which keeps its choice for the desktop viewer; its tab strip is superseded by 0015 |
| 0003 | One scene compiler produces a display list that every backend draws; the canvas uses egui meshes now and custom wgpu pipelines with GPU picking later. | Accepted |
| 0004 | PDF is the first export format, written with krilla, with the page equal to the artwork, real subset text, and flat, painter-sorted shading. | Superseded by 0010 |
| 0005 | LaTeX mathematics is typeset in process with latex-rust from source stored in the IR, with a fallback and warning for unsupported input. | Superseded by 0017 |
| 0006 | Viewer interaction edits the IR, views reset from a snapshot, and linked axes form disjoint groups whose automatic limits are shared. | Superseded by 0008 |
| 0007 | The MVP excludes sockets, bindings, GPU picking and smooth shading, and offers an in-process viewer and a file viewer. | Accepted |
| 0008 | Figures change through typed, literal edits in atomic transactions, and the viewer shows the owner's source figure with the user's view changes as an overlay whose conflicts are detected by property path. | Accepted |
| 0009 | The scene compiler thins a series larger than its plot can resolve, keyed on the view, by largest-triangle-three-buckets for lines and by binning for markers, and every drawn point carries the index it has in the source data. | Accepted |
| 0010 | PDF export keeps the page equal to the artwork, real subset text and flat, painter-sorted shading, and draws an artist too dense for vector paths as an image rendered by the viewer's own renderer. | Accepted |
| 0011 | Images are three artist kinds (true-colour, colour-indexed and colour-mapped) placed by their pixel centres in a plane of the axes, drawn by every backend as one image item beneath one transform, with a policy per category for the pixels the colormap cannot colour. | Accepted |
| 0012 | An artist whose data gives it nothing to draw is valid; validation and the scene compiler each warn of it, naming the artist, and export_pdf returns a report of what was left off the page. |
Accepted |
| 0013 | Every path and image of a three-dimensional axes carries its depth and the viewer draws the axes with a depth buffer through pipelines of its own; the exporter writes the axes as vectors when a depth-tested and a painter's render prove the same picture and embeds the depth-tested render otherwise, reporting every raster and every unverified axes with its reason. | Accepted |
| 0014 | The canvas produces one draw list per figure in figure points, which the viewer's own wgpu pipelines draw on screen and offscreen with the mapping as a uniform and clipping by scissor; the egui-mesh path is removed. | Accepted |
| 0015 | A figure is described only by the labels and parameters its author gives it; the viewer derives no facet of its own, ranks facets by how much of a collection they cover and how evenly they divide it, and counts each facet's values as though that facet were not filtered. | Accepted |
| 0016 | The figure engine is one crate, ironlab-canvas, built for WebAssembly in CI so that it can depend on no user interface; the egui viewer and an HTML <ironlab-figure> element are two hosts that draw only chrome over it, the browser host without egui, through a wgpu surface with the pipelines, multisampling and export of the native viewer, distributed as a bundle of static files. |
Accepted |
| 0017 | LaTeX mathematics is typeset in process with latex-rust, which applies TeX's conventions itself, so IronLAB neither rewrites the source nor resizes the glyphs; provenance records the typesetter's name and version separately. | Accepted |