Carlos AlvaradoTechnology Solutions Architect
Contact

Network Design Compiler

Generate a consistent IP plan, port schedule, inventory and editable topology from one validated network model.

My role
Design & implementation
Scope
Offline network design compiler
Release
v0.1.0

Validation scope

Offline design consistency

107 tests and seven CLI scenarios. CI on Python 3.11–3.13. Reference: two sites, four devices, ten interfaces and three declared links. Synthetic data.

A shared network model transformed into a topology, tables and implementation documentation.
Conceptual illustration

Inside the work

How it works

  1. Declare the design

    Define sites, VRFs, devices, interfaces and IPv4 segments in JSON. Specify port-to-port links and declared speeds explicitly.

  2. Validate the model

    Check references, duplicate addresses, overlaps, port reuse and endpoint consistency. Disconnected graphs remain visible as warnings.

  3. Generate aligned documents

    Produce eight artifacts: inventory, IP plan, port schedule, editable draw.io topology, engineering report, model, validation and manifest.

  4. Review and reproduce

    Follow link IDs across the diagram and tables. Rebuild into a fresh directory; verify artifact hashes. Invalid models emit only three reports.

Decisions & trade-offs

One model, multiple deliverablesDerive every document from the same input

Derive every document from the same input

Stable ordering and shared link identifiers keep the inventory, IP plan, port schedule and diagram consistent across rebuilds.

The trade-off

Edits made in draw.io do not flow back into JSON and are lost on regeneration. Keep presentation changes in a separate copy.

Reject misleading outputErrors produce reports, not a topology

Errors produce reports, not a topology

A duplicate IP, reused port or broken reference stops operational artifact generation. The failure still returns validation, a report and a manifest.

The trade-off

Graph disconnection is only a warning. A connected graph does not establish routing behavior or live reachability.

Keep the model boundedIPv4 routed links and loopbacks

IPv4 routed links and loopbacks

Version 0.1 covers /30 and /31 point-to-point segments, /32 loopbacks and VRF-scoped address checks with explicit endpoints.

The trade-off

L2 switching, VLAN trunks, IPv6, routing protocols and hardware compatibility require separate engineering review.

Technologies by purpose

  • Python

    Offline CLI with no runtime dependencies after installation.

  • JSON model

    Explicit sites, VRFs, IPv4 segments, interfaces and links.

  • draw.io XML

    Native editable site containers, device shapes and link IDs.

  • CSV & Markdown

    Inventory, IP assignments, port schedule and engineering report.

  • SHA-256 & CI

    Artifact hashes and seven scenarios across Python 3.11–3.13.

Scope & evidence

Published evidence

Validation limits

  • Offline consistency of declared intent. No discovery, vendor configuration generation, deployment, routing simulation or verified connectivity.
  • IPv4 /30–/31 routed links and /32 loopbacks only. Device roles and speeds are declarations, not compatibility or performance evidence.
  • Dense diagrams need visual review. Manual diagram edits are not imported back; file hashes and release checksums are unsigned.

Test captures

Recorded outputs · native draw.io topology and static evidence report.

draw.io editor showing Branch and Headquarters with four devices and three declared links.Enlarge

One model, an editable topology

Editable draw.io output: two sites, four devices, three links. Design intent, not tested connectivity.

Source · 2026-10-29
Actual duplicate-address error, validation JSON and the three observed report filenames.Enlarge

Duplicate address stops generation

Duplicate IP: exit 1 and three diagnostic files. No topology or IP tables. Static evidence viewer.

Source · 2026-10-29