System Context 다이어그램은 C4 모델의 레벨 1로, 팀이 만들 수 있는 가장 중요한 단일 아키텍처 다이어그램입니다. 이 가이드는 C4 컨텍스트 다이어그램에 무엇이 들어가야 하는지 설명하고, 완전한 컨텍스트 다이어그램 예제를 단계별로 살펴보며, 직접 만들거나 코드에서 생성하는 방법을 보여줍니다.

C4 System Context 다이어그램: 예제와 함께 보는 완벽 가이드

단 하나의 아키텍처 다이어그램만 그릴 수 있다면, System Context 다이어그램으로 하세요. 이것은 C4 모델의 진입점이며, 모든 이해관계자가 별도의 교육 없이 읽을 수 있는 다이어그램이고, 시스템이 실제로 무엇을 하는지에 대한 의견 불일치를 가장 빠르게 드러내는 방법입니다.

그러나 대부분의 팀은 이것을 잘못 그립니다. 데이터베이스, 마이크로서비스, Kubernetes 클러스터를 잔뜩 욱여넣어 "컨텍스트" 다이어그램이 읽을 수 없는 인프라 지도가 되어버립니다. 또는 아예 건너뛰고 곧장 컨테이너 다이어그램으로 넘어가, 비기술 이해관계자에게는 이해할 수 있는 것이 아무것도 남지 않게 됩니다.

이 가이드는 C4 모델 레벨 1에 대한 심층 분석입니다: System Context 다이어그램이 무엇인지, 정확히 무엇이 들어가야 하고(그리고 무엇이 들어가면 안 되는지), 완전하게 작성한 예제, 대부분의 컨텍스트 다이어그램을 망치는 실수들, 그리고 하나를 만드는 단계별 절차 — 직접 손으로 그리거나 코드베이스에서 생성하는 방법까지 다룹니다. C4 모델 자체가 처음이라면, 먼저 C4 모델 완벽 가이드부터 읽고 돌아오세요.

System Context 다이어그램이란 무엇인가?

System Context 다이어그램은 C4 모델에서 첫 번째이자 가장 높은 수준의 다이어그램입니다. 이것은 하나의 소프트웨어 시스템을 단일 상자로 표현하며 단 하나의 질문에 답합니다: 이 시스템은 그 환경에 어떻게 들어맞는가?

용어집 정의에서 설명하듯이, System Context 다이어그램은 설명 대상 시스템과 상호작용하는 사람 및 외부 시스템에 초점을 맞추며, 내부 구조는 의도적으로 생략합니다. 그 목표는 범위를 확립하는 것입니다: 누가 시스템을 사용하는지, 어떤 시스템에 의존하는지, 어떤 시스템이 이 시스템에 의존하는지.

컨텍스트 다이어그램에는 세 종류의 요소가 등장하며, 오직 그 세 가지뿐입니다:

당신의 소프트웨어 시스템 — 하나의 상자, 중앙에 위치합니다. 서비스도 아니고, 데이터베이스도 아닙니다. 하나의 상자입니다.
사람 — 시스템과 상호작용하는 사용자, 역할 또는 페르소나입니다. "Customer", "Administrator", "Support Agent" 등.
외부 소프트웨어 시스템 — 당신의 시스템이 통신하지만 당신의 팀이 소유하지 않는 시스템입니다: 결제 게이트웨이, 이메일 제공자, 레거시 ERP, 신원 제공자 등.

이들을 연결하는 것이 관계입니다: 누가 무엇을 하는지 설명하는 레이블이 붙은 화살표입니다. "주문을 처리함", "결제 요청을 보냄", "배송 업데이트를 받음" 등.

이것이 전체 어휘입니다. 시스템, 사람, 외부 시스템을 위한 상자와 관계를 위한 화살표. 이 다이어그램의 규율은 무엇을 빼느냐에서 나옵니다.

대상 독자는 누구인가?

System Context 다이어그램은 네 가지 C4 레벨 중에서 독특합니다. 코드 한 줄도 읽지 않을 사람들을 포함해 모두를 위해 설계되었기 때문입니다:

비기술 이해관계자. 프로덕트 매니저, CEO, 또는 컴플라이언스 담당자는 컨텍스트 다이어그램을 보고 1분 안에 시스템의 목적, 사용자, 서드파티 의존성을 이해할 수 있습니다.
새로운 팀원. 새로운 엔지니어가 폴더 구조를 배우기 전에, 먼저 시스템 경계를 배워야 합니다. 컨텍스트 다이어그램은 온보딩 슬라이드 1번입니다.
아키텍트와 보안 검토자. 시스템 경계를 넘는 모든 화살표는 통합 지점이자, 데이터 흐름이며, 잠재적인 공격 표면입니다. 보안 및 컴플라이언스 검토는 종종 여기에서 시작됩니다.
다른 팀. 다른 팀이 "당신의 시스템이 청구 API를 직접 호출하나요?"라고 물을 때, 컨텍스트 다이어그램은 회의 없이 답을 줍니다.

이것이 바로 기술 선택이 여기에 들어가서는 안 되는 이유입니다. 컨텍스트 다이어그램에 "PostgreSQL" 또는 "Kafka"라고 적는 순간, 대상 독자는 엔지니어로 좁혀집니다 — 그리고 그런 용도로는 컨테이너 다이어그램이 있습니다.

컨텍스트 다이어그램에 들어가야 하는 것(그리고 들어가면 안 되는 것)

포함할 것

범위에 있는 시스템 — 정확히 하나의 상자, 명확하게 이름을 붙입니다.
모든 사용자 범주 — 개별 인물이 아니라 역할이나 페르소나입니다. 고객과 창고 직원이 시스템을 다르게 사용한다면, 둘은 별도의 사람 상자입니다.
모든 외부 시스템 의존성 — 당연하게 여기는 것들까지 포함합니다: 이메일 서비스, 신원 제공자, 분석 플랫폼, 그리고 아키텍처적으로 관련이 있다면 모니터링 스택까지.
당신에게 의존하는 시스템 — 파트너의 시스템이 당신의 API를 소비한다면, 화살표가 당신을 향하도록 하여 다이어그램에 포함합니다.
레이블이 붙은 관계 — 모든 화살표에는 동사구가 필요합니다. 레이블 없는 화살표는 물음표입니다.

제외할 것

컨테이너 — 웹 앱, API 서비스, 데이터베이스, 메시지 큐는 없습니다. 그것들은 레벨 2입니다.
기술 선택 — "React", "Go", "PostgreSQL"은 없습니다. 컨텍스트 다이어그램은 스택을 완전히 재작성해도 변경 없이 살아남아야 합니다.
외부 시스템의 내부 구조 — Stripe는 하나의 상자이지, Stripe 아키텍처를 그린 다이어그램이 아닙니다.
인프라와 배포 세부 사항 — 리전도, 클러스터도, 로드 밸런서도 없습니다.
개별 기능 — 다이어그램은 기능 목록이 아니라 관계를 보여줍니다.

간단한 테스트: 어떤 요소를 제거해도 누가 시스템과 상호작용하는지 또는 어떤 외부 시스템과 접촉하는지가 바뀌지 않는다면, 그 요소는 레벨 1에 속하지 않습니다.

완전한 컨텍스트 다이어그램 예제: 온라인 결제 플랫폼

현실적인 예제를 단계별로 살펴봅시다. 상인이 자신의 웹사이트에서 카드 결제를 받을 수 있게 해주는 온라인 결제 플랫폼 PayFlow를 문서화한다고 상상해 보세요.

1단계: 시스템 이름 정하기

중앙에 하나의 상자: PayFlow Payment Platform. 한 줄 설명을 붙입니다: "상인이 온라인 카드 결제를 받고 관리할 수 있게 해줍니다."

2단계: 사람 식별하기

누가, 어떤 역할로 PayFlow와 상호작용하나요?

Merchant — 결제 페이지를 설정하고, 거래를 조회하고, 환불을 실행하는 사업주.
End Customer — PayFlow 체크아웃을 통해 구매 대금을 결제하는 쇼핑객.
Support Agent — 분쟁 거래를 조사하는 내부 직원.

3단계: 외부 시스템 식별하기

PayFlow는 무엇에 의존하고, 무엇이 PayFlow에 의존하나요?

Card Networks / Acquiring Bank — 카드 거래를 승인하고 정산합니다.
Fraud Detection Service — 거래의 사기 위험도를 점수화합니다.
Email Service — 영수증과 알림을 보냅니다.
Identity Provider — 상인의 싱글 사인온을 처리합니다.
Merchant E-Commerce Site — 상인 자신의 웹사이트로, PayFlow 체크아웃을 임베드하고 PayFlow API를 소비합니다.
Accounting Platform — 상인의 회계 처리를 위해 정산 보고서를 수신합니다.

4단계: 관계 그리기

전체 요소 및 관계 목록은 다음과 같습니다:

People:
  [Merchant]          --> [PayFlow] : Configures payments, views transactions, issues refunds
  [End Customer]      --> [PayFlow] : Pays for purchases via hosted checkout
  [Support Agent]     --> [PayFlow] : Investigates and resolves disputes

External systems:
  [Merchant E-Commerce Site] --> [PayFlow] : Initiates payments via API, embeds checkout
  [PayFlow] --> [Card Networks / Acquiring Bank] : Authorizes and settles card transactions
  [PayFlow] --> [Fraud Detection Service] : Requests risk scores for transactions
  [PayFlow] --> [Email Service] : Sends receipts and payment notifications
  [PayFlow] --> [Identity Provider] : Delegates merchant authentication
  [PayFlow] --> [Accounting Platform] : Exports settlement reports

총 10개의 요소: 하나의 시스템, 세 명의 사람, 여섯 개의 외부 시스템입니다. 모든 화살표에는 동사구가 있습니다. 서비스, 데이터베이스, 큐, 언어에 대한 언급은 전혀 없습니다 — 그럼에도 이 다이어그램을 읽는 사람은 누구나 PayFlow가 무엇이고, 누가 사용하며, 무엇에 의존하는지 이해합니다.

이 다이어그램이 즉시 드러내는 것에 주목하세요:

컴플라이언스 표면. 다이어그램의 카드 네트워크와 사기 탐지는 보안 검토자에게 PCI 관련 데이터가 정확히 어디로 흐르는지 알려줍니다.
벤더 리스크. 여섯 개의 외부 의존성, 각각이 잠재적인 장애 지점이거나 계약 협상 대상입니다.
양방향 경계. 상인의 전자상거래 사이트는 PayFlow 안으로 호출합니다 — 이 시스템은 단지 다른 서비스의 소비자일 뿐만 아니라, 다른 누군가의 의존 대상이기도 합니다.

이것이 바로 컨텍스트 다이어그램이 시작하도록 만들어진 종류의 대화입니다.

System Context 다이어그램의 흔한 실수

실수 1: 너무 많은 세부 사항

가장 흔한 실패입니다. 다이어그램은 깔끔하게 시작하지만, 그러다 누군가 "주요 데이터베이스 하나만" 추가하고, 그다음 API 게이트웨이, 그다음 세 개의 핵심 마이크로서비스를 추가하면, 한 달 안에 컨텍스트 다이어그램의 이름을 쓴 컨테이너 다이어그램이 됩니다. 해결책은 가차 없습니다: 당신의 시스템은 하나의 상자입니다. 내부를 보여주고 싶은 충동이 든다면, 그것은 이것을 과부하시키지 말고 별도의 연결된 뷰로 컨테이너 다이어그램을 만들라는 신호입니다.

실수 2: 외부 의존성 누락

팀들은 지루하다고 여기는 의존성을 어김없이 잊습니다: 이메일 제공자, SMS 게이트웨이, 신원 제공자, CDN, 기능 플래그 서비스. 하지만 "지루한" 의존성이 실제 장애와 실제 벤더 종속을 일으킵니다. 설정 파일과 환경 변수를 살펴보세요 — 보통 모든 API 키는 다이어그램에 속하는 외부 시스템에 대응합니다.

실수 3: 추상화 수준 섞기

"Customer → Web App → Orders API → PostgreSQL → Stripe"를 보여주는 다이어그램은 사람, 두 개의 컨테이너, 데이터베이스, 외부 시스템을 하나의 평면적 뷰에 뒤섞은 것입니다. 독자는 시스템 경계가 어디인지 알 수 없습니다. 각 C4 다이어그램은 정확히 하나의 줌 레벨에 있어야 합니다. C4 모델 계층 구조의 핵심은 다이어그램 사이에서 확대하는 것이지, 하나의 다이어그램 안에서 확대하는 것이 아닙니다.

실수 4: 레이블이 없거나 모호한 관계

"사용함"은 관계 레이블이 아닙니다 — 모든 것이 모든 것을 "사용"합니다. 실제로 무슨 일이 일어나는지 적으세요: "주문을 제출함", "웹훅 이벤트를 받음", "인증함". 다이어그램의 정보 대부분이 바로 이 레이블에 담겨 있습니다.

실수 5: 한 번 그리고 절대 업데이트하지 않기

작년에 마이그레이션을 마친 레거시 CRM을 여전히 보여주는 2023년의 컨텍스트 다이어그램은 적극적으로 오해를 불러일으킵니다. 컨텍스트 다이어그램은 하위 레벨 다이어그램보다는 덜 자주 바뀌지만, 그래도 바뀝니다 — 새로운 벤더 통합이 생길 때마다, 폐기된 파트너 API가 생길 때마다. 다이어그램을 킥오프 산출물이 아니라 살아있는 문서로 다루세요.

System Context 다이어그램 만드는 법: 단계별 가이드

수동 접근법

시스템 이름을 짓고 설명하기. 한 문장으로: 무엇을, 누구를 위해 하는가?
사용자 역할 나열하기. 시스템과 상호작용하는 모든 고유한 페르소나를 브레인스토밍하세요. 동일하게 상호작용하는 역할은 병합하고, 그렇지 않은 역할은 분리하세요.
외부 시스템 나열하기. 통합, API 키, 웹훅, 예약된 내보내기를 살펴보세요. 당신이 호출하는 시스템뿐만 아니라 당신을 호출하는 시스템도 포함하세요.
관계 그리기. 의미 있는 상호작용마다 화살표 하나, 각각 동사구로 레이블을 붙이세요. 방향은 주도권을 따릅니다: 누가 상호작용을 시작하나요?
팀과 함께 검토하기. 이것이 가장 가치 있는 단계입니다. 30분의 검토는 어김없이 의견 불일치를 드러냅니다: "잠깐, 우리 아직도 그 서비스를 호출하나요?", "언제부터 파트너가 우리 API를 직접 호출했죠?" 그 토론이 바로 산출물입니다.
사람들이 찾을 수 있는 곳에 게시하기 — 아무도 방문하지 않는 위키 페이지에 묻어두지 마세요.

그리는 작업 자체는 어떤 도구로도 됩니다: 화이트보드, diagrams.net, Structurizr, C4 확장이 있는 PlantUML. 병목은 결코 그리기가 아니었습니다 — 그것은 2, 3, 5단계, 그리고 결과를 시간이 지나도 정확하게 유지하는 일입니다.

자동화 접근법: Archyl로 컨텍스트 다이어그램 생성하기

이 지점에서 Archyl은 그리기 도구와 다른 길을 택합니다. 빈 캔버스에서 시작하는 대신, 리포지토리를 연결하고 AI 디스커버리를 실행합니다: Archyl은 코드 구조, 설정 파일, 의존성 그래프를 분석한 다음 초안 C4 모델 — 시스템, 외부 의존성, 컨테이너, 컴포넌트, 그리고 그것들 사이의 관계 — 을 제안합니다. 각 제안을 검토하여 수락하거나 조정하면, System Context 뷰가 모델로부터 자동으로 렌더링됩니다.

다이어그램이 손으로 그려진 것이 아니라 모델로부터 생성되기 때문에, 두 가지가 따라옵니다:

레벨들이 연결된 채로 유지됩니다. 컨텍스트 다이어그램의 시스템 상자는 컨테이너 뷰로 파고들 때와 동일한 엔티티입니다. 다이어그램 간의 복사-붙여넣기 표류가 없습니다.
노후화가 측정 가능해집니다. Archyl의 표류 탐지는 문서화된 아키텍처를 코드베이스에 실제로 존재하는 것과 지속적으로 비교합니다. 따라서 통합이 제거되거나 서비스 이름이 바뀌면, 혼란스러워하는 신입 직원이 아니라 표류 점수로부터 알게 됩니다.

버전 관리 안에 사는 문서를 선호한다면, Archyl은 Architecture as Code 워크플로우도 지원합니다: C4 모델을 YAML로 정의하고, 코드와 함께 커밋하면, 그 정의로부터 다이어그램이 렌더링됩니다.

컨텍스트에서 컨테이너로

System Context 다이어그램은 경계를 설정하고, 다음 레벨은 상자를 엽니다. 컨텍스트 다이어그램이 안정되면, 자연스러운 다음 단계는 컨테이너 다이어그램입니다 — 시스템 내부의 배포 가능한 단위(웹 앱, API, 데이터베이스, 브로커)와 그들이 어떻게 통신하는지 보여주는 레벨 2 뷰입니다. 이는 C4 컨테이너 다이어그램 가이드에서 자세히 다룹니다.

이 진행 순서가 중요합니다. 컨텍스트 다이어그램을 건너뛰고 레벨 2에서 시작하는 팀은 경계가 흐릿한 컨테이너 다이어그램을 만드는 경향이 있습니다 — 시스템이 어디서 끝나는지 아무도 합의한 적이 없기 때문에 외부 시스템이 내부 서비스와 뒤섞입니다.

FAQ

System Context 다이어그램과 Container 다이어그램의 차이는 무엇인가요?

컨텍스트 다이어그램(레벨 1)은 시스템을 단일 상자로 보여주고 그 환경, 즉 사용자와 외부 시스템에 초점을 맞춥니다. 컨테이너 다이어그램(레벨 2)은 그 상자 안으로 확대하여 배포 가능한 단위 — 웹 앱, 서비스, 데이터베이스 — 와 그 기술 선택을 보여줍니다. 컨텍스트는 "이 시스템은 무엇과 상호작용하는가?"에 답하고, 컨테이너는 "이 시스템은 무엇으로 이루어졌는가?"에 답합니다.

컨텍스트 다이어그램에는 몇 개의 요소가 있어야 하나요?

엄격한 규칙은 없지만, 대부분의 건강한 컨텍스트 다이어그램에는 하나의 시스템, 두 개에서 다섯 개의 사용자 역할, 그리고 세 개에서 열 개의 외부 시스템이 있습니다. 열다섯 개나 스무 개를 넘어선다면, 시스템 경계가 너무 넓거나, 엔터프라이즈 환경 전체를 문서화하고 있는 것입니다 — 후자의 경우 C4 System Landscape 다이어그램(여러 시스템을 하나의 뷰에)이 더 적합합니다.

데이터베이스가 System Context 다이어그램에 나타나야 하나요?

아니요 — 데이터베이스가 당신의 시스템에 속하는 한, 그것은 내부 세부 사항이며 컨테이너 레벨에 나타납니다. 예외는 당신의 시스템이 직접 읽어오는, 다른 팀이나 벤더가 운영하는 데이터베이스입니다. 그것은 사실상 외부 시스템이므로 외부 시스템으로 나타날 수 있습니다.

C4 컨텍스트 다이어그램은 UML이나 데이터 흐름 컨텍스트 다이어그램과 같은가요?

개념적으로는 사촌 관계입니다 — "컨텍스트 다이어그램"(하나의 시스템과 그 환경)이라는 아이디어는 C4보다 앞서며 구조적 분석과 UML 실무에 존재합니다. C4 버전은 계층 구조 내에서의 위치로 구별됩니다: 그 위의 모든 요소는 다음 하위 레벨로 분해될 수 있어, 독립적인 그림이 아니라 탐색 가능한 지도를 제공합니다.

System Context 다이어그램을 만들 준비가 되셨나요? Archyl을 무료로 사용해 보고 리포지토리에서 직접 C4 모델을 생성하세요. 또는 계속 읽어보세요: C4 모델이란 무엇인가? 완벽 가이드 | C4 컨테이너 다이어그램 가이드 | 용어집의 System Context 다이어그램.

C4 System Context 다이어그램: 예제와 함께 보는 완벽 가이드 - Archyl Blog