Architecture as Code：YAMLファイルでC4モデル全体を定義する - Archyl Blog

アーキテクチャドキュメントをコードベースのファーストクラスシチズンに変える機能をリリースしました。archyl.yaml をご紹介します — 完全なC4モデルを記述し、Gitに格納され、コードレビューを経て、CI/CDで自動同期される宣言型DSLです。

Architecture as Code：YAMLファイルでC4モデル全体を定義する

アーキテクチャ図には賞味期限の問題があります。デザインセッションの後に描き、1週間は見栄えが良いのですが、コードが進化する一方で図は腐っていきます。6ヶ月後、新入社員はQ2で統合された3つのサービスを表示し、Q3で構築された2つに言及していないContainer図を見つめることになります。

Archylでは初日からこの問題に取り組んできました。AI発見機能は最新状態の維持に役立ちます。ビジュアルエディタは更新を容易にします。しかし、インフラをコードとして、ポリシーをコードとして、すべてをコードとして扱うチームの一群は、もっと根本的なものを求めていました。

彼らはアーキテクチャがGitの中に、それが記述するコードの隣に存在することを望んでいました。今日、まさにそれをリリースします。

archyl.yaml とは？

アーキテクチャ全体を宣言的に記述する単一のYAMLファイルです。リポジトリのルートに配置すれば、ArchylにおけるC4モデルの信頼できる唯一の情報源となります。

最小限のファイルはこのようになります：

version: "1.0"

project:
  name: "My Platform"
  description: "Microservices architecture"

systems:
  - name: Platform
    type: software_system
    containers:
      - name: API Gateway
        type: api
        technologies: [Go, gRPC]
      - name: User Database
        type: database
        technologies: [PostgreSQL]

relationships:
  - from: API Gateway
    to: User Database
    label: "Reads user data"
    type: reads_from

これだけです。Archylはこのファイルを読み取り、完全なC4モデルを構築し、ダイアグラムをレンダリングし、すべてを同期状態に保ちます。UIのクリック不要、手動同期不要、「図の更新を忘れた」ということもありません。

すべてを1つのファイルに

DSLは簡略化されたサブセットではなく、Archylがモデル化できるすべてをカバーしています：

C4の全4レベル。 システムはコンテナを含み、コンテナはコンポーネントを含み、コンポーネントはコードエレメントを含みます。YAMLのネストが階層を直接反映します。

ドット記法によるリレーションシップ。 Payment Service.API Gateway → Payment Service.Database のような読みやすい参照で任意の2要素を接続。UUIDなし、暗号的な識別子なし。grepに対応、diffに対応、人間が読めます。

テクノロジー、環境、リリース。 テクノロジーカタログの定義、デプロイ環境（ステージング、プロダクション）の宣言、リリースの追跡 — すべて同じファイルから。

ADRとドキュメント。 Architecture Decision Recordをインラインで記述するか、リポジトリ内のフォルダを指定。プロジェクトドキュメントも同様。

APIコントラクトとイベントチャネル。 OpenAPI仕様、gRPC定義、Kafkaトピックを宣言し、それらを公開または消費するコンポーネントにリンク。

ビジュアルオーバーレイ。 名前付きオーバーレイでダイアグラム上の要素をグループ化し、色とレベルを制御。

モノレポサポート。 includeを使用してアーキテクチャを複数のファイルに分割 — サービス、チーム、またはバウンデッドコンテキストごとに1つ — Archylが自動的にマージします。

なぜYAMLか？

カスタムDSL構文の構築も検討しました（StructurizrのDSLやTerraformのHCLのような）。実用的な理由でYAMLを選びました：

  1. 学習コストゼロ。 すべての開発者はすでにYAMLを知っています。新しい構文の学習不要、パーサーのインストール不要、エディタプラグイン不要。

  2. 無料のIDEサポート。 /api/v1/dsl/schemaでJSON Schemaを公開しています。IDEで参照すれば、Archyl固有のツールなしで補完、バリデーション、インラインドキュメントが得られます。

  3. diffに対応。 YAMLのdiffはプルリクエストで見やすくクリーンです。レビュアーは「あ、Payment Serviceに新しいコンテナを追加してRedisに接続したんだ」とすぐにわかります。

  4. ツールエコシステム。 リンター、フォーマッター、テンプレートエンジン（Helm、Kustomize）、すべてYAMLでそのまま動作します。

Gitネイティブワークフロー

ここに真の力があります。archyl.yamlがリポジトリに存在するため、アーキテクチャの変更はコードの変更と同じワークフローに従います：

  1. Branch。 フィーチャーブランチを作成し、YAMLを編集。
  2. Review。 プルリクエストを開く。チームがコード変更と一緒にアーキテクチャ変更をレビュー。
  3. Merge。 承認後、mainにマージ。
  4. Sync。 Archylが変更を検出し、ダイアグラムを自動更新。

「図にはXと書いてあるがコードはYをやっている」ということがなくなります。レビューを回避するアーキテクチャ変更もなくなります。誰も更新されたことを知らないドキュメントもなくなります。

CI/CD統合

CI/CDパイプラインとのファーストクラス統合を構築しました。GitHubには、ファイルの読み取り、APIの呼び出し、変更内容の報告をすべて処理する公式GitHub Actionを提供しています。

GitHub Actions（公式Action）：

name: Sync Architecture
on:
  push:
    branches: [main]
    paths: ['archyl.yaml']
jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: archyl-com/actions/sync@v1
        with:
          api-key: ${{ secrets.ARCHYL_API_KEY }}
          project-id: 'your-project-uuid'

これだけです。3行の設定で、プッシュごとにアーキテクチャが同期されます。Actionはカスタムファイルパス（モノレポ用）、セルフホストのArchylインスタンスに対応し、後続ステップ用にsummary、systems-created、relationships-createdなどのアウトプットを公開します。

GitLab CI：

sync-architecture:
  stage: deploy
  script:
    - |
      curl -X POST \
        https://api.archyl.com/api/v1/projects/$ARCHYL_PROJECT_ID/dsl/ingest \
        -H "X-API-Key: $ARCHYL_API_KEY" \
        -H "Content-Type: application/json" \
        -d "{\"content\": \"$(cat archyl.yaml | jq -Rs .)\"}"
  only:
    changes:
      - archyl.yaml

/ingestエンドポイントはAPIキー認証を受け付けるため、CIでOAuthフローは不要です。完全なモデルをインポートし、すべての要素を作成または更新し、変更の詳細なサマリーを返します。

ArchylのUIから直接同期することもできます。プロジェクトにGitリポジトリが接続されている場合、Architecture as Code設定の「今すぐ同期」をクリックすれば、Archylがリポジトリから直接ファイルを取得します。

双方向：ExportとImport

ワークフローは一方向ではありません。Archylのビジュアルエディタですでにプロジェクトをモデル化済みですか？エクスポートしましょう：

  • Exportは現在のモデルから完全なarchyl.yamlを生成します。すべてのシステム、コンテナ、コンポーネント、リレーションシップ、オーバーレイ、ADR、APIコントラクト、イベントチャネル、リリース — すべてがクリーンなYAMLにシリアライズされます。
  • Importはarchyl.yamlをパースし、プロジェクト内のすべての要素を作成または更新します。冪等性があります：同じファイルを2回インポートしても重複は作成されません。要素は名前で照合されupsertされます。
  • Import as ProjectはYAMLファイルから新しいプロジェクトを作成します。archyl.yamlを配置すれば、ワンクリックで完全に構成されたプロジェクトが得られます。

つまり、UIで始めてYAMLにエクスポートし、Gitにコミットしてコードファーストワークフローに切り替えることも、その逆も可能です。どちらのアプローチにもロックインはありません。

スマートな参照解決

DSLの最も難しい部分の1つは、リレーションシップ、オーバーレイ、イベント、APIコントラクトにおける要素参照の解決です。これを自然に処理するリゾルバーを構築しました：

  • 短い名前は曖昧でない場合に機能：API Gatewayはその名前を持つ要素が1つだけなら直接解決されます。
  • ドット記法で曖昧さを解消：Payment Service.API Gateway vs Analytics.API Gateway。
  • 任意の深さに対応：深くネストされた参照にはSystem.Container.Component.CodeElement。

リゾルバーはすべての可能なパス深度で各要素をインデックス化するため、常に最短の曖昧でない参照を使用できます。エクスポートは同じロジックを逆方向に使用し、最も読みやすい参照を生成します。

副作用のないバリデーション

YAMLが有効かどうかわからない場合、/validateエンドポイント（およびインポートモーダルの「検証」ボタン）がデータベースに触れずにファイルをパースしてチェックします：

  • スキーマバージョンチェック
  • 必須フィールドバリデーション
  • 重複名検出
  • 型列挙バリデーション（コンテナタイプ、リレーションシップタイプなど）
  • クロスリファレンス解決

エラーは正確なパス（systems[2].containers[1].name）と明確なメッセージで返されます。pre-commitフックやCIチェックに組み込んで、mainに到達する前に問題を検出しましょう。

実践的なパターン

モノレポ

# Root archyl.yaml
version: "1.0"
project:
  name: "Our Platform"
include:
  - services/payments/archyl.yaml
  - services/users/archyl.yaml
  - services/notifications/archyl.yaml

各サービスが自身のコンテナとコンポーネントを定義する独自のarchyl.yamlを管理します。ルートファイルがそれらをマージし、サービス間のリレーションシップはルートレベルで定義されます。テクノロジーと環境は自動的に重複排除されます。

ブートストラッパー

新しいプロジェクトを始める場合、コードを書く前にarchyl.yamlを作成しましょう。構築予定のシステムとコンテナを定義。Archylの「Import as Project」を使用して即座にアーキテクチャを生成。開発が進むにつれ、YAMLはコードとともに進化します。

監査証跡

YAMLがGitにあるため、完全な履歴が無料で得られます。git log archyl.yamlはすべてのアーキテクチャ変更、誰が行ったか、いつ、議論されたPRを表示します。ダイアグラムツールでこれを実現してみてください。

ドキュメントジェネレーター

アーキテクチャをYAMLにエクスポートし、任意のテンプレートエンジンに通してMarkdownドキュメント、Confluenceページ、社内Wikiを生成。構造化フォーマットにより自動化が容易になります。

今後の展望

これはDSLフォーマットのバージョン1.0です。次に取り組んでいること：

ドリフト検出。 リポジトリ内のYAMLとライブモデルを比較し、差異をハイライト — UIで追加されたがファイルにない要素、またはその逆。

PRプレビューコメント。 PRがarchyl.yamlを変更すると、ボットがアーキテクチャで何が変わったかのビジュアルdiffをコメント。

スキーマ進化。 Archylに新機能を追加するにつれ、DSLも成長します。後方互換性を維持し、マイグレーションツールを提供します。

今すぐ試す

Architecture as Codeは本日よりすべてのArchylプランで利用可能です。すでにプロジェクトをお持ちの場合：

  1. プロジェクトのArchitecture as Codeページへ移動
  2. Exportをクリックしてarchyl.yamlを生成
  3. リポジトリにコミット
  4. 公式GitHub Actionをワークフローに追加して完了

ゼロから始める場合は、archyl.yamlを作成し、Import as Projectを使用すれば、数秒で完全にレンダリングされたC4アーキテクチャが得られます。

あなたのアーキテクチャはコードと同じ厳密さに値します。バージョン管理し、レビューし、自動化しましょう。

C4は初めてですか？C4モデル入門から始めましょう。AIに初期アーキテクチャを生成させたいですか？AI駆動アーキテクチャ発見をご覧ください。すでにAIアシスタントを使用していますか？MCPサーバーで接続しましょう。