はじめに
ソフトウェアアーキテクチャやビジネスプロセスは、文章やソースコードだけでは理解しにくく、視覚的に表現する方がはるかに分かりやすい場合が多いです。しかし、従来の図描画ツールでは図の維持管理が困難になることがあります。レイアウトの手動調整が必要で、変更のレビューが難しく、コラボレーションも画像ファイルや独自形式のプロジェクトドキュメントの交換に依存しがちです。
VPasCode、略称は「Visual Paradigm as Code、ブラウザベースの Diagram-as-Code ワークフローを通じてこれらの課題に対処します。キャンバスに図形を手動で配置するのではなく、ユーザーは PlantUML、Mermaid、Graphviz などのテキストベースの言語で図を記述します。VPasCode はその後、ソースコードをリアルタイムで視覚的な図としてレンダリングします。コードエディタ、図レンダラー、AI 支援機能、共有機能、エクスポートツールを一つのワークスペースに統合しています。
その結果、ソフトウェア開発に近く、図をテキストとして作成し、コード変更を通じてレビューし、バージョン管理に保存し、システムが変化したら再生成し、ドキュメント間で再利用できるワークフローが実現されます。
Diagram-as-Code とは何か？
Diagram-as-Code（DaC）とは、図を手動で描画するのではなく、テキスト言語で定義する実践手法です。
従来のワークフローには以下のような手順が含まれることがあります：
-
図描画アプリケーションを開く。
-
図形をキャンバスにドラッグする。
-
図形を手動で接続する。
-
構造が変更されたときにオブジェクトの位置を再配置する。
-
ドキュメント用に画像をエクスポートする。
Diagram-as-Code ワークフローでは、これらの手順をソースコードで置き換えます：
flowchart LR
User --> WebApp
WebApp --> API
API --> Database
レンダラーはこの定義を視覚的なフローチャートに変換します。アーキテクチャが変更された場合、著者はすべてのオブジェクトを手動で再配置するのではなく、テキストを編集します。
このアプローチにはいくつかの実用的な利点があります：
-
バージョン管理：図の定義を、アプリケーションコードやドキュメントと一緒に Git に保存できます。
-
可読性のある変更：レビューアーは、通常の差分（diff）を通じて追加、削除、関係性の変更を検査できます。
-
再現性:同じソースから、図を一貫して再生成できます。
-
自動化:図はドキュメントやビルドパイプラインの一部に組み込むことができます。
-
より迅速な反復作業:構造的な変更は、多くの図形を操作するのではなく、数行を編集するだけで済むことが一般的です。
VPasCode は、このワークフローを、ライブレンダリングと複数の図式標準へのサポートを備えた、統一されたブラウザベースの環境にパッケージ化します。
Visual Paradigm における VPasCode の役割
Visual Paradigm は、ソフトウェアモデリング、企業アーキテクチャ、ドキュメント作成、視覚的分析のためのより広範なエコシステムを提供します。VPasCode は、軽量でテキストファーストの入り口を提供することで、これらのツールを補完します。
チームが以下のような場合に特に役立ちます:
-
記述された説明から素早くアーキテクチャのスケッチを作成する。
-
図をソースコードや技術ドキュメントに近づけて管理する。
-
完全にカスタマイズされた視覚モデルに投資する前に、システムのプロトタイプを作成する。
-
AI を通じて図を生成し、その後結果を手動で洗練させる。
-
大きなプロジェクトファイルを送信せずに、ライブ図を共有する。
-
レポート、プレゼンテーション、およびウィキ用の図をエクスポートする。
-
テキストベースの図から、Visual Paradigm のより広範なモデリングおよびドキュメントワークフローへ移行する。
中心的な考え方は、Diagram-as-Code がすべての視覚モデリングタスクを置き換えるということではありません。むしろ、チームに図を作成するための高速で保守可能な方法を提供し、一方、Visual Paradigm はより詳細なモデリング、ドキュメント作成、およびプレゼンテーション作業のために引き続き利用可能です。
VPasCode の主要コンポーネント
ブラウザベースのコードエディタ
VPasCode はウェブブラウザ上で動作するため、ローカルインストールや複雑なセットアップは不要です。そのエディタは図のソースコード用に設計されており、構文ハイライト、行番号、インデントサポート、リアルタイムステータスフィードバックなどの機能を備えています。
一般的なワークフローは以下の通りです:
-
VPasCode エディタを開く。
-
図式言語を選択または検出する。
-
図コードを入力または貼り付ける。
-
ライブレンダリングされた結果を確認する。
-
構文を修正するか、構造を洗練させる。
-
完成した図を共有またはエクスポートする。
ライブプレビューキャンバス
プレビューパネルは、ソースを編集する際にレンダリングされた図を表示します。この並列ワークフローにより、エディタと別々のレンダリングツールの間で切り替える必要性が軽減されます。
有用な作成パターンは、2 段階で作業することです：
-
構造フェーズ：ノード、アクター、コンポーネント、および関係性を定義します。
-
プレゼンテーションフェーズ：方向、ラベル、グループ化、テーマ、および視覚的スタイルを調整します。
この分離により、ユーザーはまず正確性に、次に可読性に集中することができます。
複数の図描画エンジン
VPasCode は、複数のテキストから図への変換エンジンを一つの環境に統合しています。主なサポート形式には PlantUML、Mermaid、Graphviz が含まれ、より広範なプラットフォームでは追加の形式や機能も利用可能です。
| エンジン | 最も適した用途 | 典型的な図 |
|---|---|---|
| PlantUML | 正式なソフトウェアおよびエンタープライズモデリング | クラス、シーケンス、コンポーネント、デプロイメント、ユースケース、C4、および ArchiMate の図 |
| Mermaid | 軽量なドキュメント作成および開発ワークフロー | フローチャート、シーケンス図、状態図、タイムライン、ER 図、およびアーキテクチャ図 |
| Graphviz | グラフ関係および階層構造 | 依存関係グラフ、ネットワークマップ、組織図、および有向または無向グラフ |
| D2 およびその他のサポート形式 | 現代的なテキストベースの視覚モデリング | アーキテクチャ、システム間の関係、およびサポートされている場合の専門的な可視化 |
最適なエンジンは、対象読者と図の目的によって異なります。正式な UML やアーキテクチャ表記が重要である場合、PlantUML が適していることが多いです。Markdown ベースのドキュメント作成には Mermaid が便利です。関係性やグラフ構造の表現が主要な課題である場合、Graphviz が効果的です。
主要な概念
宣言的図定義
宣言的ワークフローでは、作成者が図に何が含まれ、その要素がどのように関連するかを記述します。レンダリングエンジンがレイアウトの多くを決定します。
例：
@startuml
actor Customer
participant "Web Application" as Web
participant "Payment Service" as Payment
database Orders
Customer -> Web: Submit order
Web -> Payment: Authorize payment
Payment --> Web: Payment approved
Web -> Orders: Save order
Web --> Customer: Show confirmation
@enduml
このコードは、作成者がライフラインや矢印を手動で描画する必要なく、参加者と相互作用を表現します。
ソースを唯一の真実の源として扱う
図のソースは、モデルの権威ある表現として扱うべきです。エクスポートされた PNG や PDF ファイルは有用な出力ですが、図のコピーとして唯一のものにしてはいけません。
推奨されるプロジェクト構造は以下のようになります：
architecture/
├── context/
│ └── system-context.puml
├── containers/
│ └── application-containers.mmd
├── deployment/
│ └── production-topology.dot
└── README.md
これにより、システムが変更された際に図を更新しやすくなります。
ライブレンダリング
ライブレンダリングとは、ソースが変更されるにつれて視覚的な出力が更新されることを意味します。これにより迅速なフィードバックが可能になり、欠落した関係、構文の誤り、不明瞭なレイアウトがエクスポート後ではなく、作成中に可視化されます。
エンジン選択
異なる言語は、異なる構文、レイアウトアルゴリズム、およびサポートされる図のタイプを持っています。早期にエンジンを選択することで、後の不要な書き換えを防ぎます。
例えば：
-
Markdown ドキュメント内の簡潔なサービスフローには Mermaid を使用します。
-
詳細な C4 または UML モデルには PlantUML を使用します。
-
大規模な依存関係ネットワークには Graphviz を使用します。
-
図が主にマインドマップ、データ可視化、またはその他の非 UML 表現である場合は、専用のサポート形式を使用してください。
AI 支援による作成
VPasCode には、自然言語のプロンプトから図コードを生成したり、既存の図を変更したり、構文の問題を診断したり、ラベルを翻訳したりするための AI 指向の機能が含まれています。一部の高度な AI 機能は、使用されている Visual Paradigm のエディションまたはサブスクリプションに依存する場合があります。
AI は、プロンプトが以下を指定している場合に最も効果的です：
-
図のタイプ。
-
意図された記法またはエンジン。
-
システムの構成要素。
-
構成要素間の関係。
-
希望する詳細レベル。
-
対象読者またはフォーマット要件。
例えば：
オンライン書店のためのPlantUML C4コンテナ図を作成してください。顧客、Webアプリケーション、カタログサービス、注文サービス、支払いプロバイダー、およびPostgreSQLデータベースを含めてください。主要なデータフローを示し、明確なシステム境界を使用してください。
AIによって生成されたコードは、以下の点について引き続きレビューする必要があります：
-
誤った関係。
-
欠落しているコンポーネント。
-
曖昧なラベル。
-
サポートされていない構文。
-
プロンプトで明示されていないセキュリティまたはアーキテクチャに関する前提条件。
バージョン管理可能な視覚的ドキュメント
テキストベースの図は、ソースコードと同様にレビューできます。変更前：
変更後：
キャッシュ層が導入されたことを明確に伝えます。
これにより、図は以下の用途により適したものになります：
-
プルリクエスト。
-
アーキテクチャ意思決定記録。
-
リリースドキュメント。
-
設計レビュー。
-
コンプライアンスの証拠。
-
オンボーディング資料。
Visual Paradigm VPasCode を使用した例
例 1：3 層 Web アプリケーション
Mermaid は、単純なアーキテクチャフローには実用的な選択肢です：
flowchart TB
User[ユーザーブラウザ]
Web[Web フロントエンド]
API[アプリケーション API]
DB[(リレーショナルデータベース)]
User --> Web
Web --> API
API --> DB
この図は、詳細な UML 表記を必要とせずに主要な層を伝達します。後で認証、キャッシュ、キュー、または外部サービスで拡張できます。
例 2：マイクロサービスリクエストフロー
タイミングや相互作用が重要になる場合、シーケンス図は有用です：
@startuml
actor User
participant "Web クライアント" as Client
participant "API ゲートウェイ" as Gateway
participant "注文サービス" as Orders
participant "支払いサービス" as Payments
database "注文データベース" as DB
User -> Client: 注文する
Client -> Gateway: POST /orders
Gateway -> Orders: 注文を作成
Orders -> Payments: 支払いを承認
Payments --> Orders: 承認済み
Orders -> DB: 注文を保存
Orders --> Gateway: 注文確認
Gateway --> Client: 201 Created
Client --> User: 確認を表示
@enduml
この例は、チームが API の境界、同期呼び出し、支払いの動作、および永続化について議論するのに役立ちます。
例 3：PlantUML を使用したシステムコンテキスト
PlantUML は、高レベルのアーキテクチャや C4 スタイルの図に非常に適しています：
@startuml
!include <C4/C4_Context>
Person(customer, "顧客", "注文を発生させ、追跡する")
System(shop, "オンラインストア", "商品閲覧とチェックアウトを提供")
System_Ext(payment, "支払いプロバイダー", "カード決済を処理")
System_Ext(email, "メールサービス", "注文通知を送信")
Rel(customer, shop, "使用する")
Rel(shop, payment, "通じて決済を処理")
Rel(shop, email, "通じて通知を送信")
@enduml
この図は実装の詳細ではなく、システム境界と外部関係に焦点を当てています。
例4：Graphvizを使用した依存関係グラフ
Graphvizは依存関係を表示するのに役立ちます：
digraph Dependencies {
rankdir=LR;
Frontend -> APIGateway;
APIGateway -> UserService;
APIGateway -> OrderService;
OrderService -> PaymentService;
OrderService -> OrderDatabase;
UserService -> UserDatabase;
}
大規模なソフトウェアシステムにおいて、この種のグラフは中核サービス、依存関係の連鎖、および潜在的な結合の問題を明らかにすることができます。
例5：AI支援による洗練
チームは自然言語によるリクエストから始めることができます：
ブラウザクライアント、APIゲートウェイ、チケットサービス、ナレッジベース、通知サービス、およびリレーショナルデータベースを備えたカスタマーサポートプラットフォームのMermaidアーキテクチャ図を生成してください。
生成後、著者はAIに以下を依頼するかもしれません：
-
チケットサービスと通知サービスの間にメッセージキューを追加する。
-
バックエンドサービスをシステム境界内にグループ化する。
-
非技術的な聴衆向けにラベルの名前を変更する。
-
図をMermaidからPlantUMLに変換する。
-
エラーを修正するレンダラーによって報告された。
重要な原則は、AIをモデリングの加速剤として扱い、アーキテクチャレビューの代替としないことです。
推奨されるVPasCodeワークフロー
1. 図の目的を定義する
コードを書く前に、図が答えるべき質問を決定してください。
例：
-
どのシステムが私たちの製品と連携していますか？
-
ユーザーのリクエストはバックエンドをどのように通過しますか？
-
どのサービスがデータベースに依存していますか？
-
アプリケーションはどのようにデプロイされますか？
-
注文承認に関与するビジネス手順は何ですか？
明確な目的が一つしかない図は、組織全体やシステム全体を示そうとする図よりも通常は理解しやすいです。
2. ダイアグラムエンジンを選択する
図の目的と対象読者に合わせて、PlantUML、Mermaid、Graphviz、または他のサポートされている形式を選択してください。
例：
-
Markdown リポジトリに埋め込まれた図の場合は Mermaid を選択してください。
-
正式な UML または C4 モデルの場合は PlantUML を選択してください。
-
依存関係分析の場合は Graphviz を選択してください。
-
記法が主題により適している場合は、専門的な形式を選択してください。
3. 最小限で有用なバージョンを構築する
主要なアクター、システム、および関係性から始めてください。すぐにすべての実装詳細を追加しないようにしてください。
アーキテクチャ図の場合は、以下から始めてください：
-
ユーザー。
-
主要なアプリケーション。
-
重要な外部システム。
-
主要なデータベース。
-
主要な通信経路。
その後、図の意図した質問に答えるのに役立つ場合のみ詳細を追加してください。
4. レンダリングと検証
ライブプレビューを使用して、以下を確認してください：
-
構文が有効かどうか。
-
図が読みやすいかどうか。
-
矢印が正しい方向を指しているかどうか。
-
ラベルが理解しやすいかどうか。
-
境界線とグループ化が正確かどうか。
-
通常のズームレベルでレイアウトが使用可能かどうか。
VPasCodeは、サポート対象のワークフローに対して構文フィードバックと AI 支援の修正機能を提供します。
5. 視覚言語を洗練させる
内容が正しいことが確認できたら、プレゼンテーションを改善します：
-
一貫した名前を使用する。
-
関連する要素をグループ化する。
-
交差する線を減らす。
-
明確な関係ラベルを使用する。
-
適切なテーマやスタイルを適用する。
-
詳細レベルを一貫させる。
目的は装飾を追加することではなく、読者の負担を減らすことです。
6. チームで図をレビューする
図を開発者、アーキテクト、アナリスト、または関係者と共有し、焦点を絞った質問を投げかけます：
-
主要なコンポーネントが欠落していることはありませんか？
-
フローは実際の動作を反映していますか？
-
システム境界は正しいですか？
-
誤解を招く関係はありませんか？
-
新しいチームメンバーは図を理解できますか？
ソースがテキストベースであるため、提案された変更をより体系的に取り込み、レビューすることができます。
7. エクスポートまたはドキュメントに接続する
図が完成したら、レポート、プレゼンテーション、技術文書、または社内ウィキでの使用のためにエクスポートします。VPasCode は、文書化されたワークフローにおいて、PNG、SVG、PDF などの画像およびベクトル指向の出力をサポートしています。また、OpenDocs を含む Visual Paradigm のドキュメント機能とも連携します。
長期的な保守のため、エクスポートされた画像とともに元のソースコードを保存してください。
コラボレーションとドキュメントのプラクティス
図は、それらが説明するシステムの近くに保持する
アーキテクチャ図を、関連するコードベースまたはドキュメントリポジトリと一緒に保存してください。これにより、実装が変更された際に図が更新される可能性が高まります。
意味のあるファイル名を使用する
以下のような名前を優先してください：
checkout-sequence.puml
production-deployment.mmd
service-dependencies.dot
以下のような一般的な名前は避けてください：diagram1 または 最終バージョン.
視聴者別にビューを分離する
1 つの図がすべての人に等しく役立つことはめったにありません。別のビューを維持することを検討してください:
-
経営層向けコンテキストビュー:主要システムとビジネス機能。
-
アーキテクチャビュー:サービス、データベース、および外部依存関係。
-
開発者向けシーケンスビュー:ランタイムの相互作用と API 呼び出し。
-
運用ビュー:ホスト、クラスター、ネットワーク、およびデプロイ先。
-
ビジネスプロセスビュー:アクティビティ、意思決定、および引き継ぎ。
各ビューは、異なるコミュニケーション目的を果たしながら、テキストから生成できます。
ラベルをドキュメントとして扱う
図のラベルは簡潔であると同時に意味のあるものであるべきです。「サービス A」は技術的に有効かもしれませんが、「注文サービス」はレビュー担当者や利害関係者により有用な文脈を提供します。
アーキテクチャ変更時に図を見直す
図は以下の場合に更新されるべきです:
-
主要なサービスが追加または削除された場合。
-
データベースまたは外部プロバイダーが変更された場合。
-
通信が非同期になった場合。
-
デプロイメントトポロジーが変更された場合。
-
公開 API またはビジネスプロセスが変更された場合。
これにより、図が時代遅れの図表になるのを防ぎます。
利点と制限
VPasCodeは、すでに Git、Markdown、継続的なドキュメント作成、またはインフラストラクチャ・アズ・コードのプラクティスを使用しているチームにとって特に価値があります。そのテキストファーストのワークフローにより、図の再現、レビュー、更新が容易になります。
また、複数の図描画構文を 1 つのブラウザベースのエディタに統合することで、ツールの断片化を減らします。ライブプレビュー、AI 支援、エクスポート、および Visual Paradigm のドキュメントワークフローを組み合わせる機能により、ソフトウェアエンジニアリング、エンタープライズアーキテクチャ、ビジネス分析の幅広い分野で有用です。
ただし、Diagram-as-Code はすべての状況で自動的に最良の選択肢ではありません。テキストベースの形式には学習曲線があり、一部の高度にカスタマイズされた図には、宣言型エンジンが提供するものよりも多くの手動による視覚的制御が必要になる場合があります。また、ソースが明確で焦点を絞ったビューに整理されていない場合、大規模な図は維持が困難になることもあります。
実用的な戦略は、VPasCode を用いて、迅速かつ保守可能でバージョン管理された図の作成を行うことですその後、より深いモデリング、カスタマイズ、またはドキュメント管理が必要になった場合に、他の Visual Paradigm の機能を使用します。
結論
VPasCodeは、ソフトウェア開発の原則を可視化モデリングに持ち込みます。テキストで図を定義することで、チームはバージョン管理、レビュー、再生成、共有が容易なアーキテクチャビュー、プロセスモデル、シーケンス図、依存関係グラフ、およびドキュメント用ビジュアルを作成できます。
PlantUML、Mermaid、Graphviz、およびその他の形式へのサポートにより、ユーザーは各問題に最も適した記法を選択できます。ライブレンダリングによりフィードバックループが短縮され、AI 機能により初期生成、構文修正、変更、翻訳が加速されます。より広範な Visual Paradigm エコシステムとの統合により、テキストベースの簡易スケッチから、より高度なモデリングおよびドキュメントワークフローへの道筋が提供されます。
VPasCode を最も効果的に使用する最も効果的な方法は、図を使い捨ての画像ではなく、維持管理されるプロジェクト資産として扱うことです：明確な目的を定義し、適切なエンジンを選択し、ソースをバージョン管理下に置き、チームと変更をレビューし、システムが変化するたびにエクスポートを再生成します。
その役割において、VPasCode は単なる図エディタ以上のものですそれは、ソースコード、AI 支援設計、共同アーキテクチャレビュー、およびプロフェッショナルな可視化モデリングをつなぐ架け橋です。