# cisco-open/network-sketcher architecture

> Architecture diagram of the GitHub repository cisco-open/network-sketcher, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cisco-open/network-sketcher
- Repository: https://github.com/cisco-open/network-sketcher

## Overview

Network Sketcher turns structured network data and user commands into topology diagrams, device tables, and AI context. The principal workflow is to submit a design through Local MCP, the online web service, or the offline GUI/CLI; the edition’s engine interprets commands and works with a master file, then generates L1/L2/L3 outputs and supporting views. The graph preserves documented edition capabilities and sampled module dependencies. Several subsystem links are documented only at a high level or come from the source index; those are marked dashed where implementation-level evidence is absent.

Main entry points: [`network-sketcher_online/ns_engine/nsm_adapter.py`](https://github.com/cisco-open/network-sketcher/blob/main/network-sketcher_online/ns_engine/nsm_adapter.py) (Online engine adapter), [`network-sketcher_offline/ns_cli.py`](https://github.com/cisco-open/network-sketcher/blob/main/network-sketcher_offline/ns_cli.py) (Offline command engine), [`network-sketcher_online/ns_engine/nsm_io.py`](https://github.com/cisco-open/network-sketcher/blob/main/network-sketcher_online/ns_engine/nsm_io.py) (Network master), [`network-sketcher_online/ns_web_start.py`](https://github.com/cisco-open/network-sketcher/blob/main/network-sketcher_online/ns_web_start.py) (Online web service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_mcp["Local MCP server<br/>[ns_mcp_server.py]"]
  node_web["Online web service<br/>[ns_web_start.py]"]
  node_offlinegui["Offline GUI"]
  node_offlinecli["Offline CLI<br/>[ns_cli.py]"]
end

subgraph group_engine["Design engine"]
  node_onlineadapter["Online engine adapter<br/>[nsm_adapter.py]"]
  node_onlinecli["Online command engine<br/>[nsm_cli.py]"]
  node_offlinecore["Offline command engine<br/>[ns_cli.py]"]
end

subgraph group_outputs["Design outputs"]
  node_l1["L1 topology"]
  node_l2["L2 topology"]
  node_l3["L3 topology"]
  node_vpn["VPN topology"]
  node_svg["SVG rendering<br/>[nsm_svg_worker.py]"]
  node_device_table["Device table"]
  node_combined_view["Combined HTML viewer<br/>[nsm_l1l2l3_html.py]"]
  node_ppt["PowerPoint figures<br/>[nsm_ddx_figure.py]"]
  node_ai_context["AI context<br/>[nsm_ai_context.py]"]
end

subgraph group_shared["Master and shared services"]
  node_master[("Network master<br/>[nsm_io.py]")]
  node_shared_defs["Master utilities<br/>[nsm_def.py]"]
  node_offline_master["Offline master utilities<br/>[ns_def.py]"]
  node_layer_sync["Layer synchronization"]
  node_attributes["Attribute tables"]
  node_extensions["Design extensions<br/>[nsm_extensions.py]"]
end

node_agent(("LLM client"))
node_browser(("Web browser"))
node_desktop(("Desktop user"))

node_agent -->|"sends tool calls"| node_mcp
node_mcp -->|"runs engine"| node_onlineadapter
node_mcp -->|"requests context"| node_ai_context
node_mcp -->|"uses file I/O"| node_master
node_browser -->|"submits design"| node_web
node_web -->|"runs commands"| node_onlineadapter
node_web -->|"generates context"| node_ai_context
node_web -->|"serves table"| node_device_table
node_web -->|"serves viewer"| node_combined_view
node_desktop -->|"edits design"| node_offlinegui
node_desktop -->|"runs commands"| node_offlinecli
node_offlinegui -->|"dispatches actions"| node_offlinecore
node_offlinegui -->|"synchronizes layers"| node_layer_sync
node_offlinecli -->|"synchronizes layers"| node_layer_sync
node_onlineadapter -->|"runs commands"| node_onlinecli
node_onlineadapter -->|"converts master"| node_master
node_onlineadapter -.->|"creates topology"| node_l1
node_onlineadapter -.->|"creates topology"| node_l2
node_onlineadapter -.->|"creates topology"| node_l3
node_onlineadapter -.->|"creates table"| node_device_table
node_onlineadapter -.->|"renders SVG"| node_svg
node_onlineadapter -.->|"creates figures"| node_ppt
node_onlineadapter -.->|"supports VPN diagrams"| node_vpn
node_offlinecore -->|"uses utilities"| node_offline_master
node_offlinecore -->|"builds L1"| node_l1
node_offlinecore -->|"builds L2"| node_l2
node_offlinecore -->|"builds L3"| node_l3
node_offlinecore -->|"builds tables"| node_attributes
node_offlinecore -->|"dispatches extensions"| node_extensions
node_l1 -.->|"reads master"| node_master
node_l2 -.->|"reads master"| node_master
node_l3 -.->|"reads master"| node_master
node_shared_defs -->|"reads master"| node_master
node_device_table -->|"uses utilities"| node_shared_defs
node_attributes -->|"uses utilities"| node_shared_defs
node_extensions -->|"uses utilities"| node_shared_defs
node_extensions -->|"supports context"| node_ai_context

click node_mcp "https://github.com/cisco-open/network-sketcher/blob/main/network-sketcher_local_mcp/ns_mcp_server.py"
click node_web "https://github.com/cisco-open/network-sketcher/blob/main/network-sketcher_online/ns_web_start.py"
click node_offlinegui "https://github.com/cisco-open/network-sketcher/blob/main/network-sketcher_offline/network_sketcher.py"
click node_offlinecli "https://github.com/cisco-open/network-sketcher/blob/main/network-sketcher_offline/ns_cli.py"
click node_onlineadapter "https://github.com/cisco-open/network-sketcher/blob/main/network-sketcher_online/ns_engine/nsm_adapter.py"
click node_onlinecli "https://github.com/cisco-open/network-sketcher/blob/main/network-sketcher_online/ns_engine/nsm_cli.py"
click node_offlinecore "https://github.com/cisco-open/network-sketcher/blob/main/network-sketcher_offline/ns_cli.py"
click node_l1 "https://github.com/cisco-open/network-sketcher/blob/main/network-sketcher_online/ns_engine/nsm_l1_diagram_create.py"
click node_l2 "https://github.com/cisco-open/network-sketcher/blob/main/network-sketcher_online/ns_engine/nsm_l2_diagram_create.py"
click node_l3 "https://github.com/cisco-open/network-sketcher/blob/main/network-sketcher_online/ns_engine/nsm_l3_diagram_create.py"
click node_vpn "https://github.com/cisco-open/network-sketcher/blob/main/network-sketcher_offline/ns_vpn_diagram_create.py"
click node_svg "https://github.com/cisco-open/network-sketcher/blob/main/network-sketcher_online/ns_engine/nsm_svg_worker.py"
click node_device_table "https://github.com/cisco-open/network-sketcher/blob/main/network-sketcher_online/ns_engine/nsm_device_table_html.py"
click node_combined_view "https://github.com/cisco-open/network-sketcher/blob/main/network-sketcher_online/ns_engine/nsm_l1l2l3_html.py"
click node_ppt "https://github.com/cisco-open/network-sketcher/blob/main/network-sketcher_online/ns_engine/nsm_ddx_figure.py"
click node_ai_context "https://github.com/cisco-open/network-sketcher/blob/main/network-sketcher_online/ns_engine/nsm_ai_context.py"
click node_master "https://github.com/cisco-open/network-sketcher/blob/main/network-sketcher_online/ns_engine/nsm_io.py"
click node_shared_defs "https://github.com/cisco-open/network-sketcher/blob/main/network-sketcher_online/ns_engine/nsm_def.py"
click node_offline_master "https://github.com/cisco-open/network-sketcher/blob/main/network-sketcher_offline/ns_def.py"
click node_layer_sync "https://github.com/cisco-open/network-sketcher/blob/main/network-sketcher_online/ns_engine/nsm_sync_between_layers.py"
click node_attributes "https://github.com/cisco-open/network-sketcher/blob/main/network-sketcher_online/ns_engine/nsm_attribute_table_from_master.py"
click node_extensions "https://github.com/cisco-open/network-sketcher/blob/main/network-sketcher_online/ns_engine/nsm_extensions.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_mcp,node_web,node_offlinegui,node_offlinecli,node_agent,node_browser,node_desktop toneBlue
class node_onlineadapter,node_onlinecli,node_offlinecore toneAmber
class node_l1,node_l2,node_l3,node_vpn,node_svg,node_device_table,node_combined_view,node_ppt,node_ai_context toneMint
class node_master,node_shared_defs,node_offline_master,node_layer_sync,node_attributes,node_extensions toneRose
```

## Components

### User interfaces

- [Local MCP server](https://github.com/cisco-open/network-sketcher/blob/main/network-sketcher_local_mcp/ns_mcp_server.py): `network-sketcher_local_mcp/ns_mcp_server.py`
- [Online web service](https://github.com/cisco-open/network-sketcher/blob/main/network-sketcher_online/ns_web_start.py): `network-sketcher_online/ns_web_start.py`
- [Offline GUI](https://github.com/cisco-open/network-sketcher/blob/main/network-sketcher_offline/network_sketcher.py): `network-sketcher_offline/network_sketcher.py`
- [Offline CLI](https://github.com/cisco-open/network-sketcher/blob/main/network-sketcher_offline/ns_cli.py): `network-sketcher_offline/ns_cli.py`

### Design engine

- [Online engine adapter](https://github.com/cisco-open/network-sketcher/blob/main/network-sketcher_online/ns_engine/nsm_adapter.py): `network-sketcher_online/ns_engine/nsm_adapter.py`
- [Online command engine](https://github.com/cisco-open/network-sketcher/blob/main/network-sketcher_online/ns_engine/nsm_cli.py): `network-sketcher_online/ns_engine/nsm_cli.py`
- [Offline command engine](https://github.com/cisco-open/network-sketcher/blob/main/network-sketcher_offline/ns_cli.py): `network-sketcher_offline/ns_cli.py`

### Design outputs

- [L1 topology](https://github.com/cisco-open/network-sketcher/blob/main/network-sketcher_online/ns_engine/nsm_l1_diagram_create.py): `network-sketcher_online/ns_engine/nsm_l1_diagram_create.py`
- [L2 topology](https://github.com/cisco-open/network-sketcher/blob/main/network-sketcher_online/ns_engine/nsm_l2_diagram_create.py): `network-sketcher_online/ns_engine/nsm_l2_diagram_create.py`
- [L3 topology](https://github.com/cisco-open/network-sketcher/blob/main/network-sketcher_online/ns_engine/nsm_l3_diagram_create.py): `network-sketcher_online/ns_engine/nsm_l3_diagram_create.py`
- [VPN topology](https://github.com/cisco-open/network-sketcher/blob/main/network-sketcher_offline/ns_vpn_diagram_create.py): `network-sketcher_offline/ns_vpn_diagram_create.py`
- [SVG rendering](https://github.com/cisco-open/network-sketcher/blob/main/network-sketcher_online/ns_engine/nsm_svg_worker.py): `network-sketcher_online/ns_engine/nsm_svg_worker.py`
- [Device table](https://github.com/cisco-open/network-sketcher/blob/main/network-sketcher_online/ns_engine/nsm_device_table_html.py): `network-sketcher_online/ns_engine/nsm_device_table_html.py`
- [Combined HTML viewer](https://github.com/cisco-open/network-sketcher/blob/main/network-sketcher_online/ns_engine/nsm_l1l2l3_html.py): `network-sketcher_online/ns_engine/nsm_l1l2l3_html.py`
- [PowerPoint figures](https://github.com/cisco-open/network-sketcher/blob/main/network-sketcher_online/ns_engine/nsm_ddx_figure.py): `network-sketcher_online/ns_engine/nsm_ddx_figure.py`
- [AI context](https://github.com/cisco-open/network-sketcher/blob/main/network-sketcher_online/ns_engine/nsm_ai_context.py): `network-sketcher_online/ns_engine/nsm_ai_context.py`

### Master and shared services

- [Network master](https://github.com/cisco-open/network-sketcher/blob/main/network-sketcher_online/ns_engine/nsm_io.py): `network-sketcher_online/ns_engine/nsm_io.py`
- [Master utilities](https://github.com/cisco-open/network-sketcher/blob/main/network-sketcher_online/ns_engine/nsm_def.py): `network-sketcher_online/ns_engine/nsm_def.py`
- [Offline master utilities](https://github.com/cisco-open/network-sketcher/blob/main/network-sketcher_offline/ns_def.py): `network-sketcher_offline/ns_def.py`
- [Layer synchronization](https://github.com/cisco-open/network-sketcher/blob/main/network-sketcher_online/ns_engine/nsm_sync_between_layers.py): `network-sketcher_online/ns_engine/nsm_sync_between_layers.py`
- [Attribute tables](https://github.com/cisco-open/network-sketcher/blob/main/network-sketcher_online/ns_engine/nsm_attribute_table_from_master.py): `network-sketcher_online/ns_engine/nsm_attribute_table_from_master.py`
- [Design extensions](https://github.com/cisco-open/network-sketcher/blob/main/network-sketcher_online/ns_engine/nsm_extensions.py): `network-sketcher_online/ns_engine/nsm_extensions.py`

### Other components

- **LLM client**
- **Web browser**
- **Desktop user**

## Connections

- LLM client → Local MCP server: sends tool calls (evidence: `README.md`)
- Local MCP server → Online engine adapter: runs engine (evidence: `network-sketcher_local_mcp/ns_mcp_server.py`)
- Local MCP server → AI context: requests context (evidence: `network-sketcher_local_mcp/ns_mcp_server.py`)
- Local MCP server → Network master: uses file I/O (evidence: `network-sketcher_local_mcp/ns_mcp_server.py`)
- Web browser → Online web service: submits design (evidence: `README.md`)
- Online web service → Online engine adapter: runs commands (evidence: `network-sketcher_online/ns_web_start.py`)
- Online web service → AI context: generates context (evidence: `network-sketcher_online/ns_web_start.py`)
- Online web service → Device table: serves table (evidence: `network-sketcher_online/ns_web_start.py`)
- Online web service → Combined HTML viewer: serves viewer (evidence: `network-sketcher_online/ns_web_start.py`)
- Desktop user → Offline GUI: edits design (evidence: `README.md`)
- Desktop user → Offline CLI: runs commands (evidence: `README.md`)
- Offline GUI → Offline command engine: dispatches actions (evidence: `network-sketcher_offline/network_sketcher.py`)
- Offline GUI → Layer synchronization: synchronizes layers (evidence: `network-sketcher_offline/network_sketcher.py`)
- Offline CLI → Layer synchronization: synchronizes layers (evidence: `network-sketcher_offline/ns_cli.py`)
- Online engine adapter → Online command engine: runs commands (evidence: `network-sketcher_online/ns_engine/nsm_adapter.py`)
- Online engine adapter → Network master: converts master (evidence: `network-sketcher_online/ns_engine/nsm_adapter.py`)
- Online engine adapter → L1 topology: creates topology
- Online engine adapter → L2 topology: creates topology
- Online engine adapter → L3 topology: creates topology
- Online engine adapter → Device table: creates table (evidence: `network-sketcher_online/ns_engine/nsm_device_table_html.py`)
- Online engine adapter → SVG rendering: renders SVG
- Online engine adapter → PowerPoint figures: creates figures
- Online engine adapter → VPN topology: supports VPN diagrams
- Offline command engine → Offline master utilities: uses utilities (evidence: `network-sketcher_offline/ns_cli.py`)
- Offline command engine → L1 topology: builds L1 (evidence: `network-sketcher_offline/ns_cli.py`)
- Offline command engine → L2 topology: builds L2 (evidence: `network-sketcher_offline/ns_cli.py`)
- Offline command engine → L3 topology: builds L3 (evidence: `network-sketcher_offline/ns_cli.py`)
- Offline command engine → Attribute tables: builds tables (evidence: `network-sketcher_offline/ns_cli.py`)
- Offline command engine → Design extensions: dispatches extensions (evidence: `network-sketcher_offline/ns_cli.py`)
- L1 topology → Network master: reads master
- L2 topology → Network master: reads master
- L3 topology → Network master: reads master
- Master utilities → Network master: reads master (evidence: `network-sketcher_online/ns_engine/nsm_def.py`)
- Device table → Master utilities: uses utilities (evidence: `network-sketcher_online/ns_engine/nsm_device_table_html.py`)
- Attribute tables → Master utilities: uses utilities
- Design extensions → Master utilities: uses utilities (evidence: `network-sketcher_online/ns_engine/nsm_extensions.py`)
- Design extensions → AI context: supports context (evidence: `network-sketcher_online/ns_engine/nsm_extensions.py`)
