# Shumokuの設計思想

Canonical: https://docs.shumoku.dev/en/about/philosophy
Language: en

docs/PHILOSOPHY.md

# Shumokuの設計思想

ネットワーク構成図を実態に追従する運用の地図として扱う理由です。

This document is currently available in Japanese only.

> 構成図を、描いて古くなる資料から、実態に追従し続ける運用の地図へ。 **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** | 機器・モジュール・ケーブルを置き、トポロジーを視覚的に **設計・編集**する。物理構成や部材表（BOM）まで扱う。 |
| **Server** | コアが生成した地図を土台に可視化・監視を行い、流量・状態・アラートを重ねて、ネットワークの **動きと現状を把握**する。 |

コアが「構造を読める図にする」土台であり、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つの軸。新機能を入れるか迷ったら、この軸に照らす。

| 軸 | 意味 |
| --- | --- |
| **Readable** | 人間が読める・美しい・構造がわかる（最優先） |
| **Reproducible** | YAML / JSON / Git / CI で再生成できる（Diagram as Code） |
| **Reality-aware** | NetBox・LLDP・SNMP・API など実態に近い情報を使う |
| **Source-agnostic** | 特定の情報源に閉じない |
| **Operational** | NOC・監視・障害対応・共有で使える |
| **Extensible** | plugins・vendor catalog・templates で広げられる |

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

## 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 は、ネットワーク構造を人間が読める地図に変換する可視化ツールである。

## 軸の早見表

| # | 軸 |
| --- | --- |
| 1 | 技術は、人を助けるための術である |
| 2 | WiFi は天から降ってこない。インフラは地にある |
| 3 | ネットワークにも、地図が必要だ |
| 4 | 構成図は、描くものではなく生成し続けるもの |
| 5 | 良い構成図は「把握できる × 信頼できる × 更新できる」 |
| 6 | 読みやすさは飾りではなく、運用価値そのもの |
| 7 | トポロジーを中心に、状態を理解する（数値中心 → 構造中心） |
| 8 | ぼーっと見ていても状態がわかる（熟練度に応じて潜れる） |
| 9 | 専門家にも非専門家にも伝わるインフラ可視化 |
| 10 | OSS として、閉じたネットワーク運用文化を開く |

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