プロジェクトのエクスポートとインポート：完全にポータブルなアーキテクチャ
私たちは、アーキテクチャドキュメントはあなたのものだと信じています。プロプライエタリなフォーマットにロックされるべきではなく、API の背後に閉じ込められるべきでもなく、サブスクリプションティアに人質に取られるべきでもありません。システム、コンテナ、コンポーネント、リレーションシップのドキュメント化に時間を投資したなら、その成果を持ち出せるべきです。
今日、この信念を具体化します。Archyl が完全なプロジェクトのエクスポートとインポートをサポートするようになりました。
すべてが1つのファイルに
プロジェクトをエクスポートすると、完全な C4 モデルを含む1つの JSON ファイルが得られます。定義したすべてのシステム、それらのシステム内のすべてのコンテナ、すべてのコンポーネント、コードレベルまでモデリングしていればコード要素も含まれます。それらを接続するリレーションシップとその説明、テクノロジーアノテーション。ダイアグラムをグループ化・整理するために作成したビジュアルオーバーレイ。
エクスポートはダイアグラムの空間レイアウトを保持します。構造を明確に伝えるために要素の配置に時間をかけたはずです——API ゲートウェイは左、データベースは右、外部システムは上部。その配置はランダムではなく、アーキテクチャを伝える方法の一部です。エクスポートはそのすべてをキャプチャします。
フォーマットはシンプルな JSON で、バージョン管理されドキュメント化されています。任意のテキストエディタで開いて読むことができます。カスタム処理をしたい場合はスクリプトで解析してください。あなたのデータが、あなたがコントロールできるフォーマットで提供されます。
エクスポートの仕組み
アクセス権のあるプロジェクトを開き、エクスポートオプションに移動してフォーマットを選択します。データポータビリティには JSON を選択してください。ファイルは即座にダウンロードされます——数百の要素を持つ大規模プロジェクトでも数秒でエクスポートされます。
異なるユースケースに対応するビジュアルエクスポートもサポートしています。SVG は Illustrator で編集可能なベクターフォーマット、またはドキュメントへの埋め込みに適しています。PNG は共有可能な画像を提供します。PDF はプロフェッショナルなドキュメントを作成します。4つの C4 レベルすべてを1つの包括的なエクスポートにまとめるオプションもあります。
自動化には、API エンドポイントが期待通りに動作します。/projects/{id}/export への GET リクエストで完全な JSON ペイロードが返されます。CI パイプラインに組み込んだり、週次バックアップをスケジュールしたり、既存のワークフローと統合したりできます。
インポートは新規プロジェクトを作成
アーキテクチャをインポートすると、Archyl は全く新しいプロジェクトを作成します。名前と slug を指定し、オプションでチームを選択し、JSON ファイルをアップロードします。システムがエクスポートを解析し、構造を検証し、新しい識別子ですべての要素を再作成します。
これは意図的な設計上の選択です。インポートは既存のプロジェクトにマージしたり、コンフリクトの調整を試みたりしません。ソースから独立したクリーンなコピーを作成します。元のプロジェクトは変更されず、インポートされたプロジェクトは独自の歩みを始めます。
インポートプロセスは ID の再マッピングの複雑さを透過的に処理します。エクスポートには要素作成時のオリジナル UUID が含まれています。インポートはすべてに新しい UUID を生成しながら、要素間のリレーションシップを保持します。特定のシステムに属していたコンテナは引き続きそのシステムに属します。2つのコンポーネントを接続していたリレーションシップは引き続き接続します。構造は同一で、識別子のみが変わります。
エクスポート内のリレーションシップが存在しない要素を参照している場合——部分エクスポートや破損したファイルからかもしれません——インポートは警告をログに記録して続行します。インポート可能なすべてのものが取得され、スキップされたものが可視化されます。
実際のユースケース
私たちが一緒に仕事をしているコンサルティングファームは、クライアントにアーキテクチャドキュメントを納品するためにエクスポートを使用しています。Archyl でクライアントのシステムをモデリングし、ディスカバリーと手動ドキュメント化で洗練し、最終結果をエクスポートします。クライアントは JSON ファイルを受け取り、自身の Archyl インスタンスにインポートするか、プロジェクト記録としてアーカイブできます。
あるエンタープライズプラットフォームチームは、毎週アーキテクチャを内部バックアップシステムにエクスポートしています。プライマリドキュメントに何か問題が起きた場合、最新のエクスポートから復元できます。JSON フォーマットなので、バックアップは読み取り可能で検証可能であり、不透明なバイナリブロブではありません。
あるスタートアップは買収時にエクスポートを使用しました。買収企業はターゲットのシステムアーキテクチャを理解する必要がありました。数週間のナレッジトランスファーミーティングをスケジュールする代わりに、チームは Archyl プロジェクトをエクスポートしてファイルを共有しました。買収企業はそれをインポートし、インタラクティブに探索し、何を買うのかを本当に理解した上で統合の議論に臨みました。
開発チームはエクスポートをアーキテクチャスナップショットとして使用しています。メジャーリリース後に現在の状態をエクスポートし、JSON ファイルをコードと一緒にコミットします。数ヶ月後、「マイクロサービス移行前のアーキテクチャはどうだった？」と誰かが聞いたとき、答えは git checkout するだけです。
エクスポートに含まれるもの
エクスポートには完全な C4 階層が含まれます。最上位のシステム、その中にネストされたコンテナ、コンテナ内のコンポーネント、コンポーネント内のコード要素。各要素は完全なメタデータを持ちます：名前、説明、タイプ、テクノロジースタック、タグ、位置座標、カスタムスタイリング。
リレーションシップは両方のエンドポイントが指定され、タイプ、説明、ラベル位置などのビジュアルプロパティとともにエクスポートされます。インポートプロセスはこれらを新しく作成された要素にマッピングし、正確な接続構造を維持します。
オーバーレイ——複雑なダイアグラムを整理するために作成したビジュアルグループ——は位置、サイズ、色、含まれる要素とともに含まれます。
現在エクスポートされないもの：ADR、プロジェクトドキュメント、ユーザーフロー、リポジトリ接続。エクスポートは C4 モデル自体——システム、コンテナ、コンポーネント、コード、およびそれらのリレーションシップに焦点を当てています。ユーザーのニーズに基づいて、将来のリリースでスコープの拡張を検討しています。
ロックインなし、トリックなし
エクスポートフォーマットは現在バージョン "1.0" を使用しています。機能を追加するにつれてフォーマットを更新しますが、後方互換性は維持します。今日作成したエクスポートは、Archyl が進化しても、何年後でも正しくインポートできます。
私たちはデータを閉じ込めることに興味はありません。あなたが留まることを選ぶほど有用であることに興味があります。エクスポートとインポートはその哲学へのコミットメントです。Archyl があなたに適したツールでなくなったら、アーキテクチャを持って行ってください。競合がより良いものを作ったなら、切り替えを簡単にしています。あなたの信頼を獲得し続けるプレッシャーは私たちにあります。
はじめに
エクスポートとインポートは、Free プランを含むすべてのプランで利用可能です。人為的な制限はなく、「エクスポートはプレミアム機能です」といったゲームはありません。
エクスポートするには：任意のプロジェクトを開き、エクスポートボタンを見つけ、JSON を選択してファイルを保存します。
インポートするには：プロジェクト一覧から「インポート」をクリックし、JSON ファイルをアップロードし、新しいプロジェクトに名前を付けて確認します。
あなたのアーキテクチャドキュメントはあなたのものです。今や、どこにでも持って行けます。
Archyl でドキュメント化できることについてもっと知りたいですか？C4 モデル入門をお読みいただくか、AI 駆動のアーキテクチャ発見で既存システムの自動マッピングをご覧ください。