Shumokuの設計思想

構成図を、描いて古くなる資料から、実態に追従し続ける運用の地図へ。 Network diagrams that don’t drift away from reality.

このドキュメントは、Shumoku が 何を変えたいプロジェクトなのか を固定するための核となる文章である。README・未踏提案書・研究ポスター・ピッチ・設計ドキュメントの上位概念として参照し、新機能や設計判断に迷ったときの拠り所とする。

0. 出発点 — 技術は、人を助けるための術である

難しいものを扱う道具ほど、人に近いものであるべきだ。

ネットワークやインフラは社会を支える基盤でありながら、その構造や状態は専門的なツールの中に閉じ込められがちだ。ログ・メトリクス・構成情報・アラートはそれぞれ別の画面に分散し、専門家でなければ全体像をつかみにくい。

専門領域だからこそ、道具はもっと人にやさしく、直感的で、触れていて楽しいものであるべきだ。Shumoku は、インフラを人間が理解しやすい形へ変換するためのプロジェクトである。

WiFi は、天から降ってくるわけではない

私たちは日々、あたりまえのように通信を使う。けれど WiFi は天から降ってくるわけではない。その裏には、ケーブルとスイッチとルータと配線でできた、地に足のついた構造がある。誰かが設計し、敷設し、維持している現実のインフラだ。

インフラは「ある」。地にある。ならば、それは 見えたほうがいい。見えない構造は、理解されず、信頼されず、いざというとき頼れない。

WiFi doesn’t fall from the sky. Infrastructure is on the ground — so let’s be able to see it.

1. ネットワークにも、地図が必要だ

ネットワーク構成図は、単なる資料ではない。機器の接続関係・通信経路・依存関係・障害の影響範囲を理解するための 地図 である。設計・構築・運用・障害対応・インシデント対応において、人はこの地図を頼りに状況を判断する。

しかし現実の構成図は PowerPoint / Excel / draw.io / Visio などで手作業で作られ、構成変更のたびに更新が必要になる。やがて更新が追いつかず、実態とずれた図が残り、かえって判断を誤らせる。

必要なのは、ただ線が引かれた図ではない。把握でき、信頼でき、更新できる地図である。

2. Shumoku の構成 — コアと、その上のアプリケーション

Shumoku の中心にあるのは一つのコア技術だ — コードベース（構造化データ）から、ネットワークのトポロジー＝依存関係・接続構造を生成し、把握すること。YAML・NetBox・LLDP・SNMP などを source of truth として機器・ポート・リンク・階層を解釈し、読みやすいトポロジー図（SVG / HTML / PNG）を生成する。これが Library + CLI として提供される、Diagram as Code の心臓部である。

そのコアの上に、コアを生かすアプリケーションが乗る。

  Zinbei  ── 別ソフト：全く新しいモダンな監視環境（Shumoku を土台に使う）
     ▲ built on
  ┌──────────────────────────────────────────────────┐
  │  Editor                  Server                   │  ← Shumoku のアプリ
  │  設計・編集する             可視化・監視で把握する       │
  ├──────────────────────────────────────────────────┤
  │  Core — コードベースのトポロジー生成（依存関係の把握）   │  ← Shumoku のコア技術
  │  Library + CLI                                     │
  └──────────────────────────────────────────────────┘

コアが「構造を読める図にする」土台であり、Editor は人がその図を作る入口、Server は生成した地図を運用の現場で 生かす 場所である。どれも出発点は同じ — 構造を、人間が読める地図にする。

Shumoku’s core generates the map from code; the Editor lets you build it, the Server brings it to life in operations.

3. 構成図は、描くものから生成し続けるものへ

Shumoku は構成図を「人が手で描く静的な資料」ではなく、「構成情報から再生成可能な図」として扱う。目的は人間の理解を置き換えることではない。人間が理解するための図を、機械的に維持できるようにすることだ。

目指すのは見た目が整っただけの図ではなく、次の3つを満たす図である。

• 把握できる — 全体像と接続関係が一目で読み取れる
• 信頼できる — 実ネットワークに基づく source of truth である
• 更新できる — 構成変更に追従し、継続的に再生成できる

読みやすさを最優先する

生成できても人が読めない図には運用価値がない。レイアウト・ラベル・階層・アイコン・視覚的明瞭さは飾りではなく、運用価値そのものである。Shumoku は、共有したくなるほど美しく、維持できるほど構造化された図を目指す。実態に即すことは、その読みやすい図を 信頼できるものにするための条件 だ。

A generated diagram is only useful if people can actually read it.

4. トポロジーを中心に、状態を理解する（Server の役割）

数値は見える。ログも取れている。アラートも鳴っている。しかし「それがネットワーク全体のどこに位置し、何に影響し、どの経路・依存に関わるのか」を理解するには、複数の画面を行き来して人間が頭の中で統合するしかない。

Shumoku の Server は、トポロジーを中心に置くことでこの負担を減らす。流量・状態・アラートを、単体のデータとしてではなく、ネットワーク構造の上に重ねて意味づけして表示する。運用者は数値の変化ではなく「どこで何が起きているのか」を構造として理解できる。

ぼーっと見ていても状態がわかる

目指す可視化は、専門家だけのための詳細画面ではない。同じ地図を、見る人の熟練度に応じて異なる深さで理解できる。

• 非専門者 — 全体として何かが起きていることが伝わる
• 運用者 — 異常の位置と影響範囲を素早くつかめる
• 専門家 — そこから詳細なメトリクス・ログ・設定へ潜っていける

情報を削って初心者向けにするのではなく、同じ地図を熟練度に応じて深く潜れること。それが、ネットワークを組織全体で共有可能なものにする。

5. 設計原則（Principles）

Shumoku の判断基準となる6つの軸。新機能を入れるか迷ったら、この軸に照らす。

判断に迷ったら問う — 読みやすさに貢献するか / 再生成性を壊さないか / 実態に近づくか / 特定ツールに閉じすぎないか / 運用で使えるか / 拡張をふさがないか。

6. ロードマップ — 思想の段階的進化

機能名の羅列ではなく、思想が段階的に深まっていく形で捉える。すべて Shumoku のコア（コードベースのトポロジー生成）と、その上の Editor / Server の上で進む。

1. Draw readable maps — きれいで読みやすいトポロジー図を生成する描画エンジン（階層・リンク・ラベル・アイコン・レイアウト・テーマ・エクスポート）
2. Make diagrams reproducible — Diagram as Code。構造化データで定義し、Git で版管理し、CI で描画し、Markdown に埋め込み、ソースが変われば再生成する
3. Connect maps to reality — NetBox・LLDP・SNMP・API と接続し、図と実態の差を縮める
4. Make maps live — 流量・状態・アラート・利用率を地図に重ね、「何が起きているか」を見せる（Server）
5. Make maps operational — NOC ダッシュボード・読み取り専用共有・障害対応・引き継ぎ・チームでの理解（Server）
6. Build an ecosystem — plugins・templates・vendor catalog・examples・community で広げる

長期の到達点は、ネットワークトポロジーデータの共通ビジュアルレイヤーになること。

7. 目指すもの

Shumoku が目指すのは、単なる描画ライブラリでも、便利な監視ツールでもない。

ネットワークの構造と状態を、専門家だけでなく運用に関わるすべての人が理解できるようにすること。構成図を、古くなる資料から、実態に近づき続ける地図へ。地にあるインフラを、見える・読める・信頼できるものに。そして、インフラを扱うことそのものを、少しでもわかりやすく、楽しいものに。

加えて、ネットワーク運用の知見や可視化のやり方を一部のベンダーや属人性に閉じ込めず、OSS として開いていくこと。

The goal is not just prettier diagrams. The goal is network maps people can trust.

より大きな絵（参考）

Shumoku はそれ単体で、ネットワーク構造を読める地図にする可視化ツールとして完結する。

その応用先の一つとして、Shumoku を土台に使う 全く新しいモダンなネットワーク監視環境 Zinbei が想定されている。Zinbei は多様な監視データ（メトリクス・ログ・フロー・アラート）を束ねる別のソフトウェアで、Shumoku が描くトポロジーをその基盤に据える。

ただし本ドキュメントの主語はあくまで Shumoku である。Zinbei はあくまで応用先であり、Shumoku 自体の設計判断はそれに依存しない。

キーフレーズ

中核（強い順）

• ネットワークにも、地図が必要だ。 — Network diagrams that don’t drift away from reality.
• WiFi は天から降ってこない。インフラは地にある。 — WiFi doesn’t fall from the sky. Infrastructure is on the ground.
• 構成図を、描くものから生成し続けるものへ。 — From static drawings to living network maps.
• トポロジーを中心に、状態を理解する。 — 数値中心から構造中心へ。

Shumoku を一文で

• Shumoku turns network diagrams from static drawings into living maps.
• Shumoku は、ネットワーク構造を人間が読める地図に変換する可視化ツールである。

軸の早見表

特に核にするなら、この3本 — ネットワークにも地図が必要だ。 / WiFi は天から降ってこない、インフラは地にある。 / 構成図を、描くものから生成し続けるものへ。