# Shumoku Canonical: https://docs.shumoku.dev/en/overview Language: en README.md # Shumoku Network diagrams that do not drift away from reality. ![Shumoku](https://raw.githubusercontent.com/konoe-akitoshi/shumoku/73ebc72ba0bc0d1caf74e1ed34c89a6debcb0e6a/assets/logo-symbol.svg) # Shumoku ### Network diagrams that don’t drift away from reality. Shumoku generates readable network topology maps from structured network data. Network diagrams should not be static drawings that slowly become outdated. They should be reproducible, updateable, and grounded in a source of truth. Shumoku turns YAML, NetBox, LLDP, SNMP, and other topology data into diagrams that reflect how the network actually exists. [![npm version](https://img.shields.io/npm/v/shumoku.svg)](https://www.npmjs.com/package/shumoku) [![License: AGPL-3.0](https://img.shields.io/badge/License-AGPL--3.0-blue.svg)](https://github.com/konoe-akitoshi/shumoku/blob/73ebc72ba0bc0d1caf74e1ed34c89a6debcb0e6a/LICENSE) [![OpenSSF Best Practices](https://www.bestpractices.dev/projects/13294/badge)](https://www.bestpractices.dev/projects/13294) [![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/konoe-akitoshi/shumoku/badge)](https://scorecard.dev/viewer/?uri=github.com/konoe-akitoshi/shumoku) [![Discord](https://img.shields.io/discord/1476527182669938720?logo=discord&logoColor=white&label=Discord)](https://discord.gg/dyYbEsDZYr) [![Buy Me A Coffee](https://img.shields.io/badge/Buy%20Me%20A%20Coffee-support-yellow?logo=buy-me-a-coffee&logoColor=white)](https://buymeacoffee.com/akitoshi) [**Try the playground**](https://www.shumoku.dev/)  ·  [**Documentation**](https://www.shumoku.dev/ja/docs/server)  ·  [**Discord**](https://discord.gg/dyYbEsDZYr) > \[!NOTE\] 製作者が janog58 NOC に参加中です。導入支援・技術サポートはお気軽にご相談ください。  📧 [contact@shumoku.dev](mailto:contact@shumoku.dev)  ·  𝕏 [@shumoku\_dev](https://x.com/shumoku_dev)
Live weathermap — traffic utilization overlaid on the topology

Live weathermap — real-time traffic overlaid on the topology

NOC dashboard in production at JANOG57

Dashboard in production — JANOG57 NOC Live

## Philosophy > **Networks need maps, too.**  _ネットワークにも、地図が必要だ。_ Network diagrams are one of the most important tools in network operations. But in many environments they are still drawn by hand, updated manually, and slowly drift away from the real network. Shumoku starts from three principles. ### 1\. A diagram should be readable A topology map should make the structure of the network understandable at a glance — the relationships, layers, paths, and points of failure. ### 2\. A diagram should be trustworthy A diagram is only useful when it reflects reality. Shumoku generates diagrams from structured data — YAML, NetBox, LLDP, SNMP — instead of relying on manual drawing alone. ### 3\. A diagram should be updateable Networks change. Diagrams should be regenerated, reviewed, and maintained as part of the operational workflow. Shumoku treats network diagrams not as static pictures, but as **generated views of the network** — close to the source of truth, and easy to keep that way. → Read the full [design philosophy](https://docs.shumoku.dev/en/about/philosophy). ## What’s in the box At its core, Shumoku is a **topology generation engine** — it turns structured network data into a readable diagram. Around that core, it ships ready-to-use apps: | | | | | --- | --- | --- | | 📦 **Library + CLI** | The core engine — turn a YAML / JSON `NetworkGraph` into SVG / HTML / PNG, in Node or the browser | [`libs/shumoku`](https://docs.shumoku.dev/en/library) | | ✏️ **Editor** | Visual topology designer built on the engine — lay out devices, modules, and cables; derive a bill of materials | [`apps/editor`](https://github.com/konoe-akitoshi/shumoku/blob/73ebc72ba0bc0d1caf74e1ed34c89a6debcb0e6a/apps/editor) | | 🖥️ **Server** | Topology-based monitoring built on the engine — overlay live metrics and alerts on the map, build dashboards, share read-only links | [`apps/server`](https://docs.shumoku.dev/en/server) | ## Features * **Live weathermap** — Overlay real-time traffic utilization on links, color-coded by load * **Alert visualization** — Show active alerts from Zabbix, Prometheus, and Grafana on topology * **Auto-generate from NetBox** — Pull devices and cables from NetBox to build topology automatically * **Network discovery** — Seed-crawl SNMP + LLDP to discover topology with no inventory at all * **Interactive dashboards** — Pan, zoom, and drill into multi-layer network views in the browser * **900+ vendor icons** — Yamaha, Aruba, AWS, Juniper, and more — rendered at correct aspect ratios * **Shareable links** — Publish topology views with a share token — no login required ## Server The server is the full platform: a Bun + Hono API with an SQLite store and a SvelteKit web UI. Run it from the **published Docker image**, or build from source. See the **[Server Setup Guide](https://docs.shumoku.dev/en/server)** for Docker, Kubernetes (Helm), systemd, and manual deployment. ``` # Published Docker image (quickest) install -d -m 700 .shumoku openssl rand -base64 32 > .shumoku/admin-password chmod 600 .shumoku/admin-password docker run -d -p 8080:8080 -v shumoku-data:/data \ -v "$PWD/.shumoku/admin-password:/run/secrets/shumoku_admin_password:ro" \ -e SHUMOKU_BOOTSTRAP_ADMIN_PASSWORD_FILE=/run/secrets/shumoku_admin_password \ ghcr.io/konoe-akitoshi/shumoku:latest # → http://localhost:8080 (add `-e DEMO_MODE=true` to preload a sample network) # Docker Compose with an exact production version cd apps/server && SHUMOKU_VERSION=0.1.1 docker compose up -d # Development from source (API :8080 + web UI :5173) bun run dev:server # from the repo root ``` What you can do: 1. **Create topologies** — Upload YAML files or write them in the built-in editor 2. **Connect data sources** — Link Zabbix, Prometheus, or NetBox to pull live metrics 3. **Monitor in real-time** — See node status and link utilization update live over WebSocket 4. **Build dashboards** — Combine multiple topologies and metric widgets into custom views 5. **Share** — Generate public links for read-only access without authentication ## Editor The [Editor](https://editor.shumoku.dev/) is hosted on Vercel independently from the Server. Branches and pull requests receive isolated Preview deployments; merging to `main` updates Production. The running version, deployment channel, and commit are shown on the Editor home screen. ### Integrations | Source | What it pulls | | --- | --- | | **Zabbix** | Traffic metrics, host status, LLDP topology, and alerts via JSON-RPC | | **Prometheus** | SNMP / node-exporter metrics for link utilization, hosts, and Alertmanager alerts | | **NetBox** | Topology and hosts auto-discovered from DCIM / IPAM | | **Grafana** | Alerts via webhook or Alertmanager | | **Aruba Instant On** | Access points, switches, and site alerts from the cloud portal | | **Network scan** | Topology discovered by SNMP + LLDP seed-crawl, no inventory required | | **REST API** | Render topologies and fetch metrics programmatically from your own tools | See **[Plugin Authoring](https://docs.shumoku.dev/en/developers/plugin-authoring)** to write your own data source. ## YAML format ``` name: "Simple Network" settings: direction: TB theme: light subgraphs: - id: core label: "Core Layer" nodes: - id: rt-01 label: "Router 01" type: router vendor: yamaha model: rtx3510 parent: core - id: sw-01 label: "Switch 01" type: l3-switch parent: core links: - from: node: rt-01 port: lan1 to: node: sw-01 port: ge-0/0/0 bandwidth: 10G ``` ## Library The rendering engine is also published to npm as standalone packages. ![Sample network diagram](https://raw.githubusercontent.com/konoe-akitoshi/shumoku/73ebc72ba0bc0d1caf74e1ed34c89a6debcb0e6a/apps/website/public/hero-diagram.png) ``` npm install shumoku ``` ``` import { YamlParser, renderGraphToHtml } from 'shumoku' const { graph } = new YamlParser().parse(yamlString) // Interactive HTML (pan / zoom / tooltips) const html = await renderGraphToHtml(graph, { title: 'My Network' }) ``` Need SVG or PNG instead? Use the dedicated renderers: ``` import { renderGraphToSvg } from '@shumoku/renderer/static' import { renderGraphToPng } from '@shumoku/renderer-png' // Node.js only const svg = await renderGraphToSvg(graph) const png = await renderGraphToPng(graph, { scale: 2 }) ``` ### CLI ``` npx @shumoku/cli render network.yaml -o diagram.svg npx @shumoku/cli render network.yaml -f html -o diagram.html npx @shumoku/cli render network.yaml -f png -o diagram.png --scale 3 ``` **[Playground](https://www.shumoku.dev/)** | **[YAML Reference](https://www.shumoku.dev/docs/npm/yaml-reference)** Packages | Package | Path | Description | | --- | --- | --- | | [`shumoku`](https://docs.shumoku.dev/en/library) | `libs/shumoku` | All-in-one — core + SVG/HTML renderers | | [`@shumoku/core`](https://docs.shumoku.dev/en/library/packages/core) | `libs/@shumoku/core` | Models, parser, layout engine, themes, plugin kit | | [`@shumoku/renderer-svg`](https://docs.shumoku.dev/en/library/packages/renderer-svg) | `libs/@shumoku/renderer-svg` | Canonical SVG pipeline + legacy LayoutResult compatibility | | [`@shumoku/renderer-html`](https://docs.shumoku.dev/en/library/packages/renderer-html) | `libs/@shumoku/renderer-html` | Interactive HTML output | | [`@shumoku/renderer-png`](https://docs.shumoku.dev/en/library/packages/renderer-png) | `libs/@shumoku/renderer-png` | PNG output (Node.js, via resvg) | | [`@shumoku/renderer`](https://docs.shumoku.dev/en/library/packages/renderer) | `libs/@shumoku/renderer` | Canonical Svelte + static SVG renderer | | [`@shumoku/catalog`](https://docs.shumoku.dev/en/library/packages/catalog) | `libs/@shumoku/catalog` | Device / service catalog (vendor, model, sysObjectID) | | [`@shumoku/plugin-sdk`](https://docs.shumoku.dev/en/library/packages/plugin-sdk) | `libs/@shumoku/plugin-sdk` | HTTP client + pagination for data-source plugins | | [`@shumoku/cli`](https://docs.shumoku.dev/en/cli) | `apps/cli` | `shumoku render` command-line tool | Data-source plugins live in [`libs/plugins`](https://github.com/konoe-akitoshi/shumoku/blob/73ebc72ba0bc0d1caf74e1ed34c89a6debcb0e6a/libs/plugins): `zabbix`, `prometheus`, `netbox`, `grafana`, `aruba-instant-on`, `network-scan`. ## Repository layout ``` apps/ server/ Real-time monitoring platform — Bun + Hono API, SvelteKit web UI editor/ Visual topology designer — SvelteKit + xyflow cli/ Render YAML → SVG / HTML / PNG docs/ Documentation site (Next.js + Fumadocs) libs/ shumoku All-in-one npm package @shumoku/* Core engine, renderers, catalog, plugin SDK plugins/* Data-source integrations docs/ Architecture, YAML reference, plugin authoring examples/ Sample YAML networks + a sample plugin ``` Each top-level directory has its own index: [`apps/`](https://github.com/konoe-akitoshi/shumoku/blob/73ebc72ba0bc0d1caf74e1ed34c89a6debcb0e6a/apps/README.md) · [`libs/`](https://docs.shumoku.dev/en/library/packages) · [`examples/`](https://docs.shumoku.dev/en/library/examples). ## Documentation * [Server Guide](https://www.shumoku.dev/ja/docs/server) — Setup, data sources, dashboards * [YAML Reference](https://www.shumoku.dev/docs/npm/yaml-reference) — Full YAML syntax * [Vendor Icons](https://www.shumoku.dev/docs/npm/vendor-icons) — Available icons * [Playground](https://www.shumoku.dev/) — Try without installation * [Architecture](https://docs.shumoku.dev/en/developers/architecture) — Monorepo overview, load pipeline, layout engine * [Plugin Authoring](https://docs.shumoku.dev/en/developers/plugin-authoring) — Writing a `DataSourcePlugin`: capability mixins, data shapes, severity mapping ## Development ``` git clone https://github.com/konoe-akitoshi/shumoku.git cd shumoku bun install bun run build # build all libraries (excludes the server app) bun run dev # run everything in dev mode ``` Common scripts: `bun run test`, `bun run lint`, `bun run typecheck`, `bun run format`. This is a [Bun](https://bun.sh/) workspaces + [Turborepo](https://turbo.build/) monorepo — see [CONTRIBUTING.md](https://docs.shumoku.dev/en/community/contributing). ## Star History [![Star History Chart](https://api.star-history.com/svg?repos=konoe-akitoshi/shumoku&type=date&legend=top-left)](https://www.star-history.com/#konoe-akitoshi/shumoku&type=date&legend=top-left) ## Community & governance Shumoku is an open-source project led by [@konoe-akitoshi](https://github.com/konoe-akitoshi). Contributions are welcome under the AGPL-3.0 license. * [Contributing](https://docs.shumoku.dev/en/community/contributing) — dev setup, pull requests, DCO sign-off * [Governance](https://docs.shumoku.dev/en/project/governance) — roles, decision-making, releases * [Support](https://docs.shumoku.dev/en/community/support) — community help on GitHub · [Commercial support](https://docs.shumoku.dev/en/community/commercial-support) — paid implementation / integration services * [Code of Conduct](https://docs.shumoku.dev/en/project/code-of-conduct) · [Security](https://docs.shumoku.dev/en/project/security) · [Brand guidelines](https://docs.shumoku.dev/en/project/trademark) · [Name & logo story](https://docs.shumoku.dev/en/about/origin) (日本語) ## License Shumoku is free and open-source software, licensed under **AGPL-3.0** ([LICENSE](https://github.com/konoe-akitoshi/shumoku/blob/73ebc72ba0bc0d1caf74e1ed34c89a6debcb0e6a/LICENSE)). For enterprise use, we provide paid commercial **support and implementation services** (deployment, NetBox/Zabbix integration, PoC, custom plugin development, priority handling) — separate from the open-source license, in collaboration with our commercial support partner. See [COMMERCIAL\_SUPPORT.md](https://docs.shumoku.dev/en/community/commercial-support), or reach out at [contact@shumoku.dev](mailto:contact@shumoku.dev). If AGPL-3.0 does not fit your use case, contact us to discuss the options.