C4 모델이란? 소프트웨어 팀을 위한 완벽 가이드 - Archyl Blog

C4 모델은 소프트웨어 아키텍처를 시각화하는 가장 실용적인 프레임워크입니다. 이 완벽 가이드에서는 네 가지 레벨 모두, 각각을 언제 사용해야 하는지, 실제 사례, 그리고 현대 팀이 Archyl과 같은 도구로 C4를 구현하는 방법을 다룹니다.

C4 모델이란? 소프트웨어 팀을 위한 완벽 가이드

소프트웨어 아키텍처 다이어그램은 평판 문제가 있습니다. 너무 추상적이어서 쓸모가 없거나, 너무 상세해서 유지보수가 불가능합니다. 아마 두 가지 모두 본 적이 있을 것입니다: "시스템"이라고 적힌 하나의 상자로 된 다이어그램은 아무것도 알려주지 않고, 200개의 클래스가 포함된 방대한 UML 다이어그램은 실제로 알아야 할 것을 제외한 모든 것을 알려줍니다.

Simon Brown이 만든 C4 모델은 지도학에서 아이디어를 빌려 이 문제를 해결합니다. 지도는 여러 확대/축소 수준에서 작동합니다. 세계 지도로 시작하여 방향을 잡고, 국가로 확대한 다음, 도시, 그리고 거리로 확대합니다. 각 수준은 질문에 맞는 적절한 양의 세부 정보를 보여줍니다. C4 모델은 이 동일한 원칙을 소프트웨어 아키텍처에 적용합니다.

이 가이드에서는 C4 모델에 대해 알아야 할 모든 것을 다룹니다: 각 레벨이 무엇을 나타내는지, 언제 사용하는지, 흔한 함정, 그리고 현대 팀이 실제로 C4를 구현하는 방법까지.

C4는 무엇을 의미하나요?

C4는 모델이 정의하는 네 가지 추상화 수준을 의미합니다:

  1. Context -- 큰 그림. 시스템이 세상에 어떻게 들어맞는지.
  2. Containers -- 시스템의 상위 수준 기술 빌딩 블록.
  3. Components -- 각 컨테이너의 내부 구조.
  4. Code -- 실제 구현 세부 사항.

각 레벨은 다른 대상을 위해 다른 질문에 답합니다. 프로덕트 매니저는 Context에 관심이 있습니다. 플랫폼 엔지니어는 Containers에 관심이 있습니다. 특정 서비스를 담당하는 개발자는 Components에 관심이 있습니다. Code 레벨을 수동으로 그릴 필요가 있는 사람은 거의 없습니다 -- 이에 대해서는 나중에 더 설명합니다.

C4의 힘은 어느 하나의 다이어그램에 있지 않습니다. 계층 구조에 있습니다. 한 레벨의 모든 요소는 다음 레벨의 다이어그램으로 분해됩니다. 컨테이너 다이어그램에서 "Backend API"라고 레이블된 상자는 내부 모듈을 보여주는 자체 컴포넌트 다이어그램이 됩니다. 이것은 탐색 가능하고 확대/축소 가능한 아키텍처 뷰를 만듭니다.

레벨 1: 시스템 컨텍스트 다이어그램

시스템 컨텍스트 다이어그램은 모든 C4 모델의 출발점입니다. 하나의 질문에 답합니다: 시스템이 더 넓은 환경에 어떻게 들어맞는가?

보여주는 것

  • 중앙에 하나의 상자로 된 소프트웨어 시스템
  • 이를 사용하는 사람들 (액터, 역할, 페르소나)
  • 통합하는 외부 시스템
  • 이들 간의 관계

보여주지 않는 것

  • 시스템의 내부 구조
  • 기술 선택
  • 데이터베이스, 큐 또는 인프라
  • 배포 세부 사항

실제 예시

전자상거래 플랫폼을 문서화한다고 상상해 보세요. 시스템 컨텍스트 다이어그램은 다음을 보여줍니다:

[Customer] --> [E-Commerce Platform] : Browses products, places orders
[Warehouse Staff] --> [E-Commerce Platform] : Manages inventory
[E-Commerce Platform] --> [Payment Gateway (Stripe)] : Processes payments
[E-Commerce Platform] --> [Shipping Provider (FedEx API)] : Creates shipments
[E-Commerce Platform] --> [Email Service (SendGrid)] : Sends notifications

5개의 사용자와 외부 시스템. 전체 플랫폼을 위한 하나의 상자. 그게 전부입니다.

이 레벨이 중요한 이유

시스템 컨텍스트 다이어그램은 경계에 대한 명확성을 강제합니다. 무엇을 소유하는가? 무엇에 의존하는가? 사용자는 누구인가? 이 질문들은 당연해 보이지만, 팀들이 일관되게 답하는 데 정기적으로 어려움을 겪습니다.

이 다이어그램은 또한 비기술 이해관계자에게 보여주는 다이어그램이기도 합니다. CEO가 시스템이 무엇을 하는지, 누가 사용하는지, 어떤 서드파티 서비스에 의존하는지 이해할 수 있습니다. UML 클래스 다이어그램으로 이것을 해보세요.

좋은 시스템 컨텍스트 다이어그램을 위한 팁

  • 한 페이지에 유지하세요. 맞지 않으면 시스템 경계가 잘못되었을 수 있습니다.
  • 모든 관계에 동사구를 레이블링하세요: "이메일 전송", "결제 처리", "재고 조회".
  • 당연하게 여기는 것까지 모든 외부 시스템을 포함하세요 (DNS, CDN, 모니터링).
  • 내부 세부 사항을 포함하지 마세요. 유혹을 참으세요.

레벨 2: 컨테이너 다이어그램

컨테이너 다이어그램은 시스템으로 확대하여 상위 수준의 기술 빌딩 블록을 보여줍니다. C4 용어에서 "컨테이너"는 별도로 배포 가능하거나 실행 가능한 모든 단위입니다 -- 반드시 Docker 컨테이너는 아닙니다.

컨테이너에 해당하는 것

  • 웹 애플리케이션 (React SPA, Next.js 앱)
  • 모바일 애플리케이션 (iOS 앱, Android 앱)
  • 백엔드 API 서비스 (Go API, Node.js 서버)
  • 데이터베이스 (PostgreSQL, MongoDB, Redis)
  • 메시지 브로커 (Kafka, RabbitMQ)
  • 파일 스토리지 시스템 (S3, MinIO)
  • 서버리스 함수 (AWS Lambda, Cloud Functions)

각 컨테이너는 자체 프로세스에서 실행되거나 자체 데이터 스토리지를 가집니다. 그것이 구별 요소입니다. 함께 배포되는 두 개의 Go 패키지는 같은 컨테이너의 일부입니다. 독립적으로 배포되는 두 개의 Go 서비스는 별도의 컨테이너입니다.

실제 예시

전자상거래 플랫폼으로 확대해 봅시다:

[Single-Page Application (React)] --> [API Gateway (Kong)] : Makes API calls (HTTPS/JSON)
[API Gateway] --> [Order Service (Go)] : Routes requests
[API Gateway] --> [Product Service (Go)] : Routes requests
[API Gateway] --> [User Service (Go)] : Routes requests
[Order Service] --> [Order Database (PostgreSQL)] : Reads/writes orders
[Product Service] --> [Product Database (PostgreSQL)] : Reads/writes products
[User Service] --> [User Database (PostgreSQL)] : Reads/writes users
[Order Service] --> [Message Queue (Kafka)] : Publishes order events
[Notification Service (Go)] --> [Message Queue] : Consumes order events

이제 기술 선택, 통신 패턴, 데이터 저장소를 볼 수 있습니다. 아키텍트는 Order와 Product 데이터베이스를 병합할지 논의할 수 있습니다. DevOps 엔지니어는 배포 토폴로지를 계획할 수 있습니다. 새 개발자는 React 프론트엔드가 어디서 끝나고 Go 백엔드가 어디서 시작하는지 이해할 수 있습니다.

좋은 컨테이너 다이어그램을 위한 팁

  • 기술을 괄호 안에 포함하세요: "Order Service (Go)", "Database (PostgreSQL)".
  • 관계에 통신 프로토콜을 표시하세요: "HTTPS/JSON", "gRPC", "AMQP".
  • 15-20개 이상의 컨테이너가 있다면, 다른 하위 시스템에 대해 여러 컨테이너 다이어그램을 만드세요.
  • 데이터베이스와 큐를 포함하세요. 이것들도 컨테이너입니다.
  • 여기서 컨테이너 레벨 아래로 내려가지 마세요. 내부 모듈은 컴포넌트 다이어그램에 속합니다.

레벨 3: 컴포넌트 다이어그램

컴포넌트 다이어그램은 단일 컨테이너로 확대하여 내부 구조적 빌딩 블록을 보여줍니다. 컴포넌트는 컨테이너 내의 주요 추상화입니다 -- 패키지, 모듈, 서비스 또는 레이어로 생각하세요.

컴포넌트에 해당하는 것

  • HTTP 핸들러 또는 컨트롤러
  • 비즈니스 로직 서비스
  • 리포지토리 또는 데이터 접근 레이어
  • 외부 API 클라이언트
  • 백그라운드 작업 프로세서
  • 미들웨어 또는 인터셉터

컴포넌트는 논리적 그룹이지, 반드시 개별 파일이 아닙니다. OrderHandler 컴포넌트는 여러 파일에 걸쳐 구현될 수 있지만, 개념적으로는 하나의 것입니다: 주문 관련 HTTP 요청을 처리하는 시스템의 일부.

실제 예시

Order Service 컨테이너로 확대합니다:

[Order Handler] --> [Order Service] : Delegates business logic
[Order Service] --> [Order Repository] : Persists orders
[Order Service] --> [Payment Client] : Validates payment
[Order Service] --> [Inventory Client] : Checks stock availability
[Order Repository] --> [Order Database (PostgreSQL)] : SQL queries
[Payment Client] --> [Payment Gateway (Stripe)] : HTTPS/REST
[Inventory Client] --> [Product Service] : gRPC

이 팀에 합류하는 개발자는 Order Service가 어떻게 구조화되어 있는지 즉시 볼 수 있습니다: 요청은 핸들러를 통해 들어오고, 비즈니스 로직은 서비스에 있고, 데이터 접근은 리포지토리를 통하며, 외부 호출은 전용 클라이언트를 통합니다.

컴포넌트 다이어그램을 언제 만들 것인가

모든 컨테이너에 컴포넌트 다이어그램이 필요한 것은 아닙니다. 다음과 같을 때 만드세요:

  • 컨테이너가 새 개발자가 탐색하기 어려울 만큼 복잡할 때
  • 다이어그램이 명시적으로 만들 수 있는 중요한 디자인 패턴(헥사고날 아키텍처, CQRS)이 있을 때
  • 여러 팀이 동일한 컨테이너에 기여하고 구조에 대한 공유된 이해가 필요할 때

컴포넌트 다이어그램을 건너뛸 때:

  • 컨테이너가 단순할 때 (엔드포인트 3개의 CRUD 서비스)
  • 코드 구조가 폴더 레이아웃에서 명백할 때
  • 컨테이너가 내부를 제어하지 않는 서드파티 도구(Redis, Kafka)일 때

레벨 4: 코드 다이어그램

코드 레벨은 실제 구현 세부 사항을 보여줍니다: 클래스, 인터페이스, 함수 및 그들의 관계. 이것은 본질적으로 UML 클래스 다이어그램 또는 엔티티-관계 다이어그램입니다.

레벨 4에 대한 솔직한 진실

Simon Brown 본인도 코드 다이어그램을 수동으로 만드는 것을 권장하지 않습니다. 이유는 다음과 같습니다:

  • 너무 자주 변경됩니다. 모든 리팩토링이 무효화합니다.
  • 유지보수 비용이 큽니다. 수동으로 클래스 다이어그램을 그리는 것은 지루합니다.
  • 이미 코드에 존재하는 정보를 복제합니다.
  • 현대 IDE가 요청 시 생성할 수 있습니다.

코드 레벨 다이어그램이 필요하다면, 언어를 지원하는 도구를 사용하여 소스 코드에서 생성하세요. 수동으로 그리지 마세요.

코드 다이어그램이 실제로 도움이 되는 경우

예외가 있습니다:

  • 시각적 설명이 도움이 되는 복잡한 알고리즘
  • 구조가 흥미로운 부분인 디자인 패턴 (Strategy, Observer, State Machine)
  • 계약을 문서화하려는 공개 API 표면
  • 패턴을 가르치는 면접 또는 온보딩 자료

실제로 대부분의 팀은 C4의 세 가지 레벨(Context, Container, Component)을 사용하고 코드 레벨은 IDE가 생성한 뷰에 맡깁니다.

보충 다이어그램

네 가지 핵심 레벨 외에도, Simon Brown은 C4 계층을 보완하는 여러 보충 다이어그램을 정의합니다:

시스템 랜드스케이프 다이어그램

시스템 컨텍스트 다이어그램을 더 축소한 것입니다. 엔터프라이즈의 모든 소프트웨어 시스템과 서로 어떻게 관련되는지 보여줍니다. 시스템 포트폴리오를 관리하는 엔터프라이즈 아키텍트에게 유용합니다.

배포 다이어그램

컨테이너를 인프라에 매핑합니다. 어떤 컨테이너가 어떤 서버에서, 어떤 클라우드 리전에서, 어떤 로드 밸런서 뒤에서 실행되는지 보여줍니다. DevOps 및 플랫폼 팀에 필수적입니다.

동적 다이어그램

런타임에 요소들이 특정 유스 케이스를 이행하기 위해 어떻게 협력하는지 보여줍니다. UML 시퀀스 다이어그램과 유사하지만 C4 표기법을 사용합니다. "사용자가 주문을 넣을 때 어떤 일이 일어나는가"와 같은 복잡한 플로우를 문서화하는 데 유용합니다.

C4 모델 vs. 다른 접근법

C4 vs. UML

UML은 14가지 다이어그램 유형을 정의합니다. 대부분의 팀은 2-3가지를 사용하며, 종종 일관성 없이 사용합니다. C4는 명확한 목적을 가진 4가지 레벨을 제공합니다. 배우기 쉽고, 사용하기 쉽고, 유지보수하기 쉽습니다.

그렇다고 C4와 UML이 상호 배타적인 것은 아닙니다. 레벨 4에서 UML 클래스 다이어그램을 사용하거나, UML 시퀀스 다이어그램을 동적 다이어그램으로 사용할 수 있습니다. C4는 계층을 제공하고, UML은 필요할 때 특정 표기법을 제공합니다.

C4 vs. Arc42

Arc42는 아키텍처 문서를 위한 템플릿입니다. 단순한 다이어그램 이상의 것을 다룹니다: 품질 요구사항, 제약 조건, 리스크, 배포 뷰 등. C4는 구체적으로 계층적 다이어그램에 초점을 맞춥니다. 많은 팀이 둘 다 사용합니다: Arc42를 문서 구조로, C4를 그 안에서의 다이어그래밍 접근법으로.

C4 vs. "그냥 화이트보드를 사용하자"

화이트보드는 탐색과 브레인스토밍에 좋습니다. 문서로서는 끔찍합니다. 화이트보드 다이어그램은 지워지고, 사진이 잘못 찍히며, 업데이트되지 않습니다. C4는 화이트보드 탐색을 지속적인 문서로 전환하는 구조를 제공합니다.

C4 도입 시 흔한 실수

모든 것을 한 번에 보여주려 하기

C4의 핵심은 점진적 공개입니다. 컨테이너 다이어그램에 개별 클래스가 표시되면 계층을 축소한 것입니다. 각 다이어그램은 하나의 확대/축소 수준에서만 요소를 보여야 합니다.

관계 무시하기

화살표 없는 상자는 아키텍처가 아니라 인벤토리입니다. 관계 -- 누가 누구를 호출하는지, 어떤 프로토콜을 사용하는지, 어떤 데이터가 흐르는지 -- 가 종종 상자 자체보다 더 가치 있습니다. 항상 관계에 레이블을 붙이세요.

한 사람만의 활동으로 만들기

아키텍처 문서화는 팀 스포츠입니다. 한 사람만 다이어그램을 만들고 유지보수하면, 그 한 사람의 이해(또는 오해)를 반영합니다. 아키텍처 리뷰 프로세스의 일부로 C4 다이어그램을 팀으로 검토하세요.

다른 문서에 연결하지 않기

C4 다이어그램은 다른 아티팩트에 연결될 때 힘을 얻습니다. 컨테이너를 배포 런북에 연결하세요. 컴포넌트를 Architecture Decision Records (ADR)에 연결하세요. 외부 시스템을 API 문서에 연결하세요. 고립된 다이어그램은 연결된 것보다 가치가 낮습니다.

다이어그램을 방치하기

모든 문서 접근법의 가장 큰 적은 진부화입니다. 작년 아키텍처를 설명하는 다이어그램은 없는 것보다 나쁩니다. 적극적으로 오도하기 때문입니다. 다이어그램 업데이트를 워크플로에 포함시키세요 -- 풀 리퀘스트 체크리스트, 스프린트 리뷰 또는 아키텍처 회의의 일부로 만드세요.

Archyl에서 C4 모델 구현하기

Archyl은 C4 모델을 핵심 개념으로 하여 구축되었습니다. 각 레벨이 플랫폼의 기능에 어떻게 매핑되는지 소개합니다:

Archyl의 시스템 컨텍스트

Archyl에서 프로젝트를 만들면 시스템과 외부 액터와의 관계를 정의합니다. 시스템 컨텍스트 뷰는 모델에서 자동으로 렌더링됩니다 -- 수동 드로잉이 필요 없습니다. 시스템을 추가하고, 외부 액터를 추가하고, 관계를 그리면 다이어그램이 실시간으로 업데이트됩니다.

Archyl의 컨테이너 다이어그램

각 시스템 내에서 기술 스택과 함께 컨테이너를 정의합니다. Archyl은 컨테이너 다이어그램을 렌더링하고 모든 컨테이너를 드릴다운하여 컴포넌트를 볼 수 있게 합니다. 컨테이너 간의 관계는 통신 프로토콜과 데이터 플로우를 보여줍니다.

Archyl의 컴포넌트 다이어그램

각 컨테이너 내에서 컴포넌트를 정의합니다. Archyl은 Code Elements 기능을 통해 이를 실제 코드에 매핑하여, 컴포넌트를 리포지토리의 특정 파일과 디렉토리에 연결합니다. 다이어그램과 코드 사이의 이 연결이 드리프트 감지를 가능하게 합니다.

AI 기반 디스커버리

Archyl을 드로잉 도구와 차별화하는 것은 모델을 수동으로 구축할 필요가 없다는 것입니다. 리포지토리를 연결하고, AI 디스커버리를 실행하면, Archyl이 코드베이스에서 초안 C4 모델을 생성합니다. AI는 코드 구조, 구성 파일 및 종속성 그래프를 분석하여 시스템, 컨테이너, 컴포넌트 및 관계를 식별합니다.

제안을 검토하고 수락하거나 수정하면 몇 주가 아닌 몇 분 만에 C4 모델을 갖게 됩니다.

드리프트 감지

C4 모델이 존재하면, Archyl은 지속적으로 현실을 반영하는지 확인합니다. 드리프트 점수는 문서화된 아키텍처의 몇 퍼센트가 실제로 코드베이스에 존재하는지 알려줍니다. 누군가 서비스 이름을 바꾸거나 컴포넌트를 삭제하면 드리프트 점수가 떨어지고, 문서를 업데이트해야 한다는 것을 알 수 있습니다.

이것이 대부분의 C4 도구가 놓치는 갭입니다. 다이어그램을 만드는 것은 쉬운 부분입니다. 정확하게 유지하는 것이 어려운 부분입니다. Archyl의 드리프트 감지가 그 갭을 메웁니다.

C4 시작하기: 단계별 접근법

팀이 C4 모델을 처음 접한다면, 실용적인 도입 경로는 다음과 같습니다:

1주차: 시스템 컨텍스트

1시간짜리 워크숍을 위해 팀을 모으세요. 시스템을 하나의 상자로 그리세요. 모든 사용자 역할과 외부 시스템을 식별하세요. 관계를 그리세요. 이 간단한 연습이 얼마나 많은 토론을 이끌어내고 얼마나 많은 정렬을 만드는지 놀랄 것입니다.

2주차: 컨테이너 다이어그램

컨텍스트 다이어그램의 시스템 상자를 가져와 컨테이너로 분해하세요. 배포 가능한 단위는 무엇인가? 어떤 데이터베이스가 있는가? 어떤 메시지 브로커나 캐시가 사용되는가? 여기서 기술 선택을 가시화합니다.

3-4주차: 주요 컨테이너의 컴포넌트 다이어그램

가장 복잡한 2~3개의 컨테이너를 선택하세요. 각각을 컴포넌트로 분해하세요. 새 개발자가 가장 많은 시간을 보내는 곳이므로, 이해하기 가장 어려운 컨테이너를 우선으로 하세요.

지속: 유지보수 및 진화

초기 생성은 쉬운 부분입니다. 다이어그램을 업데이트된 상태로 유지하는 규율이 C4에서 가치를 얻는 팀과 한 달 후 포기하는 팀을 구분합니다. 가능한 것을 자동화하세요. 드리프트를 감지하는 도구를 사용하세요. 다이어그램 리뷰를 개발 워크플로의 일부로 만드세요.

C4가 작동하는 이유

C4 모델은 기술적으로 혁신적이지 않습니다. 계층적 분해와 추상화 수준은 1960년대부터 컴퓨터 과학에 존재했습니다. Simon Brown이 한 것은 이러한 아이디어를 명확한 규칙과 최소한의 표기법을 가진 간단하고 기억에 남는 프레임워크로 패키징한 것입니다.

작동하는 이유:

  • 배우기 쉽습니다. 네 가지 레벨. 상자와 화살표. UML 인증 불필요.
  • 확장됩니다. 주말 프로젝트부터 엔터프라이즈 플랫폼까지, 동일한 네 가지 레벨이 적용됩니다.
  • 여러 대상을 지원합니다. 경영진, 아키텍트, 개발자 각각이 자신의 언어로 말하는 다이어그램을 얻습니다.
  • 도구에 구애받지 않습니다. 화이트보드, 드로잉 도구, 텍스트 기반 형식 또는 Archyl과 같은 전용 플랫폼을 사용할 수 있습니다.
  • 올바른 것에 집중합니다. 구현 세부 사항이 아닌 구조와 관계.

팀의 아키텍처 문서가 오래된 Visio 파일, Slack의 화이트보드 사진, 부족 지식으로 구성되어 있다면, C4 모델이 더 나은 것을 향한 가장 실용적인 경로입니다.

C4 모델을 구축할 준비가 되셨나요? Archyl을 무료로 시도하고 몇 분 만에 코드에서 첫 번째 아키텍처 다이어그램을 생성하세요. 또는 더 알아보기: AI 기반 아키텍처 디스커버리 | Architecture as Code: YAML로 C4 모델 정의하기 | 아키텍처 드리프트 점수.