C4 다이어그램은(는) 무엇을 하나요?
출처: 공식 C4 모델 https://c4model.com/. C4 다이어그램을 그리거나, 검토하거나, 설명할 때마다 이 규칙을 적용하세요. 출력에 산문(ADR, 문서, PR 설명)이 포함될 경우 writing 스킬도 함께 불러오세요.
1. 목적
C4는 네 가지 줌 레벨(컨텍스트, 컨테이너, 컴포넌트, 코드)로 구성된 '코드의 지도' 집합입니다. Simon Brown이 UML과 4+1 뷰 모델에서 영감을 받아 임시방편 상자-선 다이어그램을 대체하기 위해 만들었습니다. C4가 해결하는 일반적인 실패 사례: 범례 없음, 추상화 수준 혼합, 레이블 없는 화살표, 기술 정보 누락, '비즈니스 로직'과 같은 모호한 레이블.
C4는 표기법과 도구에 독립적입니다. 아래의 추상화와 규칙이 중요하며, 모양은 중요하지 않습니다.
2. 추상화
계층 구조: 사람 -> 소프트웨어 시스템 -> 컨테이너 -> 컴포넌트 -> 코드. 각 레벨은 상위 레벨의 한 요소를 확대하여 보여줍니다.
| 추상화 | 정의 | 예시 |
|---|---|---|
| 사람 | 시스템의 인간 사용자, 행위자, 역할 또는 페르소나 | 고객, 지원 에이전트, 관리자 |
| 소프트웨어 시스템 | 가장 높은 수준의 추상화; 사용자에게 가치를 제공합니다. 일반적으로 단일 팀이 소유하고 구축합니다. 제품 도메인, 바운디드 컨텍스트, 트라이브, 스쿼드가 아닙니다. | 티켓팅 플랫폼, 결제 시스템 |
| 컨테이너 | 소프트웨어 시스템 내에서 독립적으로 실행/배포 가능한 애플리케이션 또는 데이터 저장소 | 서버 사이드 웹 앱, SPA, 데스크탑 앱, 모바일 앱, 서버리스 함수, 배치/콘솔 앱, 마이크로서비스 API, 데이터베이스 스키마, S3/블롭 저장소, CDN, 파일 시스템, 셸 스크립트 |
| 컴포넌트 | 컨테이너 내에서 잘 정의된 인터페이스 뒤에 있는 관련 기능의 그룹. 별도로 배포할 수 없음: 컨테이너의 모든 컴포넌트는 하나의 프로세스 공간을 공유합니다. | OrderController, PaymentService, EmailSender |
| 코드 | 컴포넌트 내의 클래스, 인터페이스, 함수 또는 DB 테이블 | class OrderValidator, orders 테이블 |
컨테이너 규칙 (C4 FAQ)
- C4 컨테이너는 Docker가 아닙니다. 패키징 방식과 관계없이 실행/배포 가능한 애플리케이션 또는 데이터 저장소입니다.
- 서버 렌더링 HTML 앱은 1개의 컨테이너입니다. 서버와 SPA 또는 모바일 클라이언트는 원격 API를 통해 통신하는 2개의 컨테이너입니다.
- JAR, DLL, 어셈블리, 모듈은 컨테이너가 아닙니다. 이들은 컨테이너 내부의 코드를 구성합니다.
- 관리형 데이터 서비스(S3, RDS, CDN)는 사용자가 버킷이나 스키마를 소유하거나 제어하는 경우 시스템 경계 내의 컨테이너입니다. 외부 시스템이 아닙니다.
컴포넌트 규칙
- 컴포넌트는 폴더, 패키지 또는 JAR이 아닙니다. 인터페이스가 있는 기능 그룹입니다.
- 컴포넌트는 독립적으로 배포할 수 없습니다. 별도로 배포된다면 컨테이너입니다.
용어 조정
팀은 다이어그램이나 해당 문서에서 용어를 명시적으로 정의하는 경우 언어에 특화된 이름(예: 함수형 코드의 모듈 또는 함수)을 대체하여 사용할 수 있습니다. 각각이 엄격하게 정의되지 않은 한 추가 추상화 수준을 임의로 만들지 마세요.
3. 특수 모델링 패턴
큐와 토픽
- 잘못된 예: 모든 서비스가 연결된 중앙에 하나의 거대한 '메시지 버스' 컨테이너(허브-앤-스포크). 생산자와 소비자가 무엇을 누구에게 하는지 숨깁니다.
- 옵션 1 (권장): 각 큐 또는 토픽을 자체 컨테이너(메시지 데이터 저장소)로 모델링합니다. 생산자는 쓰기, 소비자는 읽기 또는 구독합니다.
- 옵션 2: 직접적인 점대점 결합의 경우 큐 박스를 생략하고 관계 레이블을
"Queue orders [AMQP]를 통해 주문 이벤트 발행"으로 지정합니다. 선택적으로 이러한 선을 HTTP 호출과 다르게 스타일 지정합니다(범례에 설명).
예: 주문 API --"[Kafka]로 OrderPlaced 발행"--> [(orders topic)] --"[Kafka]에서 OrderPlaced 읽음"--> 처리 워커.
마이크로서비스 (Conway의 법칙)
- 한 팀이 전체 소프트웨어 시스템을 소유: 각 마이크로서비스를 해당 시스템 경계 내의 컨테이너 그룹(API 컨테이너와 자체 데이터베이스 스키마 컨테이너, 또는 단일 상태 비저장 Lambda 컨테이너)으로 모델링합니다.
- 별도 팀이 각 서비스를 소유: 독립적으로 소유된 각 서비스를 자체 소프트웨어 시스템으로 승격시키고, 각각 자체 시스템 컨텍스트 및 컨테이너 다이어그램을 갖습니다. 시스템 경계 전반에 걸쳐 큐/토픽 소유권을 명시적으로 표시합니다.
4. 다이어그램 카탈로그
핵심 정적 레벨
| 레벨 | 다이어그램 | 권장 여부 | 범위 | 대상 | 표시/생략 |
|---|---|---|---|---|---|
| 1 | 시스템 컨텍스트 | 예 | 1개 소프트웨어 시스템 | 기술 및 비기술 | 시스템 주변의 사람과 외부 시스템. 하위 수준 기술 및 프로토콜 생략 |
| 2 | 컨테이너 | 예 | 1개 소프트웨어 시스템 | 기술, 운영 | 주요 기술 선택 및 프로세스 간 프로토콜. 클러스터링, 로드 밸런서, 장애 조치 생략 |
| 3 | 컴포넌트 | 아니오: 명확한 가치가 있고 이상적으로 자동화될 수 있을 때만 | 1개 컨테이너 | 아키텍트, 개발자 | 한 컨테이너 내의 컴포넌트 및 상호 작용 |
| 4 | 코드 | 아니오: IDE에서 필요 시 생성 | 1개 컴포넌트 | 개발자 | UML 클래스 다이어그램 또는 ERD |
지원 다이어그램
| 다이어그램 | 권장 여부 | 용도 |
|---|---|---|
| 시스템 랜드스케이프 | 예, 조직 및 포트폴리오용 | 모든 시스템과 사람에 대한 엔터프라이즈 또는 부서 지도. 단일 초점 시스템이 없는 컨텍스트 다이어그램 |
| 동적 | 아니오: 필요한 경우에만 사용 | 복잡한 런타임 협업. 번호가 매겨진 협업 스타일 또는 UML 시퀀스 스타일 |
| 배포 | 예 | 1개 환경(프로덕션, 스테이징, 개발). 시스템/컨테이너 인스턴스를 포함하는 중첩 배포 노드(물리, VM, Docker, Kubernetes, 런타임)와 인프라 노드(DNS, 로드 밸런서, 방화벽) |
호환성
- arc42: 컨텍스트 및 범위 -> L1; 빌딩 블록 레벨 1 -> L2; 빌딩 블록 레벨 2 -> L3; 빌딩 블록 레벨 3 -> L4.
- UML: 워크플로, 상태 머신 및 데이터 모델에 대해 C4를 UML 상태, 시퀀스 및 ERD 다이어그램으로 보완합니다.
확장 규칙
다이어그램이 복잡해지면 수십 개의 상자를 하나의 캔버스에 억지로 넣지 마세요. 동일한 추상화 수준에서 업무 영역, 바운디드 컨텍스트, 기능 또는 단일 서비스 초점(초점 서비스와 그 인바운드/아웃바운드 이웃)별로 분할합니다.
5. 표기법 규칙
다이어그램
- 제목은 다이어그램 유형과 범위를 명시합니다:
체크아웃 시스템의 컨테이너 다이어그램. - 모양, 색상, 테두리, 선 유형, 화살촉 및 약어를 설명하는 키/범례를 항상 포함합니다.
- 엄격한 추상화 순수성을 유지합니다: 추상화 수준을 절대 혼합하지 말고(예: L2 컨테이너 다이어그램 안에
컴포넌트상자를 넣지 않음), L1 시스템 컨텍스트 다이어그램 안에 프로토콜이나 내부 구현 단계([HTTPS],masked packet,tool_runner)를 절대 넣지 않습니다. - 경쟁 또는 이전 아키텍처를 비교할 때는 경계 제목을 명시적으로 레이블링하고(
옵션 A (대체됨)대옵션 B (현재)), 요구 사항이나 가정이 변경될 때마다 문서의 모든 다이어그램을 업데이트합니다.
요소
- 이름, 명시적 요소 유형(
사람,소프트웨어 시스템,컨테이너,컴포넌트,데이터베이스,배포 노드) 및 간결한 책임 설명. - 모든 컨테이너, 컴포넌트 및 배포 노드에 명시적 기술.
관계
- 단방향 화살표만 사용합니다.
<-->는 절대 사용하지 않습니다. 데이터가 양방향으로 흐르는 경우 개시자의 방향을 표시하고 레이블에 응답을 설명합니다. - 구체적인 능동 동사 레이블. 맨
사용은 절대 사용하지 않습니다.주문 제출,좌석 지도 읽음으로 작성합니다. - 컨테이너 간 관계에 프로토콜/기술:
[JSON/HTTPS],[SQL],[gRPC],[AMQP].
6. Markdown의 Mermaid
기본값은 flowchart (flowchart TB 또는 LR)이며, Mermaid 네이티브 C4Context/C4Container가 아닙니다. 네이티브 C4 문법은 실험적이며 Markdown 뷰어에서 렌더링이 실패하는 경우가 많습니다. 사용자가 명시적으로 요청하고 렌더러 지원을 확인한 경우에만 출력합니다.
Flowchart 규칙:
- 시스템 경계(컨테이너/컴포넌트) 또는 배포 노드에
subgraph사용. - 데이터베이스, 데이터 저장소, 큐 및 토픽에
[(...)]사용. - 인용된 HTML 레이블:
"<b>Name</b><br/>«Container: Tech»<br/>Short responsibility". - 인용된 레이블이 있는 화살표:
A -->|"Action [Protocol]"| B. - 요소 유형당 하나의
classDef를 일관되게 적용합니다. - 색상, 실린더 모양 또는 여러 선 스타일을 사용할 때마다 컴팩트한
범례서브그래프(연결되지 않은 노드, Dagre가 상단에 배치할 때 보이지 않는bottomNode ~~~ 범례링크로 하단에 고정)가 필요합니다. 제목은 코드 블록 바로 위에 제목 또는Title: ...줄로 배치합니다. - 동적 다이어그램:
sequenceDiagram또는 번호가 매겨진 화살표 레이블이 있는flowchart(1. 주문 제출 [JSON/HTTPS]). - 배포 다이어그램:
flowchart의 중첩subgraph. - 괄호, 대괄호 또는 콜론이 포함된 레이블은 항상 인용합니다.
sequenceDiagram또는stateDiagram-v2레이블 안에 이스케이프되지 않은 세미콜론(;)을 절대 넣지 마십시오(Mermaid는;을 문 종결자로 처리하여 나머지 텍스트를 잘못된 상태 또는 구문 오류로 분할합니다).sequenceDiagram의 긴Note블록은<br/>로 감싸서 텍스트가 뷰포트 가장자리에서 잘리지 않도록 합니다.
템플릿: L1 시스템 컨텍스트
제목: 티켓팅 플랫폼의 시스템 컨텍스트 다이어그램
flowchart TB
customer["<b>고객</b><br/>«사람»<br/>이벤트 티켓 구매"]
ticketing["<b>티켓팅 플랫폼</b><br/>«소프트웨어 시스템»<br/>고객이 이벤트를 탐색하고 티켓을 구매할 수 있음"]
payments["<b>결제 제공자</b><br/>«소프트웨어 시스템, 외부»<br/>카드 청구"]
email["<b>이메일 서비스</b><br/>«소프트웨어 시스템, 외부»<br/>확인 이메일 전송"]
customer -->|"이용하여 이벤트 탐색 및 티켓 구매"| ticketing
ticketing -->|"카드 청구 요청"| payments
ticketing -->|"사용하여 확인 이메일 전송"| email
email -->|"에게 확인 이메일 전송"| customer
classDef person fill:#08427b,stroke:#052e56,color:#fff
classDef system fill:#1168bd,stroke:#0b4884,color:#fff
classDef external fill:#999,stroke:#6b6b6b,color:#fff
class customer person
class ticketing system
class payments,email external
subgraph 범례
direction LR
l1["사람"]:::person
l2["소프트웨어 시스템 (범위 내)"]:::system
l3["소프트웨어 시스템 (외부)"]:::external
end
템플릿: L2 컨테이너 (큐 컨테이너 포함)
제목: 티켓팅 플랫폼의 컨테이너 다이어그램
flowchart TB
customer["<b>고객</b><br/>«사람»<br/>이벤트 티켓 구매"]
payments["<b>결제 제공자</b><br/>«소프트웨어 시스템, 외부»<br/>카드 청구"]
subgraph boundary["티켓팅 플랫폼 [소프트웨어 시스템]"]
spa["<b>웹 앱</b><br/>«컨테이너: React SPA»<br/>이벤트 탐색 및 체크아웃 UI"]
api["<b>주문 API</b><br/>«컨테이너: Java, Spring Boot»<br/>주문 검증 및 접수"]
db[("<b>주문 DB</b><br/>«컨테이너: PostgreSQL»<br/>주문 및 티켓 저장")]
topic[("<b>orders topic</b><br/>«컨테이너: Kafka topic»<br/>OrderPlaced 이벤트")]
worker["<b>처리 워커</b><br/>«컨테이너: Python»<br/>티켓 발행 및 이메일 전송"]
end
customer -->|"[HTTPS]로 탐색 및 구매"| spa
spa -->|"[JSON/HTTPS]로 주문 제출"| api
api -->|"[SQL/TCP]로 주문 쓰기"| db
api -->|"[Kafka]로 OrderPlaced 발행"| topic
worker -->|"[Kafka]에서 OrderPlaced 읽음"| topic
worker -->|"[SQL/TCP]로 티켓 상태 업데이트"| db
api -->|"[JSON/HTTPS]로 카드 청구 요청"| payments
classDef person fill:#08427b,stroke:#052e56,color:#fff
classDef container fill:#438dd5,stroke:#2e6295,color:#fff
classDef store fill:#2e6da4,stroke:#1b4f72,color:#fff
classDef external fill:#999,stroke:#6b6b6b,color:#fff
class customer person
class spa,api,worker container
class db,topic store
class payments external
subgraph 범례
direction LR
l1["사람"]:::person
l2["컨테이너"]:::container
l3[("데이터 저장소 / 큐 / 토픽")]:::store
l4["외부 시스템"]:::external
end
범례 참고: 화살표는 개시자에서 대상을 가리킵니다. 레이블은 동작과 [프로토콜]을 나타냅니다.
템플릿: 배포
제목: 티켓팅 플랫폼의 배포 다이어그램 (프로덕션)
flowchart TB
users["<b>고객 브라우저</b><br/>«배포 노드: Chrome»"]
subgraph aws["AWS «배포 노드: Cloud, us-east-1»"]
dns["<b>Route 53</b><br/>«인프라 노드: DNS»"]
lb["<b>로드 밸런서</b><br/>«인프라 노드: ALB»"]
subgraph eks["EKS «배포 노드: Kubernetes 클러스터»"]
subgraph pod["order-api pod «배포 노드: Docker, x3»"]
api["<b>주문 API</b><br/>«컨테이너 인스턴스: Java, Spring Boot»"]
end
end
subgraph rds["RDS «배포 노드: PostgreSQL 16»"]
db[("<b>주문 DB</b><br/>«컨테이너 인스턴스: PostgreSQL 스키마»")]
end
end
users -->|"[DNS]로 호스트 이름 확인"| dns
users -->|"[HTTPS]로 요청 전송"| lb
lb -->|"[HTTP]로 요청 전달"| api
api -->|"[SQL/TCP]로 주문 읽기 및 쓰기"| db
기본값 이상의 색상이나 스타일을 사용하는 경우 범례 서브그래프를 추가하세요.
템플릿: 동적 (시퀀스)
제목: 티켓팅 플랫폼 주문 체크아웃의 동적 다이어그램 (시퀀스 스타일)
sequenceDiagram
autonumber
actor customer as 고객
participant spa as 웹 앱 (React SPA)
participant api as 주문 API (Spring Boot)
participant payments as 결제 제공자
participant db as 주문 DB (PostgreSQL)
participant topic as orders topic (Kafka)
customer->>spa: "주문" 클릭
spa->>api: POST /orders [JSON/HTTPS]
api->>payments: 카드 청구 [JSON/HTTPS]
payments-->>api: 결제 승인됨
api->>db: 주문 행 삽입 [SQL/TCP]
api->>topic: OrderPlaced 발행 [Kafka]
api-->>spa: 201 Created (주문 확인)
spa-->>customer: 주문 영수증 표시
최대 Markdown 뷰어 호환성을 위해 sequenceDiagram 참가자 및 메시지 레이블에 인용되지 않은 슬래시, 세미콜론(;, Mermaid가 문 종결자로 구문 분석함) 또는 원시 줄바꿈이 없도록 유지하세요.
7. 다이어그래
…
[번역을 위해 잘림]