Django 아키텍처 3부: Component Diagram으로 레이어 구조 정리하기

Component Diagram image

이번에는 Component Diagram에 대해 알아보려고 하는데요. 이미 1·2부에서 우리는

  • 시스템 컨텍스트 다이어그램으로 “시스템 vs 외부 세계”
  • 컨테이너 다이어그램으로 “시스템 안의 큰 상자들(Django, DB, Worker …)”

까지 봤죠.

이제 한 단계 더 내려와서,

“Django Web App 안에서는 어떤 레이어들이
서로 어떻게 호출되는가?”

를 정리하는 것이 컴포넌트 다이어그램(Component Diagram)입니다.
C4 모델로 치면 Level 3 (Component) 에 해당해요.

지금 앞으로 함께 보려는 component.png 도 이런 구조일 거예요.

  • Views / URLs – HTTP 요청을 받는 Django View 레이어
  • Services – 비즈니스 로직 모듈 (Python 서비스 레이어)
  • Background Tasks – Celery 비동기 작업
  • Models / Repositories – Django ORM 모델 계층

이 4개의 레이어 관계를 깔끔하게 그려두면,
새로운 기능을 추가할 때 “어디에 코드를 넣어야 하지?”를 결정하기가 훨씬 편해집니다.

예시 구조: 설문·면담 Django Component Diagram

Django Component Diagram image

설문·면담 통합관리 시스템을 예로 들면,
컴포넌트 다이어그램 안에는 대략 이런 요소가 들어갑니다.

  • Views / URLs
    • 설문 목록/생성 View
    • 면담 일정/기록 View
    • 대시보드 View(API 포함)
  • Services
    • survey_service – 설문 생성·복사·배포 로직
    • interview_service – 인터뷰 커버 생성, 자동 저장, 검토 완료 처리
    • report_service – 통계 집계, 리포트 생성 로직
  • Background Tasks (Celery)
    • 응답 완료 시 이메일 알림 발송
    • 대량 리포트 생성(엑셀, PDF)
    • 야간 배치 통계 업데이트
  • Models / Repositories
    • Survey, SurveyResponse, InterviewCover, InterviewRecord
    • 조직/직급/사이트 관련 모델
    • 리포트/로그/이력 모델

이걸 “실제 코드 구조”와 함께 보여주는 지도 역할이 바로 Component Diagram입니다.

component.puml Create a basic template

docs/architecture/component.puml 파일을 새로 만들어 열고,
아래 템플릿을 그대로 붙여 넣어 볼게요.

@startuml
!define C4P https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master
!includeurl C4P/C4_Component.puml

' 1) 시스템 경계
Container_Boundary(django_app, "Django Web Application") {

  ' Views / URLs 레이어
  Component(views, "Views / URLs", "Django Views",
    "HTTP 요청을 받고 폼 검증, 서비스 호출, 템플릿 렌더링을 담당")

  ' Service 레이어
  Component(services, "Services", "Python modules",
    "설문·면담·리포트 등 비즈니스 로직을 캡슐화")

  ' Background Tasks (Celery)
  Component(background_tasks, "Background Tasks", "Celery tasks",
    "이메일 발송, 리포트 생성, 대량 처리 등 비동기 작업")

  ' Models / Repositories
  ComponentDb(models_repo, "Models / Repositories", "Django ORM",
    "Survey, Interview, Response 등 도메인 데이터 영속화")
}

' 2) 관계 설정
Rel(views, services, "비즈니스 로직 호출 (예: 설문 생성, 면담 저장)")
Rel(services, models_repo, "ORM을 통해 데이터 읽기/쓰기")
Rel(services, background_tasks, "비동기 작업 enqueue (delay())")
Rel(background_tasks, models_repo, "백그라운드에서 데이터 갱신")

SHOW_LEGEND()
@enduml

이 코드로 렌더하면,
지금 아래의 그림에서 보고 있는 component.png 와 거의 동일한 구조의
Component Diagram을 얻을 수 있습니다.

Component Diagram image

실제 Django 프로젝트와 매핑하기

위 컴포넌트들을 실제 코드와 연결해 볼게요.

  • Views / URLs
    • 위치: 각 앱의 views.py, urls.py
    • Example:
      • survey/views.py → 설문 CRUD View
      • interview/views.py → 면담 커버 저장 View (sequence 다이어그램과 연결)
  • Services
    • 위치: services/ 디렉토리 또는 각 앱 내 services.py
    • Example:
      • survey/services.py → 설문 생성, 복사, 배포 함수
      • interview/services.py → 자동 저장 세션 처리, 검토 상태 변경
  • Background Tasks
    • 위치: tasks.py
    • Example:
      • interview/tasks.py → 면담 완료 후 알림 메일 발송
      • dashboard/tasks.py → 야간 배치 통계 집계
  • Models / Repositories
    • 위치: 각 앱의 models.py
    • Example:
      • Survey, SurveyResponse, InterviewCover, InterviewRecord etc.

실무에서는 다이어그램을 먼저 그려두고
“우리 프로젝트는 View → Service → Model 구조로 간다”
라는 원칙을 팀 내에 합의시키는 데 쓰면 좋습니다.

Component Diagram 렌더링하기

방법은 1·2부에 했던 것과 동일하게 하면 됩니다.

VSCode + PlantUML 확장 사용 시

  1. component.puml Open
  2. 미리보기(Preview) 실행
  3. 필요하면 PNG로 Export 후 저장

plantuml.jar 사용 시

java -jar tools/plantuml.jar docs/architecture/component.puml

→ Β docs/architecture/component.png Create
사용하고자 하는 곳의 “Component Diagram 예시” 섹션에 삽입하면 됩니다.

실무에서 컴포넌트 다이어그램을 쓰는 이유

  1. “어디에 코드를 두지?” 고민 줄이기
    • 새 기능 추가할 때
      • 화면/요청 처리 → View
      • 규칙/계산/검증 → Service
      • 오래 걸리는 일 → Background Task
      • 데이터 저장 → Model
        이라는 공통 룰을 시각적으로 설정해 둘 수 있습니다.
  2. 리팩토링 논의용 기준
    • Service에 로직이 너무 몰려 있으면
      컴포넌트 다이어그램을 보면서
      “여기 부분을 별도 서비스/마이크로서비스로 분리하자” 같은 논의를 하기 쉽습니다.
  3. 신규 팀원 온보딩 자료
    • 새로 들어온 개발자에게
      ERD보다 먼저 이 Component Diagram을 보여주면
      “아, 이 프로젝트는 레이어가 이렇게 나뉘어 있구나”
      를 빨리 이해합니다.

Similar Posts