1. 아키텍쳐를 그리기 위해 결심한 이유
약 2주 간의 개발 과정 중 의사 소통에 있어서 크게 2가지 문제점이 있었다. 온라인에서 구두로만 이야기를 하다보니 각자 다르게 이해를 한다는 점에서 커뮤니케이션 효율성이 떨어졌고, 특정 기술을 도입하기 위해 현 상황을 파악하기 위한 설명/ 도식이 없다보니 의사결정의 근거를 명확히 보여주기가 어려웠다. 따라서 로컬에서의 개발이 어느정도 마무리된 지금 시점에서, 클라우드로의 이관 전에 현 상황에 대한 확인이 필요하다고 느껴졌다.
커뮤니케이션 효율성
Booking(공연 예약)에 대한 유저 플로우와 관련 로직에서, DB 스키마의 이름이 비슷하다 보니 로직 변경을 위한 논의 중 어떤 스키마를 변경해야하는지 소통에서 오해가 자주 생겼다. 위 사진은 회의 중 이해를 쉽게 하기 위해 작성한 플로우다.
의사결정 근거에 대한 이해
OpenAPI Generator를 도입하자는 팀원의 주장이 있어서, 현재 우리의 레포지토리 상황과 변경 전/ 후 어떻게 문서를 관리하게 되는지 파악하기 위해 작성하였다. 위의 도식 없이 구두로만 이야기를 하다보니, 각자 현 상황에 대한 이해가 달라 도입 여부를 합의하기까지 시간이 오래 걸렸다.
클라우드로의 이관
앞으로 2~3일 내에 개발을 1차적으로 마무리하고 클라우드로 서비스를 옮길 예정이다. 따라서 이관 전 어떤 상황인지 확실히 파악하고, 어느 부분을 클라우드로 이관할지 결정하기 위해 아키텍쳐를 그려야 할 필요가 있다.
2. C4 모델의 선택 이유와 정의
선택 이유
아키텍쳐 모델링 방법에는 UML, Archimate 가 잘 알려져있다. 다만 우리 팀의 상황은 현재
- 복잡한 문서화 프로세스보다 신속한 의사소통을 위해 아키텍쳐를 그리는 점
- 개발을 해본 팀원과, 해보지 않았던 팀원이 섞여있는 점
- 소규모 개발팀이고, 문서 작성을 위해 학습을 따로 할 부담을 키울 수 없는 점
을 들어, 다이어그램의 유형이 많고 표기가 복잡한 UML이나 엔터프라이즈에 적합한 Archimate는 적합하지 않다고 생각했다.
C4 모델(C4 Model https://c4model.com/)은 필요에 따라 다이어그램을 변경 / 그리는 도구에 구애받지 않는 점이 가장 특징적이었고, 특정 형식에 얽매일 필요가 없어 학습 부담이 적고 직관적으로 이해가 되는 것 같아 우리팀에 가장 적합해 보였다.
정의
이 모델은 Simon Brown이 제안한 소프트웨어 아키텍처 시각화 방법론으로, 4가지 계층적 다이어그램을 통해 시스템을 표현한다.
- Context (컨텍스트): 시스템과 외부 사용자/시스템 간의 관계
- Container (컨테이너): 시스템 내부의 주요 실행 단위들
- Component (컴포넌트): 각 컨테이너 내부의 구성 요소들
- Code (코드): 구체적인 클래스나 인터페이스 수준의 상세 설계
우리 팀의 상황
로컬 환경은 다음과 같다.
- 클라이언트: 로컬 환경에서 실행되는 프론트엔드 애플리케이션
- 백엔드: REST API 서버 (로컬 개발 서버)
- 데이터베이스: 로컬 데이터베이스를 도커 컴포즈로 띄우는 중 (Redis, PostgreSQL)
정의된 모든 다이어그램을 만들 필요는 없고, 적절한 수준에서 유지하면 된다.
현재 컨테이너 다이어그램까지 작성하면 의사소통에는 크게 문제가 없을 듯 하여, 2번째 단계까지만 작성하기로 결정하였다.
예외로, Booking 플로우는 컴포넌트 다이어그램까지 그리기로 결정했다. 거의 대부분의 스키마가 얽혀있고, 앞으로 최적화를 위한 리팩토링이 예정 되어있기 때문이다.
Notation
https://c4model.com/diagrams/notation 기본적으로 C4 모델은 표기법에 구애받지 않는다. 다만 표기법에 대한 범용적인 추천 정도는 있어서 몇가지를 메모해 보았다. 또한 아키텍쳐 작성 후, 아래 5번 수정에 대한 가이드에서 체크리스트의 도움을 받을 수 있다.
나는 Excalidraw에서 유저가 만든 c4 model 라이브러리가 있어, 표기법은 해당 도식을 활용하기로 했다.
Diagram
- 제목: 다이어그램 상단에 명확한 제목 표시 (예: "System Context for 공연 예약 시스템")
- 다이어그램 키/범례: 우측 하단에 사용된 요소들의 의미를 설명하는 범례 포함
- 날짜와 버전: 작성일과 버전 정보를 기록하여 문서 이력 관리
- 간소화: 핵심 요소만 포함하고 불필요한 세부사항 제거
Elements
- Person (사람):
- 표현: 원형 또는 인물 아이콘
- 예시: 일반 사용자, 관리자, 공연 기획자
- 라벨: "사용자" + 역할 설명
- Software System (소프트웨어 시스템):
- 표현: 둥근 모서리 사각형
- 예시: "공연 예약 시스템", "결제 시스템", "알림 시스템"
- 라벨: 시스템명 + 주요 기능 요약
- Container (컨테이너):
- 표현: 사각형 박스
- 예시: "React Web App", "Spring Boot API", "PostgreSQL Database"
- 라벨: 컨테이너명 + 기술 스택 + 포트 정보
- Component (컴포넌트):
- 표현: 작은 사각형 박스
- 예시: "BookingController", "PaymentService", "UserRepository"
- 라벨: 컴포넌트명 + 주요 책임
Relationships
- 실선 화살표: 동기 호출 (HTTP Request, 직접 메소드 호출)
- 점선 화살표: 비동기 통신 (메시지 큐, 이벤트)
- 양방향 화살표: 상호 작용이 빈번한 관계
- 라벨 표기:
- 프로토콜 정보: "HTTPS", "WebSocket", "TCP"
- 데이터 형식: "JSON", "GraphQL", "SQL"
- 포트 번호: ":3000", ":8080", ":5432"
Colors
- 파란색: 우리가 개발하는 시스템 (Internal System)
- 회색: 외부 시스템 또는 서드파티 (External System)
- 초록색: 사용자 또는 액터 (Person/Actor)
- 주황색: 데이터 저장소 (Database, Cache)
- 연한 색조: 배경이나 그룹핑에 사용
4. 실적용
- 그리기 도구 : Excalidraw
System Context Diagram
Container Diagram
Component Diagram
- booking 추가
- redis 관련 대기열 큐
5. 앞으로 예정된 추가 및 수정에 대한 가이드
추가 : Deployment Diagram
https://c4model.com/diagrams/deployment
클라우드 이관 시 작성 예정 요소들:
- Production Environment
- Load Balancer: AWS ALB 또는 CloudFlare
- Container Orchestration: AWS ECS 또는 Kubernetes
- File Storage: AWS S3 (공연 이미지, 문서)
- 네트워크 및 보안
- VPC, Security Groups 구성
- SSL/TLS 인증서 (Let's Encrypt 또는 AWS Certificate Manager)
- API Gateway 및 Rate Limiting
- 모니터링 및 로깅
- AWS CloudWatch 또는 Prometheus + Grafana
- ELK Stack (Elasticsearch, Logstash, Kibana)
수정 후 확인 체크 리스트
https://c4model.com/diagrams/checklist
정기 업데이트 가이드
- 새로운 기능 추가 시: 관련 컴포넌트 및 관계 업데이트
- 기술 스택 변경 시: Container Diagram의 기술 정보 수정
- 외부 서비스 연동 시: Context Diagram에 새로운 외부 시스템 추가
- 클라우드 이관 시: Deployment Diagram 신규 작성 및 Container 정보 업데이트