NetLay: A diagram you can read like a document

The diagram nobody could follow#

Back in post seven I built a connection diagram, and I said at the time that I was not completely happy with it. Here is what was actually wrong.

Switches went into columns by how far they were from the core, devices went into a three wide grid underneath each one, and every device got a line from the middle of the switch. That is fine with four devices. With twenty, the lines run straight through the boxes of the other devices, and the uplink labels in the middle of the curves land on top of each other.

"the connection diagram is not easy to follow, we need it to generate a clear to follow guide the size of the image is not an issue."

That second clause is the whole post. The size of the image is not an issue.

I had been trying to fit a network onto something shaped like a page, which is why it was fighting me. Once the picture is allowed to be as tall as it needs to be, the problem stops being a layout puzzle and becomes an outline, and an outline is easy.

A tree instead of a graph.#

So the connection guide, as it is now called, is a tree.

One block per switch. Each block indented underneath whichever switch it uplinks to, worked out by walking outwards from the core, or from the most connected switch if nobody has said which one that is. The connector runs down the parent's gutter, with the ports and the cable type in the gap above the child.

Inside each block, every port that has something on it is a row. A port chip in its VLAN colour, the device, its address, a VLAN chip, and then either the cabling details from post eleven, the panel port, outlet, cable identifier and length, or the make and model if there is no cabling recorded.

Uplink rows come first, so you can see a switch's way up and its ways down in the same place, each one saying whether it is the parent above, a child below, or a redundant path. Hosted devices nest under their host with a dotted guide, carrying a VM chip or a radio chip with the SSID, band and signal.

Stack members get their own treatment, because a stack is one logical switch wearing several boxes. The header says it is a stack, and the second member's connector is a purple dashed line explaining that it is a stack member with its mate and reaches the parent switch through that mate's uplink.

And there is a section at the bottom, in red, for switches with no uplink recorded at all. That is deliberate. In the old diagram an unlinked switch simply floated somewhere, which read as a drawing quirk. Putting it under a heading saying it is not linked to the core turns it into a finding, and it is nearly always a real gap in the documentation rather than a real gap in the network.

Small mechanics that mattered.#

A handful of details took as long as the structure.

Connector labels are drawn after all the blocks, so a block header can never end up on top of one. Chip text picks black or white based on the luminance of the VLAN colour behind it, which is the only way to survive a palette with both pale yellow and dark blue in it. And the PNG export clamps its scale so a tall guide stays inside the browser's maximum canvas size, because a guide for a site with thirty switches will happily exceed it and the failure mode is a blank image with no error.

The thing that improved this most, though, was rendering the SVG headlessly in a browser during development and actually looking at the pictures, instead of reasoning about the maths and assuming. That produced a polish pass I would otherwise have shipped without: the legend was sized from a fixed count rather than what was in it, the block spine was drawn over the port chips instead of under them, long VLAN names ran out of their chips, and legend labels overflowed their cells.

None of that is visible in the code. All of it is obvious in a picture.

And a border that was six pixels too narrow#

While looking at the other export, the one that groups devices by VLAN, I spotted device boxes sitting slightly over the edge of the box that was supposed to contain them.

The VLAN box width was hard coded at 280 pixels, and two columns of device boxes plus their padding came to 296. It had been wrong since post seven and nobody noticed because the demo layout never had two full columns in one VLAN.

The width is derived from the columns now, and the device boxes are a little wider. Wireless clients in that export also used to be labelled as VMs, a leftover from them sharing the hosting mechanism, which is now fixed.

Next time, a proper look at the whole interface, which found a dozen things the tests never could.

NetLayNetworking