소프트웨어 아키텍처에서 사용자 플로우 문서화하기

버그 리포트는 간단해 보였습니다: "결제가 간헐적으로 실패합니다."

아름다운 아키텍처 다이어그램이 있었습니다. 모든 서비스, 모든 데이터베이스, 모든 통합을 보여주는 C4 다이어그램. 하지만 "장바구니에 추가"부터 "주문 확인"까지 사용자의 여정을 추적하려 할 때 정확한 순서에 대해 아무도 동의할 수 없었습니다. 어떤 서비스가 관련되어 있는가? 어떤 순서로? 재고 확인은 결제 전에 일어나는가 후에 일어나는가?

세 명의 엔지니어가 세 가지 다른 멘탈 모델을 가지고 있었습니다. 정적 아키텍처 다이어그램은 구조를 보여주었지만 동작은 보여주지 않았습니다.

그때 사용자 플로우가 필요하다는 것을 깨달았습니다.

사용자 플로우란 무엇인가

사용자 플로우는 사용자가 목표를 달성하기 위해 시스템을 통해 이동하는 여정을 문서화합니다. 정적 구조가 아니라(그것은 C4 다이어그램의 역할) 동적 순서입니다.

구조와 동작 사이의 격차

C4 컨테이너 다이어그램은 컴포넌트가 존재하고 어떻게 연결되는지 알려줍니다. 하지만 답하지 않습니다: 사용자가 결제할 때 먼저 무엇이 일어나는가?

이런 질문에는 구조가 아닌 플로우의 이해가 필요합니다.

유용한 사용자 플로우의 구조

1. 목표 선언

사용자가 달성하려는 것으로 시작합니다.

2. 전제 조건

이 플로우가 시작되기 전에 무엇이 참이어야 하는가?

3. 정상 경로

예상되는 성공 경로를 먼저 문서화하고, 사용자가 하는 것과 시스템이 응답하는 것을 포함합니다.

4. 오류 경로와 엣지 케이스

정상 경로는 시작일 뿐입니다. 진정한 가치는 문제가 발생했을 때 무엇이 일어나는지 문서화하는 데서 옵니다.

5. 기술 노트

관련 기술적 맥락을 추가합니다.

플로우를 아키텍처에 연결

Archyl에서 플로우의 각 단계에 관련된 컴포넌트를 주석할 수 있습니다. 이것은 양방향 추적성을 만듭니다:

• 플로우를 보고 있나요? 어떤 컴포넌트를 터치하는지 보세요.
• 컴포넌트를 보고 있나요? 어떤 플로우가 통과하는지 보세요.

다양한 유형의 플로우

사용자 플로우

UI에서 사용자가 시작하는 시퀀스.

시스템 플로우

머신이 시작하는 시퀀스.

통합 플로우

시스템 간 시퀀스.

흔한 실수

실수 1: 너무 많은 디테일

플로우 문서는 코드처럼 읽혀서는 안 됩니다.

실수 2: 정상 경로만 문서화

오류 경로에 버그가 숨어 있습니다.

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

현실과 일치하지 않는 문서화된 플로우는 문서가 없는 것보다 나쁩니다.

실수 4: 플로우를 정적으로 취급

사용자 플로우는 진화합니다. 살아있는 문서로 취급하세요.

결론

정적 아키텍처 다이어그램은 시스템이 무엇으로 구성되어 있는지 알려줍니다. 사용자 플로우는 어떻게 동작하는지 알려줍니다. 둘 다 필요합니다.

다음에 여러 서비스에 걸친 복잡한 문제를 디버깅할 때, 스스로에게 물어보세요: "이에 대한 문서화된 플로우가 있는가?" 답이 아니오라면, 조각이 어떻게 맞춰지는지 재구성하는 데 몇 시간을 보낼 것입니다.

가장 중요한 플로우부터 시작하세요.

아키텍처 문서에 대해 더 알아보기: C4 모델 소개 | 아키텍처 결정 기록 | 왜 문서화가 중요한가