Canvas DSL

Canvas DSL은 애니메이션 다이어그램을 선언적으로 작성하는 도메인 특화 언어입니다. 복잡한 JavaScript 없이도 단계별로 나타나는 아키텍처 다이어그램을 만들 수 있습니다.

Canvas 사용 전 필수 점검 (4-Box Rule)

Canvas DSL은 단순한 다이어그램에만 사용합니다. 사용 전 반드시 확인하세요:

1. 박스+아이콘 총 개수를 세기 - 4개 이하만 canvas 허용
2. 5개 이상이면 canvas 사용 금지 - HTML Architecture 패턴 사용
3. 단방향 직선 흐름(A->B->C)만 canvas 허용
4. 다계층, 그룹, 분기 화살표가 있으면 :::html + :::css 필수

복잡도	방식	예시
단순 (박스 4개 이하 + 화살표)	:::canvas DSL 허용	A->B->C 단순 흐름
중간 (박스 5개+, 다계층)	:::html + :::css 필수	3-tier 아키텍처, 서비스 맵
복잡 (인터랙션 + 계산)	:::html + :::script 필수	슬라이더, 시뮬레이터, 대시보드
정적 아키텍처	@img: + draw.io	AWS 전체 아키텍처, VPC 네트워크

STOP 자가 점검: Canvas 코드를 작성하기 전에 아래 체크리스트를 확인하세요:

• 박스+아이콘 총 개수가 4개 이하인가?
• 단방향 직선 흐름(A->B->C->D)인가?
• 다계층, 그룹, 분기 화살표가 없는가?

하나라도 "아니오"라면 canvas 사용을 중단하고 :::html + :::css 패턴을 사용하세요.

기본 문법

---
@type: canvas
@canvas-id: simple-arch

## Simple Architecture

:::canvas
box api "API Gateway" at 100,200 size 120,60 color #FF9900
box lambda "Lambda" at 300,200 size 120,60 color #FF9900
box dynamo "DynamoDB" at 500,200 size 120,60 color #3B48CC

arrow api -> lambda "invoke"
arrow lambda -> dynamo "read/write"
:::

tip

@canvas-id는 해당 canvas 요소의 고유 식별자입니다. 여러 canvas 슬라이드가 있을 때 구분하는 데 사용됩니다.

도형 요소

Box (박스)

사각형 박스를 그립니다.

box <id> "<label>" at <x>,<y> size <width>,<height> color <color> [step <n>]

:::canvas
box user "User" at 50,100 size 80,40 color #232F3E
box web "Web App" at 200,100 size 100,50 color #FF9900 step 2
box db "Database" at 400,100 size 100,50 color #3B48CC step 3
:::

속성	설명
id	요소 식별자 (arrow 연결에 사용)
label	박스 안에 표시될 텍스트
at x,y	왼쪽 상단 좌표
size w,h 또는 size wxh	너비와 높이
color	배경 색상 (CSS 색상 또는 accent, green 등 키워드)
step n	해당 스텝에서 나타남

Circle (원)

원을 그립니다.

circle <id> "<label>" at <x>,<y> radius <r> color <color> [step <n>]

:::canvas
circle start "Start" at 50,100 radius 30 color #4CAF50
circle process "Process" at 200,100 radius 40 color #FF9900 step 2
circle end "End" at 350,100 radius 30 color #f44336 step 3
:::

Icon (아이콘)

AWS 서비스 아이콘을 표시합니다.

icon <id> "<aws-service>" at <x>,<y> size <s> [step <n>]

:::canvas
icon gw "API-Gateway" at 100,150 size 48
icon fn "Lambda" at 250,150 size 48 step 2
icon table "DynamoDB" at 400,150 size 48 step 3
:::

지원되는 서비스 이름

이름	아이콘
Lambda	AWS Lambda
EKS	Amazon Elastic Kubernetes Service
API-Gateway	Amazon API Gateway
DynamoDB	Amazon DynamoDB
S3	Amazon S3
CloudWatch	Amazon CloudWatch
EC2	Amazon EC2
VPC	Virtual Private Cloud
RDS	Amazon RDS
SQS	Amazon SQS
SNS	Amazon SNS
CloudFront	Amazon CloudFront
Route53	Amazon Route 53
Cognito	Amazon Cognito
StepFunctions	AWS Step Functions
Fargate	AWS Fargate
ECS	Amazon ECS
ALB	Elastic Load Balancing
IAM	AWS IAM
KMS	AWS KMS

전체 경로 참조

:::canvas
icon custom "../common/aws-icons/services/Arch_Amazon-S3_48.svg" at 100,250 size 48
:::

Arrow (화살표)

요소 간 연결을 그립니다. 화살표는 자동으로 직교(orthogonal) 경로로 라우팅되어 draw.io/Lucidchart 스타일의 직각 꺾임 경로를 생성합니다.

arrow <from-id> -> <to-id> "<label>" [color <color>] [style <dashed|dotted>] [step <n>]

:::canvas
box a "Service A" at 50,100 size 100,50 color #232F3E
box b "Service B" at 250,100 size 100,50 color #232F3E

arrow a -> b "HTTP" step 2
arrow b -> a "Response" color #4CAF50 style dashed step 3
:::

속성	설명
from-id -> to-id	시작과 끝 요소
label	화살표 레이블
color	화살표 색상
style	dashed 또는 dotted
step n	해당 스텝에서 나타남

Orthogonal 라우팅

화살표는 대각선 직선 대신 수평/수직 세그먼트만 사용하는 직교 경로로 자동 라우팅됩니다:

직선 (같은 축):          L자형 꺾임:             Z자형 꺾임:
A ─────────── B         A ───────┐              A ─────────┐
                                 │                          │
                                 B              ┌───────────┘
                                                │
                                                B

• 직선: 두 요소가 같은 Y 또는 X 축에 있을 때
• L자형: 한쪽이 측면 앵커, 한쪽이 상/하 앵커일 때 (수평→수직 또는 수직→수평)
• Z자형: 양쪽 모두 측면 앵커이거나 양쪽 모두 상/하 앵커이면서 축이 어긋날 때

앵커는 요소 간 주 이동 방향에 따라 자동 선택됩니다:

이동 방향	출발 앵커	도착 앵커
→ 오른쪽	우측 중앙	좌측 중앙
← 왼쪽	좌측 중앙	우측 중앙
↓ 아래	하단 중앙	상단 중앙
↑ 위	상단 중앙	하단 중앙

중간 경로에 다른 요소가 있으면 자동으로 충돌 회피 경로를 생성합니다.

Group (그룹)

여러 요소를 묶는 경계 박스를 그립니다.

group "<label>" containing <id1>, <id2>, ... [color <color>] [step <n>]

:::canvas
box web1 "Web 1" at 100,100 size 80,40 color #FF9900
box web2 "Web 2" at 100,160 size 80,40 color #FF9900
box web3 "Web 3" at 100,220 size 80,40 color #FF9900

group "Auto Scaling Group" containing web1, web2, web3 color #232F3E
:::

스텝 기반 애니메이션

step N을 사용하여 요소가 나타나는 순서를 제어합니다:

---
@type: canvas
@canvas-id: data-flow

## Data Pipeline

:::canvas
# Step 1: Source appears first
icon s3src "S3" at 50,150 size 48 step 1
box source "Source Bucket" at 30,210 size 90,30 color #3B48CC step 1

# Step 2: Processing layer
icon lambda "Lambda" at 200,150 size 48 step 2
box transform "Transform" at 180,210 size 90,30 color #FF9900 step 2

# Step 3: Destination
icon s3dst "S3" at 350,150 size 48 step 3
box dest "Dest Bucket" at 330,210 size 90,30 color #3B48CC step 3

# Step 4: Arrows connect everything
arrow source -> transform "trigger" step 4
arrow transform -> dest "write" step 4
:::

info

step이 없는 요소는 슬라이드 진입 시 즉시 표시됩니다. 스텝은 ↑/↓ 키로 제어합니다.

프리셋 DSL

복잡한 패턴을 위한 프리셋 시스템을 제공합니다:

EKS Scaling 프리셋

:::canvas
preset eks-scaling {
  cluster "Production EKS" at 40,30
    node "node-1" pods=3 max=4
    node "node-2" pods=2 max=4
    node "node-3" pods=1 max=4

  step 1 scale-out node=0 "Add pod to node-1"
  step 2 scale-out node=1 "Add pod to node-2"
  step 3 add-node "Add new node"
  step 4 scale-out node=3 "Schedule to new node"
}
:::

지원되는 프리셋

프리셋	설명
eks-scaling	EKS 클러스터 스케일링 시각화
serverless-flow	Lambda 이벤트 흐름
vpc-architecture	VPC 네트워크 다이어그램
cicd-pipeline	CI/CD 파이프라인
data-pipeline	데이터 처리 파이프라인

프리셋 액션

액션	파라미터	설명
scale-out	node=N	지정된 노드에 Pod 추가
scale-in	node=N	지정된 노드에서 Pod 제거
add-node	없음	클러스터에 새 노드 추가
remove-node	node=N	클러스터에서 노드 제거
migrate	node=N to=M	노드 간 Pod 이동

Mermaid 통합

:::canvas mermaid 변형으로 Mermaid 다이어그램을 임베드할 수 있습니다:

:::canvas mermaid
graph LR
    A[Client] --> B[API Gateway]
    B --> C[Lambda]
    C --> D[DynamoDB]
:::

지원되는 Mermaid 다이어그램 타입

• graph / flowchart - 플로우 다이어그램
• sequenceDiagram - 시퀀스 다이어그램
• classDiagram - 클래스 다이어그램
• stateDiagram - 상태 다이어그램
• erDiagram - ER 다이어그램
• gantt - 간트 차트
• pie - 파이 차트

HTML Architecture 대안

박스 5개 이상의 복잡한 다이어그램은 Canvas DSL 대신 :::html + :::css 패턴을 사용합니다. flexbox/grid 레이아웃이 더 안정적이고 유지보수가 쉽습니다.

## Service Pipeline

:::html
<div class="flow-h">
  <div class="flow-group bg-blue" data-fragment-index="1">
    <div class="flow-group-label">수집</div>
    <div class="icon-item"><img src="../common/aws-icons/services/Arch_Amazon-CloudWatch_48.svg"><span>CloudWatch</span></div>
    <div class="icon-item"><img src="../common/aws-icons/services/Arch_AWS-X-Ray_48.svg"><span>X-Ray</span></div>
  </div>
  <div class="flow-arrow">-></div>
  <div class="flow-group bg-orange" data-fragment-index="2">
    <div class="flow-group-label">분석</div>
    <div class="flow-box">DevOps Guru</div>
  </div>
</div>
:::

Canvas vs HTML Architecture 비교

항목	Canvas DSL	HTML Architecture
적합한 경우	박스 4개 이하, 단순 흐름	박스 5개+, 다계층, 복잡한 레이아웃
정렬/간격	수동 좌표 계산	flexbox/grid 자동 처리
순차 등장	step N	data-fragment-index="N"
유지보수	좌표 수정 필요	CSS만 수정

CSS 유틸리티 클래스

theme.css에서 제공 (커스텀 CSS 불필요):

• flow-h / flow-v: 수평/수직 플로우 컨테이너
• flow-group: 요소 그룹 (배경색 적용)
• flow-box, flow-arrow, icon-item: 박스, 화살표, 아이콘
• bg-blue, bg-orange, bg-pink, bg-green: 색상 유틸리티

JavaScript Escape Hatch

DSL로 표현하기 어려운 복잡한 애니메이션은 JavaScript로 직접 작성할 수 있습니다:

:::canvas js
const canvas = document.getElementById('complex-animation');
const ctx = canvas.getContext('2d');

// Custom animation logic
function animate() {
  ctx.clearRect(0, 0, canvas.width, canvas.height);
  // ... custom drawing code
  requestAnimationFrame(animate);
}
animate();
:::

전체 예제

---
@type: canvas
@canvas-id: api-pattern
@timing: 5min

## API Backend Pattern

:::canvas
box client "Client" at 30,150 size 80,40 color #232F3E step 1

icon apigw "API-Gateway" at 150,140 size 48 step 2
icon lambda "Lambda" at 280,140 size 48 step 3
icon dynamo "DynamoDB" at 410,140 size 48 step 4

arrow client -> apigw "HTTPS" step 5
arrow apigw -> lambda "invoke" step 5
arrow lambda -> dynamo "query" step 6

group "AWS Cloud" containing apigw, lambda, dynamo color #232F3E step 1
:::

:::notes
{timing: 5min}
{cue: demo}
각 컴포넌트가 나타날 때마다 역할을 설명합니다.
Step 5에서 전체 흐름을 설명합니다.
:::