Network Sketcher Administrator & Developer Guide

This guide is the operational and architectural reference for engineers who run Network Sketcher in shared environments, integrate it with surrounding systems, or extend it. It complements the User Guide: where the User Guide answers "how do I draw a diagram?", this guide answers "how does the engine work, what does every config knob do, what are the failure modes, and where do I patch behavior?".

Note

The repository ships two editions that share a common rendering engine. Operational concerns differ — the Online edition is what you deploy on a server; the Offline edition is what users run on their workstations. This guide is structured for the Online edition and calls out Offline differences explicitly where they matter.

1. Architecture Overview

Network Sketcher Online is a single-process Flask web service that fronts a deterministic Python rendering engine. The engine is the same code in both editions; the Online edition wraps it in headless stubs (nsm_adapter.py) so it can run without a display server.

1.1 What it does

A user uploads a [MASTER]*.xlsx (or .nsm) file. The engine reads its three well-known sheets (Master_Data, Master_Data_L2, Master_Data_L3), decomposes them into in-memory section arrays, and runs one of three dedicated diagram pipelines (L1, L2, L3) against them. Output is written as PowerPoint (.pptx), SVG, or Excel ([DEVICE]*.xlsx) and offered for download. A CLI layer (add/delete/rename/show/export) lets users mutate the master file by issuing line-oriented commands; mutations are versioned so the original is preserved.

1.2 ASCII architecture

                   ┌─────────────────────────────────────────────────┐
                   │              Browser (HTTPS, :5443)             │
                   │  Single-page UI · SSE · localStorage(job_id)    │
                   └────────────────────┬────────────────────────────┘
                                        │ TLS (self-signed by default)
                   ┌────────────────────▼────────────────────────────┐
                   │           ns_web_start.py (Flask app)           │
                   │ Routes: /upload /generate_step /run_commands    │
                   │   /svg_grid_stream /download(_visio|_drawio|all)│
                   │ Headers: HSTS · X-Frame-Options · CSP           │
                   │ Per-job state: uploads/<uuid>/                  │
                   │ Heartbeats: in-memory dict, 5-min idle expiry   │
                   └────┬───────────────┬───────────────┬────────────┘
                        │               │               │
        in-process run_cli              │   subprocess(_ns_worker.py)
                        │               │               │
                   ┌────▼───────────────▼───────────────▼────────────┐
                   │          ns_engine/  (headless engine)          │
                   │ nsm_adapter.py    Tk stubs + bootstrap          │
                   │ nsm_cli.py        verb dispatcher (5 verbs)     │
                   │ nsm_io.py         .xlsx ↔ .nsm (Parquet) bridge │
                   │ nsm_l1_*.py       L1 diagram + table + sync     │
                   │ nsm_l2_*.py       L2 diagram + table + sync     │
                   │ nsm_l3_*.py       L3 diagram + table + sync     │
                   │ nsm_ddx_*.py      pptx / svg renderers          │
                   │ nsm_extensions.py AI-context · flow · IP report │
                   │ nsm_sync_between_layers.py  L2↔L3 consistency   │
                   └────┬───────────────────────┬─────────────────────┘
                        │                       │
                ┌───────▼─────────┐    ┌────────▼───────────────────┐
                │ Master file     │    │ Output artifacts           │
                │ [MASTER]*.xlsx  │    │ [L1_DIAGRAM]*.pptx/.svg    │
                │  or *.nsm (zip  │    │ [L2_DIAGRAM]<area>_*       │
                │  of Parquet)    │    │ [L3_DIAGRAM]*              │
                │ ─ Master_Data   │    │ [DEVICE]*.xlsx             │
                │ ─ Master_Data_L2│    │ [AI_Context]*.txt          │
                │ ─ Master_Data_L3│    └────────────────────────────┘
                └─────────────────┘

1.3 Component inventory

1.4 Technology stack

1.5 Data flow for the canonical "upload + render" workflow

1. POST /upload (multipart) ──► validate_master_filename()
                              ► assign uuid4 job_id
                              ► save to uploads/<job_id>/[MASTER]*.xlsx
                              ► xlsx_to_nsm() → uploads/<job_id>/[MASTER]*.nsm
                              ► touch_heartbeat(job_id)
                              ◄ {job_id, filename}

2. POST /generate_step/<job_id>/init ──► run `show area`, `show device`,
                                          `show l1_link`, `show attribute`
                                          via run_ns_command()
                                       ► persist meta to .meta.json
                                       ◄ {areas, device_count, link_count,
                                          attribute_titles}

3. GET /svg_grid_stream/<job_id>     ──► fan out to ThreadPoolExecutor:
   (Server-Sent Events)                  - export l1_diagram --type all_areas_tag
                                          - export l1_diagram --type per_area_tag
                                          - export l3_diagram --type all_areas
                                          - export l3_diagram --type per_area
                                          - export l2_diagram --area <each>
                                       ► each task → run_ns_command_subprocess()
                                          (separate Python interpreter)
                                       ► moved files cached in _svg_mem_cache
                                       ◄ stream `data: {cell, files, svg_b64?}`
                                          for each completed cell
                                       ◄ background AI-context generation
                                          completes in parallel
                                       ◄ `data: {done: true, ai_filename}`

4. GET /download/<job_id>/<file>      ──► serve from uploads/<job_id>/

5. (heartbeat_timeout seconds idle)   ──► _cleanup_loop() rmtree(uploads/<job_id>/)
                                       ► drop _svg_mem_cache[job_id]
                                       ► drop _svg_grid_last_attr[job_id]

Note

The engine is deterministic. A given master file at a given commit always produces the same byte-for-byte output. This is intentional: diff-friendly diagrams let teams review topology changes the same way they review source code, and it's why subprocess timeouts default to a generous four hours rather than failing fast — large topologies are bounded by RAM and CPU, not by stochastic behavior.

2. System Requirements

2.1 Minimum

2.2 Recommended for shared / production use

2.3 Python package floor

The exact pinned versions live in network-sketcher_offline/requirements_offline.txt and network-sketcher_online/requirements_online.txt. The functional floor:

Important

The Online edition does not require Tk. nsm_adapter.bootstrap() injects no-op stubs into sys.modules['tkinter'], sys.modules['tkinter.ttk'], sys.modules['tkinter.filedialog'], and sys.modules['tkinter.messagebox'] before any engine module imports. This is how the Online edition runs cleanly in container images that have no display server.

3. Configuration Reference

This is the complete inventory of every configurable surface — JSON file, environment variable, and CLI flag. If a setting is not in one of these tables, it does not exist.

3.1 ns_web_config.json — the only config file

Located at network-sketcher_online/ns_web_config.json. Each top-level key is {"value": ..., "description": "..."}; the loader strips the description and keeps only the value. Keys whose names start with underscore (_description) are ignored.

Important

ssl_cert_validity_days defaults to 3650 (10 years). For production, replace the auto-generated cert with one from your internal CA — most browsers cap manually-trusted self-signed certs at 1 year of acceptance. See Section 7.4.

3.2 Environment variables

3.3 CLI flags (every ns_cli.py invocation)

3.3.1 Top-level verbs

3.3.2 export l1_diagram flags

3.3.3 export l2_diagram flags

3.3.4 export l3_diagram flags

3.3.5 Other export subcommands

3.3.6 Mutating-command behavior flags

3.4 First-run-state files

4. Deployment & Scaling

Network Sketcher Online is a single-process Flask app — there is no master/worker pool, no separate cache process, no message broker. This keeps deployment simple but bounds horizontal scaling to running more than one instance behind a load-balancer with sticky sessions (necessary because per-session state lives in uploads/<job_id>/ on the local filesystem).

4.1 Single-host deployment (typical)

# 1. Clone and install
git clone https://github.com/cisco-open/network-sketcher.git
cd network-sketcher
python -m pip install -r network-sketcher_online/requirements_online.txt

# 2. Optional: edit ns_web_config.json for your host/port
${EDITOR:-vi} network-sketcher_online/ns_web_config.json

# 3. Start
python start_ns_online.py

The server runs in the foreground of the Python process started by Popen, but start_ns_online.py detaches it on Windows (DETACHED_PROCESS | CREATE_NEW_PROCESS_GROUP) and creates a new POSIX session on Linux/macOS (start_new_session=True).

4.2 Run as a systemd unit (Linux)

# /etc/systemd/system/network-sketcher.service
[Unit]
Description=Network Sketcher Online
After=network.target

[Service]
Type=forking
User=netsketcher
WorkingDirectory=/opt/network-sketcher
ExecStart=/opt/network-sketcher/.venv/bin/python /opt/network-sketcher/start_ns_online.py
ExecStop=/opt/network-sketcher/.venv/bin/python /opt/network-sketcher/stop_ns_online.py
PIDFile=/opt/network-sketcher/network-sketcher_online/ns_online.pid
Restart=on-failure

[Install]
WantedBy=multi-user.target

Tip

Use a dedicated unprivileged user for the service. The Online server never needs root; reading the config and binding port 5443 work fine as a normal user (ports above 1024).

4.3 Containerized deployment

FROM python:3.11-slim

WORKDIR /opt/network-sketcher
COPY . .
RUN pip install --no-cache-dir \
    -r network-sketcher_online/requirements_online.txt

# Persist Certs and uploads across container restarts
VOLUME ["/opt/network-sketcher/network-sketcher_online/Certs",
        "/opt/network-sketcher/network-sketcher_online/uploads",
        "/opt/network-sketcher/network-sketcher_online/logs"]

EXPOSE 5443
CMD ["python", "start_ns_online.py"]

4.4 Reverse proxy with TLS termination

If you front Network Sketcher with nginx/Caddy/Traefik that already holds your real cert:

1. Set host: 127.0.0.1 and let the reverse proxy bind public ports.
2. Provide the upstream's own cert via ssl_cert_path / ssl_key_path, or disable upstream TLS by replacing the ssl.SSLContext in ns_web_start.py with a plain HTTP listener (currently not exposed as a config flag — patch required).
3. Forward X-Forwarded-For so access logs report client IPs.

Note

The default config bakes HSTS into every response with max-age=31536000; includeSubDomains. Remove that header if you're intentionally serving HTTP behind a TLS-terminating proxy without HTTPS upstream.

4.5 Horizontal scaling

Each session's working files live on local disk under uploads/<job_id>/. To run more than one Online instance:

• Place a load balancer in front (HAProxy / nginx / your cloud LB).
• Configure sticky sessions keyed on a cookie or header so a given job_id always lands on the same backend.
• Keep Certs/, uploads/, and logs/ on instance-local volumes — do not put uploads/ on shared NFS unless you're willing to serialize all parallel writes.

4.6 Stopping cleanly

stop_ns_online.py finds every running ns_web_start.py process via the OS process list (Windows: wmic process where ..., Linux/macOS: pgrep -f ns_web_start.py) and falls back to the PID file as a secondary source. It sends SIGTERM (POSIX) or taskkill /F /T /PID (Windows), then waits up to 10 seconds for the process(es) to exit.

Warning

A SIGTERM during diagram generation aborts the in-flight subprocess. Sessions persist on disk and the user can re-issue the same generate request after the server is back up — but any partial output files in the job directory are not cleaned automatically (the next session's heartbeat-expiry sweep will eventually remove them).

5. Operations

5.1 Health check

There is no dedicated /health route. A useful liveness probe is the root path:

curl -ksf https://127.0.0.1:5443/ -o /dev/null && echo OK

A readiness probe should additionally verify the cert paths exist and are readable.

5.2 Daily access log

logs/access_YYYYMMDD.log (one file per local date) contains one line per request:

2026-04-28 14:07:31 198.51.100.42 POST /upload 200 upload="[MASTER]campus.xlsx"
2026-04-28 14:07:33 198.51.100.42 POST /generate_step/96d6b2a4-.../init 200
2026-04-28 14:07:35 198.51.100.42 GET /svg_grid_stream/96d6b2a4-... 200
2026-04-28 14:08:12 198.51.100.42 GET /download/96d6b2a4-.../[L1_DIAGRAM]AllAreasTag_campus.pptx 200 download="[L1_DIAGRAM]AllAreasTag_campus.pptx"

/heartbeat/<job_id> is suppressed from access logs (it would otherwise fire every few seconds). Files older than access_log_retention_days are deleted on startup and on each date roll-over.

Note

Network Sketcher does not rotate or compress access logs itself. If you ship them off-host, run logrotate (or the equivalent) on logs/access_*.log; the in-app cleanup is best-effort, not a backup.

5.3 Heartbeat eviction

Every successful upload registers a heartbeat with touch_heartbeat(). The browser front-end refreshes it every few seconds via POST /heartbeat/<job_id>. The server's _cleanup_loop thread runs every cleanup_interval seconds and rmtree-s any session whose heartbeat is older than heartbeat_timeout. The same loop drops the SVG memory cache and the per-session attribute cache.

5.4 Common operational checklists

After a clean install

• [ ] python start_ns_online.py starts without error
• [ ] https://localhost:5443/ loads in a browser
• [ ] Upload a master file, wait for the SSE grid to populate
• [ ] Confirm logs/access_YYYYMMDD.log is being written
• [ ] Confirm Certs/server.crt was created (4096-bit RSA, 10-year validity)

After a config change

• [ ] python stop_ns_online.py reports Stopped N process(es).
• [ ] python start_ns_online.py reports a fresh PID
• [ ] First request after restart returns 200
• [ ] Loaded parallel_limit, port, etc. match what's now in ns_web_config.json

Before a TLS cert renewal

• [ ] Backup Certs/server.crt and Certs/server.key
• [ ] Drop in the new cert and key with the same paths (or update ssl_cert_path / ssl_key_path)
• [ ] Restart
• [ ] Confirm the new fingerprint with openssl x509 -in Certs/server.crt -noout -fingerprint -sha256

5.5 Backup strategy

uploads/<job_id>/ directories are not backup-worthy — they're transient and auto-deleted.

5.6 Frequent cross-edition syncs

Both editions duplicate ~95% of the engine code (Offline ns_*.py and Online ns_engine/nsm_*.py). When you backport a fix:

1. Patch the Online file under ns_engine/.
2. Diff against the Offline file under network-sketcher_offline/ — the names match one-to-one (ns_l2_diagram_create.py ↔ nsm_l2_diagram_create.py).
3. Apply the corresponding change to the Offline file.
4. Run python ns_cli.py show area --master "[MASTER]demo.xlsx" from each edition to confirm dispatcher integrity.

6. Performance

6.1 Where time goes

For a "first render after upload":

/svg_grid_stream parallelizes across parallel_limit workers; the critical path is the slowest single subprocess. For most fabrics that's the L3 all_areas render.

6.2 Tuning levers

6.3 SVG caching path

After a successful subprocess render, the moved file's bytes are cached in _svg_mem_cache[job_id][filename] under _svg_mem_cache_lock. Subsequent requests to /svg_raw/<job_id>/... serve from this cache, bypassing both the disk and the Windows AV-lock re-read. The cache is dropped on heartbeat expiry.

6.4 Known performance hazards

Warning

On Windows, antivirus engines (notably Defender) re-scan files immediately after they're moved between directories. The engine mitigates this with _wait_readable() (10-second wait with 150ms polling) before serving SVGs. If you see "File not readable after 10s" warnings in server.log, your AV is holding files longer than 10 seconds — exclude the uploads/ directory from real-time scanning or raise the timeout in _wait_readable.

7. Security

Network Sketcher's outputs are sensitive. A network topology artifact reveals device names, vendor inventory (via interface naming), IP plans, VRF / VPN structure, and broadcast-domain layout. Treat every generated file as Internal at minimum, and the AI Context file as Confidential.

7.1 What's in the box at first start

Caution

The default deployment has no authentication. Anyone who can reach the listening port can upload, render, and download. Never expose a default Network Sketcher Online directly to the internet. Put it behind an auth proxy (oauth2-proxy, Pomerium, your SSO IdP), a VPN, or a Tailscale tailnet before exposing it beyond localhost.

7.2 Sensitive data classification

Warning

The AI Context file is the highest-risk output. It is designed to be pasted into a hosted LLM, which means it will be transmitted to a third party and may be retained for training (per the LLM vendor's TOS). The CLI requires either an interactive YES confirmation or --accept-security-risk; the web UI displays the same risk text in the tooltip. Audit any policy that allows unattended --accept-security-risk use. See nsm_extensions.py for the export logic and the warning text.

7.3 Recommended access boundary

7.4 Production TLS

The auto-generated cert is for development convenience. To replace it:

# Stop the server
python stop_ns_online.py

# Drop in CA-issued cert and key
cp /path/to/your/cert.pem  network-sketcher_online/Certs/server.crt
cp /path/to/your/key.pem   network-sketcher_online/Certs/server.key

# Or set custom paths in ns_web_config.json:
#   "ssl_cert_path": {"value": "/etc/letsencrypt/live/sketcher.example.com/fullchain.pem"}
#   "ssl_key_path":  {"value": "/etc/letsencrypt/live/sketcher.example.com/privkey.pem"}
#   "fqdn":          {"value": "sketcher.example.com"}

python start_ns_online.py

Verify:

openssl s_client -connect sketcher.example.com:5443 -servername sketcher.example.com < /dev/null 2>&1 | openssl x509 -noout -subject -dates

7.5 Secrets handling

Network Sketcher itself stores no secrets in code or config. The only sensitive material on disk is:

• TLS private key (Certs/server.key) — chmod 0600, owned by the service user.
• Master files in uploads/<job_id>/ — auto-cleaned on heartbeat expiry. For long-lived hosting, consider mounting uploads/ on an encrypted volume.

There are no API keys, no database credentials, no third-party tokens. The ai_context_button_url defaults to a public LLM URL but is purely a hyperlink — Network Sketcher itself never calls out to it.

7.6 Sanitization recommendations before sharing diagrams

If you need to share a diagram externally (vendor RFP, conference talk, public docs):

1. Make a copy of the master and run a rename pass:
   • rename device <real-name> <Device-N> for every device
   • rename area <real-area> <Area-N> for every area
2. Run a delete ip_address pass on the L3 sheet (or set IPs to RFC1918-only representatives via add ip_address).
3. Re-render the diagrams from the sanitized master.
4. Do not redact PNG/PPTX exports manually — the underlying SVG may still contain the un-redacted text in <text> elements.

8. Developer Internals

8.1 Repository layout

network-sketcher/
├── README.md                  # Cisco Open project README
├── CONTRIBUTING.md
├── CODE_OF_CONDUCT.md
├── SECURITY.md
├── LICENSE                    # Apache 2.0
├── start_ns_online.py         # Cross-platform daemonizer for Online
├── stop_ns_online.py          # Cross-platform stop
├── network-sketcher_offline/  # Tkinter GUI + standalone CLI
│   ├── network_sketcher.py    # GUI entrypoint
│   ├── ns_cli.py              # Standalone CLI dispatcher
│   ├── ns_def.py              # Shared helpers (file I/O, sheet→array, etc.)
│   ├── ns_dev.py              # GUI internals
│   ├── ns_extensions.py       # AI context, flow report, IP report, etc.
│   ├── ns_l1_*.py             # L1 pipeline (5 files)
│   ├── ns_l2_*.py             # L2 pipeline (3 files)
│   ├── ns_l3_*.py             # L3 pipeline (3 files)
│   ├── ns_ddx_figure.py       # PPTX renderer
│   ├── ns_egt_maker.py        # Excel template maker
│   ├── ns_attribute_table_*.py
│   ├── ns_option_convert_to_master.py  # External-system imports
│   ├── ns_sync_between_layers.py
│   ├── ns_vpn_diagram_create.py
│   ├── hook-pptx.py           # PyInstaller hook
│   ├── ns_logo.png
│   ├── requirements_offline.txt
│   └── Sample_data/
└── network-sketcher_online/   # Flask server + headless engine
    ├── ns_web_start.py        # Flask app: routes, security headers, parallelism
    ├── ns_web_config.json     # The only config file
    ├── help_msg.json          # Tooltip text for the web UI
    ├── requirements_online.txt
    ├── Certs/                 # Auto-populated on first start
    ├── logs/                  # Auto-populated on first request
    ├── static/                # JS deps (PptxViewJS, chart.umd, jszip, xlsx)
    └── ns_engine/             # Headless engine (mirror of offline ns_*)
        ├── __init__.py
        ├── _ns_worker.py      # Subprocess worker entry
        ├── nsm_adapter.py     # Tk stubs + bootstrap + run_cli
        ├── nsm_io.py          # xlsx ↔ nsm (Parquet) bridge
        ├── nsm_cli.py
        ├── nsm_def.py
        ├── nsm_l1_*.py / nsm_l2_*.py / nsm_l3_*.py
        ├── nsm_ddx_figure.py / nsm_ddx_svg*.py
        ├── nsm_extensions.py
        ├── nsm_svg_compute.py / nsm_svg_worker.py
        └── nsm_sync_between_layers.py

8.2 Key invariants

Note

Master file integrity is preserved by design. The Online server never overwrites an uploaded master in place: any mutation creates a versioned copy ([MASTER]<basename>_<n>.xlsx) and updates .active_master. This is the single most important behavior to preserve when patching.

Note

The engine is deterministic with respect to a given master + flag combination. If a refactor changes byte-for-byte output, that's a regression that needs review even if the diagrams look the same. Reviewers should diff the SVG output against a known-good master in network-sketcher_offline/Sample_data/.

8.3 Module reference

ns_web_start.py — Flask app

Major helpers:

nsm_adapter.py — engine bootstrap

nsm_io.py — master file I/O

nsm_cli.py — verb dispatcher

The dispatcher reads argv_array and routes by literal verb match ('show' in argv_array, etc.), then by next_arg against the verb's allow-list. The five subcommand allow-lists are documented in Section 3.3. Any unsupported verb or object prints the supported list and exits.

Pipelines (nsm_l1_*.py, nsm_l2_*.py, nsm_l3_*.py)

Each layer has up to four files:

nsm_extensions.py — feature catalog

8.4 Code patterns and conventions

• Tk in the engine? All Tk imports go through stubs at module load via nsm_adapter.bootstrap(). The engine still calls tk.Entry(), tk.StringVar() etc. — those resolve to the _Noop-backed classes. Don't try to remove the Tk imports; they're required for shared code with the Offline edition.
• CLI verb parsing: simple membership checks ('show' in argv_array) followed by get_next_arg(...) lookups. There's no argparse use; if you add a flag, follow the existing if a == '--master': replace_next = True pattern.
• Versioning: never overwrite the input. Mutations write to [MASTER]<basename>_<n>.xlsx and update .active_master.
• Headless detection: check os.environ.get('NS_WEB_SERVER') rather than detecting Tk presence — the stubs make Tk presence always-truthy in Online mode.
• Subprocess vs. in-process: the Online server uses three execution modes: run_ns_command (in-process, holds _cli_lock), run_ns_command_isolated (in-process with master copy), run_ns_command_subprocess (separate interpreter for true parallelism). Pick the lowest-overhead one that satisfies your isolation needs.

8.5 Testing strategy

The repository ships no formal test suite. The maintainer-tested verification path is:

1. python ns_cli.py show area --master Sample_data/... — sanity check that the dispatcher and master loader are wired up.
2. python ns_cli.py export l1_diagram --master Sample_data/... --type all_areas_tag — full L1 pipeline.
3. python ns_cli.py export l2_diagram --master Sample_data/... --area <area> — full L2 pipeline per area.
4. python ns_cli.py export l3_diagram --master Sample_data/... --type all_areas — full L3 pipeline.
5. End-to-end via the web UI for a final visual check.

When contributing, run all four CLI exports against Sample_data/No_data_Master_file_with_AI_Context/[MASTER]no_data.xlsx and visually diff the resulting .pptx against the previous version.

Tip

Sample data is intentionally minimal — it's a no-data master with the AI-context placeholder. For more thorough testing, build a small synthetic master with two areas, four devices, and a handful of L1 wires; commit it locally as a fixture.

8.6 Potential improvements

• Test suite. Even a smoke-test wrapping the four CLI exports would catch most regressions.
• /health endpoint. Currently health checks must hit /.
• Auth integration hook. The server has no auth surface; a pluggable middleware that delegates to JWT / OIDC / mTLS would make multi-tenant deploys safer.
• Output retention policy. uploads/<job_id>/ currently lives for exactly heartbeat_timeout seconds; some users want "keep last 24 hours regardless of activity". Make the retention policy configurable separately from the heartbeat window.
• Structured error response. Routes return mixed {success, message} and {error} shapes. Standardizing would help programmatic clients.
• Headless Tk removal. Long-term, the engine would be cleaner if Tk references were stripped rather than stubbed. This is a large refactor (~25 modules) but enables packaging the engine as a library without the Adapter dance.

8.7 Contributing

The repository follows the Cisco Open contribution model:

• All code is Apache 2.0; every file carries the SPDX header SPDX-License-Identifier: Apache-2.0 and Copyright 2023 Cisco Systems, Inc. and its affiliates.
• Open issues at github.com/cisco-open/network-sketcher/issues.
• See CONTRIBUTING.md and CODE_OF_CONDUCT.md at the repo root.
• Security issues go to the address in SECURITY.md, not the public issue tracker.

9. Integration Points

Network Sketcher is intentionally narrow at its edges. It does not talk to controllers, doesn't push configs, doesn't poll devices. Integration happens through file imports and exports.

9.1 Inbound: external-system imports (Offline GUI)

The Offline GUI's External Systems tab imports four formats into a master file via ns_option_convert_to_master.py:

Two helper classes round out the import flow:

• ns_overwrite_line_to_master_yaml — overlays a YAML topology onto an existing master.
• ns_l3_config_to_master_yaml — adds L3 details from a YAML config bundle.

9.2 Outbound: derived export formats

9.3 LLM integration

The AI Context flow is the only outbound call path:

1. The web UI (or nsm_extensions.ai_context.export_ai_context_file) builds a deterministic text bundle from the configured show commands plus nsm_extensions_cmd_list.txt.
2. The user clicks Copy & Open LLM (or hits the Download button). The button label and target URL are configured via ai_context_button_label and ai_context_button_url (default https://claude.ai).
3. The clipboard content is the AI Context plus the user's natural- language prompt.
4. The user pastes into the LLM, gets back CLI commands, pastes them into the CLI Commands box, and hits Run.

Network Sketcher itself never sends the data anywhere — the user controls the transmission.

9.4 Programmatic engine usage

You can embed the engine in another Python program by bootstrapping once and calling run_cli() repeatedly:

from ns_engine.nsm_adapter import bootstrap, run_cli

bootstrap()

result = run_cli([
    'export', 'l1_diagram',
    '--master', '/path/to/[MASTER]campus.xlsx',
    '--type', 'all_areas_tag',
    '--format', 'svg',
])

print(result.returncode)   # 0 on success
print(result.stdout)        # captured stdout
print(result.stderr)        # captured stderr

run_cli holds a single global _cli_lock, so calls are serialized within one process. For true parallelism, follow the pattern in run_ns_command_subprocess and shell out to _ns_worker.py instead.

Tip

If you're embedding the engine, prefer run_cli_isolated() over run_cli() for any mutating command — it copies the master into a temp directory first, so a crash in your code can't corrupt the caller's master file.

9.5 Front-end JS dependencies

The Online edition's UI uses these vendored JS libraries (under network-sketcher_online/static/):

These are vendored to keep the deployment self-contained — no CDN calls happen at runtime. If you upgrade a library, replace the file in place and restart the server.