Django 프로젝트 아키텍처 1부: 시스템 컨텍스트 다이어그램(system context diagram)으로 전체 그림 잡기
Django 시스템을 예시로, 시스템 컨텍스트 다이어그램(system context diagram)을 만드는 방법을 단계별로 정리했습니다. C4 모델과 PlantUML을 활용해 관리자, 설문 응답자, 분석가, 외부 서비스까지 한눈에 보이는 시스템 컨텍스트 다이어그램을 직접 그려봅니다.
1. 왜 시스템 컨텍스트 다이어그램(system context diagram)부터 시작할까?
아키텍처 그림을 그릴 때 많은 분들이 바로 DB ERD나 컨테이너 다이어그램부터 시작해요.
그런데 정작 제일 중요한 질문 하나가 빠집니다.
“이 시스템, 결국 누가 사용하고 무엇과 연결돼 있지?”
이걸 한 장으로 정리해 주는 게 바로 시스템 컨텍스트 다이어그램(system context diagram)입니다.
- 시스템을 큰 박스 하나로 보고
- 바깥에 있는 사람(관리자, 설문 응답자, 분석가 등)과
- 외부 서비스(SMTP, Google API, Redis 등)를
- 데이터 흐름 기준으로 연결해 주는 그림이죠.
나중에 컨테이너/컴포넌트/시퀀스/ERD를 볼 때도
이 1부의 system context diagram이 기준이 됩니다.
2. 오늘 완성할 시스템 컨텍스트 다이어그램 살펴보기
지금 위 그림을 기준으로 설명하면, 대략 이런 구성이에요:
- 위쪽에 세 명의 사람은
- Admin – 설문·면담을 관리하는 관리자
- Survey Respondent – 웹 브라우저로 설문/면담에 응답하는 사용자
- Analyst – 대시보드에서 통계를 보는 분석자
- 가운데 큰 박스는
- Survey System / Survey Web Application (Django)
– 우리가 개발한 조직문화 통합 관리 Django 웹앱
- Survey System / Survey Web Application (Django)
- 아래쪽의 외부 시스템은
- SMTP / Gmail – 이메일 알림 발송
- Google APIs – 구글 시트/드라이브 등 필요시 연동
- Redis (optional) – 캐시/세션 저장소
이 관계를 코드로 표현한 것이 PlantUML C4 컨텍스트 다이어그램입니다.
이제 같은 걸 처음 설치하는 사람 기준으로 ‘맨땅에 헤딩식’으로 만들어 볼게요.
3. 준비 단계 – 폴더 만들기와 PlantUML 설치
3-1. 아키텍처 폴더 구조 잡기
Django 프로젝트 루트 기준으로 이렇게 폴더를 하나 만듭니다.
# 프로젝트 루트 예: django_project
mkdir -p docs/architecture여기에 앞으로 만들게 될
context.puml(system context diagram)container.puml(컨테이너 다이어그램 – 2부에서 사용)component.puml(컴포넌트 다이어그램)
등을 모아둘 거예요.
3-2. PlantUML 설치 방법 2가지 중 택1
방법 A – VSCode 확장(가장 쉬움)
- VSCode에서 Extensions 열기
PlantUML검색 후 설치- Java가 없다면 OpenJDK 하나 설치(JDK 17 권장)
.puml파일을 열고Alt + D(또는 Command Palette에서 “PlantUML: Preview”)로 미리보기
방법 B – plantuml.jar 직접 다운로드
tools폴더 생성mkdir -p tools- plantuml.jar 다운로드 (브라우저로 받아서
tools/plantuml.jar에 저장) - 렌더링 명령 예시(프로젝트 루트에서):
java -jar tools/plantuml.jar docs/architecture/context.puml→ 같은 폴더에context.png가 생성됩니다.
이제 준비 끝!
본격적으로 시스템 컨텍스트 다이어그램 코드를 작성해 볼게요.
4. C4 모델 + PlantUML 기본 템플릿 만들기
docs/architecture/context.puml 파일을 새로 만들고,
아래 기본 템플릿 코드를 붙여 넣습니다.
@startuml
' C4-PlantUML 라이브러리 불러오기
!define C4P https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master
!includeurl C4P/C4_Context.puml
' 1) 사람(Actors) 정의
Person(admin, "Admin", "설문/면담을 생성하고 관리하는 관리자")
Person(respondent, "Survey Respondent", "웹 브라우저로 설문과 면담에 응답하는 사용자")
Person(analyst, "Analyst", "대시보드에서 설문 결과를 분석하는 분석자")
' 2) 시스템(System) 정의
System(survey_system, "Survey System", "Django 시스템")
' 3) 외부 시스템 정의
System_Ext(smtp, "SMTP / Gmail", "이메일 알림 발송용 외부 메일 서버")
System_Ext(google_apis, "Google APIs", "보고서/자동화 스크립트에서 선택적으로 사용하는 외부 API")
System_Ext(redis, "Redis (optional)", "세션/캐시 저장용 인메모리 데이터베이스")
' 4) 관계(Relationship) 정의
Rel(admin, survey_system, "설문/면담 생성·관리, 리포트 조회", "HTTPS")
Rel(respondent, survey_system, "설문 응답 제출", "HTTPS")
Rel(analyst, survey_system, "대시보드/통계 조회", "HTTPS")
Rel(survey_system, smtp, "알림 이메일 발송", "SMTP")
Rel(survey_system, google_apis, "보고서 자동화 스크립트에서 호출", "HTTPS")
Rel(survey_system, redis, "세션/캐시 저장", "TCP")
SHOW_LEGEND()
@enduml여기까지가 system context diagram의 전체 코드입니다.
이 코드 한 장으로, 위에서 살펴본 다이어그램과 거의 동일한 그림을 얻을 수 있어요.
5. 다이어그램 렌더링하기
5-1. VSCode에서 바로 보기
- VSCode로
context.puml열기 Alt + D또는 Command Palette에서
“PlantUML: Preview Current Diagram” 선택- 오른쪽에 system context diagram이 나타나면 성공 🎉
5-2. plantuml.jar로 PNG 만들기
터미널(프로젝트 루트 기준)에서
java -jar tools/plantuml.jar docs/architecture/context.puml실행하면 docs/architecture/context.png가 생성됩니다.
6. 코드 한 줄씩 이해해보기 (system context diagram 해설)
1) Actor 정의 – Person()
Person(admin, "Admin", "설문/면담을 생성하고 관리하는 관리자")admin: 내부 ID (코드 안에서만 사용)"Admin": 그림에 표시되는 이름"설문/면담을 생성하고 관리하는 관리자": 설명(툴팁으로 표시)
같은 방식으로 Survey Respondent, Analyst를 정의해서
system context diagram에 사용자 3명을 배치합니다.
2) System / System_Ext
System(survey_system, "Survey System", "Django 기반 통합 관리 시스템")
System_Ext(smtp, "SMTP / Gmail", "이메일 알림 발송용 외부 메일 서버")System: 우리가 직접 개발·운영하는 시스템System_Ext: 외부 의존 시스템 (SMTP, Google APIs, Redis 등)
이렇게 나눠줘야 시스템 경계가 분명해집니다.
시스템 컨텍스트 다이어그램의 핵심은 바로 이 경계 표시예요.
3) Rel() – 관계와 데이터 흐름
Rel(respondent, survey_system, "설문 응답 제출", "HTTPS")respondent → survey_system방향 화살표- “설문 응답 제출” 이라는 텍스트
- 실제 프로토콜: HTTPS
이걸 보고 누가 봐도,
“아, 설문 응답자는 브라우저에서 Django 웹앱으로 응답을 보내는구나”
라고 이해할 수 있어야 합니다.
그래서 시스템 컨텍스트 다이어그램에서는
기술적인 포트 번호보다 ‘업무적인 데이터 흐름’ 문장이 더 중요합니다.
7. 실무에서 시스템 컨텍스트 다이어그램 활용 팁
- 회의 시작 전에 이 한 장부터 보여주기
– 개발자, 기획자, 운영자, 현장 리더가 같이 모였을 때
ERD부터 보여주면 “어렵다…”는 표정이 바로 나옵니다 😅
그 대신, system context diagram 한 장부터 보여주면
“아, 이 시스템이 우리 조직에서 어떤 역할을 하는지”가 금방 공유됩니다. - 요구사항이 바뀔 때마다 컨텍스트부터 업데이트
– 예를 들어 “향후 Kafka나 내부 LLM 서버와 연동한다”라는 요구가 생기면
새로운 System_Ext를 추가하고 화살표를 그려 넣습니다.
이게 정리되면, 그 다음에 컨테이너/컴포넌트 레벨 설계로 내려가면 돼요. - 문서/위키에 PNG + 코드(.puml) 둘 다 저장하기
– PNG는 관리자가 보기 좋고,
–.puml파일은 개발자가 수정·버전관리를 하기 좋습니다.
Git 레포에docs/architecture/context.puml을 커밋해 두면
나중에 “처음엔 어떤 구조였지?”를 추적하기도 편합니다.
다음에는 백엔드 구조를 정리하기 위한 Container Diagram을 생성하는 방법을 살펴보도록 하겠습니다.
