コードとしてのアーキテクチャ

Archyl では、C4 アーキテクチャ全体を 1 つの YAML ファイル archyl.yaml で定義できます。リポジトリにコミットしてコードと一緒に編集すれば、CI/CD がダイアグラムを自動的に同期し続けます。

概要

archyl.yaml ファイルは、アーキテクチャを宣言的に記述したものです。次の内容をサポートしています。

• C4 の 4 つのレベルすべて（システム、コンテナ、コンポーネント、コード）
• 任意の要素間のリレーションシップ
• テクノロジー、環境、リリース
• ADR、ドキュメント、APIコントラクト、イベントチャネル
• ダイアグラムをグループ化するビジュアルオーバーレイ
• include によるモノレポ対応

手書きで作成することも、既存のプロジェクトからエクスポートすることも、両方のワークフローを組み合わせることもできます。

ファイル形式

Archyl はリポジトリのルートで DSL ファイルを探し、次の名前を順に試します。

1. archyl.yaml
2. .archyl.yaml
3. archyl.yml
4. .archyl.yml

スキーマリファレンス

ルート構造

version: "1.0"

project:
  name: My Platform
  description: E-commerce platform serving 10M users
  tags: [e-commerce, saas]

technologies: [...]
environments: [...]
systems: [...]
relationships: [...]
overlays: [...]
events: [...]
api_contracts: [...]
adrs:
  folder: docs/adrs
  records: [...]
docs:
  folder: docs
  records: [...]
releases: [...]
include: [...]

必須なのは version だけです。その他のセクションはすべて省略可能なので、必要なものだけを記述してください。

システム（C4 レベル 1）

システムは C4 モデルの最上位の要素です。

systems:
  - name: Payment Service
    description: Handles all payment processing
    type: software_system   # person | software_system | external_system
    external: false
    tags: [payments, critical]
    technologies: [Go, PostgreSQL]
    owners:
      teams: [backend-team]
      users: [vincent]
    containers: [...]

コンテナ（C4 レベル 2）

コンテナは親システムの中にネストします。

systems:
  - name: Payment Service
    containers:
      - name: API Gateway
        description: REST API for payment operations
        type: api
        tags: [rest, public]
        technologies: [Go, Fiber]
        owners:
          teams: [backend-team]
        components: [...]

利用可能なコンテナタイプ：web_app、mobile_app、desktop_app、api、database、file_storage、message_queue、cache、service、function、worker、consumer、infrastructure、gateway、library。

モノレポのファイルで include を使う場合は、parent_system でこのコンテナが属するシステムを指定します。

# In services/payments/archyl.yaml
containers:
  - name: Payments API
    parent_system: Payment Service
    type: api

コンポーネント（C4 レベル 3）

コンポーネントは親コンテナの中にネストします。

containers:
  - name: API Gateway
    components:
      - name: PaymentHandler
        description: HTTP handler for payment endpoints
        type: handler
        file: internal/handler/payment.go
        tags: [http]
        technologies: [Go]
        code: [...]

利用可能なコンポーネントタイプ：controller、service、repository、handler、middleware、model、util、config、adapter、port、resource、module、job、bundle、plugin、workflow、activity、entity。

コード要素（C4 レベル 4）

コード要素は親コンポーネントの中にネストします。

components:
  - name: PaymentHandler
    code:
      - name: ProcessPayment
        description: Handles payment processing requests
        type: function
        language: go
        file: internal/handler/payment.go
        line_start: 42
        line_end: 87
        visibility: public
        signature: "func (h *PaymentHandler) ProcessPayment(c *fiber.Ctx) error"
        methods:
          - name: validate
            signature: "func validate(req PaymentRequest) error"
            return_type: error
            visibility: private
        properties:
          - name: maxRetries
            type: int
            visibility: private
            readonly: true

利用可能なコード要素タイプ：class、interface、struct、function、method、enum、constant、type。

リレーションシップ

リレーションシップは任意の 2 つの要素を接続します。ネストされた要素はドット記法で参照します。

relationships:
  - from: Payment Service.API Gateway
    to: Payment Service.Database
    label: Reads/writes payment data
    type: uses
    technologies: [SQL, PostgreSQL]
    tags: [data-access]
    style:
      color: "#6366f1"
      width: 2
      style: solid       # solid | dashed | dotted
      animated: false

ドット記法の形式：System.Container.Component.CodeElement。必要なレベルまでだけ記述します。Payment Service はシステムを、Payment Service.API Gateway はコンテナを参照します。

利用可能なリレーションシップタイプ：uses、depends_on、calls、reads_from、writes_to、sends_to、receives_from、implements、extends、contains、deployed_on、provisions、publishes_to、consumes_from。

テクノロジー

アーキテクチャ全体で使用するテクノロジーのカタログを定義します。

technologies:
  - name: Go
    description: Primary backend language
    category: programming_language
    icon: go
  - name: PostgreSQL
    description: Main relational database
    category: database
    icon: postgresql

利用可能なカテゴリ：programming_language、framework、database、message_broker、object_storage、transport_protocol、cloud_service、devops_tool、library、runtime、cache、other。

環境

リリースのデプロイ先となる環境を定義します。

environments:
  - name: Production
    color: "#22c55e"
  - name: Staging
    color: "#f59e0b"
  - name: Development
    color: "#6366f1"

リリース

環境や要素をまたいで、バージョン付きのデプロイを追跡します。

releases:
  - version: "2.4.0"
    status: deployed          # planned | in_progress | deployed | rolled_back | failed
    changelog: "Added payment retry logic and improved error handling"
    environment: Production
    container: Payment Service.API Gateway
    released_at: "2026-03-10T14:00:00Z"
    source: github_action
    source_url: "https://github.com/org/repo/actions/runs/12345"

イベントチャネル

サービス間の非同期メッセージングを定義します。

events:
  - name: PaymentCompleted
    description: Fired when a payment is successfully processed
    direction: produce         # produce | consume
    broker: kafka              # kafka | nats | sqs | rabbitmq | redis | pulsar | custom
    topic: payments.completed
    schema_format: json_schema # json_schema | avro | protobuf | text
    schema: |
      { "type": "object", "properties": { "paymentId": { "type": "string" } } }
    links:
      - Payment Service.API Gateway

APIコントラクト

アーキテクチャに API 仕様を紐付けます。

api_contracts:
  - name: Payment API
    description: REST API for payment operations
    type: http                 # http | grpc | graphql | async
    version: "2.0"
    endpoint: /api/v2/payments
    file: docs/openapi.yaml    # path to spec file in repo
    links:
      - Payment Service.API Gateway

file でリポジトリ内の仕様ファイルを参照することも、content で仕様を直接インラインで記述することもできます。

アーキテクチャ決定記録（ADR）

adrs:
  folder: docs/adrs            # optional: path to ADR folder in repo
  records:
    - title: Use event-driven architecture for payments
      number: 7
      status: accepted         # proposed | accepted | deprecated | superseded
      date: "2026-02-15"
      context: We need to decouple payment processing from order management
      decision: Use Kafka events for async communication between services
      consequences: Added complexity but improved resilience and scalability
      tags: [architecture, messaging]
      links:
        - Payment Service

ドキュメント

docs:
  folder: docs                 # optional: path to docs folder in repo
  records:
    - title: Payment Processing Guide
      file: docs/payments.md   # path to markdown file in repo
      tags: [payments, guide]
      links:
        - Payment Service.API Gateway

file でリポジトリ内の Markdown ファイルを参照することも、content で内容を直接インラインで記述することもできます。

オーバーレイ

ダイアグラム上に表示されるビジュアルなグループです。

overlays:
  - name: Payment Domain
    description: All payment-related services
    color: "#6366f1"
    level: 2                   # C4 level (1=system, 2=container, 3=component, 4=code)
    elements:
      - Payment Service.API Gateway
      - Payment Service.Database
      - Payment Service.Worker

Include（モノレポ対応）

モノレポでは、アーキテクチャを複数のファイルに分割してマージできます。

include:
  - services/payments/archyl.yaml
  - services/orders/archyl.yaml
  - services/users/archyl.yaml

インクルードされる各ファイルも同じスキーマに従います。別ファイルで定義したコンテナには parent_system を付けて、どのシステムに属するかを指定してください。

完全な例

version: "1.0"

project:
  name: E-Commerce Platform
  description: Online marketplace with payment processing
  tags: [e-commerce, saas, marketplace]

technologies:
  - name: Go
    category: programming_language
  - name: React
    category: framework
  - name: PostgreSQL
    category: database
  - name: Kafka
    category: message_broker
  - name: Redis
    category: cache

environments:
  - name: Production
    color: "#22c55e"
  - name: Staging
    color: "#f59e0b"

systems:
  - name: Storefront
    description: Customer-facing web application
    type: software_system
    technologies: [React]
    containers:
      - name: Web App
        type: web_app
        technologies: [React]
      - name: BFF
        description: Backend for frontend
        type: api
        technologies: [Go]

  - name: Payment Service
    description: Handles payment processing
    type: software_system
    technologies: [Go, PostgreSQL]
    containers:
      - name: API
        type: api
        technologies: [Go]
        components:
          - name: PaymentHandler
            type: handler
          - name: PaymentService
            type: service
          - name: PaymentRepository
            type: repository
      - name: Database
        type: database
        technologies: [PostgreSQL]
      - name: Worker
        type: worker
        technologies: [Go]

  - name: Stripe
    description: Third-party payment processor
    type: external_system
    external: true

relationships:
  - from: Storefront.Web App
    to: Storefront.BFF
    label: API calls
    type: uses
    technologies: [HTTPS]
  - from: Storefront.BFF
    to: Payment Service.API
    label: Process payments
    type: calls
    technologies: [gRPC]
  - from: Payment Service.API
    to: Payment Service.Database
    label: Reads/writes payment data
    type: uses
    technologies: [SQL]
  - from: Payment Service.API
    to: Stripe
    label: Process charges
    type: calls
    technologies: [HTTPS]
  - from: Payment Service.Worker
    to: Payment Service.Database
    label: Polls for pending payments
    type: reads_from

events:
  - name: PaymentCompleted
    broker: kafka
    topic: payments.completed
    direction: produce
    links:
      - Payment Service.API

overlays:
  - name: Payment Domain
    level: 2
    color: "#6366f1"
    elements:
      - Payment Service.API
      - Payment Service.Database
      - Payment Service.Worker

releases:
  - version: "1.2.0"
    status: deployed
    environment: Production
    container: Payment Service.API
    changelog: Added retry logic for failed charges
    released_at: "2026-03-01T10:00:00Z"

リポジトリからの同期

リポジトリに archyl.yaml がある場合は、Archyl の UI から直接同期できます。

1. プロジェクト設定 > コードとしてのアーキテクチャ に移動します
2. 今すぐ同期 をクリックします

Archyl はリポジトリのデフォルトブランチ（または DSL 設定で指定したブランチ）からファイルを取得してインポートします。既に存在する要素は更新され、新しい要素は作成されます。

CI/CD 連携

GitHub Action（公式）

公式の archyl-com/actions/sync GitHub Action を使うのが、アーキテクチャを同期し続ける最も簡単な方法です。archyl.yaml を読み込んで Archyl API にプッシュし、作成・更新された内容を報告します。

最小構成：

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'

サマリーを出力する場合：

- uses: archyl-com/actions/sync@v1
  id: sync
  with:
    api-key: ${{ secrets.ARCHYL_API_KEY }}
    project-id: 'your-project-uuid'
- run: echo "${{ steps.sync.outputs.summary }}"

ファイルパスを指定する場合（モノレポ）：

- uses: archyl-com/actions/sync@v1
  with:
    api-key: ${{ secrets.ARCHYL_API_KEY }}
    project-id: 'your-project-uuid'
    file: 'services/payments/archyl.yaml'

セルフホストの Archyl：

- uses: archyl-com/actions/sync@v1
  with:
    api-url: 'https://archyl.your-company.com'
    api-key: ${{ secrets.ARCHYL_API_KEY }}
    project-id: 'your-project-uuid'

Action の入力

Action の出力

GitLab CI/CD

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

REST API

任意の CI/CD システムやスクリプトから DSL の内容をプッシュできます。

curl -X POST https://your-instance.com/api/v1/projects/{projectId}/dsl/ingest \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d "{\"content\": $(cat archyl.yaml | jq -Rs .)}"

ingest エンドポイントは、作成された内容のサマリーを返します。

{
  "source": "api",
  "import": {
    "systemsCreated": 2,
    "containersCreated": 5,
    "componentsCreated": 12,
    "codeElementsCreated": 0,
    "relationshipsCreated": 8,
    "overlaysCreated": 1,
    "technologiesCreated": 4,
    "adrsCreated": 0,
    "docsCreated": 0,
    "eventsCreated": 1,
    "apiContractsCreated": 0,
    "environmentsCreated": 2,
    "releasesCreated": 1
  }
}

YAML へのエクスポート

既存のプロジェクトはどれでも archyl.yaml ファイルとしてエクスポートできます。

1. プロジェクトを開きます
2. ツールバーの エクスポート をクリックします
3. YAML（コードとしてのアーキテクチャ） を選択します

リポジトリにコミットできる完全な archyl.yaml が生成されます。既存のプロジェクトや、AI ディスカバリーで検出したアーキテクチャからファイルを作り始めるのに最適な方法です。

API からエクスポートすることもできます。

curl -H "X-API-Key: your-api-key" \
  https://your-instance.com/api/v1/projects/{projectId}/dsl/export \
  -o archyl.yaml

IDE サポート用の JSON Schema

Archyl は archyl.yaml ファイル用の JSON Schema を提供しているため、エディターで補完とバリデーションを利用できます。スキーマは次の URL で公開されています。

https://your-instance.com/api/v1/dsl/schema

VS Code

スキーマによるバリデーションを有効にするには、archyl.yaml に次の行を追加します。

# yaml-language-server: $schema=https://your-instance.com/api/v1/dsl/schema
version: "1.0"

または、VS Code の設定でグローバルに構成します。

{
  "yaml.schemas": {
    "https://your-instance.com/api/v1/dsl/schema": ["archyl.yaml", ".archyl.yaml"]
  }
}

画像と PDF のエクスポート

Archyl では、プレゼンテーションやドキュメントで使えるように、ダイアグラムを画像としてエクスポートすることもできます。

利用可能なフォーマット

エクスポート方法

1. エクスポートしたい C4 レベルに移動します
2. ツールバーの エクスポート をクリックします
3. フォーマット（PNG、SVG、または PDF）を選択します
4. オプション（背景、品質、ビューポート）を設定します
5. エクスポート をクリックします

すべてのレベルをエクスポート にチェックを入れると、C4 レベルごとに個別のファイルが生成されます。

エクスポートオプション

• 背景：ダークキャンバスの背景を含めるか、透明にします
• 品質（PNG のみ）：標準、高品質、印刷用の解像度
• ビューポート：コンテンツにフィット、パディングを含む、または現在のビューをエクスポート

プロジェクトのインポート

複数のフォーマットからインポートして新しいプロジェクトを作成できます。Archyl は 5つのインポートソース をサポートしています。

インポート方法

1. プロジェクト一覧から プロジェクトをインポート をクリックします
2. ソースフォーマットのタブ（Archyl YAML、Structurizr DSL、LikeC4、IcePanel、または Backstage）を選択します
3. ファイルをアップロードするか、内容を貼り付けます
4. 検証 をクリックして、作成される内容をプレビューします
5. プロジェクトを作成 をクリックします

プロセス全体は 1 分もかかりません。すべてのシステム、コンテナ、コンポーネント、リレーションシップ、テクノロジー、タグが自動的にインポートされます。

プロジェクト名と説明

プロジェクトの作成には名前が必要ですが、その名前を保持する場所は形式ごとに異なります。名前がないことは、インポートが拒否される最も一般的な原因です。

このチェックで失敗しうるのは Archyl YAML と Structurizr DSL だけです。他の形式は常に生成された名前にフォールバックし、インポート後に変更できます。

Structurizr では、名前と説明は workspace ヘッダーにある 2 つの省略可能な文字列です。

workspace "My Platform" "Microservices architecture" {
    model {
        user = person "User"
        platform = softwareSystem "My Platform" {
            api = container "API" "REST API" "Go"
        }
        user -> api "Uses"
    }
}

名前のない workspace { ... } は正しく解析されますが、プロジェクトを作成できません。Archyl はこれを拒否し、workspace に名前を付けるよう求めます。既存のプロジェクトへのインポートにはこの要件はありません。プロジェクトには既に名前があるため、workspace の名前は無視されます。

Structurizr DSL インポート

Archyl は Structurizr の .dsl ワークスペースファイルを解析し、完全な C4 モデルを抽出します。

• person、softwareSystem、container、component 要素
• 説明とテクノロジーを含むすべての -> リレーションシップ
• タグからの外部システムの検出
• 位置引数からのテクノロジーの抽出
• グループはタグにマッピング

ビュー、スタイル、テーマ、デプロイメントノードはスキップされます（Archyl には独自のビジュアルレイヤーがあります）。

workspace の名前と説明がプロジェクトの名前と説明になります。上記の プロジェクト名と説明 のセクションを参照してください。名前のない workspace は既存のプロジェクトにインポートできますが、新しいプロジェクトは作成できません。

複数ファイルのワークスペース（!include）

!include systems/payments.dsl のように複数ファイルへ分割されたワークスペースは、単一ファイルではインポートできません。参照先のファイルが存在せず解決できないためです。代わりに、Structurizr DSL タブでワークスペース全体を .zip としてアップロードしてください。アーカイブ内のファイルが展開され、すべての !include がそれらに対して解決されます。

• エントリポイントはアーカイブに workspace.dsl があればそれ、なければ最も浅い階層の .dsl ファイルです。使用したファイルは Archyl が表示します。
• パスは include を書いたファイルからの相対で解決されるため、入れ子の include も動作します。
• ディレクトリを指定すると、その直下にある .dsl を名前順にすべて取り込みます。
• include の循環は中断して報告され、インポート自体は失敗しません。
• リモート指定（!include https://…）は拒否され、アーカイブ外を指すパスはスキップされます。

解決できなかったものはインポート結果の警告になります。ワークスペースの残りはそのままインポートされます。

アーカイブの制限:

保持されるのは .dsl、.md、.json、.yaml、.yml、.txt ファイルのみで、アーカイブ内のそれ以外のファイルは無視されます。

API から送る場合は、アーカイブを multipart フォームデータの file フィールドに入れ、必要に応じてエントリポイントを指定する entry フィールドを付けます。POST /api/v1/dsl/validate-archive はアーカイブを検証し、POST /api/v1/projects/{id}/dsl/import-archive はプロジェクトにインポートし、POST /api/v1/dsl/import-project-archive はアーカイブから新しいプロジェクトを作成します。import_dsl MCP ツールとリポジトリ同期は単一ファイルを読み込むため、!include は解決しません。

LikeC4 インポート

Archyl は LikeC4 ファイルをインポートする初のツール です。インポーターは LikeC4 独自の機能に対応しています。

• specification ブロックのカスタム要素タイプを C4 レベルにマッピング
• ネストされた要素の階層をシステム、コンテナ、コンポーネントとして解決
• technology: と description: プロパティ（コロン構文の有無を問わず）
• #hashtag タグを標準のタグに変換
• 境界の分類のための #external タグの検出
• 複数の model ブロックを自動的にマージ
• シングルクォートとトリプルクォートの文字列をサポート

IcePanel JSON インポート

IcePanel の JSON エクスポート形式は完全にサポートされています。

• system、actor、app、store、component オブジェクトタイプを C4 要素にマッピング
• 外部システムの分類のための external: true フィールド
• modelConnections をリレーションシップにマッピング
• tagIds を tags 配列のタグ名に解決
• domain オブジェクトをプロジェクト名として使用

Backstage インポート

Archyl は Backstage の /api/catalog/entities エンドポイントが返す Software Catalog JSON をインポートします。

• System エンティティを Archyl のシステムにマッピング（名前空間をまたいだ名前の衝突は自動的に区別されます）
• Component と Resource エンティティは、所属するシステムの下のコンテナにまとめられます（spec.system または partOf リレーション経由）
• 親システムを持たない Component/Resource は、合成された Uncategorized システムの下にグループ化されます
• Resource タイプを Archyl のコンテナタイプにマッピング：s3-bucket → file_storage、rds-instance・dynamo-db-table・valkey-cluster・opensearch-domain → database、kafka-topic・sqs-queue → message_queue、repository → library、その他はすべて → infrastructure
• Component タイプのマッピング：service → service、cronworkflow → worker、website → web_app、library → library
• API エンティティは APIコントラクト としてインポートされ、インラインの spec.definition（OpenAPI / gRPC / GraphQL / AsyncAPI）がコンテンツとして保持され、提供側・利用側のコンポーネントにリンクされます
• dependsOn、consumesApi、producesTo、consumesFrom、versionedIn（およびその逆方向）を Archyl のリレーションシップに変換
• metadata.namespace、spec.lifecycle、spec.type をタグとして公開
• User と Group エンティティはスキップ — Backstage の人・チームのグラフは C4 の概念ではないため

カタログをエクスポートするには、次のコマンドを実行します。

curl -H "Authorization: Bearer $BACKSTAGE_TOKEN" \
  https://backstage.your-company.com/api/catalog/entities \
  -o entities.json

次に、インポートダイアログの Backstage タブに entities.json をドロップします。大規模なカタログのリソース一覧からは数千のコンテナが生成されることがあります。結果を確認し、不要なものは削除してください。

MCP 経由のインポート（AI エージェント）

同じインポート機能は import_dsl MCP ツールからも利用できます。

Use the import_dsl tool with:
- projectId: your project UUID
- content: the DSL/JSON content
- format: "archyl", "structurizr", "likec4", "icepanel", or "backstage"

これにより、AI コーディングエージェント（Claude Code、Cursor、Windsurf）がプログラムからアーキテクチャファイルをインポートできます。

既存プロジェクトへのインポート

新しいプロジェクトを作成するだけでなく、既存のプロジェクトにインポートすることもできます。

1. プロジェクトを開きます
2. コードとしてのアーキテクチャ に移動します
3. インポート をクリックします
4. フォーマットを選択してアップロードします

既に存在する要素は更新され、新しい要素は作成されます。

次のステップ

• API概要 — DSL エンドポイントの完全な API リファレンス
• 共有と埋め込み — ライブダイアグラムの共有
• リリース管理 — YAML でデプロイメントを追跡
• Webhook 通知 — アーキテクチャの変更時に通知を受け取る