혼란스러운 아키텍처 다이어그램을 수년간 그린 후, C4 모델을 발견했습니다. 이것이 우리 팀의 시스템 커뮤니케이션 방식을 어떻게 바꿨는지 설명합니다.

소프트웨어 아키텍처를 위한 C4 모델 소개

아키텍처 다이어그램에 대한 모든 것을 다시 생각하게 만든 화이트보드 세션을 아직도 기억합니다. 새로운 개발자를 온보딩하는 중이었고, 45분 동안 상자와 화살표를 그리며 전자상거래 플랫폼을 설명하려 했습니다. 끝날 때 그녀는 시작할 때보다 더 혼란스러워 보였습니다. 다이어그램에는 모든 것이 있었습니다 — 마이크로서비스, 데이터베이스, 메시지 큐, 외부 API — 일관성 없는 표기법과 명확한 계층 구조 없이 모두 뒤섞여 있었습니다.

그날 저녁 Simon Brown의 C4 모델을 발견했고, "왜 이걸 생각하지 못했을까?" 하는 순간이었습니다. 아이디어는 믿기 어려울 만큼 간단합니다: 모든 것을 하나의 다이어그램에 넣는 대신, 다른 확대/축소 수준에서 여러 다이어그램을 만듭니다. Google Maps처럼 큰 그림을 보기 위해 축소된 상태에서 시작하여 점진적으로 확대하여 더 많은 세부 사항을 봅니다.

C4의 네 가지 레벨

"C4"는 각각 다른 질문에 답하는 네 가지 추상화 수준을 나타냅니다:

레벨 1: 시스템 컨텍스트

이것은 30,000피트 높이의 뷰입니다. 전체 시스템이 하나의 상자이며, 다음을 보여줍니다:

시스템을 사용하는 사람 (사람 또는 역할)
통합하는 외부 시스템

그게 전부입니다. 내부 세부 사항 없음, 기술 선택 없음, 데이터베이스 없음. 단지 "여기 우리 시스템이 있고, 누가 사용하며, 무엇과 통신하는지"입니다.

처음으로 우리 플랫폼의 시스템 컨텍스트 다이어그램을 그렸을 때, 슬라이드 하나에 들어갔습니다. CEO가 이해할 수 있었습니다. 내 아키텍처 다이어그램에서 이전에는 한 번도 일어나지 않았던 일입니다.

이 레벨을 강력하게 만드는 것: 경계에 대해 생각하도록 강제합니다. 시스템 안에 있는 것과 밖에 있는 것은? 소유하는 것과 의존하는 것은? 이 질문들은 당연해 보이지만, 팀들이 명확하게 답하는 데 어려움을 겪는 것을 봐왔습니다.

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

이제 한 단계 확대합니다. C4 용어에서 "컨테이너"는 Docker 컨테이너가 아닙니다 — 코드를 실행하거나 데이터를 저장하는 모든 배포 가능한 단위입니다:

웹 애플리케이션
모바일 앱
백엔드 서비스
데이터베이스
메시지 큐
파일 스토리지

이 다이어그램은 상위 수준의 기술 아키텍처를 보여줍니다. 주요 기술 선택(React 프론트엔드, Go 백엔드, PostgreSQL 데이터베이스)과 데이터가 어떻게 흐르는지 볼 수 있습니다.

이 레벨이 가장 유용한 경우:

인프라 및 배포 계획
팀과 기술 선택 논의
새로운 백엔드 또는 프론트엔드 개발자에게 시스템 설명

배운 점 하나: 여기서 세분화에 주의하세요. 마이크로서비스가 30개라면 30개를 모두 별도 컨테이너로 표시하지 마세요. 관련 서비스를 그룹화하거나 시스템의 다른 영역에 대해 여러 컨테이너 다이어그램을 만드세요.

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

여기서 단일 컨테이너로 확대합니다. 컴포넌트는 해당 컨테이너 내부의 주요 구조적 빌딩 블록입니다 — 서비스, 리포지토리, 컨트롤러 또는 모듈로 생각하세요.

Go 백엔드의 경우, 컴포넌트 다이어그램은 다음을 보여줄 수 있습니다:

HTTP 핸들러
비즈니스 로직 서비스
리포지토리 인터페이스
외부 API 클라이언트

솔직히 말하면: 모든 컨테이너에 대해 컴포넌트 다이어그램을 만들지 않습니다. 새 개발자가 이해하기 어려운 복잡한 것만 합니다. 단순한 CRUD 서비스의 경우, 코드 자체가 문서입니다.

레벨 4: 코드 다이어그램

가장 깊은 레벨은 실제 코드 요소를 보여줍니다 — 클래스, 인터페이스, 함수. Simon Brown 본인도 이 레벨은 선택 사항이며 종종 코드에서 자동 생성된다고 말합니다.

실제로 코드 다이어그램을 수동으로 만드는 경우는 드뭅니다. 만들 때는 시각적 설명이 도움이 되는 특히 복잡한 알고리즘이나 패턴을 위해서입니다. 대부분의 경우, 이 수준의 세부 사항이 필요하다면 실제 코드를 읽어야 합니다.

C4가 우리 팀에 맞았던 이유

C4 이전에 우리의 아키텍처 문서는 엉망이었습니다. 우리에게는:

아무도 업데이트하지 않는 2019년 Visio 다이어그램
임의의 Slack 채널에 있는 화이트보드 사진
뭔가를 설명하는 ASCII 아트가 있는 README 파일
사람들이 떠날 때 함께 사라지는 부족 지식

C4 모델은 실제로 작동하는 프레임워크를 우리에게 제공했습니다. 그 이유는 다음과 같습니다:

기억하기에 충분히 간단합니다

네 가지 레벨. 그게 전부입니다. 14가지 다른 UML 다이어그램 유형을 외우거나 무언가가 UML 의미에서 "컴포넌트"인지 "모듈"인지 논쟁할 필요가 없습니다.

다른 대상, 다른 다이어그램

CEO는 시스템 컨텍스트 다이어그램을 봅니다. 아키텍트들은 컨테이너 다이어그램을 논의합니다. 개발자들은 컴포넌트 다이어그램으로 작업합니다. 모든 사람이 자신의 필요에 맞는 적절한 수준의 세부 사항을 얻습니다.

도구에 구애받지 않습니다

draw.io로 시작하여, 협업을 위해 Miro로 옮겼고, 이제 AI 지원 다이어그래밍을 위해 Archyl을 사용합니다. C4 모델은 개념에 관한 것이지 표기법에 관한 것이 아니기 때문에 어떤 도구와도 작동합니다.

제가 저지른 흔한 실수들 (여러분은 하지 않도록)

실수 1: 너무 일찍 너무 많은 세부 사항을 보여주기

첫 번째 컨테이너 다이어그램에는 47개의 상자가 있었습니다. 정확했지만 쓸모없었습니다. 이제 규칙을 따릅니다: 다이어그램이 한 화면에 맞지 않으면 잘못된 확대/축소 수준에 있는 것입니다.

실수 2: 관계를 잊기

상자만 있고 화살표가 없는 다이어그램은 그냥 목록입니다. 관계 — 누가 누구를 호출하는지, 어떤 데이터가 어디로 흐르는지 — 가 종종 상자 자체보다 더 중요합니다. 화살표에 레이블을 붙이세요. 프로토콜과 데이터 형식을 설명하세요.

실수 3: 변경 후 업데이트하지 않기

최고의 다이어그램도 2년 전 시스템을 설명하면 쓸모없습니다. 아키텍처 변경에 대한 PR 체크리스트의 일부로 다이어그램 업데이트를 포함시켜 이 문제를 해결했습니다. 완벽하지는 않지만 도움이 됩니다.

실수 4: 표기법 과잉 설계

C4 다이어그램을 위한 커스텀 아이콘과 색상 체계를 설계하는 데 일주일을 보냈습니다. 완전한 시간 낭비였습니다. 명확한 레이블이 있는 간단한 상자가 잘 작동합니다. 미학이 아닌 콘텐츠에 집중하세요.

시작하기

C4가 처음이라면, 이렇게 제안합니다:

시스템 컨텍스트부터 시작하세요. 30분을 투자하여 시스템을 하나의 상자로 그리고, 사용자와 외부 시스템으로 둘러싸세요. 이것만으로도 가치가 있습니다.
컨테이너 다이어그램 하나를 추가하세요. 가장 복잡한 시스템을 선택하고 배포 가능한 단위로 분해하세요. 어떻게 통신하는지 보여주세요.
일단 거기서 멈추세요. 한 번에 모든 것을 문서화하려 하지 마세요. 더 많은 시간을 투자하기 전에 다이어그램이 그 가치를 증명하게 하세요.
협업적으로 만드세요. 팀과 다이어그램을 공유하세요. 피드백을 받으세요. 아키텍처 문서화는 혼자 하는 활동이 아닙니다.

Archyl에서 C4를 사용하는 방법

Archyl을 만들면서, 당연히 우리 자신의 제품을 사용합니다. 우리의 아키텍처 문서는 전체적으로 C4를 사용합니다:

시스템 컨텍스트 다이어그램은 Archyl이 다양한 Git 제공자, AI 서비스, 결제 시스템에 연결되는 것을 보여줍니다
컨테이너 다이어그램은 Go 백엔드와 React 프론트엔드를 분해합니다
컴포넌트 다이어그램은 디스커버리 서비스와 다이어그램 렌더링 엔진을 상세히 보여줍니다

강력한 점은 이러한 다이어그램을 다른 문서에 연결하는 것입니다. PostgreSQL 대신 MongoDB를 선택한 Architecture Decision Record는 컨테이너 다이어그램의 데이터베이스 컨테이너에 직접 연결됩니다. 사용자 플로우는 통과하는 특정 컴포넌트를 참조합니다.

이 상호 연결된 문서가 우리가 Archyl에 구축하고 있는 것입니다 — 아키텍처를 고립된 다이어그램이 아닌 연결된 지식 그래프로 보는 능력.

결론

C4 모델은 개념적으로 혁명적이지 않습니다. 추상화 수준과 계층적 분해는 오래전부터 있었습니다. Simon Brown이 뛰어나게 한 것은 이러한 아이디어를 실제로 사용되는 간단하고 기억에 남는 프레임워크로 패키징한 것입니다.

아키텍처 문서가 오래된 Visio 파일과 화이트보드 사진의 혼란이라면, C4를 시도해 보세요. 시스템 컨텍스트 다이어그램 하나로 작게 시작하세요. 하나의 잘 생각된 다이어그램이 가져다주는 명확성에 놀랄 수 있습니다.

이것은 아키텍처 문서 시리즈의 일부입니다. 다음: AI가 아키텍처를 자동으로 발견하는 방법 및 문서가 생각보다 중요한 이유.

소프트웨어 아키텍처를 위한 C4 모델 소개 - Archyl Blog