AA 문서에 반드시 있어야 하는 그림 3장

 

AA 문서에 반드시 있어야 하는 그림 3장

— 코드보다 오래 살아남는 설계의 흔적들

아키텍처 문서에서 텍스트는 쉽게 잊힌다.
하지만 그림은 팀의 뇌에 남는다.

AA(Application Architecture)를 설계할 때
“그림 없이도 설명 가능하다”는 말은 대개 착각이다.
사람은 구조를 문장으로 이해하지 않는다. 공간으로 이해한다.

그래서 AA 문서에는 반드시 들어가야 하는 그림이 딱 3장 있다.
이 3장이 있으면, 나머지 설명은 따라온다.

---

1️⃣ 시스템 책임 경계 다이어그램

(System Boundary Diagram)

첫 번째 그림은 가장 단순해야 한다.
그리고 가장 중요하다.

이 그림의 목적은 하나다.

“이 시스템이 어디까지 책임지는지”를 한 눈에 보여준다

 

 

이 그림에 반드시 있어야 할 것

• 우리 시스템 (굵은 박스)
• 외부 시스템 (얇은 박스)
• 책임이 오가는 방향 (화살표)
• 우리가 하지 않는 것

실무에서 이 그림이 없으면 이런 일이 벌어진다:

• “이건 우리 쪽에서 처리하는 거 아니었나요?”
• “그거 PG에서 해주는 줄 알았는데요?”
• “왜 여기서 재고 차감이 돼요?”

AA는 코드 설계가 아니라 책임 설계다.
이 그림이 AA의 출발점이다.

---

2️⃣ 레이어 의존성 다이어그램

(Layered Dependency Diagram)

두 번째 그림은 “질서”를 보여준다.

어떤 코드가 어떤 코드를 알아도 되는가

 

 

이 그림이 말해주는 것

• 레이어 목록
  • Presentation
  • Application
  • Domain
  • Infrastructure
• 의존 방향은 단방향
• 화살표는 반드시 “아래로만”

여기서 핵심은 기술이 아니다.
권한이다.

• Controller는 비즈니스를 몰라도 된다
• Domain은 DB를 몰라도 된다
• Infrastructure는 규칙을 가지면 안 된다

이 그림이 없으면:

• Service가 Controller 호출
• Entity가 JSON 응답으로 노출
• Repository에 비즈니스 로직 등장

즉, 무질서가 시작된다.

---

3️⃣ 유스케이스 흐름 다이어그램

(Use Case Flow / Sequence)

세 번째 그림은 실행의 시간축이다.

“요청 하나가 들어와서, 어디를 거쳐, 무엇을 바꾸고, 어떻게 끝나는가”

이 그림이 반드시 담아야 할 질문들

• 트랜잭션은 어디서 시작되는가
• 상태 변경은 어디서 일어나는가
• 예외는 어디서 던지고 어디서 변환되는가
• 외부 호출은 동기인가 비동기인가

이 그림이 없는 시스템은
“동작은 하지만 설명은 안 되는” 시스템이 된다.

그리고 그런 시스템은:

• 유지보수가 어렵고
• 장애 분석이 늦고
• 신규 인원이 오면 속도가 급감한다

---

왜 하필 이 3장이냐

이유는 명확하다.

그림답해주는 질문

책임 경계	우리는 무엇을 책임지는가
레이어 구조	누가 누구를 의존하는가
흐름 다이어그램	실제로 어떻게 실행되는가

이 셋을 합치면:

정적 구조 + 동적 실행 + 책임 범위

AA의 핵심 90%가 설명된다.

---

실무 팁 하나 (중요)

이 3장은 디자인 툴로 예쁘게 그릴 필요 없다.

• 파워포인트
• 화이트보드
• draw.io
• 심지어 종이 사진

중요한 건 미학이 아니라 합의다.

팀원 전원이
“아, 이 시스템은 이렇게 생겼구나”
라고 같은 그림을 떠올릴 수 있으면 성공이다.