Backstageカタログを60秒で本物のC4アーキテクチャに変える
Backstageはザ・カタログです。プラットフォームチームで働いているなら、何ヶ月もかけてcatalog-info.yamlファイルを整え、アノテーションを設定し、dependsOnリンクを正しく繋ぎ、「なぜサービスが表示されないのか」というSlackの質問に答えてきたことでしょう。その仕事は本物です。あなたのシステムの実際の地図を表しています。
しかし、ここに問題があります：Backstageはソフトウェアをリスト化するために作られたのであって、モデリングするためではありません。コンポーネントページは便利です。リレーションは少ない。C4プラグインは後付けです。700のサービスをフラットなリストでスクロールできても、それらがどのように組み合わさっているかは見えません。
本物のアーキテクチャビューが欲しければ、たいてい選択肢は2つでした：別のツールでカタログを手動で再構築するか、Backstageが提供するもので我慢するかです。
今日、その選択肢はなくなります。
ArchylはBackstageのSoftware Catalogを直接インポートできるようになりました。 1つのcurl、1回のアップロードで、すでにあなたが整備したすべてのSystem、Component、Resource、APIが、完全でナビゲート可能なC4モデルとして現れます — リレーション、OpenAPIコントラクト、インフラリソース、メタデータすべてそのままに。
60秒、3ステップ
Backstageは1つのRESTエンドポイントから完全なエンティティカタログを公開しています。引っ張ってきて、Archylにドロップ、それで終わりです。
ステップ1 — カタログをエクスポート
curl -H "Authorization: Bearer $BACKSTAGE_TOKEN" \
https://backstage.your-company.com/api/catalog/entities \
-o entities.json
これがエクスポートのすべてです。エンドポイントはBackstageが知るすべてのエンティティをストリームします：Systems、Components、Resources、APIs、Groups、Users — すべてです。多くの組織では、何千ものエントリーを含む5〜30 MBのJSON配列が得られます。
認証なしでテストする場合（一部のBackstageインスタンスは内部ネットワークでのカタログ公開読み取りを許可）、Authorizationヘッダーを外せます。ファイルサイズを抑えるためにkindでフィルタリングが必要なら、Backstageはクエリパラメータをサポートします：?filter=kind=component,kind=system,kind=api,kind=resourceでArchylが実際にマップする内容だけにレスポンスを絞れます。
ステップ2 — インポートダイアログを開く
Archylでプロジェクトをインポートをクリック（既存プロジェクト内ならインポート）、Backstageタブを選択し、entities.jsonをアップロードまたはそのまま貼り付けます。
Archylはファイルを検証し、書き込みの前に作成される内容（システム数、コンテナ数、APIコントラクト数、リレーション数）を正確に表示します。
ステップ3 — インポートをクリック
プロジェクトが満たされます。約3,000エンティティを含む9 MBのカタログは数秒でインポートされます。任意のシステムをクリックしてC4 Level 2でコンテナを並べて見たり、APIに掘り下げたり、dependsOnエッジをスタック全体で追ったりできます。
実際に何がマッピングされるか
Backstageからのインポートで難しいのはJSONを読むことではありません — 2つの異なる思考モデルの間で翻訳することです。Backstageは型付きリレーションで接続されたフラットなエンティティで考えます。C4はネストされたレベルで考えます。Archylがどう橋渡しするかは以下の通りです：
| Backstage | Archyl | 備考 |
|---|---|---|
System |
C4 System (レベル1) | 名前空間をまたぐ同名のシステムは自動的に区別されます |
Component |
所属するSystem下のContainer | service → service、cronworkflow → worker、website → web_app |
Resource |
所属するSystem下のContainer | 型を考慮：s3-bucket → file_storage；rds-instance、dynamo-db-table、valkey-cluster、opensearch-domain → database；kafka-topic、sqs-queue → message_queue；repository → library |
API（spec.definition付き） |
APIコントラクト | OpenAPI 3、gRPC、GraphQL、AsyncAPI仕様はインラインで保存され、プロバイダー/コンシューマーコンポーネントにリンクされます |
dependsOn、dependencyOf |
depends_onリレーション |
双方向のペアは自動的に重複排除されます |
consumesApi |
usesリレーション |
APIを介して実際のプロバイダーコンポーネントまで解決されます |
producesTo、producedBy |
publishes_toリレーション |
|
consumesFrom、consumedBy |
consumes_fromリレーション |
|
versionedIn、versions |
depends_onリレーション |
"source code"とラベル付け |
metadata.namespace、spec.lifecycle、spec.type、metadata.tags |
タグ | フィルタリングとオーバーレイのためすべて引き継ぎ |
User、Group |
スキップ | 人物グラフはC4の概念ではありません |
spec.systemを持たないComponentとResourceは、何も静かに削除されないように合成的なUncategorizedシステムに入ります。
実際に最も重要な2つの詳細：
- APIコントラクトは中身を伴って届きます。
spec.definitionを含むBackstageのAPIエンティティ（インラインのOpenAPI YAML、gRPCの.proto）はすべて、完全な仕様が添付され、プロバイダーコンポーネントにリンクされたArchyl APIコントラクトとしてインポートされます。手動での仕様再アップロードは不要です。 - Resourceの型は保存されます。 Kafkaトピックは汎用の"service"にはなりません —
message_queueコンテナです。RDSインスタンスはdatabaseです。S3バケットはfile_storageです。視覚モデルは各インフラ要素の実際の性質を反映します。
リソース増殖について一言
組織がKubernetesで重く動いているなら、Backstageカタログにはおそらく数百 — おそらく数千 — のexternal-secret、repository、datadog-service、load-balancerリソースがクラスタから自動検出されています。すべてインポートします。
最初は多く見えるかもしれません。実際に多いのです。
しかし、いくつかのオプションがあります：
- 保持してフィルタする。 インポートされたコンテナはすべて
type:external-secret（など）のタグを持ちます。Archylのオーバーレイとタグフィルタで、図上で非表示にしつつクエリ可能なまま保てます。 - ノイズを一括削除する。 モデルに不要なら、タイプごとに2クリックでカテゴリ全体を削除できます。
- フィルタ付きで再エクスポート。 Backstageの
?filter=クエリパラメータを使って、関心のないリソース種をインポート前に除外できます。
すべてをインポートすることを選んだのは、代替案 — 不要と思われるデータを静かに捨てる — の方が悪いからです。あなたがカタログを整備しました。何を残すかはあなたが決めます。
実際に何が得られるか
Backstageカタログは何が存在するかを教えてくれます。Archylアーキテクチャは何が起こっているかを教えてくれます。
カタログがArchylで生きるようになると、Backstageには単純にできないことがアンロックされます：
本物のC4ダイアグラム。 インタラクティブで、ズーム可能、4レベルすべて — System Context、Container、Component、Code — を行き来できます。任意のサービスをクリックしてその内部に掘り下げ、リレーションをスタック全体で追えます。
ドリフト検出。 Archylはドキュメント化されたアーキテクチャをリポジトリの実際のコードと継続的に比較します。カタログが「ServiceAがServiceBを呼び出す」と言っていてもコードが6ヶ月前にやめていれば、見つかります — インシデント中に発見するのではなく。
アーキテクチャ準拠ルール。 「決済ドメイン外のサービスはlegacy-auth-apiを呼び出してはならない」あるいは「すべての外部呼び出しはAPI gatewayを通らなければならない」をコード化できます。Archylは自動的に強制し、すべてのPRで違反を表面化します。
APIコントラクトインテリジェンス。 Backstageに送り込んできたOpenAPI仕様が今やアーキテクチャの内側に存在し、プロデューサーとコンシューマーにリンクされています。news-apiの破壊的変更ですか？依存している下流サービスを正確に確認できます。
アーキテクチャに紐づくDORAメトリクス。 デプロイ頻度、リードタイム、変更失敗率、MTTRを特定のシステム、コンテナ、チームに接続。アーキテクチャのどの部分が健全でどこが困難に陥っているかが見えます。
Architecture Decision Records。 ようやくなぜを何の隣に書く場所ができ、影響を受けるシステムやコンポーネントに直接リンクされます。
MCP統合。 チームのすべてのAIコーディングエージェント — Claude Code、Cursor、Windsurf — が同じアーキテクチャコンテキストを共有します。サービスがどう組み合わさっているかをLLMに何度も説明するのをやめましょう。
Backstageカタログは「どんなサービスを動かしている？」に答えます。Archylは「それらはどう繋がっていて、何がドリフトしていて、何がリスクで、どこに投資すべきか？」に答えます。カタログをインポートするということは、両者の間で選ぶ必要がないということです。
AIエージェントワークフロー向け
同じインポートはArchylのMCPサーバー経由で公開されています。Claude Code、Cursor、または任意のAIコーディングエージェントをformat: "backstage"とentities.jsonの内容を持つimport_dslツールに向ければ、誰もブラウザに触らずにアーキテクチャが着地します。
import_dslツールを以下で使用：
- projectId: <あなたのプロジェクトUUID>
- content: <entities.jsonの内容>
- format: "backstage"
CIからカタログ同期をスクリプト化したいときや、Backstageのメジャーアップデート後にAIアシスタントにモデルを更新させたいときに便利です。
今すぐ試す
チームが今日Backstageを動かしているなら、文字通りcurl一発で完全なC4アーキテクチャに到達できます。
- 上記のcurlを実行。
- Archylを開き、プロジェクトをインポートをクリック、Backstageを選択。
- サービス、API、キュー、データベースがナビゲート可能なアーキテクチャに収まる様子を見守る。
インポートは無料ティアを含むすべてのプランで動作します。判断はカタログがポータブルかどうかではなく、次に何をしたいかに基づくべきだと考えています。
Backstageカタログは長い間アーキテクチャになるのを待っていました。それを叶えてあげましょう。