PR 118: draw.io diagrams now live in docs/diagrams

1 hour ago

This pull request adds a home for visual documentation. It's a docs folder for draw.io diagrams that version together with the code they describe. The change is docs only, four files, and nothing in the server itself moves.

Ask about this presentation

Chapters

  1. 0:00The change
  2. 0:15The inventory diagram
  3. 0:42Conventions
  4. 1:10What to check
Show transcript
  1. This pull request adds a home for visual documentation. It's a docs folder for draw.io diagrams that version together with the code they describe. The change is docs only, four files, and nothing in the server itself moves.

    Slide text

    Architecture diagrams now live in the repo, next to the code

    docs/diagrams/ · draw.io sources
  2. Inventory.drawio is the first diagram, and it draws the multi-device design from issue 44. The assistant calls an MCP tool. Each tool hands a device title to the connector. The inventory resolves that title to the SSH client for one specific device. Then the command runs on the router you chose. A separate tool, list devices, lets the assistant discover the fleet in the first place.

    Slide text

    The first diagram shows how one server reaches many routers

    LLMcalls MCP tools
    →
    Connectorgets a device title
    →
    Inventorytitle to SSH client
    →
    Routercommand runs here
  3. The folder README sets the rules for diagrams that come next. Each file covers one topic, named after its subsystem. The editable draw.io source is always committed, because nobody can edit a PNG. Exported images are optional companions for embedding in markdown, and each diagram gets linked from the page it illustrates. The one that matters most for reviewers is the last: a pull request that changes behaviour should change the drawing too.

    Slide text

    A few ground rules keep the folder useful

    One topic per filenamed after the subsystem
    Commit the editable .drawio sourceXML, so it diffs like text
    Update the drawing in the same pull request as the behaviour
  4. GitHub doesn't render draw.io files inline, so a reviewer opens the file in app dot diagrams dot net, draw.io Desktop, or the VS Code extension. The useful check is whether the drawing matches how the connector and inventory actually behave. Since the change touches only docs and a diagram, merging it doesn't trigger a release. The pull request is already merged, so this is a look back rather than a gate.

    Slide text

    Open the diagram in draw.io, since GitHub won't render it

    Does Inventory.drawio match the code?connector, inventory, list_devices
    Docs onlyno release is published

What happened in AI today, in your inbox

One short email each evening. Read it and you’re caught up.

Built with ❤️ in New York