Quick Start

Build your first diagram in six steps

クイックスタート

6 つのステップで最初の検証済みアーキテクチャ図を作成します。各ステップでは、1 つの新しい Datro コンセプトが導入されます。最後には、スタイルが設定され、制約がチェックされた完全な図が完成し、SVG としてエクスポートできるようになります。

ダイアグラムメーカーを開く

ライブエディターで手順に従ってください。各スニペットを貼り付けて、[検証] をクリックします。

ステップ 1 — 最初のノードとエッジを作成する

すべての .dtro ファイルはマジックヘッダーで始まります。その後、ノード (エンティティ) と エッジ (関係) を宣言します。これをエディタに貼り付けます。

arch.dtro

#!DATRO 1.0

node frontend { type: web      label: "React App" }
node backend  { type: service  label: "NestJS API" }
node db       { type: database label: "PostgreSQL" }

edge frontend -> backend { kind: http }
edge backend  -> db      { kind: query }

ℹ️

マジックヘッダーが必要です

1 行目の #!DATRO 1.0 行は必須です。パーサーは、E100 が見つからない場合に返します。

ステップ 2 — より豊富なメタデータのために `attrs` を追加する

attrs ブロックは、任意のキーと値のメタデータを保持します。値には、文字列、数値、ブール値、または配列を使用できます。共通の属性は tech、owner、deprecated、および sla です。

DATRO

node backend {
  type:  service
  label: "NestJS API"
  attrs {
    tech:  "nestjs"
    owner: "platform-team"
  }
}

属性は JSON IR に渡され、レンダリングされた SVG にツールチップとして表示されます。これは、オンコールおよび SLA メタデータに役立ちます。

ステップ 3 — エッジメタデータを追加する

エッジには種類 (セマンティック関係タイプ)、オプションの ラベル、重み (相対トラフィック)、async フラグがあります。非同期エッジは破線としてレンダリングされます。

DATRO

edge backend -> stripe {
  kind:  http
  label: "charge API"
  async: false
}

Field	Type	Required	Default	Description
`kind`	EdgeKind "http""grpc""query""publish""subscribe""read""write""deploys""monitors""depends""…21 total"	Yes	`unknown`	意味関係のタイプ
`label`	string	No	—	エッジラインに表示される短いテキスト
`weight`	number	No	`1.0`	相対的なトラフィックの重み - 重いエッジはより厚く表示されます
`async`	boolean	No	`false`	true の場合、エッジは破線でレンダリングされます (ファイアアンドフォーゲットパターン)

ステップ 4 — ノードをクラスターにグループ化する

group ブロックを使用して、関連するノードをクラスター化します。グループは、SVG 内でラベル付きのサブグラフボックスとしてレンダリングされます。ノードは 1 つのグループにのみ所属できます。

DATRO

group data_tier {
  label:   "Data Layer"
  members: [db, redis_cache]
}

node redis_cache { type: cache label: "Redis" }

edge backend -> redis_cache { kind: read  label: "session" }

💡

グループとnode.groupの比較

group: data_tier を使用してノードにグループを直接割り当てることもできます。どちらのスタイルも有効です。 group ブロックの members リストが優先されます。

ステップ 5 — アーキテクチャ上の制約を追加する

制約は、機械的にチェックされたアーキテクチャルールです。バリデーターはそれらを IR に対して評価し、ルールに違反すると E501 エラーを返します。

DATRO

constraint {
  id:       "no-db-external"
  rule:     "database !-> external"
  message:  "Databases must not connect to external services"
  severity: error
}

ルール database !-> external は、タイプ database のノードはタイプ external のノードへの有向エッジを持つことができないことを意味します。これにより、誤って DB → サードパーティ API を直接呼び出すことがブロックされます。

ステップ 6 — レイアウトのヒントとテーマを追加する

layout ブロックでダイアグラムの配置方法を制御し、theme ブロックでカラーパレットを定義します。いずれかの色が WCAG AA コントラストを下回る場合、アクセシビリティチェックは W602 を実行します。

DATRO

layout { direction: LR  algo: dagre  node_sep: 60  rank_sep: 120 }

theme {
  palette {
    service:    "#D0E8FF"
    database:   "#FFE8C0"
    web:        "#E8D0FF"
    cache:      "#C0FFE8"
    background: "#FFFFFF"
  }
  accessibility { min_contrast: AA }
}

💡

WCAG コントラストは自動です

DOT エクスポーターは、WCAG 2.1 の相対輝度公式を使用して、各ノードの塗りつぶしのフォントの色を黒または白で自動的に選択します。設定は必要ありません。

次のステップ

すべてのブロックタイプの完全な構文については、Language Reference を参照してください。
CLI Reference を使用して、コマンドラインから検証、フォーマット、エクスポートを行います。
リマークまたはマークダウン IT プラグインを使用してドキュメントを embed diagrams in Markdown する方法を学びます。

ダイアグラムメーカーを開く

図をレンダリングする準備ができました。エディターのツールバーで「レンダリング」→「SVG」をクリックします。