C4 컨테이너 다이어그램 생성기은(는) 무엇을 하나요?

C4 모델 규칙에 따라 컨테이너 다이어그램을 생성하고, draw.io(데스크톱 또는 웹)에서 바로 열 수 있는 편집 가능한 .drawio XML 파일로 내보냅니다.

사용 시기

명시적 트리거:

사용자가 C4 다이어그램, 컨테이너 다이어그램, 아키텍처 다이어그램을 요청할 때
사용자가 "아키텍처를 그려줘", "시스템 다이어그램", "컴포넌트를 보여줘"라고 말할 때
사용자가 문서화나 발표를 위해 시스템 아키텍처를 시각화해야 할 때
사용자가 draw.io, drawio를 언급하거나 편집 가능한 다이어그램을 원할 때

능동적 트리거:

3개 이상의 상호작용하는 컴포넌트가 있는 시스템을 설명할 때
마이크로서비스, API, 데이터베이스 및 그 관계를 논의할 때
시스템 아키텍처를 검토하거나 설계할 때

건너뛰어야 할 때:

사용자가 간단한 순서도를 원할 때 (대신 Mermaid 사용)
사용자가 UI 와이어프레임이나 목업을 원할 때
시스템에 컴포넌트가 3개 미만일 때

프로세스

1단계: 요구사항 수집

대화 내용에서 파악하거나 사용자에게 질문하여 확인:

어떤 시스템을 다이어그램으로 그릴까요?
사용자/액터(Person)는 누구인가요?
어떤 컨테이너(앱, 서비스, 데이터베이스, 큐, 파일 스토리지)가 있나요?
어떤 외부 시스템과 상호작용하나요?
주요 데이터 흐름과 프로토콜은 무엇인가요?

사용자가 명세, 코드베이스 설명 또는 아키텍처 개요를 제공하면 자동으로 요소를 추출하고 생성을 진행하기 전에 확인합니다.

2단계: 요소 분류

모든 요소를 C4 카테고리에 매핑:

카테고리	색상	모양	설명
Person	`#08427B` (진한 파랑)	`shape=actor` + 텍스트 레이블	사용자, 액터, 역할
Container	`#438DD5` (파랑)	둥근 사각형	애플리케이션, 서비스, API
Database	`#438DD5` (파랑)	원기둥	모든 데이터 저장소 (SQL, NoSQL, 파일)
Queue/Broker	`#438DD5` (파랑)	레이블이 있는 둥근 사각형	메시지 큐, 이벤트 버스
External System	`#999999` (회색)	둥근 사각형	타사 서비스, API
System Boundary	없음 (투명)	점선 사각형	내부 컨테이너를 그룹화

참조: 정확한 draw.io XML 템플릿은 references/element-templates.md를 확인하세요.

3단계: 레이아웃 계획

엄격한 계층형 레이아웃(위에서 아래로) 적용:

레이어 1 (y ~= 20):     Person 요소 (액터)
레이어 2 (y ~= 250):    내부 컨테이너를 포함하는 System Boundary
레이어 3 (y ~= 700+):   외부 시스템

레이아웃 규칙:

모든 요소에 명시적인 x, y 좌표 지정 (자동 레이아웃 금지)
같은 레이어의 요소 간 최소 200px 수평 간격
레이어 간 최소 200px 수직 간격
System Boundary = 40px 패딩으로 모든 내부 컨테이너를 감싸는 점선 사각형
주 데이터 흐름 방향에 따라 요소를 왼쪽에서 오른쪽으로 배치
시스템에 별개의 하위 시스템이 있는 경우 관련 컨테이너를 하위 경계 내에 그룹화
가독성을 위해 다이어그램 너비를 1600px 미만으로 유지
요소를 해당 레이어 내에서 수평 중앙 정렬

선 교차 최소화:

자주 통신하는 요소를 서로 인접하게 배치
가능하면 연결선을 수직으로 라우팅
다른 요소를 가로지르는 대각선 회피
무관한 컨테이너를 통과하는 화살표 금지: A가 C에 연결된다면 화살표는 B를 통과해서는 안 됩니다. 해결 방법: (a) A와 C를 인접 배치, (b) 명시적 출구/입구 지점 사용, (c) 레이아웃 재구성
화살표 레이블이 컨테이너 텍스트와 겹치지 않도록: 모든 엣지에 labelBackgroundColor=#ffffff를 사용하고, mxGeometry의 수직 오프셋(y)을 사용하여 레이블을 컨테이너에서 밀어내기

4단계: 연결 정의

각 연결에 대해 다음을 지정:

소스 및 타겟 요소
레이블: 동작 + 프로토콜 (예: "읽기/쓰기 [SQL/TCP]", "이벤트 전송 [AMQP]")
스타일: 실선 = 동기 호출, 점선 = 비동기 (이벤트, 큐, 웹훅)
방향: 항상 소스 -> 타겟 (데이터 흐름 따름)

연결 규칙:

모든 화살표에는 레이블이 있어야 함 (레이블이 없는 연결 금지) - 레이블이 겹칠 경우 레이아웃을 수정하거나 오프셋을 조정하고, 절대 레이블을 제거하지 않음
연결 스타일에 항상 labelBackgroundColor=#ffffff 포함
[Protocol] 접미사 사용: [REST/JSON], [gRPC], [SQL], [AMQP], [WebSocket]
양방향 흐름: 별도의 레이블이 있는 두 개의 화살표 사용
자기 참조: 금지 (대신 다이어그램을 재구성)

5단계: .drawio XML 생성

references/drawio-template.md의 XML 구조를 기본으로 사용합니다.

다음 규칙에 따라 XML을 작성:

<mxfile> 래퍼와 적절한 크기의 <mxGraphModel>로 시작
루트 셀(id="0" 및 id="1") 추가
먼저 System Boundary 사각형 추가 (포함된 요소의 부모 역할)
명시적 지오메트리(x, y, width, height)로 모든 요소 추가
소스/타겟 참조로 모든 연결 추가
오른쪽 하단 모서리에 범례 추가

요소 크기:

Person: 40 x 60px 액터 + 아래 220 x 60px 텍스트 레이블
Container: 240 x 120px
Database (원기둥): 240 x 120px
External System: 240 x 120px
System Boundary: 자식을 포함하도록 계산 + 각 면 40px 패딩

6단계: 범례 추가

모든 다이어그램에는 범례가 포함되어야 합니다. 오른쪽 하단 모서리에 배치합니다.

범례에는 다음이 표시되어야 함:

Person = 진한 파란색 막대인간 (#08427B)
Container = 파란색 둥근 사각형 (#438DD5)
Database = 파란색 원기둥 (#438DD5)
External System = 회색 둥근 사각형 (#999999)
실선 화살표 = 동기 흐름
점선 화살표 = 비동기 흐름

참조: 정확한 XML은 references/legend-template.md를 확인하세요.

7단계: 저장 및 검증

사용자가 요청한 경로에 저장하거나 기본값 ./c4_[system_name].drawio를 사용합니다.

검증 체크리스트:

C4 모델 규칙

C4 컨테이너 다이어그램 제약 조건 준수:

컨테이너 다이어그램은 상위 수준의 기술 선택과 컨테이너 간 통신 방식을 보여줍니다.
각 컨테이너는 별도로 배포/실행 가능한 단위입니다 (클래스나 모듈이 아님).
C4 수준을 혼합하지 마십시오: 이 스킬은 컨테이너 수준만 생성합니다.
컨테이너 내부의 컴포넌트 수준 세부사항은 별도의 다이어그램을 만드십시오.
Person 요소는 개인이 아닌 역할을 나타냅니다.
외부 시스템은 팀이 소유하지 않은 시스템 경계 외부의 모든 것입니다.

안티패턴

자동 레이아웃 금지 - 예측 가능한 결과를 위해 항상 명시적 x, y 좌표 사용
레이블 없는 화살표 금지 - 모든 연결에는 동작과 프로토콜이 필요
범례 누락 금지 - 모든 다이어그램에 범례는 필수
좁은 레이아웃 금지 - 요소 간 최소 간격 유지
C4 수준 혼합 금지 - 컨테이너 수준만 (클래스, 인프라 없음)
보이지 않는 텍스트 금지 - 배경과 대비되는 글꼴 색상 보장
하드코딩된 크기 금지 - 자식으로부터 시스템 경계 크기 계산
mxgraph.c4.* 모양 금지 - draw.io에서 기본적으로 로드되지 않는 C4 모양 라이브러리가 필요합니다. 기본 제공 모양 사용: Person은 shape=actor, 데이터베이스는 shape=cylinder3
무관한 컨테이너를 통과하는 화살표 금지 - 모든 화살표가 소스와 타겟 사이에 명확한 경로를 가지도록 레이아웃 재구성
labelBackgroundColor=#ffffff 없는 레이블 금지 - 레이블이 다른 요소를 가로지를 때 읽을 수 없게 됨
겹침 해결을 위해 레이블 제거 금지 - 레이블이 컨테이너와 겹칠 경우 레이아웃을 수정하거나 오프셋을 조정하고, 정보를 절대 제거하지 않음

C4 컨테이너 다이어그램 생성기