시스템 아키텍처 다이어그램, 이렇게 그리면 아무도 안 읽습니다

다이어그램은 왜 항상 기대만큼 유용하지 않을까

시스템 아키텍처 다이어그램은 개발 조직에서 가장 많이 만들면서도 가장 많이 실패하는 문서 중 하나입니다. 온보딩 문서에 넣어두고, 기술 리뷰 미팅에서 꺼내 보여주고, README에 첨부하지만, 정작 그 다이어그램을 보고 시스템을 제대로 이해한 사람이 몇이나 되는지 돌아보면 회의적일 때가 많습니다.

다이어그램 도구 Ilograph의 블로그에서 시스템 아키텍처 다이어그램을 그릴 때 흔히 저지르는 실수들을 정리한 글이 공개되었습니다. 이 글은 이전 시리즈의 후속편으로, 실무에서 반복적으로 나타나는 패턴들을 구체적으로 짚고 있어 아키텍처 문서화에 관심 있는 개발자라면 참고할 만합니다.

실수 1: 하나의 다이어그램에 모든 것을 담으려 한다

가장 흔하고 가장 치명적인 실수입니다. 시스템의 전체 구조를 단 하나의 다이어그램에 표현하려는 시도는 거의 항상 실패합니다. 마이크로서비스 아키텍처를 예로 들어보겠습니다. 10개 이상의 서비스, 메시지 큐, 데이터베이스, 외부 API, CDN, 로드밸런서를 모두 하나의 다이어그램에 넣으면 어떻게 될까요? 선이 엉키고, 박스가 겹치고, 결국 "스파게티 다이어그램"이 완성됩니다.

해결 방법은 관점(viewpoint)별로 다이어그램을 분리하는 것입니다. C4 모델이 좋은 프레임워크를 제공합니다. C4 모델은 시스템을 Context(전체 맥락), Container(컨테이너/서비스), Component(컴포넌트), Code(코드) 네 가지 추상화 수준으로 나누어 표현합니다. 각 수준의 다이어그램은 해당 수준의 질문에만 답합니다. "이 시스템이 외부와 어떻게 연동되는가"는 Context 다이어그램에서, "내부 서비스 간 통신은 어떻게 되는가"는 Container 다이어그램에서 다루는 식입니다.

실수 2: 화살표의 의미가 불분명하다

다이어그램에서 두 요소 사이에 화살표를 그리는 것은 가장 기본적인 행위이지만, 그 화살표가 무엇을 의미하는지 명확하지 않은 경우가 놀라울 정도로 많습니다. A에서 B로 향하는 화살표는 "A가 B를 호출한다"는 뜻일까요, "데이터가 A에서 B로 흐른다"는 뜻일까요, 아니면 "A가 B에 의존한다"는 뜻일까요?

이 세 가지는 완전히 다른 의미입니다. API 호출의 경우 요청은 A에서 B로 가지만 응답 데이터는 B에서 A로 돌아옵니다. 호출 방향과 데이터 흐름 방향이 반대인 셈입니다. 화살표 하나로 이 두 가지를 동시에 표현하려 하면 혼란이 발생합니다.

해결 방법은 간단합니다. 다이어그램에 범례(legend)를 추가하고, 화살표의 의미를 명시하는 것입니다. "실선 화살표 = 동기 호출, 점선 화살표 = 비동기 메시지, 두꺼운 화살표 = 대용량 데이터 흐름" 같은 식으로 규칙을 정하면 다이어그램의 가독성이 크게 향상됩니다.

실수 3: 기술 스택만 나열하고 역할을 설명하지 않는다

"PostgreSQL", "Redis", "Kafka", "nginx" 같은 기술 이름만 박스 안에 적어놓은 다이어그램을 자주 봅니다. 이런 다이어그램은 해당 시스템에 어떤 기술이 사용되는지는 알려주지만, 각 컴포넌트가 어떤 역할을 하는지는 알려주지 않습니다.

"PostgreSQL"이라고만 적힌 박스를 보면, 이것이 사용자 데이터를 저장하는 것인지, 주문 이력을 저장하는 것인지, 세션 정보를 저장하는 것인지 알 수 없습니다. "사용자 프로필 DB (PostgreSQL)"이라고 적으면 기술 스택과 역할을 동시에 전달할 수 있습니다. 다이어그램의 목적은 시스템의 구조와 동작 방식을 설명하는 것이지, 기술 선택지를 나열하는 것이 아닙니다.

실수 4: 다이어그램을 업데이트하지 않는다

사실 이것이 가장 근본적인 문제일 수 있습니다. 프로젝트 초기에 열심히 그린 아키텍처 다이어그램이 6개월 후에는 현실과 완전히 동떨어진 상태가 되어 있는 경우가 흔합니다. 코드는 매일 변하지만 다이어그램은 그대로이기 때문입니다.

이 문제에 대한 접근법 중 하나는 "다이어그램을 코드처럼 관리하는 것(Diagram as Code)"입니다. Mermaid, PlantUML, Structurizr 같은 도구들은 텍스트 기반으로 다이어그램을 정의하므로 Git으로 버전 관리가 가능합니다. 코드 변경과 함께 다이어그램 소스도 업데이트하는 습관을 들이면 동기화 문제를 어느 정도 완화할 수 있습니다.

한국 개발자에게 주는 시사점

한국 개발 조직에서도 아키텍처 문서화의 중요성은 점점 더 인식되고 있습니다. 특히 MSA(마이크로서비스 아키텍처) 전환이 활발히 진행되면서 시스템 간 관계를 시각적으로 표현할 필요성이 커지고 있습니다. 하지만 문서화 문화가 코드 작성 문화만큼 성숙하지 않은 조직에서는 다이어그램이 "있긴 하지만 아무도 신뢰하지 않는" 상태에 머물기 쉽습니다.

실무에서 바로 적용할 수 있는 팁을 정리하면 이렇습니다. 하나의 다이어그램은 하나의 질문에만 답하도록 범위를 좁히세요. 화살표에는 반드시 레이블을 붙이세요. 기술 이름보다 역할을 먼저 적으세요. 그리고 가능하다면 Mermaid 같은 텍스트 기반 도구를 사용해 코드 리뷰 프로세스에 다이어그램 변경도 포함시키세요.