Decisions
Architecture decision records — the load-bearing choices behind Marrow's shape, and why they were made.
These record decisions that are hard to reverse, surprising without context, and the result of a real trade-off. If a choice fails any of those three tests it is documented in the guides instead.
They prevent regressions by documenting the technical constraints and rejected alternatives behind non-obvious architecture choices.
| # | Decision | In one line |
|---|---|---|
| 0001 | Declare structure, not layout | There is no layout: key; the engine computes one layout from declared meaning |
| 0002 | Agent-driven, no GUI | The editor is a conversation; AGENTS.md is a product surface |
| 0003 | Branding is global-only | A topology describes a network, not who owns it |
| 0004 | Self-contained output | Everything inlined; zero network requests, ever |
| 0005 | Vendor icon packs are fetched | Use is granted; redistribution is not |
| 0006 | Strict schema, x- escape hatch | Unknown keys are errors, because a silent typo changes the picture |
| 0007 | Determinism & the geometry gate | Byte-identical output; overlapping geometry fails the build |
| 0008 | Page-split thresholds | 150 devices / 5 zones, chosen not configurable |
| 0009 | Link semantics & visual language | A link's logical function (mode) is a separate axis from its medium; one symbol per mode |
| 0010 | Importers may infer; the compiler may not (proposed) | Import adapters emit explicit, provenance-tagged declarations; the compiler still never guesses |
| 0011 | Discovered and overlay files (proposed) | A machine-owned discovered file plus a human-owned overlay via extends:; re-import never destroys edits |
| 0012 | Agent-optional import path (proposed) | Amends 0002: import → build is a first-class path with no agent involved |
| 0013 | Design token contract & theme overrides | Unified design tokens, CSS variables, and injection-safe theme overrides |
| 0014 | Density presets & layout metrics | Configurable compact, standard, and spacious metrics with scale multipliers |
| 0015 | Modular UI chrome & embed modes | Zero-FOUC minimal chrome, inspector suppression, and dynamic hash syncing |
| 0016 | Extensible metadata & inspector sections | Structured custom fields, collapsible tabular drawer tabs, and link inspection |
| 0017 | Configurable blueprint export chrome | Modular engineering title blocks, dynamic auto-legends, and forced port labels on export |
| 0018 | Diagram-level documentation modal & attribution | Declarative about metadata schema, interactive document modal dialog, and permanent Marrow watermarked attribution |
| 0019 | Shadcn component registry & modular React UI | Source-distributed network primitives, Fumadocs layout engines, and bi-directional postMessage event bus |
On assumed rationale. These records were written from the code, the commit history, and the existing prose. Where the reasoning behind a decision had to be inferred rather than read, it is marked with an Assumed callout. Those are the paragraphs to correct first — an ADR that records the wrong reason is worse than no ADR, because it gets cited.