diff --git a/claude/class-design.md b/claude/class-design.md
new file mode 100644
index 0000000..943df9f
--- /dev/null
+++ b/claude/class-design.md
@@ -0,0 +1,68 @@
+# 클래스설계가이드
+
+[요청사항]
+- <작성원칙>을 준용하여 설계
+- <작성순서>에 따라 설계
+- [결과파일] 안내에 따라 파일 작성
+
+[가이드]
+<작성원칙>
+- **유저스토리와 매칭**되어야 함. **불필요한 추가 설계 금지**
+- API설계서와 일관성 있게 설계. Controller에 API를 누락하지 말고 모두 설계
+ - Controller 클래스는 API로 정의하지 않은 메소드 생성 안함. 단, 필요한 Private 메소드는 추가함
+ - {service-name}-simple.puml파일에 Note로 Controller 클래스 메소드와 API 매핑표 작성: {Methond}: {API Path} {API 제목}
+ 예) login: /login 로그인
+- 내부시퀀스설계서와 일관성 있게 설계
+- 각 서비스별 지정된 {설계 아키텍처 패턴}을 적용
+- Clean아키텍처 적용 시 Port/Adapter라는 용어 대신 Clean 아키텍처에 맞는 용어 사용
+- 클래스의 프라퍼티와 메소드를 모두 기술할 것. 단 "Getter/Setter 메소드"는 작성하지 않음
+- 클래스 간의 관계를 표현: Generalization, Realization, Dependency, Association, Aggregation, Composition
+
+<작성순서>
+- **서브 에이전트를 활용한 병렬 작성 필수**
+- **3단계 하이브리드 접근법 적용**
+- **마이크로서비스 아키텍처 기반 설계**
+
+- 1단계: 공통 컴포넌트 설계 (순차적)
+ - 결과: design/backend/class/common-base.puml
+
+- 2단계: 서비스별 병렬 설계 (병렬 실행)
+ - 1단계 공통 컴포넌트 참조
+ - '!include'는 사용하지 말고 필요한 인터페이스 직접 정의
+ - 클래스 설계 후 프라퍼티와 메소드를 생략한 간단한 클래스설계서도 추가로 작성
+ - 결과:
+ - design/backend/class/{service-name}.puml
+ - design/backend/class/{service-name}-simple.puml
+
+ - 병렬 처리 기준
+ - 서비스 간 의존성이 없는 경우: 모든 서비스 동시 실행
+ - 의존성이 있는 경우: 의존성 그룹별로 묶어서 실행
+ - 예: A→B 의존 시, A 완료 후 B 실행
+ - 독립 서비스 C,D는 A,B와 병렬 실행
+
+- 3단계: 통합 및 검증 (순차적)
+ - '패키지구조표준'의 예시를 참조하여 모든 클래스와 파일이 포함된 패키지 구조도를 작성
+ (plantuml 스크립트가 아니라 트리구조 텍스트로 작성)
+ - 인터페이스 일치성 검증
+ - 명명 규칙 통일성 확인
+ - 의존성 검증
+ - 크로스 서비스 참조 검증
+ - **PlantUML 스크립트 파일 검사 실행**: 'PlantUML문법검사가이드' 준용
+
+[참고자료]
+- 유저스토리
+- API설계서
+- 내부시퀀스설계서
+- 패키지구조표준
+- PlantUML문법검사가이드
+
+[예시]
+- 링크: https://raw.githubusercontent.com/cna-bootcamp/clauding-guide/refs/heads/main/samples/sample-클래스설계서.puml
+
+[결과파일]
+- 패키지 구조도: design/backend/class/package-structure.md
+- 클래스설계서:
+ - design/backend/class/common-base.puml
+ - design/backend/class/{service-name}.puml
+- 클래스설계서(요약): design/backend/class/{service-name}-simple.puml
+- service-name은 영어로 작성 (예: profile, location, itinerary)
diff --git a/claude/data-design.md b/claude/data-design.md
new file mode 100644
index 0000000..e3761db
--- /dev/null
+++ b/claude/data-design.md
@@ -0,0 +1,55 @@
+# 데이터설계가이드
+
+[요청사항]
+- <작성원칙>을 준용하여 설계
+- <작성순서>에 따라 설계
+- [결과파일] 안내에 따라 파일 작성
+
+[가이드]
+<작성원칙>
+- **클래스설계서의 각 서비스별 Entity정의와 일치**해야 함. **불필요한 추가 설계 금지**
+- <데이터독립성원칙>에 따라 각 서비스마다 데이터베이스를 분리
+<작성순서>
+- 준비:
+ - 유저스토리, API설계서, 외부시퀀스설계서, 내부시퀀스설계서, 패키지구조표준 분석 및 이해
+- 실행:
+ - <병렬처리>안내에 따라 각 서비스별 병렬 수행
+ - 데이터설계서 작성
+ - 캐시 사용 시 캐시DB 설계 포함
+ - 시작 부분에 '데이터설계 요약' 제공
+ - 결과: {service-name}.md
+ - ERD 작성
+ - 결과: {service-name}-erd.puml
+ - **PlantUML 스크립트 파일 생성 즉시 검사 실행**: 'PlantUML 문법 검사 가이드' 준용
+ - 데이터베이스 스키마 스크립트 작성
+ - 실행 가능한 SQL 스크립트 작성
+ - 결과: {service-name}-schema.psql
+- 검토:
+ - <작성원칙> 준수 검토
+ - 스쿼드 팀원 리뷰: 누락 및 개선 사항 검토
+ - 수정 사항 선택 및 반영
+
+<병렬처리>
+Agent 1~N: 각 서비스별 데이터베이스 설계
+ - 서비스별 독립적인 스키마 설계
+ - Entity 클래스와 1:1 매핑
+ - 서비스 간 데이터 공유 금지
+ - FK 관계는 서비스 내부에서만 설정
+
+<데이터독립성원칙>
+- **데이터 소유권**: 각 서비스가 자신의 데이터 완전 소유
+- **크로스 서비스 조인 금지**: 서비스 간 DB 조인 불가
+- **이벤트 기반 동기화**: 필요시 이벤트/메시지로 데이터 동기화
+- **캐시 활용**: 타 서비스 데이터는 캐시로만 참조
+
+[참고자료]
+- 클래스설계서
+
+[예시]
+- 링크: https://raw.githubusercontent.com/cna-bootcamp/clauding-guide/refs/heads/main/samples/sample-데이터설계서.puml
+
+[결과파일]
+- design/backend/database/{service-name}.md
+- design/backend/database/{service-name}-erd.puml
+- design/backend/database/{service-name}-schema.psql
+- service-name은 영어로 작성
diff --git a/claude/highlevel-architecture-template.md b/claude/highlevel-architecture-template.md
new file mode 100644
index 0000000..e615891
--- /dev/null
+++ b/claude/highlevel-architecture-template.md
@@ -0,0 +1,425 @@
+# High Level 아키텍처 정의서
+
+## 1. 개요 (Executive Summary)
+
+### 1.1 프로젝트 개요
+- **비즈니스 목적**:
+- **핵심 기능**:
+- **대상 사용자**:
+- **예상 사용자 규모**:
+
+### 1.2 아키텍처 범위 및 경계
+- **시스템 범위**:
+- **포함되는 시스템**:
+- **제외되는 시스템**:
+- **외부 시스템 연동**:
+
+### 1.3 문서 구성
+이 문서는 4+1 뷰 모델을 기반으로 구성되며, 논리적/물리적/프로세스/개발 관점에서 아키텍처를 정의합니다.
+
+---
+
+## 2. 아키텍처 요구사항
+
+### 2.1 기능 요구사항 요약
+| 영역 | 주요 기능 | 우선순위 |
+|------|-----------|----------|
+| | | |
+
+### 2.2 비기능 요구사항 (NFRs)
+
+#### 2.2.1 성능 요구사항
+- **응답시간**:
+- **처리량**:
+- **동시사용자**:
+- **데이터 처리량**:
+
+#### 2.2.2 확장성 요구사항
+- **수평 확장**:
+- **수직 확장**:
+- **글로벌 확장**:
+
+#### 2.2.3 가용성 요구사항
+- **목표 가용성**: 99.9% / 99.99% / 99.999%
+- **다운타임 허용**:
+- **재해복구 목표**: RTO/RPO
+
+#### 2.2.4 보안 요구사항
+- **인증/인가**:
+- **데이터 암호화**:
+- **네트워크 보안**:
+- **컴플라이언스**:
+
+### 2.3 아키텍처 제약사항
+- **기술적 제약**:
+- **비용 제약**:
+- **시간 제약**:
+- **조직적 제약**:
+
+---
+
+## 3. 아키텍처 설계 원칙
+
+### 3.1 핵심 설계 원칙
+1. **확장성 우선**: 수평적 확장이 가능한 구조
+2. **장애 격리**: 단일 장애점 제거 및 Circuit Breaker 패턴
+3. **느슨한 결합**: 마이크로서비스 간 독립성 보장
+4. **관측 가능성**: 로깅, 모니터링, 추적 체계 구축
+5. **보안 바이 데자인**: 설계 단계부터 보안 고려
+
+### 3.2 아키텍처 품질 속성 우선순위
+| 순위 | 품질 속성 | 중요도 | 전략 |
+|------|-----------|--------|------|
+| 1 | | High | |
+| 2 | | Medium | |
+| 3 | | Low | |
+
+---
+
+## 4. 논리 아키텍처 (Logical View)
+
+### 4.1 시스템 컨텍스트 다이어그램
+```
+{논리아키텍처 경로}
+```
+
+### 4.2 도메인 아키텍처
+#### 4.2.1 도메인 모델
+| 도메인 | 책임 | 주요 엔티티 |
+|--------|------|-------------|
+| | | |
+
+#### 4.2.2 바운디드 컨텍스트
+```
+[도메인별 바운디드 컨텍스트 다이어그램]
+```
+
+### 4.3 서비스 아키텍처
+#### 4.3.1 마이크로서비스 구성
+| 서비스명 | 책임 |
+|----------|------|
+| | |
+
+#### 4.3.2 서비스 간 통신 패턴
+- **동기 통신**: REST API, GraphQL
+- **비동기 통신**: Event-driven, Message Queue
+- **데이터 일관성**: Saga Pattern, Event Sourcing
+
+---
+
+## 5. 프로세스 아키텍처 (Process View)
+
+### 5.1 주요 비즈니스 프로세스
+#### 5.1.1 핵심 사용자 여정
+```
+[사용자 여정별 프로세스 플로우]
+```
+
+#### 5.1.2 시스템 간 통합 프로세스
+```
+[시스템 통합 시퀀스 다이어그램]
+```
+
+### 5.2 동시성 및 동기화
+- **동시성 처리 전략**:
+- **락 관리**:
+- **이벤트 순서 보장**:
+
+---
+
+## 6. 개발 아키텍처 (Development View)
+
+### 6.1 개발 언어 및 프레임워크 선정
+#### 6.1.1 백엔드 기술스택
+| 서비스 | 언어 | 프레임워크 | 선정이유 |
+|----------|------|---------------|----------|
+
+#### 6.1.2 프론트엔드 기술스택
+- **언어**:
+- **프레임워크**:
+- **선정 이유**:
+
+### 6.2 서비스별 개발 아키텍처 패턴
+| 서비스 | 아키텍처 패턴 | 선정 이유 |
+|--------|---------------|-----------|
+| | Clean/Layered/Hexagonal | |
+
+
+### 6.3 개발 가이드라인
+- **코딩 표준**:
+- **테스트 전략**:
+
+---
+
+## 7. 물리 아키텍처 (Physical View)
+
+### 7.1 클라우드 아키텍처 패턴
+#### 7.1.1 선정된 클라우드 패턴
+- **패턴명**:
+- **적용 이유**:
+- **예상 효과**:
+
+#### 7.1.2 클라우드 제공자
+- **주 클라우드**: Azure/AWS/GCP
+- **멀티 클라우드 전략**:
+- **하이브리드 구성**:
+
+### 7.2 인프라스트럭처 구성
+#### 7.2.1 컴퓨팅 리소스
+| 구성요소 | 사양 | 스케일링 전략 |
+|----------|------|---------------|
+| 웹서버 | | |
+| 앱서버 | | |
+| 데이터베이스 | | |
+
+#### 7.2.2 네트워크 구성
+```
+[네트워크 토폴로지 다이어그램]
+```
+
+#### 7.2.3 보안 구성
+- **방화벽**:
+- **WAF**:
+- **DDoS 방어**:
+- **VPN/Private Link**:
+
+---
+
+## 8. 기술 스택 아키텍처
+
+### 8.1 API Gateway & Service Mesh
+#### 8.1.1 API Gateway
+- **제품**:
+- **주요 기능**: 인증, 라우팅, 레이트 리미팅, 모니터링
+- **설정 전략**:
+
+#### 8.1.2 Service Mesh
+- **제품**: Istio/Linkerd/Consul Connect
+- **적용 범위**:
+- **트래픽 관리**:
+
+### 8.2 데이터 아키텍처
+#### 8.2.1 데이터베이스 전략
+| 용도 | 데이터베이스 | 타입 | 특징 |
+|------|-------------|------|------|
+| 트랜잭션 | | RDBMS | |
+| 캐시 | | In-Memory | |
+| 검색 | | Search Engine | |
+| 분석 | | Data Warehouse | |
+
+#### 8.2.2 데이터 파이프라인
+```
+[데이터 플로우 다이어그램]
+```
+
+### 8.3 백킹 서비스 (Backing Services)
+#### 8.3.1 메시징 & 이벤트 스트리밍
+- **메시지 큐**:
+- **이벤트 스트리밍**:
+- **이벤트 스토어**:
+
+#### 8.3.2 스토리지 서비스
+- **객체 스토리지**:
+- **블록 스토리지**:
+- **파일 스토리지**:
+
+### 8.4 관측 가능성 (Observability)
+#### 8.4.1 로깅 전략
+- **로그 수집**:
+- **로그 저장**:
+- **로그 분석**:
+
+#### 8.4.2 모니터링 & 알람
+- **메트릭 수집**:
+- **시각화**:
+- **알람 정책**:
+
+#### 8.4.3 분산 추적
+- **추적 도구**:
+- **샘플링 전략**:
+- **성능 분석**:
+
+---
+
+## 9. AI/ML 아키텍처
+
+### 9.1 AI API 통합 전략
+#### 9.1.1 AI 서비스/모델 매핑
+| 목적 | 서비스 | 모델 | Input 데이터 | Output 데이터 | SLA |
+|------|--------|-------|-------------|-------------|-----|
+| | | | | | |
+
+#### 9.1.2 AI 파이프라인
+```
+[AI 데이터 처리 파이프라인]
+```
+
+### 9.2 데이터 과학 플랫폼
+- **모델 개발 환경**:
+- **모델 배포 전략**:
+- **모델 모니터링**:
+
+---
+
+## 10. 개발 운영 (DevOps)
+
+### 10.1 CI/CD 파이프라인
+#### 10.1.1 지속적 통합 (CI)
+- **도구**:
+- **빌드 전략**:
+- **테스트 자동화**:
+
+#### 10.1.2 지속적 배포 (CD)
+- **배포 도구**:
+- **배포 전략**: Blue-Green/Canary/Rolling
+- **롤백 정책**:
+
+### 10.2 컨테이너 오케스트레이션
+#### 10.2.1 Kubernetes 구성
+- **클러스터 전략**:
+- **네임스페이스 설계**:
+- **리소스 관리**:
+
+#### 10.2.2 헬름 차트 관리
+- **차트 구조**:
+- **환경별 설정**:
+- **의존성 관리**:
+
+---
+
+## 11. 보안 아키텍처
+
+### 11.1 보안 전략
+#### 11.1.1 보안 원칙
+- **Zero Trust**:
+- **Defense in Depth**:
+- **Least Privilege**:
+
+#### 11.1.2 위협 모델링
+| 위협 | 영향도 | 대응 방안 |
+|------|--------|-----------|
+| | | |
+
+### 11.2 보안 구현
+#### 11.2.1 인증 & 인가
+- **ID 제공자**:
+- **토큰 전략**: JWT/OAuth2/SAML
+- **권한 모델**: RBAC/ABAC
+
+#### 11.2.2 데이터 보안
+- **암호화 전략**:
+- **키 관리**:
+- **데이터 마스킹**:
+
+---
+
+## 12. 품질 속성 구현 전략
+
+### 12.1 성능 최적화
+#### 12.1.1 캐싱 전략
+| 계층 | 캐시 유형 | TTL | 무효화 전략 |
+|------|-----------|-----|-------------|
+| | | | |
+
+#### 12.1.2 데이터베이스 최적화
+- **인덱싱 전략**:
+- **쿼리 최적화**:
+- **커넥션 풀링**:
+
+### 12.2 확장성 구현
+#### 12.2.1 오토스케일링
+- **수평 확장**: HPA/VPA
+- **수직 확장**:
+- **예측적 스케일링**:
+
+#### 12.2.2 부하 분산
+- **로드 밸런서**:
+- **트래픽 분산 정책**:
+- **헬스체크**:
+
+### 12.3 가용성 및 복원력
+#### 12.3.1 장애 복구 전략
+- **Circuit Breaker**:
+- **Retry Pattern**:
+- **Bulkhead Pattern**:
+
+#### 12.3.2 재해 복구
+- **백업 전략**:
+- **RTO/RPO**:
+- **DR 사이트**:
+
+---
+
+## 13. 아키텍처 의사결정 기록 (ADR)
+
+### 13.1 주요 아키텍처 결정
+| ID | 결정 사항 | 결정 일자 | 상태 | 결정 이유 |
+|----|-----------|-----------|------|-----------|
+| ADR-001 | | | | |
+
+### 13.2 트레이드오프 분석
+#### 13.2.1 성능 vs 확장성
+- **고려사항**:
+- **선택**:
+- **근거**:
+
+#### 13.2.2 일관성 vs 가용성 (CAP 정리)
+- **고려사항**:
+- **선택**: AP/CP
+- **근거**:
+
+---
+
+## 14. 구현 로드맵
+
+### 14.1 개발 단계
+| 단계 | 기간 | 주요 산출물 | 마일스톤 |
+|------|------|-------------|-----------|
+| Phase 1 | | | |
+| Phase 2 | | | |
+| Phase 3 | | | |
+
+### 14.2 마이그레이션 전략 (레거시 시스템이 있는 경우)
+- **데이터 마이그레이션**:
+- **기능 마이그레이션**:
+- **병행 운영**:
+
+---
+
+## 15. 위험 관리
+
+### 15.1 아키텍처 위험
+| 위험 | 영향도 | 확률 | 완화 방안 |
+|------|--------|------|-----------|
+| | | | |
+
+### 15.2 기술 부채 관리
+- **식별된 기술 부채**:
+- **해결 우선순위**:
+- **해결 계획**:
+
+---
+
+## 16. 부록
+
+### 16.1 참조 아키텍처
+- **업계 표준**:
+- **내부 표준**:
+- **외부 참조**:
+
+### 16.2 용어집
+| 용어 | 정의 |
+|------|------|
+| | |
+
+### 16.3 관련 문서
+- {문서명}: {파일 위치}
+- ...
+
+---
+
+## 문서 이력
+| 버전 | 일자 | 작성자 | 변경 내용 | 승인자 |
+|------|------|--------|-----------|-------|
+| v1.0 | | | 초기 작성 | |
+
diff --git a/claude/physical-architecture-design.md b/claude/physical-architecture-design.md
new file mode 100644
index 0000000..e84bd1b
--- /dev/null
+++ b/claude/physical-architecture-design.md
@@ -0,0 +1,230 @@
+# 물리아키텍처설계가이드
+
+[요청사항]
+- <작성원칙>을 준용하여 설계
+- <작성순서>에 따라 설계
+- [결과파일] 안내에 따라 파일 작성
+- 완료 후 mermaid 스크립트 테스트 방법 안내
+ - https://mermaid.live/edit 에 접근
+ - 스크립트 내용을 붙여넣어 확인
+
+[가이드]
+<작성원칙>
+- 클라우드 기반의 물리 아키텍처 설계
+- HighLevel아키텍처정의서와 일치해야 함
+- 백킹서비스설치방법에 있는 제품을 우선적으로 사용
+- 환경별 특성에 맞는 차별화 전략 적용
+- 비용 효율성과 운영 안정성의 균형 고려
+- 선정된 아키텍처 패턴 반영 및 최적화
+
+<작성순서>
+- 준비:
+ - 아키텍처패턴, 논리아키텍처, 외부시퀀스설계서, 데이터설계서, HighLevel아키텍처정의서 분석 및 이해
+
+- 실행:
+ - 물리아키텍처 다이어그램 작성
+ - 서브에이전트로 병렬 수행
+ - Mermaid 형식으로 작성
+ - Mermaid 스크립트 파일 검사 실행
+ - 개발환경 물리아키텍처 다이어그램
+ - '<예시>의 '개발환경 물리아키텍처 다이어그램'의 내용을 읽어 참조
+ - 사용자 → Ingress → 서비스 → 데이터베이스 플로우만 표시
+ - 클라우드 서비스는 최소한으로만 포함
+ - 부가 설명은 문서에만 기록, 다이어그램에서 제거
+ - 네트워크, 보안, 운영 관련 아키텍처는 생략
+ - 모니터링/로깅/보안과 관련된 제품/서비스 생략함
+ - 운영환경 물리아키텍처 다이어그램
+ - '<예시>의 '운영환경 물리아키텍처 다이어그램'의 내용을 읽어 참조
+ - 결과:
+ - 개발환경: physical-architecture-dev.mmd
+ - 운영환경: physical-architecture-prod.mmd
+ - 네트워크 아키텍처 다이어그램 작성
+ - 서브에이전트로 병렬 수행
+ - Mermaid 형식으로 작성
+ - Mermaid 스크립트 파일 검사 실행
+ - 개발환경 네트워크 다이어그램: '<예시>의 '개발환경 네트워크 다이어그램'의 내용을 읽어 참조
+ - 운영환경 네트워크 다이어그램: '<예시>의 '운영환경 네트워크 다이어그램'의 내용을 읽어 참조
+ - 결과:
+ - 개발환경: network-dev.mmd
+ - 운영환경: network-prod.mmd
+ - 개발환경 물리아키텍처 설계서 작성
+ - <개발환경가이드>의 항목별 작성
+ - '<예시>의 '개발환경 물리아키텍처 설계서'의 내용을 읽어 참조
+ - 비용 최적화 중심의 개발 친화적 환경 구성
+ - 빠른 배포와 테스트를 위한 단순화된 아키텍처
+ - Pod 기반 백킹서비스와 기본 보안 설정
+ - 개발팀 규모와 워크플로우에 최적화
+ - 제품/서비스 구성
+ - Application Gateway: Kubernetes Ingress
+ - Database: "백킹서비스설치방법"에 있는 오픈소스 DB사용
+ - Message Queue: "백킹서비스설치방법"에 있는 {CLOUD}에서 제공하는 제품
+ - CI/CD: 'HighLevel아키텍처정의서'에 있는 CI/CD 제품
+ - 결과: physical-architecture-dev.md
+ - 운영환경 물리아키텍처 설계서 작성
+ - <운영환경가이드>의 항목별 작성
+ - '<예시>의 '운영환경 물리아키텍처 설계서'의 내용을 읽어 참조
+ - 고가용성과 확장성을 고려한 프로덕션 환경
+ - 관리형 서비스 중심의 안정적인 구성
+ - 엔터프라이즈급 보안과 모니터링 체계
+ - 실사용자 규모에 따른 성능 최적화
+ - 결과: physical-architecture-prod.md
+ - 마스터 아키텍처 설계서 작성
+ - <마스터가이드>의 항목별 작성
+ - '<예시>의 '마스터 물리아키텍처 설계서'의 내용을 읽어 참조
+ - 환경별 아키텍처 비교 및 통합 관리
+ - 단계별 전환 전략과 확장 로드맵
+ - 비용 분석과 운영 가이드라인
+ - 전체 시스템 거버넌스 체계
+ - 결과: physical-architecture.md
+- 검토:
+ - <작성원칙> 준수 검토
+ - 선정 아키텍처 패턴 적용 확인
+ - 환경별 비용 효율성 검증
+ - 확장성 및 성능 요구사항 충족 확인
+ - 프로젝트 팀원 리뷰 및 피드백 반영
+ - 수정 사항 선택 및 최종 반영
+
+<개발환경가이드>
+```
+대분류|중분류|소분류|작성가이드
+---|---|---|---
+1. 개요|1.1 설계 목적||개발환경 물리 아키텍처의 설계 범위, 목적, 대상을 명확히 기술
+1. 개요|1.2 설계 원칙||개발환경에 적합한 핵심 설계 원칙 4가지 정의 (MVP 우선, 비용 최적화, 개발 편의성, 단순성)
+1. 개요|1.3 참조 아키텍처||관련 아키텍처 문서들의 연관관계와 참조 방법 명시
+2. 개발환경 아키텍처 개요|2.1 환경 특성||개발환경의 목적, 사용자 규모, 가용성 목표, 확장성, 보안 수준 등 특성 정의
+2. 개발환경 아키텍처 개요|2.2 전체 아키텍처||전체 시스템 구성도와 주요 컴포넌트 간 연결 관계 설명 및 다이어그램 링크
+3. 컴퓨팅 아키텍처|3.1 Kubernetes 클러스터 구성|3.1.1 클러스터 설정|Kubernetes 버전, 서비스 계층, 네트워크 플러그인, DNS 등 클러스터 기본 설정값 표 작성
+3. 컴퓨팅 아키텍처|3.1 Kubernetes 클러스터 구성|3.1.2 노드 풀 구성|인스턴스 크기, 노드 수, 스케일링 설정, 가용영역, 가격 정책 등 노드 풀 상세 설정 표 작성
+3. 컴퓨팅 아키텍처|3.2 서비스별 리소스 할당|3.2.1 애플리케이션 서비스|각 마이크로서비스별 CPU/Memory requests, limits, replicas 상세 리소스 할당 표 작성
+3. 컴퓨팅 아키텍처|3.2 서비스별 리소스 할당|3.2.2 백킹 서비스|데이터베이스, 캐시 등 백킹서비스 Pod의 리소스 할당 및 스토리지 설정 표 작성 (PVC 사용 시 클라우드 스토리지 클래스 지정: standard, premium-ssd 등)
+3. 컴퓨팅 아키텍처|3.2 서비스별 리소스 할당|3.2.3 스토리지 클래스 구성|클라우드 제공자별 스토리지 클래스 설정 (hostPath 사용 금지, 관리형 디스크만 사용)
+4. 네트워크 아키텍처|4.1 네트워크 구성|4.1.1 네트워크 토폴로지|네트워크 구성도 및 서브넷 구조 설명, 네트워크 다이어그램 링크 제공
+4. 네트워크 아키텍처|4.1 네트워크 구성|4.1.2 네트워크 보안|Network Policy 설정, 접근 제한 규칙, 보안 정책 표 작성
+4. 네트워크 아키텍처|4.2 서비스 디스커버리||각 서비스의 내부 DNS 주소, 포트, 용도를 정리한 서비스 디스커버리 표 작성
+5. 데이터 아키텍처|5.1 데이터베이스 구성|5.1.1 주 데이터베이스 Pod 구성|컨테이너 이미지, 리소스 설정, 스토리지 구성, 데이터베이스 설정값 상세 표 작성 (스토리지는 클라우드 제공자별 관리형 스토리지 사용: Azure Disk, AWS EBS, GCP Persistent Disk 등)
+5. 데이터 아키텍처|5.1 데이터베이스 구성|5.1.2 캐시 Pod 구성|캐시 컨테이너 이미지, 리소스, 메모리 설정, 캐시 정책 등 상세 설정 표 작성 (영구 저장이 필요한 경우 클라우드 스토리지 클래스 사용)
+5. 데이터 아키텍처|5.2 데이터 관리 전략|5.2.1 데이터 초기화|Kubernetes Job을 이용한 데이터 초기화 프로세스, 실행 절차, 검증 방법 상세 기술
+5. 데이터 아키텍처|5.2 데이터 관리 전략|5.2.2 백업 전략|백업 방법, 주기, 보존 전략, 복구 절차를 서비스별로 정리한 표 작성
+6. 메시징 아키텍처|6.1 Message Queue 구성|6.1.1 Basic Tier 설정|Message Queue 전체 설정값과 큐별 상세 설정을 표로 정리하여 작성
+6. 메시징 아키텍처|6.1 Message Queue 구성|6.1.2 연결 설정|인증 방식, 연결 풀링, 재시도 정책 등 연결 관련 설정 표 작성
+7. 보안 아키텍처|7.1 개발환경 보안 정책|7.1.1 기본 보안 설정|보안 계층별 설정값과 수준을 정리한 표와 관리 대상 시크릿 목록 작성
+7. 보안 아키텍처|7.1 개발환경 보안 정책|7.1.2 시크릿 관리|시크릿 관리 방식, 순환 정책, 저장소 등 시크릿 관리 전략 표 작성
+7. 보안 아키텍처|7.2 Network Policies|7.2.1 기본 정책|Network Policy 설정 상세 내용과 보안 정책 적용 범위 표 작성
+8. 모니터링 및 로깅|8.1 기본 모니터링|8.1.1 Kubernetes 기본 모니터링|모니터링 스택 구성과 기본 알림 설정 임계값을 표로 정리
+8. 모니터링 및 로깅|8.1 기본 모니터링|8.1.2 애플리케이션 모니터링|헬스체크 설정과 수집 메트릭 유형을 표로 정리하여 작성
+8. 모니터링 및 로깅|8.2 로깅|8.2.1 로그 수집|로그 수집 방식, 저장 방식, 보존 기간과 로그 레벨 설정을 표로 작성
+9. 배포 관련 컴포넌트|||CI/CD 파이프라인 구성 요소들과 각각의 역할을 표 형태로 정리
+10. 비용 최적화|10.1 개발환경 비용 구조|10.1.1 주요 비용 요소|구성요소별 사양과 월간 예상 비용, 절약 방안을 상세 표로 작성
+10. 비용 최적화|10.1 개발환경 비용 구조|10.1.2 비용 절약 전략|컴퓨팅, 스토리지, 네트워킹 영역별 절약 방안과 절약률을 표로 정리
+11. 개발환경 운영 가이드|11.1 일상 운영|11.1.1 환경 시작/종료|일상적인 환경 관리를 위한 kubectl 명령어와 절차를 코드 블록으로 제공
+11. 개발환경 운영 가이드|11.1 일상 운영|11.1.2 데이터 관리|데이터 초기화, 백업, 복원을 위한 구체적 명령어와 절차를 코드 블록으로 작성
+11. 개발환경 운영 가이드|11.2 트러블슈팅|11.2.1 일반적인 문제 해결|자주 발생하는 문제 유형별 원인과 해결방안, 예방법을 표로 정리
+12. 개발환경 특성 요약|||개발환경의 핵심 설계 원칙, 주요 제약사항, 최적화 목표를 요약하여 기술
+```
+
+<운영환경가이드>
+```
+대분류|중분류|소분류|작성가이드
+---|---|---|---
+1. 개요|1.1 설계 목적||운영환경 물리 아키텍처의 설계 범위, 목적, 대상을 명확히 기술
+1. 개요|1.2 설계 원칙||고가용성, 확장성, 보안 우선, 관측 가능성, 재해복구 등 5대 핵심 원칙 정의
+1. 개요|1.3 참조 아키텍처||관련 아키텍처 문서들의 연관관계와 참조 방법 명시
+2. 운영환경 아키텍처 개요|2.1 환경 특성||운영환경의 목적, 사용자 규모, 가용성 목표, 확장성, 보안 수준 등 특성 정의
+2. 운영환경 아키텍처 개요|2.2 전체 아키텍처||전체 시스템 구성도와 주요 컴포넌트 간 연결 관계 설명 및 다이어그램 링크
+3. 컴퓨팅 아키텍처|3.1 Kubernetes 클러스터 구성|3.1.1 클러스터 설정|Kubernetes 버전, Standard 서비스 티어, CNI 플러그인, RBAC 등 클러스터 기본 설정값 표 작성
+3. 컴퓨팅 아키텍처|3.1 Kubernetes 클러스터 구성|3.1.2 노드 풀 구성|시스템 노드 풀과 애플리케이션 노드 풀의 인스턴스 크기, 노드 수, Multi-Zone 배포 설정 표 작성
+3. 컴퓨팅 아키텍처|3.2 고가용성 구성|3.2.1 Multi-Zone 배포|가용성 전략과 Pod Disruption Budget 설정을 표로 정리
+3. 컴퓨팅 아키텍처|3.3 서비스별 리소스 할당|3.3.1 애플리케이션 서비스|각 마이크로서비스별 CPU/Memory requests, limits, replicas, HPA 설정 상세 표 작성
+3. 컴퓨팅 아키텍처|3.3 서비스별 리소스 할당|3.3.2 HPA 구성|Horizontal Pod Autoscaler 설정을 YAML 코드 블록으로 상세 작성
+4. 네트워크 아키텍처|4.1 네트워크 토폴로지||네트워크 흐름도와 VNet 구성, 서브넷 세부 구성을 표로 정리하고 다이어그램 링크 제공
+4. 네트워크 아키텍처|4.1 네트워크 토폴로지|4.1.1 Virtual Network 구성|VPC/VNet 기본 설정과 서브넷별 주소 대역, 용도, 특별 설정을 상세 표로 작성
+4. 네트워크 아키텍처|4.1 네트워크 토폴로지|4.1.2 네트워크 보안 그룹|보안 그룹 규칙을 방향, 규칙 이름, 포트, 소스/대상별로 정리한 표 작성
+4. 네트워크 아키텍처|4.2 트래픽 라우팅|4.2.1 Application Gateway 구성|기본 설정, 프론트엔드 구성, 백엔드 및 라우팅 설정을 표로 정리
+4. 네트워크 아키텍처|4.2 트래픽 라우팅|4.2.2 WAF 구성|WAF 정책과 커스텀 규칙, 관리 규칙을 YAML 코드 블록으로 작성
+4. 네트워크 아키텍처|4.3 Network Policies|4.3.1 마이크로서비스 간 통신 제어|Network Policy 기본 설정과 Ingress/Egress 규칙을 표로 정리
+4. 네트워크 아키텍처|4.4 서비스 디스커버리||각 서비스의 내부 DNS 주소, 포트, 용도를 정리한 서비스 디스커버리 표 작성
+5. 데이터 아키텍처|5.1 관리형 주 데이터베이스|5.1.1 데이터베이스 구성|기본 설정, 고가용성, 백업 및 보안 설정을 표로 정리하여 작성 (클라우드 제공자의 관리형 데이터베이스 서비스 사용: Azure Database, AWS RDS, Google Cloud SQL 등)
+5. 데이터 아키텍처|5.1 관리형 주 데이터베이스|5.1.2 읽기 전용 복제본|읽기 복제본 구성을 YAML 코드 블록으로 상세 작성
+5. 데이터 아키텍처|5.2 관리형 캐시 서비스|5.2.1 캐시 클러스터 구성|기본 설정, 클러스터 구성, 지속성 및 보안 설정을 표로 정리 (관리형 캐시 서비스 사용: Azure Cache for Redis, AWS ElastiCache, Google Cloud Memorystore 등)
+5. 데이터 아키텍처|5.2 관리형 캐시 서비스|5.2.2 캐시 전략|운영 최적화된 캐시 전략과 패턴을 YAML 코드 블록으로 작성
+5. 데이터 아키텍처|5.3 데이터 백업 및 복구|5.3.1 자동 백업 전략|주 데이터베이스와 캐시의 자동 백업 전략을 YAML 코드 블록으로 상세 작성
+6. 메시징 아키텍처|6.1 관리형 Message Queue|6.1.1 Message Queue 구성|Premium 티어 설정과 네임스페이스, 보안 설정을 YAML 코드 블록으로 작성
+6. 메시징 아키텍처|6.1 관리형 Message Queue|6.1.2 큐 및 토픽 설계|큐와 토픽의 상세 설정을 YAML 코드 블록으로 작성
+7. 보안 아키텍처|7.1 다층 보안 아키텍처|7.1.1 보안 계층 구조|L1-L4 보안 계층별 구성 요소를 YAML 코드 블록으로 상세 작성
+7. 보안 아키텍처|7.2 인증 및 권한 관리|7.2.1 클라우드 Identity 통합|클라우드 Identity 구성과 애플리케이션 등록을 YAML 코드 블록으로 작성
+7. 보안 아키텍처|7.2 인증 및 권한 관리|7.2.2 RBAC 구성|클러스터 역할과 서비스 계정을 YAML 코드 블록으로 상세 작성
+7. 보안 아키텍처|7.3 네트워크 보안|7.3.1 Private Endpoints|각 서비스별 Private Endpoint 설정을 YAML 코드 블록으로 작성
+7. 보안 아키텍처|7.4 암호화 및 키 관리|7.4.1 관리형 Key Vault 구성|Key Vault 설정과 액세스 정책, 순환 정책을 YAML 코드 블록으로 작성
+8. 모니터링 및 관측 가능성|8.1 종합 모니터링 스택|8.1.1 클라우드 모니터링 통합|Log Analytics, Application Insights, Container Insights 설정을 YAML 코드 블록으로 작성
+8. 모니터링 및 관측 가능성|8.1 종합 모니터링 스택|8.1.2 메트릭 및 알림|중요 알림과 리소스 알림 설정을 YAML 코드 블록으로 상세 작성
+8. 모니터링 및 관측 가능성|8.2 로깅 및 추적|8.2.1 중앙집중식 로깅|로그 수집 설정과 중앙 로그 시스템 쿼리를 YAML 코드 블록으로 작성
+8. 모니터링 및 관측 가능성|8.2 로깅 및 추적|8.2.2 애플리케이션 성능 모니터링|APM 설정과 커스텀 메트릭을 YAML 코드 블록으로 작성
+9. 배포 관련 컴포넌트|||CI/CD 파이프라인 구성 요소들과 각각의 역할, 보안 스캔, 롤백 정책을 표 형태로 정리
+10. 재해복구 및 고가용성|10.1 재해복구 전략|10.1.1 백업 및 복구 목표|RTO, RPO와 백업 전략을 YAML 코드 블록으로 상세 작성
+10. 재해복구 및 고가용성|10.1 재해복구 전략|10.1.2 자동 장애조치|데이터베이스, 캐시, 애플리케이션별 장애조치 설정을 YAML 코드 블록으로 작성
+10. 재해복구 및 고가용성|10.2 비즈니스 연속성|10.2.1 운영 절차|인시던트 대응, 유지보수 윈도우, 변경 관리를 YAML 코드 블록으로 작성
+11. 비용 최적화|11.1 운영환경 비용 구조|11.1.1 월간 비용 분석|구성요소별 사양, 예상 비용, 최적화 방안을 상세 표로 작성
+11. 비용 최적화|11.1 운영환경 비용 구조|11.1.2 비용 최적화 전략|컴퓨팅, 스토리지, 네트워크 영역별 최적화 방안을 YAML 코드 블록으로 작성
+11. 비용 최적화|11.2 성능 대비 비용 효율성|11.2.1 Auto Scaling 최적화|예측 스케일링과 비용 인식 스케일링을 YAML 코드 블록으로 작성
+12. 운영 가이드|12.1 일상 운영 절차|12.1.1 정기 점검 항목|일일, 주간, 월간 운영 체크리스트를 YAML 코드 블록으로 작성
+12. 운영 가이드|12.2 인시던트 대응|12.2.1 장애 대응 절차|심각도별 대응 절차를 YAML 코드 블록으로 상세 작성
+12. 운영 가이드|12.2 인시던트 대응|12.2.2 자동 복구 메커니즘|Pod 재시작, 노드 교체, 트래픽 라우팅 등 자동 복구를 YAML 코드 블록으로 작성
+13. 확장 계획|13.1 단계별 확장 로드맵|13.1.1 Phase 1-3|각 단계별 목표, 대상, 결과물을 YAML 코드 블록으로 상세 작성
+13. 확장 계획|13.2 기술적 확장성|13.2.1 수평 확장 전략|애플리케이션, 데이터베이스, 캐시 티어별 확장 전략을 YAML 코드 블록으로 작성
+14. 운영환경 특성 요약|||운영환경의 핵심 설계 원칙, 주요 성과 목표, 최적화 목표를 요약하여 기술
+```
+
+<마스터가이드>
+```
+대분류|중분류|소분류|작성가이드
+---|---|---|---
+1. 개요|1.1 설계 목적||전체 물리 아키텍처의 통합 관리 체계와 마스터 인덱스 역할 기술
+1. 개요|1.2 아키텍처 분리 원칙||개발환경과 운영환경 분리 원칙과 단계적 발전 전략 정의
+1. 개요|1.3 문서 구조||마스터 인덱스와 환경별 상세 문서 구조 및 참조 관계 명시
+1. 개요|1.4 참조 아키텍처||관련 아키텍처 문서들(HighLevel, 논리, 패턴, API)의 연관관계 명시
+2. 환경별 아키텍처 개요|2.1 환경별 특성 비교||목적, 가용성, 사용자, 확장성, 보안, 비용 등 환경별 특성을 비교 표로 작성
+2. 환경별 아키텍처 개요|2.2 환경별 세부 문서|2.2.1 개발환경 아키텍처|개발환경 문서 링크와 주요 특징, 핵심 구성을 요약하여 기술
+2. 환경별 아키텍처 개요|2.2 환경별 세부 문서|2.2.2 운영환경 아키텍처|운영환경 문서 링크와 주요 특징, 핵심 구성을 요약하여 기술
+2. 환경별 아키텍처 개요|2.3 핵심 아키텍처 결정사항|2.3.1 공통 아키텍처 원칙|서비스 메시 제거, 비동기 통신, 관리형 Identity, 다층 보안 등 공통 원칙 기술
+2. 환경별 아키텍처 개요|2.3 핵심 아키텍처 결정사항|2.3.2 환경별 차별화 전략|개발환경과 운영환경의 최적화 전략 차이점을 비교하여 기술
+3. 네트워크 아키텍처 비교|3.1 환경별 네트워크 전략|3.1.1 환경별 네트워크 전략 비교|인그레스, 네트워크, 보안, 접근 방식을 환경별로 비교한 표 작성
+3. 네트워크 아키텍처 비교|3.2 네트워크 보안 전략|3.2.1 공통 보안 원칙|Network Policies, 관리형 Identity, Private Endpoints, TLS 암호화 등 공통 보안 원칙 기술
+3. 네트워크 아키텍처 비교|3.2 네트워크 보안 전략|3.2.2 환경별 보안 수준|Network Policy, 시크릿 관리, 암호화, 웹 보안 수준을 환경별로 비교한 표 작성
+4. 데이터 아키텍처 비교|4.1 환경별 데이터 전략|4.1.1 환경별 데이터 구성 비교|주 데이터베이스와 캐시의 환경별 구성, 가용성, 비용을 비교한 상세 표 작성 (개발환경: Pod 기반 + 클라우드 스토리지, 운영환경: 관리형 서비스)
+4. 데이터 아키텍처 비교|4.2 캐시 전략 비교|4.2.1 다층 캐시 아키텍처|L1 애플리케이션 캐시와 L2 분산 캐시의 계층별 설정을 표로 정리
+4. 데이터 아키텍처 비교|4.2 캐시 전략 비교|4.2.2 환경별 캐시 특성 비교|캐시 구성, 데이터 지속성, 성능 특성을 환경별로 비교한 표 작성
+5. 보안 아키텍처 비교|5.1 다층 보안 아키텍처|5.1.1 공통 보안 계층|L1-L4 보안 계층의 보안 기술, 적용 범위, 보안 목적을 표로 정리
+5. 보안 아키텍처 비교|5.2 환경별 보안 수준|5.2.1 환경별 보안 수준 비교|인증, 네트워크, 시크릿, 암호화 영역별 보안 수준과 강화 방안을 비교한 표 작성
+6. 모니터링 및 운영|6.1 환경별 모니터링 전략|6.1.1 환경별 모니터링 도구 비교|모니터링 도구, 메트릭, 알림, 로그 수집 방식을 환경별로 비교한 표 작성
+6. 모니터링 및 운영|6.2 CI/CD 및 배포 전략|6.2.1 환경별 배포 방식 비교|배포 방식, 자동화, 테스트, 다운타임 허용도를 환경별로 비교한 표 작성
+7. 비용 분석|7.1 환경별 비용 구조|7.1.1 월간 비용 비교|구성요소별 개발환경과 운영환경 비용을 상세 비교한 표 작성
+7. 비용 분석|7.1 환경별 비용 구조|7.1.2 환경별 비용 최적화 전략 비교|컴퓨팅, 백킹서비스, 리소스 관리 최적화 방안을 환경별로 비교한 표 작성
+8. 전환 및 확장 계획|8.1 개발환경 → 운영환경 전환 체크리스트||데이터 마이그레이션, 설정 변경, 모니터링 등 전환 체크리스트를 카테고리별로 표 작성
+8. 전환 및 확장 계획|8.2 단계별 확장 로드맵||Phase 1-3 단계별 기간, 핵심 목표, 주요 작업, 사용자 지원, 가용성을 표로 정리
+9. 핵심 SLA 지표|9.1 환경별 서비스 수준 목표||가용성, 응답시간, 배포시간, 복구시간, 동시사용자, 월간비용을 환경별로 비교한 표 작성
+```
+
+[참고자료]
+- 아키텍처패턴
+- 논리아키텍처
+- 외부시퀀스설계서
+- 데이터설계서
+- HighLevel아키텍처정의서
+
+[예시]
+- 개발환경 물리아키텍처 설계서: https://raw.githubusercontent.com/cna-bootcamp/clauding-guide/refs/heads/main/samples/physical/sample-physical-architecture-dev.md
+- 운영환경 물리아키텍처 설계서: https://raw.githubusercontent.com/cna-bootcamp/clauding-guide/refs/heads/main/samples/physical/sample-physical-architecture-prod.md
+- 마스터 물리아키텍처 설계서: https://raw.githubusercontent.com/cna-bootcamp/clauding-guide/refs/heads/main/samples/physical/sample-physical-architecture.md
+- 개발환경 물리아키텍처 다이어그램: https://raw.githubusercontent.com/cna-bootcamp/clauding-guide/refs/heads/main/samples/physical/sample-physical-architecture-dev.mmd
+- 운영환경 물리아키텍처 다이어그램: https://raw.githubusercontent.com/cna-bootcamp/clauding-guide/refs/heads/main/samples/physical/sample-physical-architecture-prod.mmd
+- 개발환경 네트워크 다이어그램: https://raw.githubusercontent.com/cna-bootcamp/clauding-guide/refs/heads/main/samples/physical/sample-network-dev.mmd
+- 운영환경 네트워크 다이어그램: https://raw.githubusercontent.com/cna-bootcamp/clauding-guide/refs/heads/main/samples/physical/sample-network-prod.mmd
+
+[결과파일]
+- design/backend/physical/physical-architecture.md
+- design/backend/physical/physical-architecture-dev.md
+- design/backend/physical/physical-architecture-prod.md
+- design/backend/physical/physical-architecture-dev.mmd
+- design/backend/physical/physical-architecture-prod.mmd
+- design/backend/physical/network-dev.mmd
+- design/backend/physical/network-prod.mmd
diff --git a/claude/sample-network-dev.mmd b/claude/sample-network-dev.mmd
new file mode 100644
index 0000000..fae3278
--- /dev/null
+++ b/claude/sample-network-dev.mmd
@@ -0,0 +1,138 @@
+graph TB
+ %% 개발환경 네트워크 다이어그램
+ %% AI 기반 여행 일정 생성 서비스 - 개발환경
+
+ %% 외부 영역
+ subgraph Internet["🌐 인터넷"]
+ Developer["👨💻 개발자"]
+ QATester["🧪 QA팀"]
+ end
+
+ %% Azure 클라우드 영역
+ subgraph AzureCloud["☁️ Azure Cloud"]
+
+ %% Virtual Network
+ subgraph VNet["🏢 Virtual Network (VNet)
주소 공간: 10.0.0.0/16"]
+
+ %% AKS 서브넷
+ subgraph AKSSubnet["🎯 AKS Subnet
10.0.1.0/24"]
+
+ %% Kubernetes 클러스터
+ subgraph AKSCluster["⚙️ AKS Cluster"]
+
+ %% Ingress Controller
+ subgraph IngressController["🚪 NGINX Ingress Controller"]
+ LoadBalancer["⚖️ LoadBalancer Service
(External IP)"]
+ IngressPod["📦 Ingress Controller Pod"]
+ end
+
+ %% Application Tier
+ subgraph AppTier["🚀 Application Tier"]
+ UserService["👤 User Service
Pod"]
+ TripService["🗺️ Trip Service
Pod"]
+ AIService["🤖 AI Service
Pod"]
+ LocationService["📍 Location Service
Pod"]
+ end
+
+ %% Database Tier
+ subgraph DBTier["🗄️ Database Tier"]
+ PostgreSQL["🐘 PostgreSQL
Pod"]
+ PostgreSQLStorage["💾 hostPath Volume
(/data/postgresql)"]
+ end
+
+ %% Cache Tier
+ subgraph CacheTier["⚡ Cache Tier"]
+ Redis["🔴 Redis
Pod"]
+ end
+
+ %% Cluster Internal Services
+ subgraph ClusterServices["🔗 ClusterIP Services"]
+ UserServiceDNS["user-service:8080"]
+ TripServiceDNS["trip-service:8080"]
+ AIServiceDNS["ai-service:8080"]
+ LocationServiceDNS["location-service:8080"]
+ PostgreSQLDNS["postgresql:5432"]
+ RedisDNS["redis:6379"]
+ end
+ end
+ end
+
+ %% Service Bus 서브넷
+ subgraph ServiceBusSubnet["📨 Service Bus Subnet
10.0.2.0/24"]
+ ServiceBus["📮 Azure Service Bus
(Basic Tier)"]
+
+ subgraph Queues["📬 Message Queues"]
+ AIQueue["🤖 ai-schedule-generation"]
+ LocationQueue["📍 location-search"]
+ NotificationQueue["🔔 notification"]
+ end
+ end
+ end
+ end
+
+ %% 네트워크 연결 관계
+
+ %% 외부에서 클러스터로의 접근
+ Developer -->|"HTTPS:443
(개발용 도메인)"| LoadBalancer
+ QATester -->|"API 호출/테스트"| LoadBalancer
+
+ %% Ingress Controller 내부 흐름
+ LoadBalancer -->|"트래픽 라우팅"| IngressPod
+
+ %% Ingress에서 Application Services로
+ IngressPod -->|"/api/users/**"| UserServiceDNS
+ IngressPod -->|"/api/trips/**"| TripServiceDNS
+ IngressPod -->|"/api/ai/**"| AIServiceDNS
+ IngressPod -->|"/api/locations/**"| LocationServiceDNS
+
+ %% ClusterIP Services에서 실제 Pod로
+ UserServiceDNS -->|"내부 로드밸런싱"| UserService
+ TripServiceDNS -->|"내부 로드밸런싱"| TripService
+ AIServiceDNS -->|"내부 로드밸런싱"| AIService
+ LocationServiceDNS -->|"내부 로드밸런싱"| LocationService
+
+ %% Application Services에서 Database로
+ UserService -->|"DB 연결
TCP:5432"| PostgreSQLDNS
+ TripService -->|"DB 연결
TCP:5432"| PostgreSQLDNS
+ AIService -->|"DB 연결
TCP:5432"| PostgreSQLDNS
+ LocationService -->|"DB 연결
TCP:5432"| PostgreSQLDNS
+
+ %% Application Services에서 Cache로
+ UserService -->|"캐시 연결
TCP:6379"| RedisDNS
+ TripService -->|"캐시 연결
TCP:6379"| RedisDNS
+ AIService -->|"캐시 연결
TCP:6379"| RedisDNS
+ LocationService -->|"캐시 연결
TCP:6379"| RedisDNS
+
+ %% ClusterIP Services에서 실제 Pod로 (Database/Cache)
+ PostgreSQLDNS -->|"DB 요청 처리"| PostgreSQL
+ RedisDNS -->|"캐시 요청 처리"| Redis
+
+ %% Storage 연결
+ PostgreSQL -->|"데이터 영속화"| PostgreSQLStorage
+
+ %% Service Bus 연결
+ AIService -->|"비동기 메시징
HTTPS/AMQP"| ServiceBus
+ LocationService -->|"비동기 메시징
HTTPS/AMQP"| ServiceBus
+ TripService -->|"알림 메시징
HTTPS/AMQP"| ServiceBus
+
+ ServiceBus --> AIQueue
+ ServiceBus --> LocationQueue
+ ServiceBus --> NotificationQueue
+
+ %% 스타일 정의
+ classDef azureStyle fill:#0078D4,stroke:#fff,stroke-width:2px,color:#fff
+ classDef k8sStyle fill:#326CE5,stroke:#fff,stroke-width:2px,color:#fff
+ classDef appStyle fill:#28A745,stroke:#fff,stroke-width:2px,color:#fff
+ classDef dbStyle fill:#DC3545,stroke:#fff,stroke-width:2px,color:#fff
+ classDef cacheStyle fill:#FF6B35,stroke:#fff,stroke-width:2px,color:#fff
+ classDef serviceStyle fill:#6610F2,stroke:#fff,stroke-width:2px,color:#fff
+ classDef queueStyle fill:#FD7E14,stroke:#fff,stroke-width:2px,color:#fff
+
+ %% 스타일 적용
+ class AzureCloud,VNet azureStyle
+ class AKSCluster,AKSSubnet,IngressController k8sStyle
+ class AppTier,UserService,TripService,AIService,LocationService appStyle
+ class DBTier,PostgreSQL,PostgreSQLStorage dbStyle
+ class CacheTier,Redis cacheStyle
+ class ClusterServices,UserServiceDNS,TripServiceDNS,AIServiceDNS,LocationServiceDNS,PostgreSQLDNS,RedisDNS serviceStyle
+ class ServiceBus,ServiceBusSubnet,Queues,AIQueue,LocationQueue,NotificationQueue queueStyle
\ No newline at end of file
diff --git a/claude/sample-network-prod.mmd b/claude/sample-network-prod.mmd
new file mode 100644
index 0000000..21ae21e
--- /dev/null
+++ b/claude/sample-network-prod.mmd
@@ -0,0 +1,190 @@
+graph TB
+ %% 운영환경 네트워크 다이어그램
+ %% AI 기반 여행 일정 생성 서비스 - 운영환경
+
+ %% 외부 영역
+ subgraph Internet["🌐 인터넷"]
+ Users["👥 실사용자
(1만~10만 명)"]
+ CDN["🌍 Azure Front Door
+ CDN"]
+ end
+
+ %% Azure 클라우드 영역
+ subgraph AzureCloud["☁️ Azure Cloud (운영환경)"]
+
+ %% Virtual Network
+ subgraph VNet["🏢 Virtual Network (VNet)
주소 공간: 10.0.0.0/16"]
+
+ %% Gateway Subnet
+ subgraph GatewaySubnet["🚪 Gateway Subnet
10.0.4.0/24"]
+ subgraph AppGateway["🛡️ Application Gateway + WAF"]
+ PublicIP["📍 Public IP
(고정)"]
+ PrivateIP["📍 Private IP
(10.0.4.10)"]
+ WAF["🛡️ WAF
(OWASP CRS 3.2)"]
+ RateLimiter["⏱️ Rate Limiting
(100 req/min/IP)"]
+ end
+ end
+
+ %% Application Subnet
+ subgraph AppSubnet["🎯 Application Subnet
10.0.1.0/24"]
+
+ %% AKS 클러스터
+ subgraph AKSCluster["⚙️ AKS Premium Cluster
(Multi-Zone)"]
+
+ %% System Node Pool
+ subgraph SystemNodes["🔧 System Node Pool"]
+ SystemNode1["📦 System Node 1
(Zone 1)"]
+ SystemNode2["📦 System Node 2
(Zone 2)"]
+ SystemNode3["📦 System Node 3
(Zone 3)"]
+ end
+
+ %% Application Node Pool
+ subgraph AppNodes["🚀 Application Node Pool"]
+ AppNode1["📦 App Node 1
(Zone 1)"]
+ AppNode2["📦 App Node 2
(Zone 2)"]
+ AppNode3["📦 App Node 3
(Zone 3)"]
+ end
+
+ %% Application Services (High Availability)
+ subgraph AppServices["🚀 Application Services"]
+ UserServiceHA["👤 User Service
(3 replicas, HPA)"]
+ TripServiceHA["🗺️ Trip Service
(3 replicas, HPA)"]
+ AIServiceHA["🤖 AI Service
(2 replicas, HPA)"]
+ LocationServiceHA["📍 Location Service
(2 replicas, HPA)"]
+ end
+
+ %% Internal Load Balancer
+ subgraph InternalLB["⚖️ Internal Services"]
+ UserServiceLB["user-service:8080"]
+ TripServiceLB["trip-service:8080"]
+ AIServiceLB["ai-service:8080"]
+ LocationServiceLB["location-service:8080"]
+ end
+ end
+ end
+
+ %% Database Subnet
+ subgraph DBSubnet["🗄️ Database Subnet
10.0.2.0/24"]
+ subgraph AzurePostgreSQL["🐘 Azure PostgreSQL Flexible Server"]
+ PGPrimary["📊 Primary Server
(Zone 1)"]
+ PGSecondary["📊 Read Replica
(Zone 2)"]
+ PGBackup["💾 Automated Backup
(Point-in-time Recovery)"]
+ end
+ end
+
+ %% Cache Subnet
+ subgraph CacheSubnet["⚡ Cache Subnet
10.0.3.0/24"]
+ subgraph AzureRedis["🔴 Azure Cache for Redis Premium"]
+ RedisPrimary["⚡ Primary Cache
(Zone 1)"]
+ RedisSecondary["⚡ Secondary Cache
(Zone 2)"]
+ RedisCluster["🔗 Redis Cluster
(High Availability)"]
+ end
+ end
+ end
+
+ %% Service Bus (Premium)
+ subgraph ServiceBus["📨 Azure Service Bus Premium"]
+ ServiceBusHA["📮 Service Bus Namespace
(sb-tripgen-prod)"]
+
+ subgraph QueuesHA["📬 Premium Message Queues"]
+ AIQueueHA["🤖 ai-schedule-generation
(Partitioned, 16GB)"]
+ LocationQueueHA["📍 location-search
(Partitioned, 16GB)"]
+ NotificationQueueHA["🔔 notification
(Partitioned, 16GB)"]
+ end
+ end
+
+ %% Private Endpoints
+ subgraph PrivateEndpoints["🔒 Private Endpoints"]
+ PGPrivateEndpoint["🔐 PostgreSQL
Private Endpoint"]
+ RedisPrivateEndpoint["🔐 Redis
Private Endpoint"]
+ ServiceBusPrivateEndpoint["🔐 Service Bus
Private Endpoint"]
+ end
+ end
+
+ %% 네트워크 연결 관계
+
+ %% 외부에서 Azure로의 접근
+ Users -->|"HTTPS 요청"| CDN
+ CDN -->|"글로벌 가속"| PublicIP
+
+ %% Application Gateway 내부 흐름
+ PublicIP --> WAF
+ WAF --> RateLimiter
+ RateLimiter --> PrivateIP
+
+ %% Application Gateway에서 AKS로
+ PrivateIP -->|"/api/users/**
NodePort 30080"| UserServiceLB
+ PrivateIP -->|"/api/trips/**
NodePort 30081"| TripServiceLB
+ PrivateIP -->|"/api/ai/**
NodePort 30082"| AIServiceLB
+ PrivateIP -->|"/api/locations/**
NodePort 30083"| LocationServiceLB
+
+ %% Load Balancer에서 실제 서비스로
+ UserServiceLB -->|"고가용성 라우팅"| UserServiceHA
+ TripServiceLB -->|"고가용성 라우팅"| TripServiceHA
+ AIServiceLB -->|"고가용성 라우팅"| AIServiceHA
+ LocationServiceLB -->|"고가용성 라우팅"| LocationServiceHA
+
+ %% 서비스 배치 (Multi-Zone)
+ UserServiceHA -.-> AppNode1
+ UserServiceHA -.-> AppNode2
+ UserServiceHA -.-> AppNode3
+
+ TripServiceHA -.-> AppNode1
+ TripServiceHA -.-> AppNode2
+ TripServiceHA -.-> AppNode3
+
+ %% Application Services에서 Database로 (Private Endpoint)
+ UserServiceHA -->|"Private Link
TCP:5432"| PGPrivateEndpoint
+ TripServiceHA -->|"Private Link
TCP:5432"| PGPrivateEndpoint
+ AIServiceHA -->|"Private Link
TCP:5432"| PGPrivateEndpoint
+ LocationServiceHA -->|"Private Link
TCP:5432"| PGPrivateEndpoint
+
+ %% Private Endpoint에서 실제 서비스로
+ PGPrivateEndpoint --> PGPrimary
+ PGPrivateEndpoint --> PGSecondary
+
+ %% Application Services에서 Cache로 (Private Endpoint)
+ UserServiceHA -->|"Private Link
TCP:6379"| RedisPrivateEndpoint
+ TripServiceHA -->|"Private Link
TCP:6379"| RedisPrivateEndpoint
+ AIServiceHA -->|"Private Link
TCP:6379"| RedisPrivateEndpoint
+ LocationServiceHA -->|"Private Link
TCP:6379"| RedisPrivateEndpoint
+
+ %% Private Endpoint에서 Redis로
+ RedisPrivateEndpoint --> RedisPrimary
+ RedisPrivateEndpoint --> RedisSecondary
+
+ %% High Availability 연결
+ PGPrimary -.->|"복제"| PGSecondary
+ RedisPrimary -.->|"HA 동기화"| RedisSecondary
+ PGPrimary -.->|"자동 백업"| PGBackup
+
+ %% Service Bus 연결 (Private Endpoint)
+ AIServiceHA -->|"Private Link
HTTPS/AMQP"| ServiceBusPrivateEndpoint
+ LocationServiceHA -->|"Private Link
HTTPS/AMQP"| ServiceBusPrivateEndpoint
+ TripServiceHA -->|"Private Link
HTTPS/AMQP"| ServiceBusPrivateEndpoint
+
+ ServiceBusPrivateEndpoint --> ServiceBusHA
+ ServiceBusHA --> AIQueueHA
+ ServiceBusHA --> LocationQueueHA
+ ServiceBusHA --> NotificationQueueHA
+
+ %% 스타일 정의
+ classDef azureStyle fill:#0078D4,stroke:#fff,stroke-width:2px,color:#fff
+ classDef k8sStyle fill:#326CE5,stroke:#fff,stroke-width:2px,color:#fff
+ classDef appStyle fill:#28A745,stroke:#fff,stroke-width:2px,color:#fff
+ classDef dbStyle fill:#DC3545,stroke:#fff,stroke-width:2px,color:#fff
+ classDef cacheStyle fill:#FF6B35,stroke:#fff,stroke-width:2px,color:#fff
+ classDef serviceStyle fill:#6610F2,stroke:#fff,stroke-width:2px,color:#fff
+ classDef queueStyle fill:#FD7E14,stroke:#fff,stroke-width:2px,color:#fff
+ classDef securityStyle fill:#E83E8C,stroke:#fff,stroke-width:2px,color:#fff
+ classDef haStyle fill:#20C997,stroke:#fff,stroke-width:2px,color:#fff
+
+ %% 스타일 적용
+ class AzureCloud,VNet azureStyle
+ class AKSCluster,AppSubnet,SystemNodes,AppNodes k8sStyle
+ class AppServices,UserServiceHA,TripServiceHA,AIServiceHA,LocationServiceHA appStyle
+ class DBSubnet,AzurePostgreSQL,PGPrimary,PGSecondary,PGBackup dbStyle
+ class CacheSubnet,AzureRedis,RedisPrimary,RedisSecondary,RedisCluster cacheStyle
+ class InternalLB,UserServiceLB,TripServiceLB,AIServiceLB,LocationServiceLB serviceStyle
+ class ServiceBus,ServiceBusHA,QueuesHA,AIQueueHA,LocationQueueHA,NotificationQueueHA queueStyle
+ class AppGateway,WAF,RateLimiter,PrivateEndpoints,PGPrivateEndpoint,RedisPrivateEndpoint,ServiceBusPrivateEndpoint securityStyle
+ class CDN,SystemNode1,SystemNode2,SystemNode3,AppNode1,AppNode2,AppNode3 haStyle
\ No newline at end of file
diff --git a/claude/sample-physical-architecture-dev.mmd b/claude/sample-physical-architecture-dev.mmd
new file mode 100644
index 0000000..ffe2e94
--- /dev/null
+++ b/claude/sample-physical-architecture-dev.mmd
@@ -0,0 +1,49 @@
+graph TB
+ %% Development Environment Physical Architecture
+ %% Core Flow: Users → Ingress → Services → Database
+
+ Users[Mobile/Web Users] --> Ingress[Kubernetes Ingress Controller]
+
+ subgraph "Azure Kubernetes Service - Development"
+ Ingress --> UserService[User Service Pod]
+ Ingress --> TravelService[Travel Service Pod]
+ Ingress --> ScheduleService[AI Service Pod]
+ Ingress --> LocationService[Location Service Pod]
+
+ UserService --> PostgreSQL[PostgreSQL Pod
16GB Storage]
+ TravelService --> PostgreSQL
+ ScheduleService --> PostgreSQL
+ LocationService --> PostgreSQL
+
+ UserService --> Redis[Redis Pod
Memory Cache]
+ TravelService --> Redis
+ ScheduleService --> Redis
+ LocationService --> Redis
+
+ TravelService --> ServiceBus[Azure Service Bus
Basic Tier]
+ ScheduleService --> ServiceBus
+ LocationService --> ServiceBus
+ end
+
+ %% External APIs
+ ExternalAPI[External APIs
OpenAI, Maps, Weather] --> ScheduleService
+ ExternalAPI --> LocationService
+
+ %% Essential Azure Services
+ AKS --> ContainerRegistry[Azure Container Registry]
+
+ %% Node Configuration
+ subgraph "Node Pool"
+ NodePool[2x Standard B2s
2 vCPU, 4GB RAM]
+ end
+
+ %% Styling
+ classDef azureService fill:#0078d4,stroke:#333,stroke-width:2px,color:#fff
+ classDef microservice fill:#ff6b6b,stroke:#333,stroke-width:2px,color:#fff
+ classDef database fill:#4ecdc4,stroke:#333,stroke-width:2px,color:#fff
+ classDef external fill:#95e1d3,stroke:#333,stroke-width:2px,color:#333
+
+ class Ingress,ServiceBus,ContainerRegistry azureService
+ class UserService,TravelService,ScheduleService,LocationService microservice
+ class PostgreSQL,Redis database
+ class Users,ExternalAPI external
\ No newline at end of file
diff --git a/claude/sample-physical-architecture-prod.mmd b/claude/sample-physical-architecture-prod.mmd
new file mode 100644
index 0000000..87ed907
--- /dev/null
+++ b/claude/sample-physical-architecture-prod.mmd
@@ -0,0 +1,184 @@
+graph TB
+ %% Production Environment Physical Architecture
+ %% Enterprise-grade Azure Cloud Architecture
+
+ Users[Mobile/Web Users
1만~10만 명] --> CDN[Azure Front Door
+ CDN]
+
+ subgraph "Azure Cloud - Production Environment"
+ CDN --> AppGateway[Application Gateway
+ WAF v2
Zone Redundant]
+
+ subgraph "VNet (10.0.0.0/16)"
+ subgraph "Gateway Subnet (10.0.4.0/24)"
+ AppGateway
+ end
+
+ subgraph "Application Subnet (10.0.1.0/24)"
+ subgraph "AKS Premium Cluster - Multi-Zone"
+ direction TB
+
+ subgraph "System Node Pool"
+ SystemNode1[System Node 1
Zone 1
D2s_v3]
+ SystemNode2[System Node 2
Zone 2
D2s_v3]
+ SystemNode3[System Node 3
Zone 3
D2s_v3]
+ end
+
+ subgraph "Application Node Pool"
+ AppNode1[App Node 1
Zone 1
D4s_v3]
+ AppNode2[App Node 2
Zone 2
D4s_v3]
+ AppNode3[App Node 3
Zone 3
D4s_v3]
+ end
+
+ subgraph "Application Services"
+ UserService[User Service
3 replicas, HPA
2-10 replicas]
+ TripService[Trip Service
3 replicas, HPA
3-15 replicas]
+ AIService[AI Service
2 replicas, HPA
2-8 replicas]
+ LocationService[Location Service
2 replicas, HPA
2-10 replicas]
+ end
+ end
+ end
+
+ AppGateway -->|NodePort 30080-30083| UserService
+ AppGateway -->|NodePort 30080-30083| TripService
+ AppGateway -->|NodePort 30080-30083| AIService
+ AppGateway -->|NodePort 30080-30083| LocationService
+
+ subgraph "Database Subnet (10.0.2.0/24)"
+ PostgreSQLPrimary[Azure PostgreSQL
Flexible Server
Primary - Zone 1
GP_Standard_D4s_v3]
+ PostgreSQLReplica[PostgreSQL
Read Replica
Zone 2]
+ PostgreSQLBackup[Automated Backup
Point-in-time Recovery
35 days retention]
+ end
+
+ subgraph "Cache Subnet (10.0.3.0/24)"
+ RedisPrimary[Azure Redis Premium
P2 - 6GB
Primary - Zone 1]
+ RedisSecondary[Redis Secondary
Zone 2
HA Enabled]
+ end
+ end
+
+ subgraph "Service Bus Premium"
+ ServiceBusPremium[Azure Service Bus
Premium Tier
sb-tripgen-prod]
+
+ subgraph "Message Queues"
+ AIQueue[ai-schedule-generation
Partitioned, 16GB]
+ LocationQueue[location-search
Partitioned, 16GB]
+ NotificationQueue[notification
Partitioned, 16GB]
+ end
+ end
+
+ subgraph "Private Endpoints"
+ PostgreSQLEndpoint[PostgreSQL
Private Endpoint
10.0.2.10]
+ RedisEndpoint[Redis
Private Endpoint
10.0.3.10]
+ ServiceBusEndpoint[Service Bus
Private Endpoint
10.0.5.10]
+ KeyVaultEndpoint[Key Vault
Private Endpoint
10.0.6.10]
+ end
+
+ subgraph "Security & Management"
+ KeyVault[Azure Key Vault
Premium
HSM-backed]
+ AAD[Azure Active Directory
RBAC Integration]
+ Monitor[Azure Monitor
+ Application Insights
Log Analytics]
+ end
+
+ %% Private Link Connections
+ UserService -->|Private Link| PostgreSQLEndpoint
+ TripService -->|Private Link| PostgreSQLEndpoint
+ AIService -->|Private Link| PostgreSQLEndpoint
+ LocationService -->|Private Link| PostgreSQLEndpoint
+
+ PostgreSQLEndpoint --> PostgreSQLPrimary
+ PostgreSQLEndpoint --> PostgreSQLReplica
+
+ UserService -->|Private Link| RedisEndpoint
+ TripService -->|Private Link| RedisEndpoint
+ AIService -->|Private Link| RedisEndpoint
+ LocationService -->|Private Link| RedisEndpoint
+
+ RedisEndpoint --> RedisPrimary
+ RedisEndpoint --> RedisSecondary
+
+ AIService -->|Private Link| ServiceBusEndpoint
+ LocationService -->|Private Link| ServiceBusEndpoint
+ TripService -->|Private Link| ServiceBusEndpoint
+
+ ServiceBusEndpoint --> ServiceBusPremium
+ ServiceBusPremium --> AIQueue
+ ServiceBusPremium --> LocationQueue
+ ServiceBusPremium --> NotificationQueue
+
+ %% High Availability Connections
+ PostgreSQLPrimary -.->|Replication| PostgreSQLReplica
+ PostgreSQLPrimary -.->|Auto Backup| PostgreSQLBackup
+ RedisPrimary -.->|HA Sync| RedisSecondary
+
+ %% Security Connections
+ UserService -.->|Managed Identity| KeyVaultEndpoint
+ TripService -.->|Managed Identity| KeyVaultEndpoint
+ AIService -.->|Managed Identity| KeyVaultEndpoint
+ LocationService -.->|Managed Identity| KeyVaultEndpoint
+
+ KeyVaultEndpoint --> KeyVault
+
+ UserService -.->|RBAC| AAD
+ TripService -.->|RBAC| AAD
+ AIService -.->|RBAC| AAD
+ LocationService -.->|RBAC| AAD
+
+ %% Monitoring Connections
+ UserService -.->|Telemetry| Monitor
+ TripService -.->|Telemetry| Monitor
+ AIService -.->|Telemetry| Monitor
+ LocationService -.->|Telemetry| Monitor
+ end
+
+ %% External Integrations
+ subgraph "External Services"
+ ExternalAPI[External APIs
OpenAI GPT-4 Turbo
Google Maps API
OpenWeatherMap API]
+ end
+
+ %% External Connections
+ ExternalAPI -->|HTTPS/TLS 1.3| AIService
+ ExternalAPI -->|HTTPS/TLS 1.3| LocationService
+
+ %% DevOps & CI/CD
+ subgraph "DevOps Infrastructure"
+ GitHubActions[GitHub Actions
Enterprise CI/CD]
+ ArgoCD[ArgoCD
GitOps Deployment
HA Mode]
+ ContainerRegistry[Azure Container Registry
Premium Tier
Geo-replicated]
+ end
+
+ %% DevOps Connections
+ GitHubActions -->|Build & Push| ContainerRegistry
+ ArgoCD -->|Deploy| UserService
+ ArgoCD -->|Deploy| TripService
+ ArgoCD -->|Deploy| AIService
+ ArgoCD -->|Deploy| LocationService
+
+ %% Backup & DR
+ subgraph "Backup & Disaster Recovery"
+ BackupVault[Azure Backup Vault
GRS - 99.999999999%]
+ DRSite[DR Site
Secondary Region
Korea Central]
+ end
+
+ PostgreSQLPrimary -.->|Automated Backup| BackupVault
+ RedisPrimary -.->|Data Persistence| BackupVault
+ ContainerRegistry -.->|Image Backup| BackupVault
+ BackupVault -.->|Geo-replication| DRSite
+
+ %% Styling
+ classDef azureService fill:#0078d4,stroke:#333,stroke-width:2px,color:#fff
+ classDef microservice fill:#28a745,stroke:#333,stroke-width:2px,color:#fff
+ classDef database fill:#dc3545,stroke:#333,stroke-width:2px,color:#fff
+ classDef security fill:#ffc107,stroke:#333,stroke-width:2px,color:#333
+ classDef external fill:#17a2b8,stroke:#333,stroke-width:2px,color:#fff
+ classDef devops fill:#6f42c1,stroke:#333,stroke-width:2px,color:#fff
+ classDef backup fill:#e83e8c,stroke:#333,stroke-width:2px,color:#fff
+ classDef privateEndpoint fill:#fd7e14,stroke:#333,stroke-width:2px,color:#fff
+ classDef nodePool fill:#20c997,stroke:#333,stroke-width:2px,color:#fff
+
+ class CDN,AppGateway,ServiceBusPremium,ContainerRegistry,Monitor,AAD azureService
+ class UserService,TripService,AIService,LocationService microservice
+ class PostgreSQLPrimary,PostgreSQLReplica,PostgreSQLBackup,RedisPrimary,RedisSecondary database
+ class KeyVault,KeyVaultEndpoint security
+ class Users,ExternalAPI external
+ class GitHubActions,ArgoCD devops
+ class BackupVault,DRSite backup
+ class PostgreSQLEndpoint,RedisEndpoint,ServiceBusEndpoint privateEndpoint
+ class SystemNode1,SystemNode2,SystemNode3,AppNode1,AppNode2,AppNode3 nodePool
\ No newline at end of file
diff --git a/claude/sample-physical-architecture.md b/claude/sample-physical-architecture.md
new file mode 100644
index 0000000..27662e6
--- /dev/null
+++ b/claude/sample-physical-architecture.md
@@ -0,0 +1,268 @@
+# 물리 아키텍처 설계서 - 마스터 인덱스
+
+## 1. 개요
+
+### 1.1 설계 목적
+- AI 기반 여행 일정 생성 서비스의 Azure Cloud 기반 물리 아키텍처 설계
+- 개발환경과 운영환경의 체계적인 아키텍처 분리 및 관리
+- 환경별 특화 구성과 단계적 확장 전략 제시
+
+### 1.2 아키텍처 분리 원칙
+- **환경별 특화**: 개발환경과 운영환경의 목적에 맞는 최적화
+- **단계적 발전**: 개발→운영 단계적 아키텍처 진화
+- **비용 효율성**: 환경별 비용 최적화 전략
+- **운영 단순성**: 환경별 복잡도 적정 수준 유지
+
+### 1.3 문서 구조
+```
+physical-architecture.md (마스터 인덱스)
+├── physical-architecture-dev.md (개발환경)
+└── physical-architecture-prod.md (운영환경)
+```
+
+### 1.4 참조 아키텍처
+- HighLevel아키텍처정의서: design/high-level-architecture.md
+- 논리아키텍처: design/backend/logical/logical-architecture.md
+- 아키텍처패턴: design/pattern/아키텍처패턴.md
+- API설계서: design/backend/api/*.yaml
+
+## 2. 환경별 아키텍처 개요
+
+### 2.1 환경별 특성 비교
+
+| 구분 | 개발환경 | 운영환경 |
+|------|----------|----------|
+| **목적** | MVP 개발/검증 | 실제 서비스 운영 |
+| **가용성** | 95% | 99.9% |
+| **사용자** | 개발팀(5명) | 실사용자(1만~10만) |
+| **확장성** | 고정 리소스 | 자동 스케일링 |
+| **보안** | 기본 수준 | 엔터프라이즈급 |
+| **비용** | 최소화($150/월) | 최적화($2,650/월) |
+| **복잡도** | 단순 | 고도화 |
+
+### 2.2 환경별 세부 문서
+
+#### 2.2.1 개발환경 아키텍처
+📄 **[물리 아키텍처 설계서 - 개발환경](./physical-architecture-dev.md)**
+
+**주요 특징:**
+- **비용 최적화**: Spot Instance, 로컬 스토리지 활용
+- **개발 편의성**: 복잡한 설정 최소화, 빠른 배포
+- **단순한 보안**: 기본 Network Policy, JWT 검증
+- **Pod 기반 백킹서비스**: PostgreSQL, Redis Pod 배포
+
+**핵심 구성:**
+📄 **[개발환경 물리 아키텍처 다이어그램](./physical-architecture-dev.mmd)**
+- NGINX Ingress → AKS Basic → Pod Services 구조
+- Application Pods, PostgreSQL Pod, Redis Pod 배치
+
+#### 2.2.2 운영환경 아키텍처
+📄 **[물리 아키텍처 설계서 - 운영환경](./physical-architecture-prod.md)**
+
+**주요 특징:**
+- **고가용성**: Multi-Zone 배포, 자동 장애조치
+- **확장성**: HPA 기반 자동 스케일링 (10배 확장)
+- **엔터프라이즈 보안**: 다층 보안, Private Endpoint
+- **관리형 서비스**: Azure Database, Cache for Redis
+
+**핵심 구성:**
+📄 **[운영환경 물리 아키텍처 다이어그램](./physical-architecture-prod.mmd)**
+- Azure Front Door → App Gateway + WAF → AKS Premium 구조
+- Multi-Zone Apps, Azure PostgreSQL, Azure Redis Premium 배치
+
+### 2.3 핵심 아키텍처 결정사항
+
+#### 2.3.1 공통 아키텍처 원칙
+- **서비스 메시 제거**: Istio 대신 Kubernetes Network Policies 사용
+- **비동기 통신 중심**: 직접적인 서비스 간 호출 최소화
+- **Managed Identity**: 키 없는 인증으로 보안 강화
+- **다층 보안**: L1(Network) → L2(Gateway) → L3(Identity) → L4(Data)
+
+#### 2.3.2 환경별 차별화 전략
+
+**개발환경 최적화:**
+- 개발 속도와 비용 효율성 우선
+- 단순한 구성으로 운영 부담 최소화
+- Pod 기반 백킹서비스로 의존성 제거
+
+**운영환경 최적화:**
+- 가용성과 확장성 우선
+- 관리형 서비스로 운영 안정성 확보
+- 엔터프라이즈급 보안 및 모니터링
+
+## 3. 네트워크 아키텍처 비교
+
+### 3.1 환경별 네트워크 전략
+
+#### 3.1.1 환경별 네트워크 전략 비교
+
+| 구성 요소 | 개발환경 | 운영환경 | 비교 |
+|-----------|----------|----------|------|
+| **인그레스** | NGINX Ingress Controller | Azure Application Gateway + WAF | 운영환경에서 WAF 보안 강화 |
+| **네트워크** | 단일 서브넷 구성 | 다중 서브넷 (Application/Database/Cache) | 운영환경에서 계층적 분리 |
+| **보안** | 기본 Network Policy | Private Endpoint, NSG 강화 | 운영환경에서 엔터프라이즈급 보안 |
+| **접근** | 인터넷 직접 접근 허용 | Private Link 기반 보안 접근 | 운영환경에서 보안 접근 제한 |
+
+### 3.2 네트워크 보안 전략
+
+#### 3.2.1 공통 보안 원칙
+- **Network Policies**: Pod 간 통신 제어
+- **Managed Identity**: 키 없는 인증
+- **Private Endpoints**: Azure 서비스 보안 접근
+- **TLS 암호화**: 모든 외부 통신
+
+#### 3.2.2 환경별 보안 수준
+
+| 보안 요소 | 개발환경 | 운영환경 | 보안 수준 |
+|-----------|----------|----------|----------|
+| **Network Policy** | 기본 (개발 편의성 고려) | 엄격한 적용 | 운영환경에서 강화 |
+| **시크릿 관리** | Kubernetes Secrets | Azure Key Vault | 운영환경에서 HSM 보안 |
+| **암호화** | HTTPS 인그레스 레벨 | End-to-End TLS 1.3 | 운영환경에서 완전 암호화 |
+| **웹 보안** | - | WAF + DDoS 보호 | 운영환경 전용 |
+
+## 4. 데이터 아키텍처 비교
+
+### 4.1 환경별 데이터 전략
+
+#### 4.1.1 환경별 데이터 구성 비교
+
+| 데이터 서비스 | 개발환경 | 운영환경 | 가용성 | 비용 |
+|-------------|----------|----------|---------|------|
+| **PostgreSQL** | Kubernetes Pod (hostPath) | Azure Database Flexible Server | 95% vs 99.9% | 무료 vs $450/월 |
+| **Redis** | Memory Only Pod | Azure Cache Premium (Cluster) | 단일 vs 클러스터 | 무료 vs $250/월 |
+| **백업** | 수동 (주 1회) | 자동 (35일 보존) | 로컬 vs 지역간 복제 | - |
+| **데이터 지속성** | 재시작 시 손실 가능 | Zone Redundant | - | - |
+
+### 4.2 캐시 전략 비교
+
+#### 4.2.1 다층 캐시 아키텍처
+| 캐시 계층 | 캐시 타입 | TTL | 개발환경 설정 | 운영환경 설정 | 용도 |
+|----------|----------|-----|-------------|-------------|------|
+| **L1_Application** | Caffeine Cache | 5분 | max_entries: 1000 | max_entries: 2000 | 애플리케이션 레벨 로컬 캐시 |
+| **L2_Distributed** | Redis | 30분 | cluster_mode: false | cluster_mode: true | 분산 캐시, eviction_policy: allkeys-lru |
+
+#### 4.2.2 환경별 캐시 특성 비교
+
+| 캐시 특성 | 개발환경 | 운영환경 | 비고 |
+|-----------|----------|----------|------|
+| **Redis 구성** | 단일 Pod | Premium 클러스터 | 운영환경에서 고가용성 |
+| **데이터 지속성** | 메모리 전용 | 지속성 백업 | 운영환경에서 데이터 보장 |
+| **성능** | 기본 성능 | 최적화된 성능 | 운영환경에서 향상된 처리 능력 |
+
+## 5. 보안 아키텍처 비교
+
+### 5.1 다층 보안 아키텍처
+
+#### 5.1.1 공통 보안 계층
+| 보안 계층 | 보안 기술 | 적용 범위 | 보안 목적 |
+|----------|----------|----------|----------|
+| **L1_Network** | Kubernetes Network Policies | Pod-to-Pod 통신 제어 | 내부 네트워크 마이크로 세그먼테이션 |
+| **L2_Gateway** | API Gateway JWT 검증 | 외부 요청 인증/인가 | API 레벨 인증 및 인가 제어 |
+| **L3_Identity** | Azure Managed Identity | Azure 서비스 접근 | 클라우드 리소스 안전한 접근 |
+| **L4_Data** | Private Link + Key Vault | 데이터 암호화 및 비밀 관리 | 엔드투엔드 데이터 보호 |
+
+### 5.2 환경별 보안 수준
+
+#### 5.2.1 환경별 보안 수준 비교
+
+| 보안 영역 | 개발환경 | 운영환경 | 보안 강화 |
+|-----------|----------|----------|----------|
+| **인증** | JWT (고정 시크릿) | Azure AD + Managed Identity | 운영환경에서 엔터프라이즈 인증 |
+| **네트워크** | 기본 Network Policy | 엄격한 Network Policy + Private Endpoint | 운영환경에서 네트워크 격리 강화 |
+| **시크릿** | Kubernetes Secrets | Azure Key Vault (HSM) | 운영환경에서 하드웨어 보안 모듈 |
+| **암호화** | HTTPS (인그레스 레벨) | End-to-End TLS 1.3 | 운영환경에서 전 구간 암호화 |
+
+## 6. 모니터링 및 운영
+
+### 6.1 환경별 모니터링 전략
+
+#### 6.1.1 환경별 모니터링 도구 비교
+
+| 모니터링 요소 | 개발환경 | 운영환경 | 기능 차이 |
+|-------------|----------|----------|----------|
+| **도구** | Kubernetes Dashboard, kubectl logs | Azure Monitor, Application Insights | 운영환경에서 전문 APM 도구 |
+| **메트릭** | 기본 Pod/Node 메트릭 | 포괄적 APM, 비즈니스 메트릭 | 운영환경에서 비즈니스 인사이트 |
+| **알림** | 기본 알림 (Pod 재시작) | 다단계 알림 (PagerDuty, Teams) | 운영환경에서 전문 알림 체계 |
+| **로그** | 로컬 파일시스템 (7일) | Log Analytics (90일) | 운영환경에서 장기 보존 |
+
+### 6.2 CI/CD 및 배포 전략
+
+#### 6.2.1 환별별 배포 방식
+
+#### 6.2.1 환경별 배포 방식 비교
+
+| 배포 요소 | 개발환경 | 운영환경 | 안정성 차이 |
+|-----------|----------|----------|----------|
+| **배포 방식** | Rolling Update | Blue-Green Deployment | 운영환경에서 무중단 배포 |
+| **자동화** | develop 브랜치 자동 | tag 생성 + 수동 승인 | 운영환경에서 더 신중한 배포 |
+| **테스트** | 기본 헬스체크 | 종합 품질 게이트 (80% 커버리지) | 운영환경에서 더 엄격한 테스트 |
+| **다운타임** | 허용 (1-2분) | Zero Downtime | 운영환경에서 서비스 연속성 보장 |
+
+## 7. 비용 분석
+
+### 7.1 환경별 비용 구조
+
+#### 7.1.1 월간 비용 비교 (USD)
+
+| 구성요소 | 개발환경 | 운영환경 | 차이 |
+|----------|----------|----------|------|
+| **컴퓨팅** | | | |
+| AKS 노드 | $120 (Spot) | $1,200 (Reserved) | 10배 |
+| **데이터** | | | |
+| PostgreSQL | $0 (Pod) | $450 (Managed) | 무제한 |
+| Redis | $0 (Pod) | $250 (Premium) | 무제한 |
+| **네트워킹** | | | |
+| Load Balancer | $20 | $150 | 7.5배 |
+| **기타** | | | |
+| Service Bus | $10 | $150 | 15배 |
+| 모니터링 | $0 | $100 | 무제한 |
+| **총합** | **$150** | **$2,650** | **17.7배** |
+
+#### 7.1.2 비용 최적화 전략
+
+#### 7.1.2 환경별 비용 최적화 전략 비교
+
+| 최적화 영역 | 개발환경 | 운영환경 | 절약 효과 |
+|-------------|----------|----------|----------|
+| **컴퓨팅 비용** | Spot Instances 사용 | Reserved Instances | 70% vs 30% 절약 |
+| **백킹서비스** | Pod 기반 (무료) | 관리형 서비스 | 100% 절약 vs 안정성 |
+| **리소스 관리** | 비업무시간 자동 종료 | 자동 스케일링 | 시간 절약 vs 효율성 |
+| **사이징 전략** | 고정 리소스 | 성능 기반 적정 sizing | 단순 vs 최적화 |
+
+## 8. 전환 및 확장 계획
+
+### 8.1 개발환경 → 운영환경 전환 체크리스트
+
+| 카테고리 | 체크 항목 | 상태 | 우선순위 | 비고 |
+|---------|-----------|------|----------|------|
+| **데이터 마이그레이션** | 개발 데이터 백업 | ☐ | 높음 | pg_dump 사용 |
+| **데이터 마이그레이션** | 스키마 마이그레이션 스크립트 | ☐ | 높음 | Flyway/Liquibase 고려 |
+| **데이터 마이그레이션** | Azure Database 프로비저닝 | ☐ | 높음 | Flexible Server 구성 |
+| **설정 변경** | 환경 변수 분리 | ☐ | 높음 | ConfigMap/Secret 분리 |
+| **설정 변경** | Azure Key Vault 설정 | ☐ | 높음 | HSM 보안 모듈 |
+| **설정 변경** | Managed Identity 구성 | ☐ | 높음 | 키 없는 인증 |
+| **모니터링** | Azure Monitor 설정 | ☐ | 중간 | Log Analytics 연동 |
+| **모니터링** | 알림 정책 수립 | ☐ | 중간 | PagerDuty/Teams 연동 |
+| **모니터링** | 대시보드 구축 | ☐ | 낮음 | Application Insights |
+
+### 8.2 단계별 확장 로드맵
+
+| 단계 | 기간 | 핵심 목표 | 주요 작업 | 사용자 지원 | 가용성 |
+|------|------|----------|----------|-------------|----------|
+| **Phase 1** | 현재-6개월 | 안정화 | 개발환경 → 운영환경 전환
기본 모니터링 및 알림 구축 | 1만 사용자 | 99.9% |
+| **Phase 2** | 6-12개월 | 최적화 | 성능 최적화 및 비용 효율화
고급 모니터링 (APM) 도입 | 10만 동시 사용자 | 99.9% |
+| **Phase 3** | 12-18개월 | 글로벌 확장 | 다중 리전 배포
글로벌 CDN 및 로드 밸런싱 | 100만 사용자 | 99.95% |
+
+## 9. 핵심 SLA 지표
+
+### 9.1 환경별 서비스 수준 목표
+
+| SLA 항목 | 개발환경 | 운영환경 | 글로벌환경 (Phase 3) |
+|---------|----------|----------|---------------------|
+| **가용성** | 95% | 99.9% | 99.95% |
+| **응답시간** | < 10초 | < 5초 | < 2초 |
+| **배포시간** | 30분 | 10분 | 5분 |
+| **복구시간** | 수동 복구 | < 5분 | < 2분 |
+| **동시사용자** | 개발팀 (5명) | 10만명 | 100만명 |
+| **월간비용** | $150 | $2,650 | $15,000+ |
+| **보안인시던트** | 모니터링 없음 | 0건 목표 | 0건 목표 |
\ No newline at end of file
diff --git a/design/backend/class/ai-service-simple.puml b/design/backend/class/ai-service-simple.puml
new file mode 100644
index 0000000..d3a483e
--- /dev/null
+++ b/design/backend/class/ai-service-simple.puml
@@ -0,0 +1,204 @@
+@startuml
+!theme mono
+
+title AI Service 클래스 다이어그램 (요약) - Clean Architecture
+
+' ===== Presentation Layer =====
+package "Presentation Layer" <> #E8F5E9 {
+ class HealthController
+ class InternalRecommendationController
+ class InternalJobController
+}
+
+' ===== Application Layer =====
+package "Application Layer (Use Cases)" <> #FFF9C4 {
+ class AIRecommendationService
+ class TrendAnalysisService
+ class JobStatusService
+ class CacheService
+}
+
+' ===== Domain Layer =====
+package "Domain Layer" <> #E1BEE7 {
+ class AIRecommendationResult
+ class TrendAnalysis
+ class EventRecommendation
+ class ExpectedMetrics
+ class JobStatusResponse
+ class HealthCheckResponse
+
+ enum AIProvider
+ enum JobStatus
+ enum EventMechanicsType
+ enum ServiceStatus
+}
+
+' ===== Infrastructure Layer =====
+package "Infrastructure Layer" <> #FFCCBC {
+ interface ClaudeApiClient
+ class ClaudeRequest
+ class ClaudeResponse
+ class CircuitBreakerManager
+ class AIServiceFallback
+ class AIJobConsumer
+ class AIJobMessage
+}
+
+' ===== Exception Layer =====
+package "Exception Layer" <> #FFEBEE {
+ class GlobalExceptionHandler
+ class AIServiceException
+ class JobNotFoundException
+ class RecommendationNotFoundException
+ class CircuitBreakerOpenException
+}
+
+' ===== Configuration Layer =====
+package "Configuration Layer" <> #E3F2FD {
+ class SecurityConfig
+ class RedisConfig
+ class CircuitBreakerConfig
+ class KafkaConsumerConfig
+ class JacksonConfig
+ class SwaggerConfig
+}
+
+' ===== 레이어 간 의존성 =====
+InternalRecommendationController --> AIRecommendationService
+InternalJobController --> JobStatusService
+
+AIRecommendationService --> TrendAnalysisService
+AIRecommendationService --> CacheService
+AIRecommendationService --> JobStatusService
+AIRecommendationService --> ClaudeApiClient
+AIRecommendationService --> CircuitBreakerManager
+AIRecommendationService --> AIServiceFallback
+
+TrendAnalysisService --> ClaudeApiClient
+TrendAnalysisService --> CircuitBreakerManager
+TrendAnalysisService --> AIServiceFallback
+
+JobStatusService --> CacheService
+
+AIJobConsumer --> AIRecommendationService
+
+AIRecommendationService ..> AIRecommendationResult : creates
+TrendAnalysisService ..> TrendAnalysis : creates
+JobStatusService ..> JobStatusResponse : creates
+
+AIRecommendationResult *-- TrendAnalysis
+AIRecommendationResult *-- EventRecommendation
+EventRecommendation *-- ExpectedMetrics
+
+ClaudeApiClient ..> ClaudeRequest : uses
+ClaudeApiClient ..> ClaudeResponse : returns
+
+GlobalExceptionHandler ..> AIServiceException : handles
+GlobalExceptionHandler ..> JobNotFoundException : handles
+GlobalExceptionHandler ..> RecommendationNotFoundException : handles
+GlobalExceptionHandler ..> CircuitBreakerOpenException : handles
+
+note right of InternalRecommendationController
+ **Controller API Mappings**
+
+ GET /api/v1/ai-service/internal/recommendations/{eventId}
+ → AI 추천 결과 조회
+
+ GET /api/v1/ai-service/internal/recommendations/debug/redis-keys
+ → Redis 키 조회 (디버그)
+
+ GET /api/v1/ai-service/internal/recommendations/debug/redis-key/{key}
+ → Redis 특정 키 조회 (디버그)
+
+ GET /api/v1/ai-service/internal/recommendations/debug/search-all-databases
+ → 모든 Redis DB 검색 (디버그)
+
+ GET /api/v1/ai-service/internal/recommendations/debug/create-test-data/{eventId}
+ → 테스트 데이터 생성 (디버그)
+end note
+
+note right of InternalJobController
+ **Controller API Mappings**
+
+ GET /api/v1/ai-service/internal/jobs/{jobId}/status
+ → 작업 상태 조회
+
+ GET /api/v1/ai-service/internal/jobs/debug/create-test-job/{jobId}
+ → Job 테스트 데이터 생성 (디버그)
+end note
+
+note right of HealthController
+ **Controller API Mappings**
+
+ GET /api/v1/ai-service/health
+ → 헬스 체크
+end note
+
+note bottom of "Application Layer (Use Cases)"
+ **Clean Architecture - Use Cases**
+
+ - AIRecommendationService: AI 추천 생성 유스케이스
+ - TrendAnalysisService: 트렌드 분석 유스케이스
+ - JobStatusService: 작업 상태 관리 유스케이스
+ - CacheService: 캐싱 인프라 서비스
+
+ 비즈니스 로직과 외부 의존성 격리
+end note
+
+note bottom of "Domain Layer"
+ **Clean Architecture - Entities**
+
+ - 순수 비즈니스 도메인 객체
+ - 외부 의존성 없음 (Framework-independent)
+ - 불변 객체 (Immutable)
+ - Builder 패턴 적용
+end note
+
+note bottom of "Infrastructure Layer"
+ **Clean Architecture - External Interfaces**
+
+ - ClaudeApiClient: 외부 AI API 연동
+ - CircuitBreakerManager: 장애 격리 인프라
+ - AIJobConsumer: Kafka 메시지 수신
+ - AIServiceFallback: Fallback 로직
+
+ 외부 시스템과의 통신 계층
+end note
+
+note top of "Configuration Layer"
+ **Spring Configuration**
+
+ - SecurityConfig: 보안 설정
+ - RedisConfig: Redis 연결 설정
+ - CircuitBreakerConfig: Circuit Breaker 설정
+ - KafkaConsumerConfig: Kafka Consumer 설정
+ - JacksonConfig: JSON 변환 설정
+ - SwaggerConfig: API 문서 설정
+end note
+
+note as N1
+ **Clean Architecture 적용**
+
+ 1. **Domain Layer (Core)**
+ - 순수 비즈니스 로직
+ - 외부 의존성 없음
+
+ 2. **Application Layer (Use Cases)**
+ - 비즈니스 유스케이스 구현
+ - Domain과 Infrastructure 연결
+
+ 3. **Infrastructure Layer**
+ - 외부 시스템 연동
+ - 데이터베이스, API, 메시징
+
+ 4. **Presentation Layer**
+ - REST API 컨트롤러
+ - 요청/응답 처리
+
+ **의존성 규칙:**
+ Presentation → Application → Domain
+ Infrastructure → Application
+ (Domain은 외부 의존성 없음)
+end note
+
+@enduml
diff --git a/design/backend/class/ai-service.puml b/design/backend/class/ai-service.puml
new file mode 100644
index 0000000..38587c3
--- /dev/null
+++ b/design/backend/class/ai-service.puml
@@ -0,0 +1,529 @@
+@startuml
+!theme mono
+
+title AI Service 클래스 다이어그램 (Clean Architecture)
+
+' ===== Presentation Layer (Interface Adapters) =====
+package "com.kt.ai.controller" <> #E8F5E9 {
+ class HealthController {
+ + checkHealth(): ResponseEntity
+ - getServiceStatus(): ServiceStatus
+ - checkRedisConnection(): boolean
+ }
+
+ class InternalRecommendationController {
+ - aiRecommendationService: AIRecommendationService
+ - cacheService: CacheService
+ - redisTemplate: RedisTemplate
+ + getRecommendation(eventId: String): ResponseEntity
+ + debugRedisKeys(): ResponseEntity>
+ + debugRedisKey(key: String): ResponseEntity>
+ + searchAllDatabases(): ResponseEntity>
+ + createTestData(eventId: String): ResponseEntity>
+ }
+
+ class InternalJobController {
+ - jobStatusService: JobStatusService
+ - cacheService: CacheService
+ + getJobStatus(jobId: String): ResponseEntity
+ + createTestJob(jobId: String): ResponseEntity>
+ }
+}
+
+' ===== Application Layer (Use Cases) =====
+package "com.kt.ai.service" <> #FFF9C4 {
+ class AIRecommendationService {
+ - cacheService: CacheService
+ - jobStatusService: JobStatusService
+ - trendAnalysisService: TrendAnalysisService
+ - claudeApiClient: ClaudeApiClient
+ - circuitBreakerManager: CircuitBreakerManager
+ - fallback: AIServiceFallback
+ - objectMapper: ObjectMapper
+ - aiProvider: String
+ - apiKey: String
+ - anthropicVersion: String
+ - model: String
+ - maxTokens: Integer
+ - temperature: Double
+ + getRecommendation(eventId: String): AIRecommendationResult
+ + generateRecommendations(message: AIJobMessage): void
+ - analyzeTrend(message: AIJobMessage): TrendAnalysis
+ - createRecommendations(message: AIJobMessage, trendAnalysis: TrendAnalysis): List
+ - callClaudeApiForRecommendations(message: AIJobMessage, trendAnalysis: TrendAnalysis): List
+ - buildRecommendationPrompt(message: AIJobMessage, trendAnalysis: TrendAnalysis): String
+ - parseRecommendationResponse(responseText: String): List
+ - parseEventRecommendation(node: JsonNode): EventRecommendation
+ - parseRange(node: JsonNode): ExpectedMetrics.Range
+ - extractJsonFromMarkdown(text: String): String
+ }
+
+ class TrendAnalysisService {
+ - claudeApiClient: ClaudeApiClient
+ - circuitBreakerManager: CircuitBreakerManager
+ - fallback: AIServiceFallback
+ - objectMapper: ObjectMapper
+ - apiKey: String
+ - anthropicVersion: String
+ - model: String
+ - maxTokens: Integer
+ - temperature: Double
+ + analyzeTrend(industry: String, region: String): TrendAnalysis
+ - callClaudeApi(industry: String, region: String): TrendAnalysis
+ - buildPrompt(industry: String, region: String): String
+ - parseResponse(responseText: String): TrendAnalysis
+ - extractJsonFromMarkdown(text: String): String
+ - parseTrendKeywords(arrayNode: JsonNode): List
+ }
+
+ class JobStatusService {
+ - cacheService: CacheService
+ - objectMapper: ObjectMapper
+ + getJobStatus(jobId: String): JobStatusResponse
+ + updateJobStatus(jobId: String, status: JobStatus, message: String): void
+ - calculateProgress(status: JobStatus): int
+ }
+
+ class CacheService {
+ - redisTemplate: RedisTemplate
+ - recommendationTtl: long
+ - jobStatusTtl: long
+ - trendTtl: long
+ + set(key: String, value: Object, ttlSeconds: long): void
+ + get(key: String): Object
+ + delete(key: String): void
+ + saveJobStatus(jobId: String, status: Object): void
+ + getJobStatus(jobId: String): Object
+ + saveRecommendation(eventId: String, recommendation: Object): void
+ + getRecommendation(eventId: String): Object
+ + saveTrend(industry: String, region: String, trend: Object): void
+ + getTrend(industry: String, region: String): Object
+ }
+}
+
+' ===== Domain Layer (Entities & Business Logic) =====
+package "com.kt.ai.model" <> #E1BEE7 {
+ package "dto.response" {
+ class AIRecommendationResult {
+ - eventId: String
+ - trendAnalysis: TrendAnalysis
+ - recommendations: List
+ - generatedAt: LocalDateTime
+ - expiresAt: LocalDateTime
+ - aiProvider: AIProvider
+ }
+
+ class TrendAnalysis {
+ - industryTrends: List
+ - regionalTrends: List
+ - seasonalTrends: List
+ }
+
+ class "TrendAnalysis.TrendKeyword" as TrendKeyword {
+ - keyword: String
+ - relevance: Double
+ - description: String
+ }
+
+ class EventRecommendation {
+ - optionNumber: Integer
+ - concept: String
+ - title: String
+ - description: String
+ - targetAudience: String
+ - duration: Duration
+ - mechanics: Mechanics
+ - promotionChannels: List
+ - estimatedCost: EstimatedCost
+ - expectedMetrics: ExpectedMetrics
+ - differentiator: String
+ }
+
+ class "EventRecommendation.Duration" as Duration {
+ - recommendedDays: Integer
+ - recommendedPeriod: String
+ }
+
+ class "EventRecommendation.Mechanics" as Mechanics {
+ - type: EventMechanicsType
+ - details: String
+ }
+
+ class "EventRecommendation.EstimatedCost" as EstimatedCost {
+ - min: Integer
+ - max: Integer
+ - breakdown: Map
+ }
+
+ class ExpectedMetrics {
+ - newCustomers: Range
+ - revenueIncrease: Range
+ - roi: Range
+ }
+
+ class "ExpectedMetrics.Range" as Range {
+ - min: Double
+ - max: Double
+ }
+
+ class JobStatusResponse {
+ - jobId: String
+ - status: JobStatus
+ - progress: Integer
+ - message: String
+ - createdAt: LocalDateTime
+ }
+
+ class HealthCheckResponse {
+ - status: ServiceStatus
+ - timestamp: LocalDateTime
+ - redisConnected: boolean
+ }
+
+ class ErrorResponse {
+ - success: boolean
+ - errorCode: String
+ - message: String
+ - timestamp: LocalDateTime
+ - details: Map
+ }
+ }
+
+ package "enums" {
+ enum AIProvider {
+ CLAUDE
+ GPT_4
+ }
+
+ enum JobStatus {
+ PENDING
+ PROCESSING
+ COMPLETED
+ FAILED
+ }
+
+ enum EventMechanicsType {
+ DISCOUNT
+ GIFT
+ STAMP
+ EXPERIENCE
+ LOTTERY
+ COMBO
+ }
+
+ enum ServiceStatus {
+ UP
+ DOWN
+ DEGRADED
+ }
+
+ enum CircuitBreakerState {
+ CLOSED
+ OPEN
+ HALF_OPEN
+ }
+ }
+}
+
+' ===== Infrastructure Layer (External Interfaces) =====
+package "com.kt.ai.client" <> #FFCCBC {
+ interface ClaudeApiClient {
+ + sendMessage(apiKey: String, anthropicVersion: String, request: ClaudeRequest): ClaudeResponse
+ }
+
+ package "dto" {
+ class ClaudeRequest {
+ - model: String
+ - messages: List
+ - maxTokens: Integer
+ - temperature: Double
+ - system: String
+ }
+
+ class "ClaudeRequest.Message" as Message {
+ - role: String
+ - content: String
+ }
+
+ class ClaudeResponse {
+ - id: String
+ - type: String
+ - role: String
+ - content: List
+ - model: String
+ - stopReason: String
+ - stopSequence: String
+ - usage: Usage
+ + extractText(): String
+ }
+
+ class "ClaudeResponse.Content" as Content {
+ - type: String
+ - text: String
+ }
+
+ class "ClaudeResponse.Usage" as Usage {
+ - inputTokens: Integer
+ - outputTokens: Integer
+ }
+ }
+
+ package "config" {
+ class FeignClientConfig {
+ + feignEncoder(): Encoder
+ + feignDecoder(): Decoder
+ + feignLoggerLevel(): Logger.Level
+ + feignErrorDecoder(): ErrorDecoder
+ }
+ }
+}
+
+package "com.kt.ai.circuitbreaker" <> #FFCCBC {
+ class CircuitBreakerManager {
+ - circuitBreakerRegistry: CircuitBreakerRegistry
+ + executeWithCircuitBreaker(circuitBreakerName: String, supplier: Supplier, fallback: Supplier): T
+ + executeWithCircuitBreaker(circuitBreakerName: String, supplier: Supplier): T
+ + getCircuitBreakerState(circuitBreakerName: String): CircuitBreaker.State
+ }
+
+ package "fallback" {
+ class AIServiceFallback {
+ + getDefaultTrendAnalysis(industry: String, region: String): TrendAnalysis
+ + getDefaultRecommendations(objective: String, industry: String): List
+ - createDefaultTrendKeyword(keyword: String, relevance: Double, description: String): TrendAnalysis.TrendKeyword
+ - createDefaultRecommendation(optionNumber: Integer, concept: String, title: String): EventRecommendation
+ }
+ }
+}
+
+package "com.kt.ai.kafka" <> #FFCCBC {
+ package "consumer" {
+ class AIJobConsumer {
+ - aiRecommendationService: AIRecommendationService
+ - objectMapper: ObjectMapper
+ + consumeAIJobMessage(message: String): void
+ - parseAIJobMessage(message: String): AIJobMessage
+ }
+ }
+
+ package "message" {
+ class AIJobMessage {
+ - jobId: String
+ - eventId: String
+ - storeName: String
+ - industry: String
+ - region: String
+ - objective: String
+ - targetAudience: String
+ - budget: Integer
+ - requestedAt: LocalDateTime
+ }
+ }
+}
+
+' ===== Exception Layer =====
+package "com.kt.ai.exception" <> #FFEBEE {
+ class GlobalExceptionHandler {
+ + handleBusinessException(e: BusinessException): ResponseEntity
+ + handleJobNotFoundException(e: JobNotFoundException): ResponseEntity
+ + handleRecommendationNotFoundException(e: RecommendationNotFoundException): ResponseEntity
+ + handleCircuitBreakerOpenException(e: CircuitBreakerOpenException): ResponseEntity
+ + handleAIServiceException(e: AIServiceException): ResponseEntity
+ + handleException(e: Exception): ResponseEntity
+ - buildErrorResponse(errorCode: String, message: String): ErrorResponse
+ }
+
+ class AIServiceException {
+ - errorCode: String
+ - details: String
+ + AIServiceException(message: String)
+ + AIServiceException(message: String, cause: Throwable)
+ + AIServiceException(errorCode: String, message: String)
+ + AIServiceException(errorCode: String, message: String, details: String)
+ }
+
+ class JobNotFoundException {
+ - jobId: String
+ + JobNotFoundException(jobId: String)
+ + JobNotFoundException(jobId: String, cause: Throwable)
+ }
+
+ class RecommendationNotFoundException {
+ - eventId: String
+ + RecommendationNotFoundException(eventId: String)
+ + RecommendationNotFoundException(eventId: String, cause: Throwable)
+ }
+
+ class CircuitBreakerOpenException {
+ - circuitBreakerName: String
+ + CircuitBreakerOpenException(circuitBreakerName: String)
+ + CircuitBreakerOpenException(circuitBreakerName: String, cause: Throwable)
+ }
+}
+
+' ===== Configuration Layer =====
+package "com.kt.ai.config" <> #E3F2FD {
+ class SecurityConfig {
+ + securityFilterChain(http: HttpSecurity): SecurityFilterChain
+ + passwordEncoder(): PasswordEncoder
+ }
+
+ class RedisConfig {
+ - host: String
+ - port: int
+ - password: String
+ + redisConnectionFactory(): LettuceConnectionFactory
+ + redisTemplate(): RedisTemplate
+ }
+
+ class CircuitBreakerConfig {
+ + circuitBreakerRegistry(): CircuitBreakerRegistry
+ + circuitBreakerConfigCustomizer(): Customizer
+ }
+
+ class KafkaConsumerConfig {
+ - bootstrapServers: String
+ - groupId: String
+ + consumerFactory(): ConsumerFactory
+ + kafkaListenerContainerFactory(): ConcurrentKafkaListenerContainerFactory
+ }
+
+ class JacksonConfig {
+ + objectMapper(): ObjectMapper
+ }
+
+ class SwaggerConfig {
+ + openAPI(): OpenAPI
+ }
+}
+
+' ===== Main Application =====
+package "com.kt.ai" <> #F3E5F5 {
+ class AiServiceApplication {
+ + {static} main(args: String[]): void
+ }
+}
+
+' ===== 관계 정의 =====
+
+' Controller → Service
+InternalRecommendationController --> AIRecommendationService : uses
+InternalRecommendationController --> CacheService : uses
+InternalJobController --> JobStatusService : uses
+InternalJobController --> CacheService : uses
+
+' Service → Service
+AIRecommendationService --> TrendAnalysisService : uses
+AIRecommendationService --> JobStatusService : uses
+AIRecommendationService --> CacheService : uses
+JobStatusService --> CacheService : uses
+
+' Service → Client
+AIRecommendationService --> ClaudeApiClient : uses
+TrendAnalysisService --> ClaudeApiClient : uses
+
+' Service → CircuitBreaker
+AIRecommendationService --> CircuitBreakerManager : uses
+AIRecommendationService --> AIServiceFallback : uses
+TrendAnalysisService --> CircuitBreakerManager : uses
+TrendAnalysisService --> AIServiceFallback : uses
+
+' Kafka → Service
+AIJobConsumer --> AIRecommendationService : uses
+AIJobConsumer --> AIJobMessage : uses
+
+' Service → Domain
+AIRecommendationService --> AIRecommendationResult : creates
+AIRecommendationService --> EventRecommendation : creates
+TrendAnalysisService --> TrendAnalysis : creates
+JobStatusService --> JobStatusResponse : creates
+
+' Domain Relationships
+AIRecommendationResult *-- TrendAnalysis
+AIRecommendationResult *-- EventRecommendation
+AIRecommendationResult --> AIProvider
+TrendAnalysis *-- TrendKeyword
+EventRecommendation *-- Duration
+EventRecommendation *-- Mechanics
+EventRecommendation *-- EstimatedCost
+EventRecommendation *-- ExpectedMetrics
+Mechanics --> EventMechanicsType
+ExpectedMetrics *-- Range
+JobStatusResponse --> JobStatus
+HealthCheckResponse --> ServiceStatus
+
+' Client Relationships
+ClaudeApiClient --> ClaudeRequest : uses
+ClaudeApiClient --> ClaudeResponse : returns
+ClaudeRequest *-- Message
+ClaudeResponse *-- Content
+ClaudeResponse *-- Usage
+
+' Exception Relationships
+GlobalExceptionHandler ..> ErrorResponse : creates
+GlobalExceptionHandler ..> AIServiceException : handles
+GlobalExceptionHandler ..> JobNotFoundException : handles
+GlobalExceptionHandler ..> RecommendationNotFoundException : handles
+GlobalExceptionHandler ..> CircuitBreakerOpenException : handles
+
+AIServiceException <|-- JobNotFoundException
+AIServiceException <|-- RecommendationNotFoundException
+AIServiceException <|-- CircuitBreakerOpenException
+
+note top of AiServiceApplication
+ Spring Boot Application Entry Point
+ - @SpringBootApplication
+ - @EnableFeignClients
+ - @EnableKafka
+end note
+
+note top of AIRecommendationService
+ **Use Case (Application Layer)**
+ - AI 추천 생성 비즈니스 로직
+ - 트렌드 분석 → 추천안 생성
+ - Circuit Breaker 적용
+ - Redis 캐싱 전략
+end note
+
+note top of TrendAnalysisService
+ **Use Case (Application Layer)**
+ - Claude AI를 통한 트렌드 분석
+ - 업종/지역/계절 트렌드
+ - Circuit Breaker Fallback
+end note
+
+note top of ClaudeApiClient
+ **Infrastructure (External Interface)**
+ - Feign Client
+ - Claude API 연동
+ - HTTP 통신 처리
+end note
+
+note top of CircuitBreakerManager
+ **Infrastructure (Resilience)**
+ - Resilience4j Circuit Breaker
+ - 외부 API 장애 격리
+ - Fallback 메커니즘
+end note
+
+note top of CacheService
+ **Infrastructure (Data Access)**
+ - Redis 캐싱 인프라
+ - TTL 관리
+ - 추천/트렌드/상태 캐싱
+end note
+
+note right of AIRecommendationResult
+ **Domain Entity**
+ - AI 추천 결과
+ - 불변 객체 (Immutable)
+ - Builder 패턴
+end note
+
+note right of TrendAnalysis
+ **Domain Entity**
+ - 트렌드 분석 결과
+ - 업종/지역/계절별 구분
+end note
+
+@enduml
diff --git a/design/backend/class/analytics-service-simple.puml b/design/backend/class/analytics-service-simple.puml
new file mode 100644
index 0000000..04a6f90
--- /dev/null
+++ b/design/backend/class/analytics-service-simple.puml
@@ -0,0 +1,534 @@
+@startuml
+!theme mono
+
+title Analytics Service 클래스 다이어그램 (요약)
+
+' ============================================================
+' Presentation Layer - Controller
+' ============================================================
+package "com.kt.event.analytics.controller" <> #F0F8FF {
+
+ class AnalyticsDashboardController {
+ }
+ note right of AnalyticsDashboardController
+ **API Mapping:**
+ getEventAnalytics: GET /api/v1/events/{eventId}/analytics
+ - 성과 대시보드 조회
+ end note
+
+ class ChannelAnalyticsController {
+ }
+ note right of ChannelAnalyticsController
+ **API Mapping:**
+ getChannelAnalytics: GET /api/v1/events/{eventId}/analytics/channels
+ - 채널별 성과 분석
+ end note
+
+ class RoiAnalyticsController {
+ }
+ note right of RoiAnalyticsController
+ **API Mapping:**
+ getRoiAnalytics: GET /api/v1/events/{eventId}/analytics/roi
+ - 투자 대비 수익률 분석
+ end note
+
+ class TimelineAnalyticsController {
+ }
+ note right of TimelineAnalyticsController
+ **API Mapping:**
+ getTimelineAnalytics: GET /api/v1/events/{eventId}/analytics/timeline
+ - 시간대별 참여 추이 분석
+ end note
+
+ class UserAnalyticsDashboardController {
+ }
+ note right of UserAnalyticsDashboardController
+ **API Mapping:**
+ getUserEventAnalytics: GET /api/v1/users/{userId}/analytics
+ - 사용자 전체 이벤트 성과 대시보드
+ end note
+
+ class UserChannelAnalyticsController {
+ }
+ note right of UserChannelAnalyticsController
+ **API Mapping:**
+ getUserChannelAnalytics: GET /api/v1/users/{userId}/analytics/channels
+ - 사용자 채널별 성과 분석
+ end note
+
+ class UserRoiAnalyticsController {
+ }
+ note right of UserRoiAnalyticsController
+ **API Mapping:**
+ getUserRoiAnalytics: GET /api/v1/users/{userId}/analytics/roi
+ - 사용자 ROI 분석
+ end note
+
+ class UserTimelineAnalyticsController {
+ }
+ note right of UserTimelineAnalyticsController
+ **API Mapping:**
+ getUserTimelineAnalytics: GET /api/v1/users/{userId}/analytics/timeline
+ - 사용자 시간대별 분석
+ end note
+}
+
+' ============================================================
+' Business Layer - Service
+' ============================================================
+package "com.kt.event.analytics.service" <> #E6F7E6 {
+
+ class AnalyticsService {
+ }
+ note right of AnalyticsService
+ **핵심 역할:**
+ - 대시보드 데이터 통합
+ - Redis 캐싱 (1시간 TTL)
+ - 외부 API 호출 조율
+ - ROI 계산 로직
+ end note
+
+ class ChannelAnalyticsService {
+ }
+ note right of ChannelAnalyticsService
+ **핵심 역할:**
+ - 채널별 성과 분석
+ - 채널 간 비교 분석
+ - 외부 채널 API 통합
+ end note
+
+ class RoiAnalyticsService {
+ }
+ note right of RoiAnalyticsService
+ **핵심 역할:**
+ - ROI 상세 분석
+ - 투자/수익 분석
+ - 비용 효율성 계산
+ end note
+
+ class TimelineAnalyticsService {
+ }
+ note right of TimelineAnalyticsService
+ **핵심 역할:**
+ - 시간대별 추이 분석
+ - 트렌드 분석
+ - 피크 시간 분석
+ end note
+
+ class UserAnalyticsService {
+ }
+ note right of UserAnalyticsService
+ **핵심 역할:**
+ - 사용자별 통합 분석
+ - 여러 이벤트 집계
+ end note
+
+ class UserChannelAnalyticsService {
+ }
+ note right of UserChannelAnalyticsService
+ **핵심 역할:**
+ - 사용자별 채널 분석
+ - 채널별 통합 성과
+ end note
+
+ class UserRoiAnalyticsService {
+ }
+ note right of UserRoiAnalyticsService
+ **핵심 역할:**
+ - 사용자별 ROI 분석
+ - 전체 투자/수익 계산
+ end note
+
+ class UserTimelineAnalyticsService {
+ }
+ note right of UserTimelineAnalyticsService
+ **핵심 역할:**
+ - 사용자별 시간대 분석
+ - 여러 이벤트 타임라인 통합
+ end note
+
+ class ExternalChannelService {
+ }
+ note right of ExternalChannelService
+ **외부 API 통합:**
+ - 우리동네TV API
+ - 지니TV API
+ - 링고비즈 API
+ - SNS APIs
+ - Circuit Breaker 패턴
+ - Fallback 처리
+ end note
+
+ class ROICalculator {
+ }
+ note right of ROICalculator
+ **ROI 계산 로직:**
+ - ROI 계산
+ - 비용 효율성 계산
+ - 수익 예측
+ end note
+}
+
+' ============================================================
+' Data Access Layer - Repository
+' ============================================================
+package "com.kt.event.analytics.repository" <> #FFF8DC {
+
+ interface EventStatsRepository {
+ }
+ note right of EventStatsRepository
+ **이벤트 통계 저장소**
+ JpaRepository 상속
+ end note
+
+ interface ChannelStatsRepository {
+ }
+ note right of ChannelStatsRepository
+ **채널 통계 저장소**
+ JpaRepository 상속
+ end note
+
+ interface TimelineDataRepository {
+ }
+ note right of TimelineDataRepository
+ **타임라인 데이터 저장소**
+ JpaRepository 상속
+ end note
+}
+
+' ============================================================
+' Domain Layer - Entity
+' ============================================================
+package "com.kt.event.analytics.entity" <> #FFFACD {
+
+ class EventStats {
+ }
+ note right of EventStats
+ **이벤트 통계 엔티티**
+ - 이벤트 기본 정보
+ - 참여자, 조회수
+ - ROI, 투자/수익 정보
+ end note
+
+ class ChannelStats {
+ }
+ note right of ChannelStats
+ **채널별 통계 엔티티**
+ - 채널명, 유형
+ - 노출/조회/클릭/참여/전환
+ - SNS 반응 (좋아요/댓글/공유)
+ - 링고비즈 통화 정보
+ - 배포 비용
+ end note
+
+ class TimelineData {
+ }
+ note right of TimelineData
+ **시간대별 데이터 엔티티**
+ - 시간별 참여자 수
+ - 조회수, 참여, 전환
+ - 누적 참여자 수
+ end note
+}
+
+' ============================================================
+' DTO Layer
+' ============================================================
+package "com.kt.event.analytics.dto.response" <> #E6E6FA {
+
+ class AnalyticsDashboardResponse {
+ }
+ note right of AnalyticsDashboardResponse
+ **대시보드 응답**
+ 통합 성과 데이터
+ end note
+
+ class ChannelAnalyticsResponse {
+ }
+ note right of ChannelAnalyticsResponse
+ **채널 분석 응답**
+ 채널별 상세 데이터
+ end note
+
+ class RoiAnalyticsResponse {
+ }
+ note right of RoiAnalyticsResponse
+ **ROI 분석 응답**
+ 투자/수익 상세 데이터
+ end note
+
+ class TimelineAnalyticsResponse {
+ }
+ note right of TimelineAnalyticsResponse
+ **타임라인 분석 응답**
+ 시간대별 추이 데이터
+ end note
+
+ class UserAnalyticsDashboardResponse {
+ }
+ note right of UserAnalyticsDashboardResponse
+ **사용자 대시보드 응답**
+ 여러 이벤트 통합 데이터
+ end note
+
+ class UserChannelAnalyticsResponse {
+ }
+ note right of UserChannelAnalyticsResponse
+ **사용자 채널 분석 응답**
+ 사용자별 채널 통합 데이터
+ end note
+
+ class UserRoiAnalyticsResponse {
+ }
+ note right of UserRoiAnalyticsResponse
+ **사용자 ROI 분석 응답**
+ 사용자별 ROI 통합 데이터
+ end note
+
+ class UserTimelineAnalyticsResponse {
+ }
+ note right of UserTimelineAnalyticsResponse
+ **사용자 타임라인 분석 응답**
+ 사용자별 타임라인 통합 데이터
+ end note
+}
+
+' ============================================================
+' Messaging Layer - Kafka Consumer
+' ============================================================
+package "com.kt.event.analytics.messaging.consumer" <> #FFE4E1 {
+
+ class EventCreatedConsumer {
+ }
+ note right of EventCreatedConsumer
+ **이벤트 생성 Consumer**
+ Topic: sample.event.created
+ - EventStats 초기화
+ - 멱등성 처리
+ - 캐시 무효화
+ end note
+
+ class ParticipantRegisteredConsumer {
+ }
+ note right of ParticipantRegisteredConsumer
+ **참여자 등록 Consumer**
+ Topic: sample.participant.registered
+ - 참여자 수 증가
+ - TimelineData 업데이트
+ - 캐시 무효화
+ end note
+
+ class DistributionCompletedConsumer {
+ }
+ note right of DistributionCompletedConsumer
+ **배포 완료 Consumer**
+ Topic: sample.distribution.completed
+ - ChannelStats 업데이트
+ - 배포 비용, 노출 수 저장
+ - 캐시 무효화
+ end note
+}
+
+package "com.kt.event.analytics.messaging.event" <> #FFE4E1 {
+
+ class EventCreatedEvent {
+ }
+
+ class ParticipantRegisteredEvent {
+ }
+
+ class DistributionCompletedEvent {
+ }
+}
+
+' ============================================================
+' Batch Layer
+' ============================================================
+package "com.kt.event.analytics.batch" <> #FFF5EE {
+
+ class AnalyticsBatchScheduler {
+ }
+ note right of AnalyticsBatchScheduler
+ **배치 스케줄러**
+ - 5분 단위 캐시 갱신
+ - 초기 데이터 로딩
+ - 캐시 워밍업
+ end note
+}
+
+' ============================================================
+' Configuration Layer
+' ============================================================
+package "com.kt.event.analytics.config" <> #F5F5F5 {
+
+ class RedisConfig {
+ }
+ note right of RedisConfig
+ Redis 연결 설정
+ end note
+
+ class KafkaConsumerConfig {
+ }
+ note right of KafkaConsumerConfig
+ Kafka Consumer 설정
+ end note
+
+ class KafkaTopicConfig {
+ }
+ note right of KafkaTopicConfig
+ Kafka Topic 설정
+ end note
+
+ class Resilience4jConfig {
+ }
+ note right of Resilience4jConfig
+ Circuit Breaker 설정
+ end note
+
+ class SecurityConfig {
+ }
+ note right of SecurityConfig
+ Spring Security 설정
+ end note
+
+ class SwaggerConfig {
+ }
+ note right of SwaggerConfig
+ Swagger/OpenAPI 설정
+ end note
+}
+
+' ============================================================
+' Common Components
+' ============================================================
+package "com.kt.event.common" <> #DCDCDC {
+
+ abstract class BaseTimeEntity {
+ }
+ note right of BaseTimeEntity
+ JPA Auditing
+ - createdAt
+ - updatedAt
+ end note
+
+ class "ApiResponse" {
+ }
+ note right of "ApiResponse"
+ 표준 API 응답 포맷
+ end note
+
+ interface ErrorCode {
+ }
+
+ class BusinessException {
+ }
+}
+
+' ============================================================
+' Layer Relationships
+' ============================================================
+
+' Controller Layer -> Service Layer
+AnalyticsDashboardController ..> AnalyticsService
+ChannelAnalyticsController ..> ChannelAnalyticsService
+RoiAnalyticsController ..> RoiAnalyticsService
+TimelineAnalyticsController ..> TimelineAnalyticsService
+UserAnalyticsDashboardController ..> UserAnalyticsService
+UserChannelAnalyticsController ..> UserChannelAnalyticsService
+UserRoiAnalyticsController ..> UserRoiAnalyticsService
+UserTimelineAnalyticsController ..> UserTimelineAnalyticsService
+
+' Service Layer -> Repository Layer
+AnalyticsService ..> EventStatsRepository
+AnalyticsService ..> ChannelStatsRepository
+ChannelAnalyticsService ..> ChannelStatsRepository
+RoiAnalyticsService ..> EventStatsRepository
+RoiAnalyticsService ..> ChannelStatsRepository
+TimelineAnalyticsService ..> TimelineDataRepository
+TimelineAnalyticsService ..> EventStatsRepository
+UserAnalyticsService ..> EventStatsRepository
+UserAnalyticsService ..> ChannelStatsRepository
+UserChannelAnalyticsService ..> ChannelStatsRepository
+UserChannelAnalyticsService ..> EventStatsRepository
+UserRoiAnalyticsService ..> EventStatsRepository
+UserRoiAnalyticsService ..> ChannelStatsRepository
+UserTimelineAnalyticsService ..> TimelineDataRepository
+UserTimelineAnalyticsService ..> EventStatsRepository
+
+' Service Layer Dependencies
+AnalyticsService ..> ExternalChannelService
+AnalyticsService ..> ROICalculator
+ChannelAnalyticsService ..> ExternalChannelService
+RoiAnalyticsService ..> ROICalculator
+UserAnalyticsService ..> ROICalculator
+UserRoiAnalyticsService ..> ROICalculator
+
+' Repository Layer -> Entity Layer
+EventStatsRepository ..> EventStats
+ChannelStatsRepository ..> ChannelStats
+TimelineDataRepository ..> TimelineData
+
+' Consumer Layer -> Repository Layer
+EventCreatedConsumer ..> EventStatsRepository
+ParticipantRegisteredConsumer ..> EventStatsRepository
+ParticipantRegisteredConsumer ..> TimelineDataRepository
+DistributionCompletedConsumer ..> ChannelStatsRepository
+
+' Consumer Layer -> Event
+EventCreatedConsumer ..> EventCreatedEvent
+ParticipantRegisteredConsumer ..> ParticipantRegisteredEvent
+DistributionCompletedConsumer ..> DistributionCompletedEvent
+
+' Batch Layer -> Service/Repository
+AnalyticsBatchScheduler ..> AnalyticsService
+AnalyticsBatchScheduler ..> EventStatsRepository
+
+' Entity -> Base Entity
+EventStats --|> BaseTimeEntity
+ChannelStats --|> BaseTimeEntity
+TimelineData --|> BaseTimeEntity
+
+' Controller -> Response DTO
+AnalyticsDashboardController ..> AnalyticsDashboardResponse
+ChannelAnalyticsController ..> ChannelAnalyticsResponse
+RoiAnalyticsController ..> RoiAnalyticsResponse
+TimelineAnalyticsController ..> TimelineAnalyticsResponse
+UserAnalyticsDashboardController ..> UserAnalyticsDashboardResponse
+UserChannelAnalyticsController ..> UserChannelAnalyticsResponse
+UserRoiAnalyticsController ..> UserRoiAnalyticsResponse
+UserTimelineAnalyticsController ..> UserTimelineAnalyticsResponse
+
+' Controller -> ApiResponse
+AnalyticsDashboardController ..> "ApiResponse"
+ChannelAnalyticsController ..> "ApiResponse"
+RoiAnalyticsController ..> "ApiResponse"
+TimelineAnalyticsController ..> "ApiResponse"
+
+' Exception
+BusinessException ..> ErrorCode
+
+note top of AnalyticsService
+ **Layered Architecture 패턴 적용**
+ - Presentation Layer: Controller
+ - Business Layer: Service
+ - Data Access Layer: Repository
+ - Domain Layer: Entity
+ - Infrastructure: Config, Messaging, Batch
+end note
+
+note bottom of ExternalChannelService
+ **핵심 기능:**
+ - 외부 채널 API 병렬 호출
+ - Resilience4j Circuit Breaker
+ - Fallback 메커니즘
+ - 비동기 처리 (CompletableFuture)
+end note
+
+note bottom of AnalyticsBatchScheduler
+ **배치 처리:**
+ - @Scheduled (fixedRate = 300000) - 5분
+ - @Scheduled (initialDelay = 30000) - 초기 로딩
+ - Redis 캐시 확인 후 선택적 갱신
+end note
+
+@enduml
diff --git a/design/backend/class/analytics-service.puml b/design/backend/class/analytics-service.puml
new file mode 100644
index 0000000..2c3c389
--- /dev/null
+++ b/design/backend/class/analytics-service.puml
@@ -0,0 +1,738 @@
+@startuml
+!theme mono
+
+title Analytics Service 클래스 다이어그램 (상세)
+
+' ============================================================
+' Presentation Layer - Controller
+' ============================================================
+package "com.kt.event.analytics.controller" <> #F0F8FF {
+
+ class AnalyticsDashboardController {
+ - analyticsService: AnalyticsService
+ + getEventAnalytics(eventId: String, startDate: LocalDateTime, endDate: LocalDateTime, refresh: Boolean): ResponseEntity>
+ }
+
+ class ChannelAnalyticsController {
+ - channelAnalyticsService: ChannelAnalyticsService
+ + getChannelAnalytics(eventId: String, channels: String, sortBy: String, sortOrder: String): ResponseEntity>
+ }
+
+ class RoiAnalyticsController {
+ - roiAnalyticsService: RoiAnalyticsService
+ + getRoiAnalytics(eventId: String): ResponseEntity>
+ }
+
+ class TimelineAnalyticsController {
+ - timelineAnalyticsService: TimelineAnalyticsService
+ + getTimelineAnalytics(eventId: String, granularity: String, startDate: LocalDateTime, endDate: LocalDateTime): ResponseEntity>
+ }
+
+ class UserAnalyticsDashboardController {
+ - userAnalyticsService: UserAnalyticsService
+ + getUserEventAnalytics(userId: String, startDate: LocalDateTime, endDate: LocalDateTime): ResponseEntity>
+ }
+
+ class UserChannelAnalyticsController {
+ - userChannelAnalyticsService: UserChannelAnalyticsService
+ + getUserChannelAnalytics(userId: String, channels: String): ResponseEntity>
+ }
+
+ class UserRoiAnalyticsController {
+ - userRoiAnalyticsService: UserRoiAnalyticsService
+ + getUserRoiAnalytics(userId: String): ResponseEntity>
+ }
+
+ class UserTimelineAnalyticsController {
+ - userTimelineAnalyticsService: UserTimelineAnalyticsService
+ + getUserTimelineAnalytics(userId: String, granularity: String, startDate: LocalDateTime, endDate: LocalDateTime): ResponseEntity>
+ }
+}
+
+' ============================================================
+' Business Layer - Service
+' ============================================================
+package "com.kt.event.analytics.service" <> #E6F7E6 {
+
+ class AnalyticsService {
+ - eventStatsRepository: EventStatsRepository
+ - channelStatsRepository: ChannelStatsRepository
+ - externalChannelService: ExternalChannelService
+ - roiCalculator: ROICalculator
+ - redisTemplate: RedisTemplate
+ - objectMapper: ObjectMapper
+ + getDashboardData(eventId: String, startDate: LocalDateTime, endDate: LocalDateTime, refresh: boolean): AnalyticsDashboardResponse
+ - buildDashboardData(eventStats: EventStats, channelStatsList: List, startDate: LocalDateTime, endDate: LocalDateTime): AnalyticsDashboardResponse
+ - buildPeriodInfo(startDate: LocalDateTime, endDate: LocalDateTime): PeriodInfo
+ - buildAnalyticsSummary(eventStats: EventStats, channelStatsList: List): AnalyticsSummary
+ - buildChannelPerformance(channelStatsList: List, totalInvestment: BigDecimal): List
+ }
+
+ class ChannelAnalyticsService {
+ - channelStatsRepository: ChannelStatsRepository
+ - externalChannelService: ExternalChannelService
+ - redisTemplate: RedisTemplate
+ - objectMapper: ObjectMapper
+ + getChannelAnalytics(eventId: String, channels: List, sortBy: String, sortOrder: String): ChannelAnalyticsResponse
+ - buildChannelMetrics(channelStats: ChannelStats): ChannelMetrics
+ - buildChannelPerformance(channelStats: ChannelStats): ChannelPerformance
+ - buildChannelComparison(channelStatsList: List): ChannelComparison
+ }
+
+ class RoiAnalyticsService {
+ - eventStatsRepository: EventStatsRepository
+ - channelStatsRepository: ChannelStatsRepository
+ - roiCalculator: ROICalculator
+ - redisTemplate: RedisTemplate
+ - objectMapper: ObjectMapper
+ + getRoiAnalytics(eventId: String): RoiAnalyticsResponse
+ - buildRoiCalculation(eventStats: EventStats, channelStatsList: List): RoiCalculation
+ - buildInvestmentDetails(channelStatsList: List): InvestmentDetails
+ - buildRevenueDetails(eventStats: EventStats): RevenueDetails
+ }
+
+ class TimelineAnalyticsService {
+ - timelineDataRepository: TimelineDataRepository
+ - eventStatsRepository: EventStatsRepository
+ - redisTemplate: RedisTemplate
+ - objectMapper: ObjectMapper
+ + getTimelineAnalytics(eventId: String, granularity: String, startDate: LocalDateTime, endDate: LocalDateTime): TimelineAnalyticsResponse
+ - buildTimelineDataPoints(timelineDataList: List): List
+ - buildTrendAnalysis(timelineDataList: List): TrendAnalysis
+ - buildPeakTimeInfo(timelineDataList: List): PeakTimeInfo
+ }
+
+ class UserAnalyticsService {
+ - eventStatsRepository: EventStatsRepository
+ - channelStatsRepository: ChannelStatsRepository
+ - roiCalculator: ROICalculator
+ + getUserEventAnalytics(userId: String, startDate: LocalDateTime, endDate: LocalDateTime): UserAnalyticsDashboardResponse
+ - buildUserAnalyticsSummary(eventStatsList: List, channelStatsList: List): AnalyticsSummary
+ }
+
+ class UserChannelAnalyticsService {
+ - channelStatsRepository: ChannelStatsRepository
+ - eventStatsRepository: EventStatsRepository
+ + getUserChannelAnalytics(userId: String, channels: List): UserChannelAnalyticsResponse
+ }
+
+ class UserRoiAnalyticsService {
+ - eventStatsRepository: EventStatsRepository
+ - channelStatsRepository: ChannelStatsRepository
+ - roiCalculator: ROICalculator
+ + getUserRoiAnalytics(userId: String): UserRoiAnalyticsResponse
+ }
+
+ class UserTimelineAnalyticsService {
+ - timelineDataRepository: TimelineDataRepository
+ - eventStatsRepository: EventStatsRepository
+ + getUserTimelineAnalytics(userId: String, granularity: String, startDate: LocalDateTime, endDate: LocalDateTime): UserTimelineAnalyticsResponse
+ }
+
+ class ExternalChannelService {
+ + updateChannelStatsFromExternalAPIs(eventId: String, channelStatsList: List): void
+ - updateChannelStatsFromAPI(eventId: String, channelStats: ChannelStats): void
+ - updateWooriTVStats(eventId: String, channelStats: ChannelStats): void
+ - wooriTVFallback(eventId: String, channelStats: ChannelStats, e: Exception): void
+ - updateGenieTVStats(eventId: String, channelStats: ChannelStats): void
+ - genieTVFallback(eventId: String, channelStats: ChannelStats, e: Exception): void
+ - updateRingoBizStats(eventId: String, channelStats: ChannelStats): void
+ - ringoBizFallback(eventId: String, channelStats: ChannelStats, e: Exception): void
+ - updateSNSStats(eventId: String, channelStats: ChannelStats): void
+ - snsFallback(eventId: String, channelStats: ChannelStats, e: Exception): void
+ }
+
+ class ROICalculator {
+ + calculateRoiSummary(eventStats: EventStats): RoiSummary
+ + calculateRoi(investment: BigDecimal, revenue: BigDecimal): BigDecimal
+ + calculateCostPerParticipant(totalInvestment: BigDecimal, participants: int): BigDecimal
+ + calculateRevenueProjection(currentRevenue: BigDecimal, targetRoi: BigDecimal): RevenueProjection
+ }
+}
+
+' ============================================================
+' Data Access Layer - Repository
+' ============================================================
+package "com.kt.event.analytics.repository" <> #FFF8DC {
+
+ interface EventStatsRepository {
+ + findByEventId(eventId: String): Optional
+ + findByUserId(userId: String): List
+ + save(eventStats: EventStats): EventStats
+ + findAll(): List
+ }
+
+ interface ChannelStatsRepository {
+ + findByEventId(eventId: String): List
+ + findByEventIdAndChannelName(eventId: String, channelName: String): Optional
+ + findByEventIdIn(eventIds: List): List
+ + save(channelStats: ChannelStats): ChannelStats
+ }
+
+ interface TimelineDataRepository {
+ + findByEventIdOrderByTimestampAsc(eventId: String): List
+ + findByEventIdAndTimestampBetween(eventId: String, startDate: LocalDateTime, endDate: LocalDateTime): List
+ + findByEventIdIn(eventIds: List): List
+ + save(timelineData: TimelineData): TimelineData
+ }
+}
+
+' ============================================================
+' Domain Layer - Entity
+' ============================================================
+package "com.kt.event.analytics.entity" <> #FFFACD {
+
+ class EventStats {
+ - id: Long
+ - eventId: String
+ - eventTitle: String
+ - userId: String
+ - totalParticipants: Integer
+ - totalViews: Integer
+ - estimatedRoi: BigDecimal
+ - targetRoi: BigDecimal
+ - salesGrowthRate: BigDecimal
+ - totalInvestment: BigDecimal
+ - expectedRevenue: BigDecimal
+ - status: String
+ + incrementParticipants(): void
+ + incrementParticipants(count: int): void
+ }
+
+ class ChannelStats {
+ - id: Long
+ - eventId: String
+ - channelName: String
+ - channelType: String
+ - impressions: Integer
+ - views: Integer
+ - clicks: Integer
+ - participants: Integer
+ - conversions: Integer
+ - distributionCost: BigDecimal
+ - likes: Integer
+ - comments: Integer
+ - shares: Integer
+ - totalCalls: Integer
+ - completedCalls: Integer
+ - averageDuration: Integer
+ }
+
+ class TimelineData {
+ - id: Long
+ - eventId: String
+ - timestamp: LocalDateTime
+ - participants: Integer
+ - views: Integer
+ - engagement: Integer
+ - conversions: Integer
+ - cumulativeParticipants: Integer
+ }
+}
+
+' ============================================================
+' DTO Layer
+' ============================================================
+package "com.kt.event.analytics.dto.response" <> #E6E6FA {
+
+ class AnalyticsDashboardResponse {
+ - eventId: String
+ - eventTitle: String
+ - period: PeriodInfo
+ - summary: AnalyticsSummary
+ - channelPerformance: List
+ - roi: RoiSummary
+ - lastUpdatedAt: LocalDateTime
+ - dataSource: String
+ }
+
+ class AnalyticsSummary {
+ - participants: Integer
+ - participantsDelta: Integer
+ - totalViews: Integer
+ - totalReach: Integer
+ - engagementRate: Double
+ - conversionRate: Double
+ - averageEngagementTime: Integer
+ - targetRoi: Double
+ - socialInteractions: SocialInteractionStats
+ }
+
+ class ChannelSummary {
+ - channel: String
+ - views: Integer
+ - participants: Integer
+ - engagementRate: Double
+ - conversionRate: Double
+ - roi: Double
+ }
+
+ class PeriodInfo {
+ - startDate: LocalDateTime
+ - endDate: LocalDateTime
+ - durationDays: Integer
+ }
+
+ class SocialInteractionStats {
+ - likes: Integer
+ - comments: Integer
+ - shares: Integer
+ }
+
+ class RoiSummary {
+ - currentRoi: Double
+ - targetRoi: Double
+ - achievementRate: Double
+ - expectedReturn: BigDecimal
+ - totalInvestment: BigDecimal
+ }
+
+ class ChannelAnalyticsResponse {
+ - eventId: String
+ - eventTitle: String
+ - totalChannels: Integer
+ - channels: List
+ - comparison: ChannelComparison
+ - lastUpdatedAt: LocalDateTime
+ }
+
+ class ChannelAnalytics {
+ - channelName: String
+ - channelType: String
+ - metrics: ChannelMetrics
+ - performance: ChannelPerformance
+ - costs: ChannelCosts
+ - voiceCallStats: VoiceCallStats
+ - socialStats: SocialInteractionStats
+ }
+
+ class ChannelMetrics {
+ - impressions: Integer
+ - views: Integer
+ - clicks: Integer
+ - participants: Integer
+ - conversions: Integer
+ }
+
+ class ChannelPerformance {
+ - engagementRate: Double
+ - clickThroughRate: Double
+ - conversionRate: Double
+ - participationRate: Double
+ }
+
+ class ChannelCosts {
+ - distributionCost: BigDecimal
+ - costPerImpression: BigDecimal
+ - costPerClick: BigDecimal
+ - costPerParticipant: BigDecimal
+ }
+
+ class ChannelComparison {
+ - bestPerformingChannel: String
+ - mostCostEffectiveChannel: String
+ - highestEngagementChannel: String
+ }
+
+ class VoiceCallStats {
+ - totalCalls: Integer
+ - completedCalls: Integer
+ - completionRate: Double
+ - averageDuration: Integer
+ }
+
+ class RoiAnalyticsResponse {
+ - eventId: String
+ - eventTitle: String
+ - roiCalculation: RoiCalculation
+ - investment: InvestmentDetails
+ - revenue: RevenueDetails
+ - costEfficiency: CostEfficiency
+ - projection: RevenueProjection
+ - lastUpdatedAt: LocalDateTime
+ }
+
+ class RoiCalculation {
+ - currentRoi: Double
+ - targetRoi: Double
+ - achievementRate: Double
+ - breakEvenPoint: BigDecimal
+ }
+
+ class InvestmentDetails {
+ - totalInvestment: BigDecimal
+ - channelDistribution: Map
+ - costPerChannel: Map
+ }
+
+ class RevenueDetails {
+ - expectedRevenue: BigDecimal
+ - currentRevenue: BigDecimal
+ - salesGrowthRate: Double
+ }
+
+ class CostEfficiency {
+ - costPerParticipant: BigDecimal
+ - costPerConversion: BigDecimal
+ - costPerView: BigDecimal
+ }
+
+ class RevenueProjection {
+ - projectedRevenue: BigDecimal
+ - projectedRoi: Double
+ - estimatedGrowth: Double
+ }
+
+ class TimelineAnalyticsResponse {
+ - eventId: String
+ - eventTitle: String
+ - granularity: String
+ - period: PeriodInfo
+ - dataPoints: List
+ - trend: TrendAnalysis
+ - peakTime: PeakTimeInfo
+ - lastUpdatedAt: LocalDateTime
+ }
+
+ class TimelineDataPoint {
+ - timestamp: LocalDateTime
+ - participants: Integer
+ - views: Integer
+ - engagement: Integer
+ - conversions: Integer
+ - cumulativeParticipants: Integer
+ }
+
+ class TrendAnalysis {
+ - growthRate: Double
+ - averageParticipantsPerHour: Double
+ - totalEngagement: Integer
+ - conversionTrend: String
+ }
+
+ class PeakTimeInfo {
+ - peakTimestamp: LocalDateTime
+ - peakParticipants: Integer
+ - peakHour: Integer
+ }
+
+ class UserAnalyticsDashboardResponse {
+ - userId: String
+ - totalEvents: Integer
+ - period: PeriodInfo
+ - summary: AnalyticsSummary
+ - events: List
+ - lastUpdatedAt: LocalDateTime
+ }
+
+ class UserChannelAnalyticsResponse {
+ - userId: String
+ - totalEvents: Integer
+ - channels: List
+ - comparison: ChannelComparison
+ - lastUpdatedAt: LocalDateTime
+ }
+
+ class UserRoiAnalyticsResponse {
+ - userId: String
+ - totalEvents: Integer
+ - roiCalculation: RoiCalculation
+ - investment: InvestmentDetails
+ - revenue: RevenueDetails
+ - lastUpdatedAt: LocalDateTime
+ }
+
+ class UserTimelineAnalyticsResponse {
+ - userId: String
+ - totalEvents: Integer
+ - granularity: String
+ - period: PeriodInfo
+ - dataPoints: List
+ - lastUpdatedAt: LocalDateTime
+ }
+}
+
+' ============================================================
+' Messaging Layer - Kafka Consumer
+' ============================================================
+package "com.kt.event.analytics.messaging.consumer" <> #FFE4E1 {
+
+ class EventCreatedConsumer {
+ - eventStatsRepository: EventStatsRepository
+ - objectMapper: ObjectMapper
+ - redisTemplate: RedisTemplate
+ + handleEventCreated(message: String): void
+ }
+
+ class ParticipantRegisteredConsumer {
+ - eventStatsRepository: EventStatsRepository
+ - timelineDataRepository: TimelineDataRepository
+ - objectMapper: ObjectMapper
+ - redisTemplate: RedisTemplate
+ + handleParticipantRegistered(message: String): void
+ - updateTimelineData(eventId: String): void
+ }
+
+ class DistributionCompletedConsumer {
+ - channelStatsRepository: ChannelStatsRepository
+ - objectMapper: ObjectMapper
+ - redisTemplate: RedisTemplate
+ + handleDistributionCompleted(message: String): void
+ }
+}
+
+package "com.kt.event.analytics.messaging.event" <> #FFE4E1 {
+
+ class EventCreatedEvent {
+ - eventId: String
+ - eventTitle: String
+ - storeId: String
+ - totalInvestment: BigDecimal
+ - status: String
+ }
+
+ class ParticipantRegisteredEvent {
+ - eventId: String
+ - participantId: String
+ - channelName: String
+ - registeredAt: LocalDateTime
+ }
+
+ class DistributionCompletedEvent {
+ - eventId: String
+ - channelName: String
+ - distributionCost: BigDecimal
+ - estimatedReach: Integer
+ - completedAt: LocalDateTime
+ }
+}
+
+' ============================================================
+' Batch Layer
+' ============================================================
+package "com.kt.event.analytics.batch" <> #FFF5EE {
+
+ class AnalyticsBatchScheduler {
+ - analyticsService: AnalyticsService
+ - eventStatsRepository: EventStatsRepository
+ - redisTemplate: RedisTemplate
+ + refreshAnalyticsDashboard(): void
+ + initialDataLoad(): void
+ }
+}
+
+' ============================================================
+' Configuration Layer
+' ============================================================
+package "com.kt.event.analytics.config" <> #F5F5F5 {
+
+ class RedisConfig {
+ + redisConnectionFactory(): RedisConnectionFactory
+ + redisTemplate(): RedisTemplate
+ }
+
+ class KafkaConsumerConfig {
+ + consumerFactory(): ConsumerFactory
+ + kafkaListenerContainerFactory(): ConcurrentKafkaListenerContainerFactory
+ }
+
+ class KafkaTopicConfig {
+ + sampleEventCreatedTopic(): NewTopic
+ + sampleParticipantRegisteredTopic(): NewTopic
+ + sampleDistributionCompletedTopic(): NewTopic
+ }
+
+ class Resilience4jConfig {
+ + customize(factory: Resilience4JCircuitBreakerFactory): Customizer
+ }
+
+ class SecurityConfig {
+ + securityFilterChain(http: HttpSecurity): SecurityFilterChain
+ }
+
+ class SwaggerConfig {
+ + openAPI(): OpenAPI
+ }
+}
+
+' ============================================================
+' Common Components (from common-base)
+' ============================================================
+package "com.kt.event.common" <> #DCDCDC {
+
+ abstract class BaseTimeEntity {
+ - createdAt: LocalDateTime
+ - updatedAt: LocalDateTime
+ }
+
+ class "ApiResponse" {
+ - success: boolean
+ - data: T
+ - errorCode: String
+ - message: String
+ - timestamp: LocalDateTime
+ + success(data: T): ApiResponse
+ + success(): ApiResponse
+ + error(errorCode: String, message: String): ApiResponse
+ }
+
+ interface ErrorCode {
+ + getCode(): String
+ + getMessage(): String
+ }
+
+ class BusinessException {
+ - errorCode: ErrorCode
+ - details: String
+ }
+}
+
+' ============================================================
+' Relationships
+' ============================================================
+
+' Controller -> Service
+AnalyticsDashboardController --> AnalyticsService : uses
+ChannelAnalyticsController --> ChannelAnalyticsService : uses
+RoiAnalyticsController --> RoiAnalyticsService : uses
+TimelineAnalyticsController --> TimelineAnalyticsService : uses
+UserAnalyticsDashboardController --> UserAnalyticsService : uses
+UserChannelAnalyticsController --> UserChannelAnalyticsService : uses
+UserRoiAnalyticsController --> UserRoiAnalyticsService : uses
+UserTimelineAnalyticsController --> UserTimelineAnalyticsService : uses
+
+' Service -> Repository
+AnalyticsService --> EventStatsRepository : uses
+AnalyticsService --> ChannelStatsRepository : uses
+ChannelAnalyticsService --> ChannelStatsRepository : uses
+RoiAnalyticsService --> EventStatsRepository : uses
+RoiAnalyticsService --> ChannelStatsRepository : uses
+TimelineAnalyticsService --> TimelineDataRepository : uses
+TimelineAnalyticsService --> EventStatsRepository : uses
+UserAnalyticsService --> EventStatsRepository : uses
+UserAnalyticsService --> ChannelStatsRepository : uses
+UserChannelAnalyticsService --> ChannelStatsRepository : uses
+UserChannelAnalyticsService --> EventStatsRepository : uses
+UserRoiAnalyticsService --> EventStatsRepository : uses
+UserRoiAnalyticsService --> ChannelStatsRepository : uses
+UserTimelineAnalyticsService --> TimelineDataRepository : uses
+UserTimelineAnalyticsService --> EventStatsRepository : uses
+
+' Service -> Service
+AnalyticsService --> ExternalChannelService : uses
+AnalyticsService --> ROICalculator : uses
+ChannelAnalyticsService --> ExternalChannelService : uses
+RoiAnalyticsService --> ROICalculator : uses
+UserAnalyticsService --> ROICalculator : uses
+UserRoiAnalyticsService --> ROICalculator : uses
+
+' Service -> External Components
+ExternalChannelService --> ChannelStats : modifies
+
+' Consumer -> Repository
+EventCreatedConsumer --> EventStatsRepository : uses
+ParticipantRegisteredConsumer --> EventStatsRepository : uses
+ParticipantRegisteredConsumer --> TimelineDataRepository : uses
+DistributionCompletedConsumer --> ChannelStatsRepository : uses
+
+' Consumer -> Event
+EventCreatedConsumer --> EventCreatedEvent : consumes
+ParticipantRegisteredConsumer --> ParticipantRegisteredEvent : consumes
+DistributionCompletedConsumer --> DistributionCompletedEvent : consumes
+
+' Batch -> Service/Repository
+AnalyticsBatchScheduler --> AnalyticsService : uses
+AnalyticsBatchScheduler --> EventStatsRepository : uses
+
+' Repository -> Entity
+EventStatsRepository --> EventStats : manages
+ChannelStatsRepository --> ChannelStats : manages
+TimelineDataRepository --> TimelineData : manages
+
+' Entity -> BaseTimeEntity
+EventStats --|> BaseTimeEntity : extends
+ChannelStats --|> BaseTimeEntity : extends
+TimelineData --|> BaseTimeEntity : extends
+
+' Controller -> DTO
+AnalyticsDashboardController --> AnalyticsDashboardResponse : returns
+ChannelAnalyticsController --> ChannelAnalyticsResponse : returns
+RoiAnalyticsController --> RoiAnalyticsResponse : returns
+TimelineAnalyticsController --> TimelineAnalyticsResponse : returns
+UserAnalyticsDashboardController --> UserAnalyticsDashboardResponse : returns
+UserChannelAnalyticsController --> UserChannelAnalyticsResponse : returns
+UserRoiAnalyticsController --> UserRoiAnalyticsResponse : returns
+UserTimelineAnalyticsController --> UserTimelineAnalyticsResponse : returns
+
+' Service -> DTO
+AnalyticsService --> AnalyticsDashboardResponse : creates
+ChannelAnalyticsService --> ChannelAnalyticsResponse : creates
+RoiAnalyticsService --> RoiAnalyticsResponse : creates
+TimelineAnalyticsService --> TimelineAnalyticsResponse : creates
+UserAnalyticsService --> UserAnalyticsDashboardResponse : creates
+UserChannelAnalyticsService --> UserChannelAnalyticsResponse : creates
+UserRoiAnalyticsService --> UserRoiAnalyticsResponse : creates
+UserTimelineAnalyticsService --> UserTimelineAnalyticsResponse : creates
+
+' DTO Composition
+AnalyticsDashboardResponse *-- PeriodInfo : contains
+AnalyticsDashboardResponse *-- AnalyticsSummary : contains
+AnalyticsDashboardResponse *-- RoiSummary : contains
+AnalyticsSummary *-- SocialInteractionStats : contains
+ChannelAnalyticsResponse *-- ChannelAnalytics : contains
+ChannelAnalyticsResponse *-- ChannelComparison : contains
+ChannelAnalytics *-- ChannelMetrics : contains
+ChannelAnalytics *-- ChannelPerformance : contains
+ChannelAnalytics *-- ChannelCosts : contains
+ChannelAnalytics *-- VoiceCallStats : contains
+RoiAnalyticsResponse *-- RoiCalculation : contains
+RoiAnalyticsResponse *-- InvestmentDetails : contains
+RoiAnalyticsResponse *-- RevenueDetails : contains
+RoiAnalyticsResponse *-- CostEfficiency : contains
+RoiAnalyticsResponse *-- RevenueProjection : contains
+TimelineAnalyticsResponse *-- PeriodInfo : contains
+TimelineAnalyticsResponse *-- TimelineDataPoint : contains
+TimelineAnalyticsResponse *-- TrendAnalysis : contains
+TimelineAnalyticsResponse *-- PeakTimeInfo : contains
+UserAnalyticsDashboardResponse *-- PeriodInfo : contains
+UserAnalyticsDashboardResponse *-- AnalyticsSummary : contains
+
+' Common Dependencies
+BusinessException --> ErrorCode : uses
+AnalyticsDashboardController --> "ApiResponse" : uses
+ChannelAnalyticsController --> "ApiResponse" : uses
+RoiAnalyticsController --> "ApiResponse" : uses
+TimelineAnalyticsController --> "ApiResponse" : uses
+
+note top of AnalyticsService
+ **핵심 서비스**
+ - Redis 캐싱 (1시간 TTL)
+ - 외부 API 병렬 호출
+ - Circuit Breaker 패턴
+ - Cache-Aside 패턴
+end note
+
+note top of ExternalChannelService
+ **외부 채널 통합**
+ - 우리동네TV API
+ - 지니TV API
+ - 링고비즈 API
+ - SNS APIs
+ - Resilience4j Circuit Breaker
+end note
+
+note top of EventCreatedConsumer
+ **Kafka Event Consumer**
+ - EventCreated 이벤트 구독
+ - 멱등성 처리 (Redis Set)
+ - 캐시 무효화
+end note
+
+note top of AnalyticsBatchScheduler
+ **배치 스케줄러**
+ - 5분 단위 캐시 갱신
+ - 초기 데이터 로딩
+ - 캐시 워밍업
+end note
+
+@enduml
diff --git a/design/backend/class/common-base.puml b/design/backend/class/common-base.puml
new file mode 100644
index 0000000..464e011
--- /dev/null
+++ b/design/backend/class/common-base.puml
@@ -0,0 +1,189 @@
+@startuml
+!theme mono
+
+title 공통 컴포넌트 클래스 다이어그램
+
+package "com.kt.event.common" {
+
+ package "entity" {
+ abstract class BaseTimeEntity {
+ - createdAt: LocalDateTime
+ - updatedAt: LocalDateTime
+ }
+ }
+
+ package "dto" {
+ class "ApiResponse" {
+ - success: boolean
+ - data: T
+ - errorCode: String
+ - message: String
+ - timestamp: LocalDateTime
+ + success(data: T): ApiResponse
+ + success(): ApiResponse
+ + error(errorCode: String, message: String): ApiResponse
+ }
+
+ class ErrorResponse {
+ - success: boolean
+ - errorCode: String
+ - message: String
+ - timestamp: LocalDateTime
+ - details: Map
+ + of(errorCode: ErrorCode): ErrorResponse
+ + of(errorCode: ErrorCode, details: Map): ErrorResponse
+ }
+
+ class "PageResponse" {
+ - content: List
+ - totalElements: long
+ - totalPages: int
+ - number: int
+ - size: int
+ - first: boolean
+ - last: boolean
+ + of(content: List, pageable: Pageable, total: long): PageResponse
+ }
+ }
+
+ package "exception" {
+ interface ErrorCode {
+ + getCode(): String
+ + getMessage(): String
+ }
+
+ enum CommonErrorCode implements ErrorCode {
+ COMMON_001
+ COMMON_002
+ COMMON_003
+ COMMON_004
+ COMMON_005
+ NOT_FOUND
+ INVALID_INPUT_VALUE
+ AUTH_001 ~ AUTH_005
+ USER_001 ~ USER_005
+ EVENT_001 ~ EVENT_005
+ JOB_001 ~ JOB_004
+ AI_001 ~ AI_004
+ CONTENT_001 ~ CONTENT_004
+ DIST_001 ~ DIST_004
+ PART_001 ~ PART_008
+ ANALYTICS_001 ~ ANALYTICS_003
+ EXTERNAL_001 ~ EXTERNAL_003
+ DB_001 ~ DB_004
+ REDIS_001 ~ REDIS_003
+ KAFKA_001 ~ KAFKA_003
+ - code: String
+ - message: String
+ + getCode(): String
+ + getMessage(): String
+ }
+
+ class BusinessException extends RuntimeException {
+ - errorCode: ErrorCode
+ - details: String
+ + BusinessException(errorCode: ErrorCode)
+ + BusinessException(errorCode: ErrorCode, message: String)
+ + BusinessException(errorCode: ErrorCode, message: String, details: String)
+ + BusinessException(errorCode: ErrorCode, cause: Throwable)
+ + BusinessException(errorCode: ErrorCode, message: String, details: String, cause: Throwable)
+ + getErrorCode(): ErrorCode
+ + getDetails(): String
+ }
+
+ class InfraException extends RuntimeException {
+ - errorCode: ErrorCode
+ - details: String
+ + InfraException(errorCode: ErrorCode)
+ + InfraException(errorCode: ErrorCode, message: String)
+ + InfraException(errorCode: ErrorCode, cause: Throwable)
+ + getErrorCode(): ErrorCode
+ + getDetails(): String
+ }
+ }
+
+ package "util" {
+ class ValidationUtil {
+ + requireNonNull(object: Object, errorCode: ErrorCode): void
+ + requireNonNull(object: Object, errorCode: ErrorCode, message: String): void
+ + requireNotBlank(str: String, errorCode: ErrorCode): void
+ + requireNotBlank(str: String, errorCode: ErrorCode, message: String): void
+ + require(condition: boolean, errorCode: ErrorCode): void
+ + require(condition: boolean, errorCode: ErrorCode, message: String): void
+ + requireValidPhoneNumber(phoneNumber: String, errorCode: ErrorCode): void
+ + requireValidEmail(email: String, errorCode: ErrorCode): void
+ + requireValidBusinessNumber(businessNumber: String, errorCode: ErrorCode): void
+ + requirePositive(value: long, errorCode: ErrorCode): void
+ + requireNonNegative(value: long, errorCode: ErrorCode): void
+ + requireInRange(value: long, min: long, max: long, errorCode: ErrorCode): void
+ }
+
+ class StringUtil {
+ + isBlank(str: String): boolean
+ + isNotBlank(str: String): boolean
+ + hasText(str: String): boolean
+ + isEmpty(str: String): boolean
+ + isNotEmpty(str: String): boolean
+ + isValidEmail(email: String): boolean
+ + isValidPhoneNumber(phoneNumber: String): boolean
+ + isValidBusinessNumber(businessNumber: String): boolean
+ + maskEmail(email: String): String
+ + maskPhoneNumber(phoneNumber: String): String
+ + generateRandomString(length: int): String
+ + removeSpecialCharacters(str: String): String
+ }
+
+ class DateTimeUtil {
+ + now(): LocalDateTime
+ + nowZoned(): ZonedDateTime
+ + toEpochMilli(dateTime: LocalDateTime): long
+ + fromEpochMilli(epochMilli: long): LocalDateTime
+ + format(dateTime: LocalDateTime, pattern: String): String
+ + parse(dateTimeString: String, pattern: String): LocalDateTime
+ + isAfter(dateTime1: LocalDateTime, dateTime2: LocalDateTime): boolean
+ + isBefore(dateTime1: LocalDateTime, dateTime2: LocalDateTime): boolean
+ + isDateInRange(target: LocalDateTime, start: LocalDateTime, end: LocalDateTime): boolean
+ + getDaysBetween(start: LocalDateTime, end: LocalDateTime): long
+ }
+
+ class EncryptionUtil {
+ + encrypt(plainText: String): String
+ + decrypt(encryptedText: String): String
+ + hash(plainText: String): String
+ + matches(plainText: String, hashedText: String): boolean
+ + generateSalt(): String
+ + encryptWithSalt(plainText: String, salt: String): String
+ }
+ }
+
+ package "security" {
+ class JwtAuthenticationFilter extends OncePerRequestFilter {
+ - jwtTokenProvider: JwtTokenProvider
+ - userDetailsService: UserDetailsService
+ + doFilterInternal(request: HttpServletRequest, response: HttpServletResponse, filterChain: FilterChain): void
+ - extractTokenFromRequest(request: HttpServletRequest): String
+ - authenticateUser(token: String): void
+ }
+
+ interface JwtTokenProvider {
+ + generateToken(userDetails: UserDetails): String
+ + validateToken(token: String): boolean
+ + getUsernameFromToken(token: String): String
+ + getExpirationDateFromToken(token: String): Date
+ }
+ }
+}
+
+' 관계 정의
+BusinessException --> ErrorCode : uses
+InfraException --> ErrorCode : uses
+ValidationUtil --> ErrorCode : uses
+ValidationUtil --> StringUtil : uses
+ErrorResponse --> ErrorCode : uses
+
+note top of BaseTimeEntity : JPA Auditing을 위한 기본 엔티티\n모든 도메인 엔티티가 상속
+note top of "ApiResponse" : 모든 API 응답을 감싸는\n표준 응답 포맷
+note top of CommonErrorCode : 시스템 전체에서 사용하는\n표준 에러 코드
+note top of ValidationUtil : 비즈니스 로직에서 사용하는\n공통 유효성 검증 기능
+
+@enduml
\ No newline at end of file
diff --git a/design/backend/class/content-service-simple.puml b/design/backend/class/content-service-simple.puml
new file mode 100644
index 0000000..5a1e28f
--- /dev/null
+++ b/design/backend/class/content-service-simple.puml
@@ -0,0 +1,227 @@
+@startuml
+!theme mono
+
+title Content Service - 클래스 다이어그램 요약 (Clean Architecture)
+
+' ============================================
+' 레이어 구조 표시
+' ============================================
+package "Domain Layer" <> {
+ class Content {
+ - id: Long
+ - eventId: String
+ - images: List
+ + addImage(image: GeneratedImage): void
+ + getSelectedImages(): List
+ }
+
+ class GeneratedImage {
+ - id: Long
+ - eventId: String
+ - style: ImageStyle
+ - platform: Platform
+ - cdnUrl: String
+ + select(): void
+ + deselect(): void
+ }
+
+ class Job {
+ - id: String
+ - eventId: String
+ - status: Status
+ - progress: int
+ + start(): void
+ + updateProgress(progress: int): void
+ + complete(resultMessage: String): void
+ + fail(errorMessage: String): void
+ }
+
+ enum ImageStyle {
+ FANCY
+ SIMPLE
+ TRENDY
+ }
+
+ enum Platform {
+ INSTAGRAM
+ FACEBOOK
+ KAKAO
+ BLOG
+ }
+}
+
+package "Application Layer" <> {
+ package "Use Cases (Input Port)" {
+ interface GenerateImagesUseCase {
+ + execute(command: ContentCommand.GenerateImages): JobInfo
+ }
+
+ interface GetJobStatusUseCase {
+ + execute(jobId: String): JobInfo
+ }
+
+ interface GetEventContentUseCase {
+ + execute(eventId: String): ContentInfo
+ }
+
+ interface GetImageListUseCase {
+ + execute(eventId: String, style: ImageStyle, platform: Platform): List
+ }
+
+ interface DeleteImageUseCase {
+ + execute(imageId: Long): void
+ }
+
+ interface RegenerateImageUseCase {
+ + execute(command: ContentCommand.RegenerateImage): JobInfo
+ }
+ }
+
+ package "Ports (Output Port)" {
+ interface ContentReader {
+ + findByEventDraftIdWithImages(eventId: String): Optional
+ }
+
+ interface ContentWriter {
+ + save(content: Content): Content
+ + saveImage(image: GeneratedImage): GeneratedImage
+ }
+
+ interface JobReader {
+ + getJob(jobId: String): Optional
+ }
+
+ interface JobWriter {
+ + saveJob(jobData: RedisJobData, ttlSeconds: long): void
+ + updateJobStatus(jobId: String, status: String, progress: Integer): void
+ }
+
+ interface CDNUploader {
+ + upload(imageData: byte[], fileName: String): String
+ }
+ }
+
+ package "Service Implementation" {
+ class StableDiffusionImageGenerator implements GenerateImagesUseCase {
+ - replicateClient: ReplicateApiClient
+ - cdnUploader: CDNUploader
+ - jobWriter: JobWriter
+ - contentWriter: ContentWriter
+ + execute(command: ContentCommand.GenerateImages): JobInfo
+ }
+
+ class JobManagementService implements GetJobStatusUseCase {
+ - jobReader: JobReader
+ + execute(jobId: String): JobInfo
+ }
+
+ class GetEventContentService implements GetEventContentUseCase {
+ - contentReader: ContentReader
+ + execute(eventId: String): ContentInfo
+ }
+
+ class GetImageListService implements GetImageListUseCase {
+ - imageReader: ImageReader
+ + execute(eventId: String, style: ImageStyle, platform: Platform): List
+ }
+
+ class DeleteImageService implements DeleteImageUseCase {
+ - imageWriter: ImageWriter
+ + execute(imageId: Long): void
+ }
+
+ class RegenerateImageService implements RegenerateImageUseCase {
+ - imageReader: ImageReader
+ - imageWriter: ImageWriter
+ - jobWriter: JobWriter
+ + execute(command: ContentCommand.RegenerateImage): JobInfo
+ }
+ }
+}
+
+package "Infrastructure Layer" <> {
+ class RedisGateway implements ContentReader, ContentWriter, JobReader, JobWriter {
+ - redisTemplate: RedisTemplate
+ - objectMapper: ObjectMapper
+ + getAIRecommendation(eventId: String): Optional>
+ + saveJob(jobData: RedisJobData, ttlSeconds: long): void
+ + getJob(jobId: String): Optional
+ + save(content: Content): Content
+ + saveImage(image: GeneratedImage): GeneratedImage
+ }
+
+ class ReplicateApiClient {
+ - apiToken: String
+ - baseUrl: String
+ + createPrediction(request: ReplicateRequest): ReplicateResponse
+ + getPrediction(predictionId: String): ReplicateResponse
+ }
+
+ class AzureBlobStorageUploader implements CDNUploader {
+ - connectionString: String
+ - containerName: String
+ - circuitBreaker: CircuitBreaker
+ + upload(imageData: byte[], fileName: String): String
+ }
+}
+
+package "Presentation Layer" <> {
+ class ContentController {
+ - generateImagesUseCase: GenerateImagesUseCase
+ - getJobStatusUseCase: GetJobStatusUseCase
+ - getEventContentUseCase: GetEventContentUseCase
+ - getImageListUseCase: GetImageListUseCase
+ - deleteImageUseCase: DeleteImageUseCase
+ - regenerateImageUseCase: RegenerateImageUseCase
+ + generateImages(command: ContentCommand.GenerateImages): ResponseEntity
+ + getJobStatus(jobId: String): ResponseEntity
+ + getContentByEventId(eventId: String): ResponseEntity
+ + deleteImage(imageId: Long): ResponseEntity
+ }
+}
+
+' ============================================
+' 관계 정의
+' ============================================
+Content "1" o-- "0..*" GeneratedImage : contains
+GeneratedImage --> ImageStyle
+GeneratedImage --> Platform
+
+ContentController ..> GenerateImagesUseCase
+ContentController ..> GetJobStatusUseCase
+ContentController ..> GetEventContentUseCase
+ContentController ..> GetImageListUseCase
+ContentController ..> DeleteImageUseCase
+ContentController ..> RegenerateImageUseCase
+
+StableDiffusionImageGenerator ..> CDNUploader
+StableDiffusionImageGenerator ..> JobWriter
+StableDiffusionImageGenerator ..> ContentWriter
+StableDiffusionImageGenerator --> ReplicateApiClient
+
+JobManagementService ..> JobReader
+GetEventContentService ..> ContentReader
+GetImageListService ..> "ImageReader\n(extends ContentReader)"
+DeleteImageService ..> "ImageWriter\n(extends ContentWriter)"
+RegenerateImageService ..> "ImageReader\n(extends ContentReader)"
+RegenerateImageService ..> "ImageWriter\n(extends ContentWriter)"
+RegenerateImageService ..> JobWriter
+
+RedisGateway ..|> ContentReader
+RedisGateway ..|> ContentWriter
+RedisGateway ..|> JobReader
+RedisGateway ..|> JobWriter
+AzureBlobStorageUploader ..|> CDNUploader
+
+' ============================================
+' 레이어 의존성 방향
+' ============================================
+note top of Content : **Domain Layer**\n순수 비즈니스 로직\n외부 의존성 없음
+note top of "Use Cases (Input Port)" : **Application Layer**\nUse Case 인터페이스 (Input Port)\n비즈니스 흐름 정의
+note top of "Ports (Output Port)" : **Application Layer**\n외부 시스템 추상화 (Output Port)\n의존성 역전 원칙
+note top of RedisGateway : **Infrastructure Layer**\nOutput Port 구현체\nRedis 저장소 연동
+note top of ContentController : **Presentation Layer**\nREST API 컨트롤러\nHTTP 요청 처리
+
+note bottom of ContentController : **의존성 방향**\nPresentation → Application → Domain\nInfrastructure → Application\n\n**핵심 원칙**\n• Domain은 다른 레이어에 의존하지 않음\n• Application은 Domain에만 의존\n• Infrastructure는 Application Port 구현\n• Presentation은 Application Use Case 호출
+
+@enduml
diff --git a/design/backend/class/content-service.puml b/design/backend/class/content-service.puml
new file mode 100644
index 0000000..ce25bf9
--- /dev/null
+++ b/design/backend/class/content-service.puml
@@ -0,0 +1,528 @@
+@startuml
+!theme mono
+
+title Content Service - 클래스 다이어그램 (Clean Architecture)
+
+' ============================================
+' Domain Layer (엔티티 및 비즈니스 로직)
+' ============================================
+package "com.kt.event.content.biz.domain" <> {
+
+ class Content {
+ - id: Long
+ - eventId: String
+ - eventTitle: String
+ - eventDescription: String
+ - images: List
+ - createdAt: LocalDateTime
+ - updatedAt: LocalDateTime
+ + addImage(image: GeneratedImage): void
+ + getSelectedImages(): List
+ + getImagesByStyle(style: ImageStyle): List
+ + getImagesByPlatform(platform: Platform): List
+ }
+
+ class GeneratedImage {
+ - id: Long
+ - eventId: String
+ - style: ImageStyle
+ - platform: Platform
+ - cdnUrl: String
+ - prompt: String
+ - selected: boolean
+ - createdAt: LocalDateTime
+ - updatedAt: LocalDateTime
+ + select(): void
+ + deselect(): void
+ }
+
+ class Job {
+ - id: String
+ - eventId: String
+ - jobType: String
+ - status: Status
+ - progress: int
+ - resultMessage: String
+ - errorMessage: String
+ - createdAt: LocalDateTime
+ - updatedAt: LocalDateTime
+ + start(): void
+ + updateProgress(progress: int): void
+ + complete(resultMessage: String): void
+ + fail(errorMessage: String): void
+ + isProcessing(): boolean
+ + isCompleted(): boolean
+ + isFailed(): boolean
+ }
+
+ enum JobStatus {
+ PENDING
+ PROCESSING
+ COMPLETED
+ FAILED
+ }
+
+ enum ImageStyle {
+ FANCY
+ SIMPLE
+ TRENDY
+ + getDescription(): String
+ }
+
+ enum Platform {
+ INSTAGRAM
+ FACEBOOK
+ KAKAO
+ BLOG
+ + getWidth(): int
+ + getHeight(): int
+ + getAspectRatio(): String
+ }
+}
+
+' ============================================
+' Application Layer (Use Cases)
+' ============================================
+package "com.kt.event.content.biz.usecase" <> {
+
+ package "in" {
+ interface GenerateImagesUseCase {
+ + execute(command: GenerateImagesCommand): JobInfo
+ }
+
+ interface GetJobStatusUseCase {
+ + execute(jobId: String): JobInfo
+ }
+
+ interface GetEventContentUseCase {
+ + execute(eventId: String): ContentInfo
+ }
+
+ interface GetImageListUseCase {
+ + execute(eventId: String, style: ImageStyle, platform: Platform): List
+ }
+
+ interface GetImageDetailUseCase {
+ + execute(imageId: Long): ImageInfo
+ }
+
+ interface RegenerateImageUseCase {
+ + execute(command: RegenerateImageCommand): JobInfo
+ }
+
+ interface DeleteImageUseCase {
+ + execute(imageId: Long): void
+ }
+ }
+
+ package "out" {
+ interface ContentReader {
+ + findByEventDraftIdWithImages(eventId: String): Optional
+ + findImageById(imageId: Long): Optional
+ + findImagesByEventDraftId(eventId: String): List
+ }
+
+ interface ContentWriter {
+ + save(content: Content): Content
+ + saveImage(image: GeneratedImage): GeneratedImage
+ + getImageById(imageId: Long): GeneratedImage
+ + deleteImageById(imageId: Long): void
+ }
+
+ interface ImageReader {
+ + getImage(eventId: String, style: ImageStyle, platform: Platform): Optional
+ + getImagesByEventId(eventId: String): List
+ }
+
+ interface ImageWriter {
+ + saveImage(image: GeneratedImage): GeneratedImage
+ + getImageById(imageId: Long): GeneratedImage
+ + deleteImageById(imageId: Long): void
+ }
+
+ interface JobReader {
+ + getJob(jobId: String): Optional
+ }
+
+ interface JobWriter {
+ + saveJob(jobData: RedisJobData, ttlSeconds: long): void
+ + updateJobStatus(jobId: String, status: String, progress: Integer): void
+ + updateJobResult(jobId: String, resultMessage: String): void
+ + updateJobError(jobId: String, errorMessage: String): void
+ }
+
+ interface RedisAIDataReader {
+ + getAIRecommendation(eventId: String): Optional>
+ }
+
+ interface RedisImageWriter {
+ + cacheImages(eventId: String, images: List, ttlSeconds: long): void
+ }
+
+ interface CDNUploader {
+ + upload(imageData: byte[], fileName: String): String
+ }
+
+ interface ImageGeneratorCaller {
+ + generateImage(prompt: String, width: int, height: int): String
+ }
+ }
+}
+
+' ============================================
+' Application Service Layer
+' ============================================
+package "com.kt.event.content.biz.service" <> {
+
+ class StableDiffusionImageGenerator implements GenerateImagesUseCase {
+ - replicateClient: ReplicateApiClient
+ - cdnUploader: CDNUploader
+ - jobWriter: JobWriter
+ - contentWriter: ContentWriter
+ - circuitBreaker: CircuitBreaker
+ - modelVersion: String
+ + execute(command: GenerateImagesCommand): JobInfo
+ - processImageGeneration(jobId: String, command: GenerateImagesCommand): void
+ - generateImage(prompt: String, platform: Platform): String
+ - waitForCompletion(predictionId: String): String
+ - buildPrompt(command: GenerateImagesCommand, style: ImageStyle, platform: Platform): String
+ - downloadImage(imageUrl: String): byte[]
+ - createPredictionWithCircuitBreaker(request: ReplicateRequest): ReplicateResponse
+ - getPredictionWithCircuitBreaker(predictionId: String): ReplicateResponse
+ }
+
+ class JobManagementService implements GetJobStatusUseCase {
+ - jobReader: JobReader
+ + execute(jobId: String): JobInfo
+ }
+
+ class GetEventContentService implements GetEventContentUseCase {
+ - contentReader: ContentReader
+ - redisAIDataReader: RedisAIDataReader
+ + execute(eventId: String): ContentInfo
+ }
+
+ class GetImageListService implements GetImageListUseCase {
+ - imageReader: ImageReader
+ + execute(eventId: String, style: ImageStyle, platform: Platform): List
+ }
+
+ class GetImageDetailService implements GetImageDetailUseCase {
+ - imageReader: ImageReader
+ + execute(imageId: Long): ImageInfo
+ }
+
+ class RegenerateImageService implements RegenerateImageUseCase {
+ - imageReader: ImageReader
+ - imageWriter: ImageWriter
+ - jobWriter: JobWriter
+ - cdnUploader: CDNUploader
+ - replicateClient: ReplicateApiClient
+ + execute(command: RegenerateImageCommand): JobInfo
+ }
+
+ class DeleteImageService implements DeleteImageUseCase {
+ - imageWriter: ImageWriter
+ + execute(imageId: Long): void
+ }
+}
+
+' ============================================
+' DTO Layer
+' ============================================
+package "com.kt.event.content.biz.dto" <> {
+
+ class ContentCommand
+
+ class GenerateImagesCommand {
+ - eventId: String
+ - eventTitle: String
+ - eventDescription: String
+ - industry: String
+ - location: String
+ - trends: List
+ - styles: List
+ - platforms: List
+ }
+
+ class RegenerateImageCommand {
+ - imageId: Long
+ - newPrompt: String
+ }
+
+ class ContentInfo {
+ - id: Long
+ - eventId: String
+ - eventTitle: String
+ - eventDescription: String
+ - images: List
+ - createdAt: LocalDateTime
+ - updatedAt: LocalDateTime
+ + {static} from(content: Content): ContentInfo
+ }
+
+ class ImageInfo {
+ - id: Long
+ - eventId: String
+ - style: ImageStyle
+ - platform: Platform
+ - cdnUrl: String
+ - prompt: String
+ - selected: boolean
+ - createdAt: LocalDateTime
+ - updatedAt: LocalDateTime
+ + {static} from(image: GeneratedImage): ImageInfo
+ }
+
+ class JobInfo {
+ - id: String
+ - eventId: String
+ - jobType: String
+ - status: String
+ - progress: int
+ - resultMessage: String
+ - errorMessage: String
+ - createdAt: LocalDateTime
+ - updatedAt: LocalDateTime
+ + {static} from(job: Job): JobInfo
+ }
+
+ class RedisJobData {
+ - id: String
+ - eventId: String
+ - jobType: String
+ - status: String
+ - progress: int
+ - resultMessage: String
+ - errorMessage: String
+ - createdAt: LocalDateTime
+ - updatedAt: LocalDateTime
+ }
+
+ class RedisImageData {
+ - eventId: String
+ - style: ImageStyle
+ - platform: Platform
+ - imageUrl: String
+ - prompt: String
+ - createdAt: LocalDateTime
+ }
+
+ class RedisAIEventData {
+ - eventId: String
+ - recommendedStyles: List
+ - recommendedKeywords: List
+ - cachedAt: LocalDateTime
+ }
+}
+
+' ============================================
+' Infrastructure Layer (Gateway & Adapter)
+' ============================================
+package "com.kt.event.content.infra.gateway" <> {
+
+ class RedisGateway implements ContentReader, ContentWriter, ImageReader, ImageWriter, JobReader, JobWriter, RedisAIDataReader, RedisImageWriter {
+ - redisTemplate: RedisTemplate
+ - objectMapper: ObjectMapper
+ - nextContentId: Long
+ - nextImageId: Long
+ + getAIRecommendation(eventId: String): Optional>
+ + cacheImages(eventId: String, images: List, ttlSeconds: long): void
+ + saveImage(imageData: RedisImageData, ttlSeconds: long): void
+ + getImage(eventId: String, style: ImageStyle, platform: Platform): Optional
+ + getImagesByEventId(eventId: String): List
+ + deleteImage(eventId: String, style: ImageStyle, platform: Platform): void
+ + saveImages(eventId: String, images: List, ttlSeconds: long): void
+ + saveJob(jobData: RedisJobData, ttlSeconds: long): void
+ + getJob(jobId: String): Optional
+ + updateJobStatus(jobId: String, status: String, progress: Integer): void
+ + updateJobResult(jobId: String, resultMessage: String): void
+ + updateJobError(jobId: String, errorMessage: String): void
+ + findByEventDraftIdWithImages(eventId: String): Optional
+ + findImageById(imageId: Long): Optional
+ + findImagesByEventDraftId(eventId: String): List
+ + save(content: Content): Content
+ + saveImage(image: GeneratedImage): GeneratedImage
+ + getImageById(imageId: Long): GeneratedImage
+ + deleteImageById(imageId: Long): void
+ - buildImageKey(eventId: String, style: ImageStyle, platform: Platform): String
+ - getString(map: Map, key: String): String
+ - getLong(map: Map, key: String): Long
+ - getInteger(map: Map, key: String): Integer
+ - getLocalDateTime(map: Map, key: String): LocalDateTime
+ }
+
+ package "client" {
+ class ReplicateApiClient {
+ - apiToken: String
+ - baseUrl: String
+ - restClient: RestClient
+ + createPrediction(request: ReplicateRequest): ReplicateResponse
+ + getPrediction(predictionId: String): ReplicateResponse
+ }
+
+ class AzureBlobStorageUploader implements CDNUploader {
+ - connectionString: String
+ - containerName: String
+ - circuitBreaker: CircuitBreaker
+ - blobServiceClient: BlobServiceClient
+ - containerClient: BlobContainerClient
+ + init(): void
+ + upload(imageData: byte[], fileName: String): String
+ - doUpload(imageData: byte[], fileName: String): String
+ - generateBlobName(fileName: String): String
+ }
+
+ class ReplicateRequest {
+ - version: String
+ - input: Input
+ }
+
+ class ReplicateInputRequest {
+ - prompt: String
+ - negativePrompt: String
+ - width: int
+ - height: int
+ - numOutputs: int
+ - guidanceScale: double
+ - numInferenceSteps: int
+ - seed: long
+ }
+
+ class ReplicateResponse {
+ - id: String
+ - status: String
+ - output: List
+ - error: String
+ }
+
+ class ReplicateApiConfig {
+ - apiToken: String
+ - baseUrl: String
+ + restClient(): RestClient
+ }
+ }
+}
+
+' ============================================
+' Presentation Layer (REST Controller)
+' ============================================
+package "com.kt.event.content.infra.web.controller" <> {
+
+ class ContentController {
+ - generateImagesUseCase: GenerateImagesUseCase
+ - getJobStatusUseCase: GetJobStatusUseCase
+ - getEventContentUseCase: GetEventContentUseCase
+ - getImageListUseCase: GetImageListUseCase
+ - getImageDetailUseCase: GetImageDetailUseCase
+ - regenerateImageUseCase: RegenerateImageUseCase
+ - deleteImageUseCase: DeleteImageUseCase
+ + generateImages(command: GenerateImagesCommand): ResponseEntity
+ + getJobStatus(jobId: String): ResponseEntity
+ + getContentByEventId(eventId: String): ResponseEntity
+ + getImages(eventId: String, style: String, platform: String): ResponseEntity>
+ + getImageById(imageId: Long): ResponseEntity
+ + deleteImage(imageId: Long): ResponseEntity
+ + regenerateImage(imageId: Long, requestBody: RegenerateImageCommand): ResponseEntity
+ }
+}
+
+' ============================================
+' Configuration Layer
+' ============================================
+package "com.kt.event.content.infra.config" <> {
+
+ class RedisConfig {
+ - host: String
+ - port: int
+ + redisConnectionFactory(): RedisConnectionFactory
+ + redisTemplate(): RedisTemplate
+ + objectMapper(): ObjectMapper
+ }
+
+ class Resilience4jConfig {
+ + replicateCircuitBreaker(): CircuitBreaker
+ + azureCircuitBreaker(): CircuitBreaker
+ }
+
+ class SecurityConfig {
+ + securityFilterChain(http: HttpSecurity): SecurityFilterChain
+ }
+
+ class SwaggerConfig {
+ + openAPI(): OpenAPI
+ }
+}
+
+' ============================================
+' 관계 정의 (Domain)
+' ============================================
+Content "1" o-- "0..*" GeneratedImage : contains
+GeneratedImage --> ImageStyle : uses
+GeneratedImage --> Platform : uses
+Job --> JobStatus : has
+
+' ============================================
+' 관계 정의 (Service → Port)
+' ============================================
+StableDiffusionImageGenerator ..> CDNUploader
+StableDiffusionImageGenerator ..> JobWriter
+StableDiffusionImageGenerator ..> ContentWriter
+StableDiffusionImageGenerator --> ReplicateApiClient
+
+JobManagementService ..> JobReader
+GetEventContentService ..> ContentReader
+GetEventContentService ..> RedisAIDataReader
+GetImageListService ..> ImageReader
+GetImageDetailService ..> ImageReader
+RegenerateImageService ..> ImageReader
+RegenerateImageService ..> ImageWriter
+RegenerateImageService ..> JobWriter
+RegenerateImageService ..> CDNUploader
+DeleteImageService ..> ImageWriter
+
+' ============================================
+' 관계 정의 (Gateway → Port Implementation)
+' ============================================
+RedisGateway ..|> ContentReader
+RedisGateway ..|> ContentWriter
+RedisGateway ..|> ImageReader
+RedisGateway ..|> ImageWriter
+RedisGateway ..|> JobReader
+RedisGateway ..|> JobWriter
+RedisGateway ..|> RedisAIDataReader
+RedisGateway ..|> RedisImageWriter
+
+AzureBlobStorageUploader ..|> CDNUploader
+
+' ============================================
+' 관계 정의 (Controller → UseCase)
+' ============================================
+ContentController ..> GenerateImagesUseCase
+ContentController ..> GetJobStatusUseCase
+ContentController ..> GetEventContentUseCase
+ContentController ..> GetImageListUseCase
+ContentController ..> GetImageDetailUseCase
+ContentController ..> RegenerateImageUseCase
+ContentController ..> DeleteImageUseCase
+
+' ============================================
+' 관계 정의 (DTO)
+' ============================================
+ContentInfo ..> ImageInfo
+ContentCommand ..> GenerateImagesCommand : uses
+ContentCommand ..> RegenerateImageCommand : uses
+ReplicateRequest ..> ReplicateInputRequest : contains
+
+' ============================================
+' 레이어 노트
+' ============================================
+note top of Content : Domain Layer\n순수 비즈니스 로직\n외부 의존성 없음
+note top of GenerateImagesUseCase : Application Layer (Input Port)\nUse Case 인터페이스
+note top of ContentReader : Application Layer (Output Port)\n외부 시스템 의존성 추상화
+note top of StableDiffusionImageGenerator : Application Service Layer\nUse Case 구현체\n비즈니스 로직 오케스트레이션
+note top of RedisGateway : Infrastructure Layer\nOutput Port 구현체\nRedis 연동
+note top of ContentController : Presentation Layer\nREST API 엔드포인트
+note top of RedisConfig : Configuration Layer\n인프라 설정
+
+@enduml
diff --git a/design/backend/class/distribution-service-simple.puml b/design/backend/class/distribution-service-simple.puml
new file mode 100644
index 0000000..29c6c8d
--- /dev/null
+++ b/design/backend/class/distribution-service-simple.puml
@@ -0,0 +1,171 @@
+@startuml
+!theme mono
+
+title Distribution Service 클래스 다이어그램 (요약)
+
+package "com.kt.distribution" {
+
+ package "controller" {
+ class DistributionController <>
+ }
+
+ package "service" {
+ class DistributionService <>
+ class KafkaEventPublisher <>
+ }
+
+ package "adapter" {
+ interface ChannelAdapter <>
+ abstract class AbstractChannelAdapter <>
+ class UriDongNeTvAdapter <>
+ class RingoBizAdapter <>
+ class GiniTvAdapter <>
+ class InstagramAdapter <>
+ class NaverAdapter <>
+ class KakaoAdapter <>
+ }
+
+ package "dto" {
+ class DistributionRequest <>
+ class DistributionResponse <>
+ class ChannelDistributionResult <>
+ class DistributionStatusResponse <>
+ class ChannelStatus <>
+ enum ChannelType <>
+ }
+
+ package "repository" {
+ class DistributionStatusRepository <>
+ interface DistributionStatusJpaRepository <>
+ }
+
+ package "entity" {
+ class DistributionStatus <>
+ class ChannelStatusEntity <>
+ }
+
+ package "mapper" {
+ class DistributionStatusMapper <>
+ }
+
+ package "event" {
+ class DistributionCompletedEvent <>
+ class DistributedChannelInfo <>
+ }
+
+ package "config" {
+ class KafkaConfig <>
+ class OpenApiConfig <>
+ class WebConfig <>
+ }
+}
+
+' 주요 관계만 표시
+DistributionController --> DistributionService
+DistributionService --> ChannelAdapter
+DistributionService --> KafkaEventPublisher
+DistributionService --> DistributionStatusRepository
+
+AbstractChannelAdapter ..|> ChannelAdapter
+UriDongNeTvAdapter --|> AbstractChannelAdapter
+RingoBizAdapter --|> AbstractChannelAdapter
+GiniTvAdapter --|> AbstractChannelAdapter
+InstagramAdapter --|> AbstractChannelAdapter
+NaverAdapter --|> AbstractChannelAdapter
+KakaoAdapter --|> AbstractChannelAdapter
+
+DistributionStatusRepository --> DistributionStatusJpaRepository
+DistributionStatusRepository --> DistributionStatusMapper
+DistributionStatusJpaRepository ..> DistributionStatus
+
+DistributionStatus "1" *-- "many" ChannelStatusEntity
+
+KafkaEventPublisher ..> DistributionCompletedEvent
+DistributionCompletedEvent --> DistributedChannelInfo
+
+note top of DistributionController
+ **Controller 메소드 - API 매핑**
+
+ distribute: POST /distribution/distribute
+ - 다중 채널 배포 요청
+
+ getDistributionStatus: GET /distribution/{eventId}/status
+ - 배포 상태 조회
+end note
+
+note top of DistributionService
+ **핵심 비즈니스 로직**
+
+ • 다중 채널 병렬 배포
+ • ExecutorService 기반 비동기 처리
+ • 배포 상태 관리 (저장/조회)
+ • Kafka 이벤트 발행
+
+ distribute(request)
+ → 병렬 배포 실행
+ → 결과 집계
+ → 상태 저장
+ → 이벤트 발행
+end note
+
+note top of AbstractChannelAdapter
+ **Resilience4j 패턴 적용**
+
+ • Circuit Breaker
+ • Retry (지수 백오프)
+ • Bulkhead (리소스 격리)
+ • Fallback 처리
+
+ 각 채널별 독립적 장애 격리
+end note
+
+note top of DistributionStatusRepository
+ **배포 상태 영구 저장**
+
+ • PostgreSQL 저장
+ • JPA Repository 패턴
+ • Entity ↔ DTO 매핑
+
+ save(eventId, status)
+ findByEventId(eventId)
+end note
+
+note right of ChannelType
+ **배포 채널 종류**
+
+ TV 채널:
+ • URIDONGNETV (우리동네TV)
+ • GINITV (지니TV)
+
+ CALL 채널:
+ • RINGOBIZ (링고비즈)
+
+ SNS 채널:
+ • INSTAGRAM
+ • NAVER (Blog)
+ • KAKAO (Channel)
+end note
+
+note bottom of DistributionStatus
+ **배포 상태 엔티티**
+
+ 전체 배포 상태 관리:
+ • PENDING: 대기중
+ • IN_PROGRESS: 진행중
+ • COMPLETED: 완료
+ • PARTIAL_FAILURE: 부분성공
+ • FAILED: 실패
+
+ 1:N 관계로 채널별 상태 관리
+end note
+
+note bottom of KafkaEventPublisher
+ **Kafka 이벤트 발행**
+
+ Topic: distribution-completed
+
+ 배포 완료 시 이벤트 발행
+ → Analytics Service 소비
+end note
+
+@enduml
diff --git a/design/backend/class/distribution-service.puml b/design/backend/class/distribution-service.puml
new file mode 100644
index 0000000..8dfceb3
--- /dev/null
+++ b/design/backend/class/distribution-service.puml
@@ -0,0 +1,318 @@
+@startuml
+!theme mono
+
+title Distribution Service 클래스 다이어그램 (상세)
+
+package "com.kt.distribution" {
+
+ package "controller" {
+ class DistributionController {
+ - distributionService: DistributionService
+ + distribute(request: DistributionRequest): ResponseEntity
+ + getDistributionStatus(eventId: String): ResponseEntity
+ }
+ }
+
+ package "service" {
+ class DistributionService {
+ - channelAdapters: List
+ - kafkaEventPublisher: Optional
+ - statusRepository: DistributionStatusRepository
+ - executorService: ExecutorService
+ + distribute(request: DistributionRequest): DistributionResponse
+ + getDistributionStatus(eventId: String): DistributionStatusResponse
+ - saveInProgressStatus(eventId: String, channels: List, startedAt: LocalDateTime): void
+ - saveCompletedStatus(eventId: String, results: List, startedAt: LocalDateTime, completedAt: LocalDateTime, successCount: long, failureCount: long): void
+ - convertToChannelStatus(result: ChannelDistributionResult, eventId: String, completedAt: LocalDateTime): ChannelStatus
+ - publishDistributionCompletedEvent(eventId: String, results: List): void
+ }
+
+ class KafkaEventPublisher {
+ - kafkaTemplate: KafkaTemplate