소프트웨어 아키텍처 101

소프트웨어 아키텍처 101, 한빛미디어

신규 시스템의 개발을 준비하면서 설계 과정을 어떻게 체계적으로 정리하고 문서화할 수 있을지 고민하고 있습니다.

설계 과정을 빠짐없이 기록으로 남기는 것은 현실적으로 불가능합니다. 또한, 대부분의 개발자들은 문서화를 부담스럽게 느낍니다.

그렇다고 기록을 남기지 않는다면, 나중에는 “왜 이렇게 설계했는가?”라는 질문에 답하기 어려워질 것입니다.

담당자가 교체되거나 시스템의 운영을 다른 조직에 이관해야 하는 상황이 발생한다고 가정해 봅시다. 문서 없이 시스템의 설계 의도를 전달할 수 있을까요?

특히 설계는 한 번에 완성되는 것이 아니라 점진적으로 진화합니다. 이 과정에서 결정의 근거가 사라지는 순간 아키텍처는 더 이상 의도된 구조가 아닌 우연의 결과가 됩니다.

1. ADR이란?

그래서 저는 최소한의 문서 작업으로 설계 의도를 남길 수 있는 방법을 찾고 있었습니다.

그러던 중 우연히 소프트웨어 아키텍처 101에서 아키텍처 결정 레코드(Architecture Decision Record, 이하 ADR)라는 개념을 접하게 되었습니다.

이것이 바로 제가 찾고 있던 문서화 방식이라는 생각이 들었습니다.

ADR은 말 그대로 아키텍처적 의사결정을 기록하는 문서입니다. 여기서 중요한 점은 “설계(Design)”가 아니라 “결정(Decision)” 자체를 기록한다는 것입니다.

예를 들어 다음과 같은 것들입니다.

  • 왜 우리 서비스는 마이크로서비스 대신 서비스 기반 아키텍처를 선택했는가?
  • 왜 메시징 시스템으로 Kafka를 사용하기로 했는가?
  • 왜 JWT 기반 인증 전략을 채택했는가?
  • 왜 컬럼 암호화는 JPA AttributeConverter 방식으로 구현했는가?

이러한 선택들은 시간이 지나면 자연스럽게 잊히게 됩니다. 하지만 시스템의 구조를 제대로 이해하기 위해 반드시 필요한 정보입니다.

2. ADR은 어떻게 작성할까?

ADR에는 다음과 같은 정보들이 기록됩니다.

  • 어떤 배경에서 결정이 내려졌는가?
  • 어떤 대안이 검토되었는가?
  • 어떤 트레이드오프가 존재하는가?

ADR은 복잡한 문서가 아닙니다. 하나의 아키텍처 결정마다 하나의 문서로 작성하면 됩니다.

중요한 것은 문서의 분량이 아니라 결정의 맥락과 이유를 명확하게 기록하는 것입니다.

『소프트웨어 아키텍처 101』에서는 ADR의 기본 구조를 다음과 같이 설명하고 있습니다.

목차 내용
제목 아키텍처의 결정을 간략하게 기재
상태 제안됨, 수락됨, 대체됨
콘텍스트 왜 이렇게 결정할 수 밖에 없었나?
결정 그렇게 결정한 합당한 사유
결과 이 결정이 어떤 영향을 끼쳤는가?
컴플라이언스 이 결정의 컴플라이언스를 어떻게 보장할 것인가?
노트 이 결정에 관한 메타데이터(결정한 사람 등)

메시징 시스템으로 Kafka를 채택하는 결정을 가정하고, 작성해본 ADR 예시는 다음과 같습니다.

3. ADR 작성 예시

# ADR-0001: 메시징 시스템으로 Kafka 채택

## 상태
Accepted

## 컨텍스트
서비스 간 비동기 통신과 이벤트 기반 처리를 위해 메시징 시스템이 필요하다.

현재 고려 가능한 후보는 다음과 같다.

- RabbitMQ
- Redis Stream
- Kafka

RabbitMQ는 안정적인 메시지 큐 기능을 제공하지만 대규모 이벤트 스트리밍 처리에는 한계가 있다.

Redis Stream은 운영이 단순하지만 장기 이벤트 로그 보존에는 적합하지 않다.

서비스 간 이벤트 기반 아키텍처를 구축하기 위해서는 높은 처리량과 이벤트 로그 보존 기능이 필요하다.

## 결정
서비스 간 이벤트 전달을 위한 메시징 시스템으로 Apache Kafka를 채택한다.

Kafka는 높은 처리량과 확장성을 제공하며, 이벤트 로그를 장기간 보존할 수 있어 이벤트 기반 아키텍처에 적합하다.

## 결과

### 장점
- 높은 메시지 처리량
- 이벤트 로그 보존 가능
- 스트림 처리 확장성

### 단점
- 운영 복잡도 증가
- 초기 인프라 구축 비용 증가

## 컴플라이언스
Kafka 사용 시 다음 운영 정책을 준수한다.

- 토픽 네이밍 규칙 정의
- 메시지 보존 기간 정책 설정
- 메시지 스키마 관리 체계 적용

## 노트
Kafka는 초기 도입 비용이 존재하므로
운영 환경 구축 시 운영팀과 협업이 필요하다.

향후 이벤트 스트림 처리 기능을 활용하기 위해
Kafka Streams 또는 Flink 도입 가능성을 검토한다.

3. ADR은 어디에 저장하는 것이 좋을까?

ADR를 작성하고 보관할 수 있는 장소는 다양합니다.

대표적인 보관 장소는 다음과 같습니다.

  • Git 저장소
  • Jira
  • 사내 위키

3.1. Git 저장소

ADR 문서를 개발자에게 익숙한 마크다운으로 작성해서 Git 저장소에 관리하는 개발 조직도 있습니다.

repo-root
 └ docs
     └ adr
         ├ 0001-architecture-style.md
         ├ 0002-messaging-system.md
         └ 0003-authentication-strategy.md

Git 저장소에 ADR을 관리하는 경우 장점은 다음과 같습니다.

  • 코드와 함께 버전 관리 가능
  • Pull Request 기반 리뷰 가능
  • 개발자 친화적

하지만 여러 저장소에 문서가 분산될 수 있고, 개발팀이 아닌 다른 팀에서의 접근성이 낮은 단점이 있습니다.

3.2. Jira

ADR 문서를 Jira에 관리하면 의사결정 과정과 토론 기록을 함께 남길 수 있다는 장점이 있습니다.

하지만 Jira는 기본적으로 업무 관리 도구이기 때문에 장기적인 지식 관리 관점에서는 다소 불편할 수 있습니다.

3.3. 사내 위키

여러 요소를 종합적으로 고려했을 때 저는 사내 위키가 가장 적합한 저장소라고 판단하고 있습니다.

그 이유는 다음과 같습니다.

  • 조직 전체가 접근 가능
  • 서비스 단위로 문서를 중앙 관리할 수 있음
  • 운영 조직과의 협업에 유리
  • 장기 보관에 적합

특히 ADR 문서가 특정 Git 저장소에 묶여 있기보다는 서비스 단위의 지식 자산으로 관리되는 것이 더 적절한 것 같습니다.

4. 마무리

ADR은 “왜 이런 아키텍처를 선택했는가?”라는 질문에 답을 할 수 있게 해주는 문서입니다.

결국 아키텍처는 수많은 설계 판단이 쌓여 만들어진 결과입니다.

모든 설계 결정을 기록할 수는 없지만, 시스템의 구조에 영향을 주는 중요한 결정만큼은 기록으로 남길 필요가 있습니다.

ADR은 그 판단을 남기는 가장 단순하면서도 효과적인 방법입니다.

5. 포스팅 시리즈

#소프트웨어아키텍처101 #한빛미디어 #소프트웨어 #아키텍처 #ADR