diff --git a/.claude/settings.local.json b/.claude/settings.local.json index b540f70..ca938e6 100644 --- a/.claude/settings.local.json +++ b/.claude/settings.local.json @@ -22,14 +22,7 @@ "Bash(git add \"design/uiux_다람지/\")", "Bash(git commit -m \"$(cat <<''EOF''\n프로토타입 개발 완료 (다람지팀)\n\n- 스타일 가이드 작성 (style-guide.md)\n - 14개 섹션으로 구성된 완전한 디자인 시스템\n - Mobile First 철학 및 접근성 기준 정의\n \n- 공통 리소스 개발\n - common.css: 700+ 라인 반응형 스타일시트\n - common.js: 400+ 라인 유틸리티 라이브러리\n \n- 9개 프로토타입 화면 개발\n - 01-로그인: 사용자 인증\n - 02-대시보드: 메인 대시보드\n - 03-회의예약: 회의 생성 폼\n - 04-템플릿선택: 회의록 템플릿 선택\n - 05-회의진행: 실시간 회의 진행\n - 06-검증완료: 섹션별 검증\n - 07-회의종료: 회의 통계\n - 08-회의록공유: 공유 설정\n - 09-Todo관리: Todo 목록 및 진행 관리\n \n- 주요 특징\n - Mobile First 반응형 디자인\n - WCAG 2.1 Level AA 접근성 준수\n - 실제 동작하는 인터랙션 구현\n - 일관된 예제 데이터 활용\n - Playwright 브라우저 테스트 완료\n\n🤖 Generated with [Claude Code](https://claude.com/claude-code)\n\nCo-Authored-By: Claude \nEOF\n)\")", "Bash(git commit -m \"UI/UX 프로토타입 디렉토리 정리\n\n- 기존 프로토타입 파일 삭제\n- 백업 디렉토리(uiux_bk) 추가\n- 프로젝트 구조 정리\n\n🤖 Generated with [Claude Code](https://claude.com/claude-code)\n\nCo-Authored-By: Claude \")", - "Bash(git add design-last/uiux/)", - "Bash(git commit -m \"$(cat <<''EOF''\nUI/UX 설계서 작성 완료\n\n- Mobile First 설계 원칙에 따라 UI/UX 설계서 작성\n- 11개 주요 화면 설계 (로그인, 대시보드, 회의예약, 템플릿선택, 회의진행, 검증완료, 회의종료, 회의록공유, Todo관리, 회의록상세조회, 회의록수정)\n- 화면별 상세 설계 (개요, 기능, UI 구성, 인터랙션, 데이터 요구사항, 에러 처리)\n- 화면 간 사용자 플로우 및 네비게이션 전략 정의\n- 반응형 설계 전략 (Mobile/Tablet/Desktop 브레이크포인트)\n- WCAG 2.1 Level AA 접근성 보장 방안\n- 성능 최적화 방안 (코드 스플리팅, 캐싱, WebSocket 최적화)\n- 유저스토리와 1:1 매칭 확인\n\n🤖 Generated with [Claude Code](https://claude.com/claude-code)\n\nCo-Authored-By: Claude \nEOF\n)\")", - "Bash(git add \"design-last/uiux_다람지/\")", - "Bash(git commit -m \"$(cat <<''EOF''\n프로토타입 개발 완료 (다람지팀)\n\n- 스타일 가이드 작성 (style-guide.md)\n - 14개 섹션으로 구성된 완전한 디자인 시스템\n - Mobile First 철학 및 접근성 기준 정의\n \n- 공통 리소스 개발\n - common.css: 1,007줄 완전한 반응형 스타일시트\n - common.js: 400+줄 유틸리티 라이브러리\n \n- 11개 프로토타입 화면 개발\n - 01-로그인: 사용자 인증\n - 02-대시보드: 메인 대시보드\n - 03-회의예약: 회의 생성 폼\n - 04-템플릿선택: 회의록 템플릿 선택\n - 05-회의진행: 실시간 회의 진행\n - 06-검증완료: 섹션별 검증\n - 07-회의종료: 회의 통계\n - 08-회의록공유: 공유 설정\n - 09-Todo관리: Todo 목록 및 진행 관리\n - 10-회의록상세조회: 회의록 상세 보기\n - 11-회의록수정: 지난 회의록 수정\n \n- 주요 특징\n - Mobile First 반응형 디자인\n - WCAG 2.1 Level AA 접근성 준수\n - 실제 동작하는 인터랙션 구현\n - 일관된 예제 데이터 활용\n - 완전한 사용자 플로우 구현\n\n🤖 Generated with [Claude Code](https://claude.com/claude-code)\n\nCo-Authored-By: Claude \nEOF\n)\")", - "Bash(git add \"design-last/uiux_다람지/prototype/01-로그인.html\")", - "Bash(git commit -m \"로그인 페이지 버그 수정\n\n- CSS keyframes를 script 태그에서 style 태그로 이동\n- FormValidator 검증을 간단한 검증으로 변경하여 안정성 향상\n- 로그인 후 대시보드 이동 기능 정상화\n\n🤖 Generated with [Claude Code](https://claude.com/claude-code)\n\nCo-Authored-By: Claude \")", - "Bash(git commit -m \"프로젝트 구조 정리 및 프로토타입 업데이트\n\n- design-last, design-v1 디렉토리 정리\n- UI/UX 프로토타입 개선 및 통합\n- 스타일 가이드 및 테스트 결과 업데이트\n- 유저스토리 목록 추가\n- 불필요한 문서 제거\n\n🤖 Generated with [Claude Code](https://claude.com/claude-code)\n\nCo-Authored-By: Claude \")", - "Bash(git commit -m \"UI/UX 프로토타입 통합 및 백업\n\n- design/uiux 디렉토리로 프로토타입 통합\n- 다람지팀 프로토타입을 design/uiux_bk로 백업\n- 9개 프로토타입 화면 업데이트 (01-09)\n- 회의록 상세조회, 수정 화면 추가 (10-11)\n- 스타일 가이드 및 공통 리소스 개선\n- 테스트 결과 문서 업데이트\n\n🤖 Generated with [Claude Code](https://claude.com/claude-code)\n\nCo-Authored-By: Claude \")" + "Bash(curl -s https://raw.githubusercontent.com/cna-bootcamp/clauding-guide/refs/heads/main/guides/design/architecture-patterns.md -o claude/architecture-patterns.md)" ], "deny": [], "ask": [] diff --git a/claude/architecture-patterns.md b/claude/architecture-patterns.md new file mode 100644 index 0000000..4177e80 --- /dev/null +++ b/claude/architecture-patterns.md @@ -0,0 +1,169 @@ +# 클라우드 아키텍처패턴선정 가이드 + +## 개요 +이 가이드는 마이크로서비스 기반 클라우드 시스템을 위한 아키텍처 패턴 선정 방법론을 제공합니다. 체계적인 분석과 정량적 평가를 통해 최적의 패턴을 선정할 수 있습니다. + +## 1. 요구사항 분석 + +### 1.1 유저스토리 분석 +각 서비스별로 기능적/비기능적 요구사항을 명확히 도출합니다. + +**기능적 요구사항**: +- 각 유저스토리에서 요구하는 핵심 기능 +- 서비스 간 데이터 교환 요구사항 +- 비즈니스 로직의 복잡도와 특성 + +**비기능적 요구사항**: +- 성능 요구사항 (응답시간, 처리량) +- 가용성 및 신뢰성 요구사항 +- 확장성 및 유지보수성 요구사항 +- 보안 및 컴플라이언스 요구사항 + +### 1.2 UI/UX설계 분석 +Wireframe을 통해 사용자 인터랙션 패턴과 데이터 플로우를 파악합니다. + +**분석 항목**: +- 사용자 인터랙션 패턴 (동기/비동기 처리 필요성) +- 데이터 조회/변경 패턴 +- 화면 간 전환 흐름 +- 실시간 업데이트 요구사항 + +### 1.3 통합 분석 +유저스토리와 UI/UX 설계를 연계하여 **기술적 도전과제를 식별**합니다. + +**도전과제 식별**: +- 복잡한 비즈니스 트랜잭션 +- 대용량 데이터 처리 +- 실시간 처리 요구사항 +- 외부 시스템 연동 복잡성 +- 서비스 간 의존성 관리 + +## 2. 패턴 선정 + +### 2.1 평가 기준 +다음 5가지 기준으로 각 패턴을 정량적으로 평가합니다. + +| 기준 | 가중치 | 평가 내용 | +|------|--------|-----------| +| **기능 적합성** | 35% | 요구사항을 직접 해결하는 능력 | +| **성능 효과** | 25% | 응답시간 및 처리량 개선 효과 | +| **운영 복잡도** | 20% | 구현 및 운영의 용이성 | +| **확장성** | 15% | 미래 요구사항에 대한 대응력 | +| **비용 효율성** | 5% | 개발/운영 비용 대비 효과(ROI) | + +### 2.2 정량적 평가 방법 + +**평가 척도**: 1-10점 (10점이 가장 우수) + +**패턴별 평가 매트릭스 예시**: + +| 패턴 | 기능 적합성
(35%) | 성능 효과
(25%) | 운영 복잡도
(20%) | 확장성
(15%) | 비용 효율성
(5%) | **총점** | +|------|:---:|:---:|:---:|:---:|:---:|:---:| +| API Gateway | 8 × 0.35 = 2.8 | 7 × 0.25 = 1.75 | 8 × 0.20 = 1.6 | 9 × 0.15 = 1.35 | 7 × 0.05 = 0.35 | **7.85** | +| CQRS | 9 × 0.35 = 3.15 | 9 × 0.25 = 2.25 | 5 × 0.20 = 1.0 | 8 × 0.15 = 1.2 | 6 × 0.05 = 0.3 | **7.90** | +| Event Sourcing | 7 × 0.35 = 2.45 | 8 × 0.25 = 2.0 | 4 × 0.20 = 0.8 | 9 × 0.15 = 1.35 | 5 × 0.05 = 0.25 | **6.85** | + +### 2.3 단계별 적용 로드맵 +MVP → 확장 → 고도화 3단계로 구분하여 점진적 적용 계획을 수립합니다. + +**Phase 1: MVP (Minimum Viable Product)** +- 핵심 비즈니스 기능 중심 +- 단순하고 안정적인 패턴 우선 +- 빠른 출시를 위한 최소 기능 + +**Phase 2: 확장 (Scale-up)** +- 사용자 증가에 따른 성능 최적화 +- 고급 패턴 도입 +- 모니터링 및 운영 자동화 + +**Phase 3: 고도화 (Advanced)** +- 복잡한 비즈니스 요구사항 대응 +- 최신 기술 및 패턴 적용 +- 글로벌 확장 대비 + +## 3. 문서 작성 + +### 3.1 구조화된 작성 순서 +1. **요구사항 분석 결과** +2. **패턴 평가** (평가 매트릭스 포함) +3. **적용 설계** (Mermaid 다이어그램) +4. **구현 계획** (Phase별 로드맵) + +### 3.2 Mermaid 다이어그램 작성 +서비스 아키텍처와 패턴 적용을 시각적으로 표현합니다. + +```mermaid +graph TB + Client[클라이언트] --> Gateway[API Gateway] + Gateway --> Auth[인증 서비스] + Gateway --> UserSvc[사용자 서비스] + Gateway --> OrderSvc[주문 서비스] + + OrderSvc --> EventBus[이벤트 버스] + EventBus --> PaymentSvc[결제 서비스] + EventBus --> NotificationSvc[알림 서비스] + + UserSvc --> UserDB[(사용자 DB)] + OrderSvc --> OrderDB[(주문 DB)] + PaymentSvc --> PaymentDB[(결제 DB)] +``` + +### 3.3 실용적 내용 포함 +- **코드 예시**: 패턴 구현을 위한 구체적인 코드 스니펫 +- **구현 시 고려사항**: 실제 개발 시 주의할 점 +- **예상 효과**: 정량적 성과 지표 (응답시간 개선, 처리량 증가 등) + +## 참고 자료 +- **유저스토리** +- UI/UX설계서 +- **클라우드아키텍처패턴요약표** + +## 결과 파일 +선정된 아키텍처 패턴은 다음과 같이 문서화됩니다: + +### 파일명 +design/pattern/architecture-pattern.md + +### 필수 포함 내용 +1. **요구사항 분석 결과** + - 기능적/비기능적 요구사항 상세 분석 + - 기술적 도전과제 식별 + +2. **패턴 선정 매트릭스 (평가표)** + - 후보 패턴별 정량적 평가 점수 + - 선정 근거 및 이유 + +3. **서비스별 패턴 적용 설계 (Mermaid)** + - 전체 아키텍처 구조 + - 패턴별 적용 영역 표시 + +4. **Phase별 구현 로드맵** + - 단계별 적용 계획 + - 마일스톤 및 목표 설정 + +5. **예상 성과 지표** + - 성능 개선 예상치 + - 비용 절감 효과 + - 개발 생산성 향상 + +## 체크리스트 + +작성 완료 후 다음 항목들을 검토하세요: + +- [ ] **각 유저스토리가 어떤 패턴으로 해결되는지 명시했는가?** +- [ ] **패턴 선정 이유를 정량적으로 설명했는가?** +- [ ] **패턴 간 상호작용과 통합 아키텍처를 표현했는가?** +- [ ] **구현 우선순위와 단계별 목표가 명확한가?** +- [ ] **실무자가 바로 활용할 수 있는 수준인가?** + +## 작성 시 주의사항 + +1. **객관적 평가**: 주관적 판단보다는 정량적 데이터 기반 선정 +2. **현실성**: 팀의 기술 수준과 프로젝트 일정을 고려한 실현 가능한 패턴 선정 +3. **확장성**: 현재 요구사항뿐만 아니라 미래 확장성까지 고려 +4. **비용 효율성**: 과도한 엔지니어링 지양, 비즈니스 가치 중심 선정 +5. **문서화**: 선정 과정과 근거를 명확히 문서화하여 후속 의사결정 지원 + +## 완료 후 mermaid 스크립트 테스트 방법 안내 +- https://mermaid.live/edit 에 접근 +- 스크립트 내용을 붙여넣어 확인 \ No newline at end of file diff --git a/claude/cloud-design-patterns.md b/claude/cloud-design-patterns.md new file mode 100644 index 0000000..4e39358 --- /dev/null +++ b/claude/cloud-design-patterns.md @@ -0,0 +1,104 @@ +# 클라우드 디자인 패턴 개요 + +## 전체 분류 현황 + +총 **42개의 클라우드 디자인 패턴** + +- **DB 성능개선**: 1개 +- **읽기 최적화**: 4개 +- **핵심업무 집중**: 6개 +- **안정적 현대화**: 2개 +- **효율적 분산처리**: 13개 +- **안정성**: 6개 +- **보안**: 3개 +- **운영**: 7개 + +--- + +## 패턴 목록 + +### 1. DB 성능개선 (1개) + +| No. | 패턴명 | 목적 | 설명 | +|-----|--------|------|------| +| 1 | Sharding | 데이터 양 줄이기 | 데이터 저장소를 수평적으로 분할(shard)하여 대규모 데이터 저장 및 접근 시 확장성을 높이는 패턴 | + +### 2. 읽기 최적화 (4개) + +| No. | 패턴명 | 목적 | 설명 | +|-----|--------|------|------| +| 2 | Index Table | NoSQL DB Query 최적화 | 데이터 저장소에서 자주 참조되는 필드에 대한 인덱스를 생성하여 쿼리 성능을 개선하는 패턴 | +| 3 | Cache-Aside | 성능 향상 및 데이터 일관성 유지 | 데이터 저장소에서 캐시에 데이터를 필요에 따라 로드하여 성능을 개선하고, 캐시와 데이터 저장소 간의 일관성을 유지하는 패턴 | +| 4 | Materialized View | 쿼리 성능 최적화 | 데이터를 미리 변환하여 준비된 뷰를 생성함으로써 쿼리 성능을 높이고 데이터 추출을 효율화하는 패턴 | +| 5 | CQRS | 읽기/쓰기 분리 | 데이터 저장소의 읽기와 쓰기 작업을 분리하여 성능, 확장성, 보안성을 높이는 패턴 | + +### 3. 핵심업무 집중 (6개) + +| No. | 패턴명 | 목적 | 설명 | +|-----|--------|------|------| +| 6 | Gateway Offloading | 횡단관심사 분리 | SSL 인증서 관리, 인증, 로깅 등의 공통 기능을 게이트웨이로 분리하여 애플리케이션의 복잡도를 낮추는 패턴 | +| 7 | Gateway Routing | 라우팅 중앙 처리 | 단일 엔드포인트를 통해 요청을 받아 백엔드 서비스나 인스턴스로 라우팅하는 패턴 | +| 8 | Gateway Aggregation | 클라이언트 요청 수 줄이기 | 단일 엔드포인트에서 클라이언트 요청을 받아 여러 백엔드 서비스로 분배하고 응답을 취합하는 패턴 | +| 9 | Backends for Frontends | 프론트엔드 유형별 전용처리 | 특정 프런트엔드에 특화된 백엔드 서비스를 별도로 구축하는 패턴 | +| 10 | Sidecar | 공통 기능 분리 | 애플리케이션의 일부 컴포넌트를 별도 프로세스나 컨테이너로 분리하여 격리와 확장성을 제공하는 패턴 | +| 11 | Ambassador | 네트워크 통신의 안정성과 보안 강화 | 클라이언트를 대신해 네트워크 요청을 처리하는 헬퍼 서비스를 생성하는 패턴 | + +### 4. 안정적 현대화 (2개) + +| No. | 패턴명 | 목적 | 설명 | +|-----|--------|------|------| +| 12 | Strangler Fig | 현대화의 위험 최소화와 점진적 전환 | 레거시 시스템을 점진적으로 새로운 애플리케이션 및 서비스로 교체하는 패턴 | +| 13 | Anti-Corruption Layer | 시스템 간 안정적 인터페이스 | 서로 다른 하위 시스템 간의 의미적 차이를 조정하기 위해 중간 계층을 구현하는 패턴 | + +### 5. 효율적 분산처리 (13개) + +| No. | 패턴명 | 목적 | 설명 | +|-----|--------|------|------| +| 14 | Pipes and Filters | 작업 단계 모듈화로 재사용성과 성능 향상 | 복잡한 작업을 독립적인 단계(필터)로 분리하고 메시지(파이프)로 연결하여 모듈성과 유연성을 높이는 패턴 | +| 15 | Scheduler Agent Supervisor | 워크플로우의 신뢰성 향상 | 작업 단계를 스케줄러, 에이전트, 감독자로 분리하여 신뢰성과 확장성을 높이는 패턴 | +| 16 | Leader Election | 분산 작업의 충돌 방지와 안정성 향상 | 분산 시스템에서 여러 작업 인스턴스 중 하나를 리더로 선출하여 조정 역할을 맡기는 패턴 | +| 17 | Saga | 데이터 일관성 보장 | 각 서비스의 로컬 트랜잭션을 사용하여 분산 트랜잭션의 일관성을 보장하는 패턴 | +| 18 | Compensating Transaction | 오류 복구로 데이터 일관성 보장 | 분산 트랜잭션에서 실패한 작업을 보상하기 위해 이전 작업을 취소하거나 상쇄하는 트랜잭션을 실행하는 패턴 | +| 19 | Priority Queue | 중요 작업의 우선 처리 보장 | 메시지의 우선순위에 따라 처리 순서를 조정하는 큐를 사용하는 패턴 | +| 20 | Queue-Based Load Leveling | 부하의 균등한 분산으로 안정성 확보 | 메시지 큐를 사용하여 작업과 서비스 간의 부하를 균등하게 분산시키는 패턴 | +| 21 | Sequential Convoy | 처리순서 보장 | 관련 메시지 집합을 순서대로 처리하되 다른 메시지 처리를 차단하지 않도록 하는 패턴 | +| 22 | Claim Check | 메시지 크기 최소화 및 성능과 보안 향상 | 메시지에서 페이로드를 분리하여 외부 저장소에 저장하고 참조키(클레임 체크)를 사용하는 패턴 | +| 23 | Publisher-Subscriber | 단일 이벤트 메시지의 복수 서비스 처리 보장 | 다수의 소비자(Consumer)에게 이벤트를 발행하는 패턴 | +| 24 | Asynchronous Request-Reply | 장시간 처리 작업의 응답시간 단축 | 프런트엔드(클라이언트)와 백엔드 간 비동기로 요청과 응답을 분리하여 응답 시간을 단축하는 패턴 | +| 25 | Competing Consumers | 병렬처리로 작업 처리 속도 향상 | 동일 메시지 채널에서 여러 소비자가 경쟁적으로 메시지를 처리하여 병렬성을 높이는 패턴 | +| 26 | Choreography | 중앙집중 처리의 병목현상 방지 | 중앙 조정자 없이 각 서비스가 자율적으로 이벤트를 구독하고 반응하여 전체 워크플로를 수행하는 패턴 | + +### 6. 안정성 (6개) + +| No. | 패턴명 | 목적 | 설명 | +|-----|--------|------|------| +| 27 | Rate Limiting | 요청 폭주 방지로 안정성 유지 | 일정 기간 동안 허용되는 요청 수를 제한하여 과부하를 방지하고 서비스 안정성을 높이는 패턴 | +| 28 | Throttling | 요청 폭주 방지로 안정성 유지 | 시스템의 부하 상태에 따라 요청 처리량을 동적으로 조절하여 과부하를 방지하는 패턴 | +| 29 | Bulkhead | 자원풀 격리로 장애 전파 방지 | 애플리케이션 요소를 격리된 풀로 분할하여 하나의 장애가 전체로 전파되는 것을 방지하는 패턴 | +| 30 | Circuit Breaker | 장애전파 방지 | 장애가 발생한 구성 요소를 빠르게 감지하고 요청 실패를 최소화하는 패턴 | +| 31 | Retry | 일시적 오류시 처리 보장 | 일시적인 오류에 대해 실패한 요청을 재시도하여 복원력을 높이는 패턴 | +| 32 | Event Sourcing | 데이터 멱등성 보장과 변경 기록 제공 | 데이터에 대한 모든 변경사항을 이벤트로 저장하고, 이벤트를 재생하여 데이터의 상태를 복원하는 패턴 | + +### 7. 보안 (3개) + +| No. | 패턴명 | 목적 | 설명 | +|-----|--------|------|------| +| 33 | Federated Identity | 사용자 인증 및 관리 효율화 | 인증을 외부 ID 제공자에 위임하여 사용자 관리를 간소화하고 SSO를 구현하는 패턴 | +| 34 | Gatekeeper | 데이터 접근 제어와 보안 강화 | 신뢰할 수 있는 호스트에 보안 관련 기능을 집중시켜 스토리지나 서비스의 보안을 강화하는 패턴 | +| 35 | Valet Key | 네트워크 대역폭 감소 | 클라이언트가 특정 리소스에 제한된 직접 접근을 할 수 있도록 토큰을 사용하는 패턴 | + +### 8. 운영 (7개) + +| No. | 패턴명 | 목적 | 설명 | +|-----|--------|------|------| +| 36 | Geodes | 글로벌 서비스 가용성과 성능 최적화 | 백엔드 서비스를 여러 지역에 분산 배치하여 지연 시간을 줄이고 가용성을 높이는 패턴 | +| 37 | Deployment Stamps | 멀티 테넌트 관리 | 리소스 그룹을 복제하여 작업이나 테넌트 단위로 격리된 운영 환경을 제공하는 패턴 | +| 38 | Health Endpoint Monitoring | 서비스 가용성 상태 점검 | 애플리케이션의 상태를 모니터링하기 위한 전용 API 엔드포인트를 노출하는 패턴 | +| 39 | Compute Resource Consolidation | 자원 사용 효율성과 비용 절감 | 여러 작업이나 운영을 단일 컴퓨팅 단위로 통합하여 효율성과 비용을 최적화하는 패턴 | +| 40 | Static Content Hosting | 정적 자원 제공, 비용절감과 성능 향상 | 정적 콘텐츠를 클라우드 스토리지에 배포하여 클라이언트에 직접 제공함으로써 컴퓨팅 인스턴스 사용을 줄이는 패턴 | +| 41 | External Configuration Store | 환경설정 중앙관리와 재배포 없이 설정 변경 적용 | 애플리케이션의 설정 정보를 중앙화하여 관리 효율성을 높이고 설정 값 변경 시 재배포 없이 적용하는 패턴 | +| 42 | Edge Workload Configuration | 엣지컴퓨팅의 효율적 관리 | 장치와 시스템이 혼재된 엣지 환경에서 워크로드 구성을 효율적으로 관리하여 지연 시간 단축과 네트워크 비용 절감을 하는 패턴 | + +--- + +> **참고**: 이 문서는 클라우드 환경에서 자주 사용되는 디자인 패턴들을 체계적으로 분류하여 정리한 것입니다. 각 패턴은 특정 목적과 상황에 맞게 적용될 수 있으며, 실제 구현 시에는 프로젝트의 요구사항과 제약사항을 충분히 고려해야 합니다. diff --git a/claude/mermaid-guide.md b/claude/mermaid-guide.md new file mode 100644 index 0000000..6d6b3f0 --- /dev/null +++ b/claude/mermaid-guide.md @@ -0,0 +1,300 @@ +# Mermaid문법검사가이드 + +## 개요 + +Mermaid 다이어그램의 문법 오류를 사전에 검출하여 렌더링 실패를 방지하기 위한 가이드입니다. Docker 기반 Mermaid CLI를 활용하여 로컬에서 빠르게 문법을 검증할 수 있습니다. + +## Mermaid CLI 서버 설치 및 검사 + +### Docker로 Mermaid CLI 컨테이너 실행 + +```bash +# Mermaid CLI 컨테이너가 실행 중인지 확인 +docker ps | grep mermaid-cli + +# ⚠️ 중요: 첫 실행 시 이미지 다운로드를 먼저 진행 (큰 이미지로 인한 타임아웃 방지) +docker pull minlag/mermaid-cli:latest + +# Mermaid CLI 컨테이너가 없으면 설치 및 실행 (root 권한으로 실행, 포트 48080 사용) +docker run -d --rm --name mermaid-cli -u root -p 48080:8080 --entrypoint sh minlag/mermaid-cli:latest -c "while true;do sleep 3600; done" + +# 컨테이너 상태 확인 +docker logs mermaid-cli +``` + +#### 💡 Docker 이미지 다운로드 관련 주의사항 + +**첫 실행 시 발생할 수 있는 문제:** +- `minlag/mermaid-cli:latest` 이미지가 큰 용량(약 700MB+)이므로 다운로드에 시간이 오래 걸림 +- `docker run` 명령 실행 시 이미지가 없으면 자동 다운로드하지만 타임아웃 발생 가능 +- **해결방법**: `docker pull` 명령으로 이미지를 먼저 다운로드한 후 컨테이너 실행 + +**권장 실행 순서:** +1. `docker pull minlag/mermaid-cli:latest` (이미지 다운로드) +2. `docker run` 명령으로 컨테이너 실행 +3. 필수 설정 진행 + +#### ⚠️ 중요: 최초 컨테이너 생성 후 필수 설정 + +Mermaid CLI는 Puppeteer를 사용하여 다이어그램을 렌더링하므로 Chromium 브라우저가 필요합니다. +컨테이너를 처음 생성한 후 다음 명령을 실행하여 필요한 패키지를 설치해야 합니다: + +```bash +# Chromium 및 필요한 종속성 설치 +docker exec mermaid-cli sh -c "apk add --no-cache chromium chromium-chromedriver nss freetype harfbuzz ca-certificates ttf-freefont" + +# Puppeteer가 사용할 설정 파일 생성 +docker exec mermaid-cli sh -c "echo '{\"executablePath\": \"/usr/bin/chromium-browser\", \"args\": [\"--no-sandbox\", \"--disable-setuid-sandbox\", \"--disable-dev-shm-usage\"]}' > /tmp/puppeteer-config.json" +``` + +이 설정은 컨테이너가 실행되는 동안 유지되므로 한 번만 실행하면 됩니다. + +문법검사 후 Container를 중지하지 않고 계속 사용함 + +## 문법 검사 방법 +현재 OS에 맞게 수행. + +### Linux/macOS 버전 +**스크립트 파일(tools/check-mermaid.sh)을 이용하여 수행** + +1. tools/check-mermaid.sh 파일 존재 여부 확인 +2. 스크립트 파일이 없으면 "Mermaid문법검사기(Linux/Mac)"를 tools/check-mermaid.sh 파일로 다운로드하여 스크립트 파일을 만듦 +3. 스크립트 파일이 있으면 그 스크립트 파일을 이용하여 검사 + +```bash +# 1. 스크립트 실행 권한 부여 (최초 1회) +chmod +x tools/check-mermaid.sh + +# 2. 문법 검사 실행 +./tools/check-mermaid.sh {검사할 파일} + +# 예시 +./tools/check-mermaid.sh design/backend/physical/physical-architecture.mmd +``` + +### Windows PowerShell 버전 +**스크립트 파일(tools/check-mermaid.ps1)을 이용하여 수행** + +1. tools/check-mermaid.ps1 파일 존재 여부 확인 +2. 스크립트 파일이 없으면 "Mermaid문법검사기(Window)"를 tools/check-mermaid.ps1 파일로 다운로드하여 스크립트 파일을 만듦 +3. 스크립트 파일이 있으면 그 스크립트 파일을 이용하여 검사 + +```powershell +# 문법 검사 실행 +.\tools\check-mermaid.ps1 {검사할 파일} + +# 예시 +.\tools\check-mermaid.ps1 design\backend\physical\physical-architecture.mmd +``` + +### 수동 검사 방법 (스크립트 없이) + +```bash +# 1. 고유 파일명 생성 (충돌 방지) +TEMP_FILE="/tmp/mermaid_$(date +%s)_$$.mmd" + +# 2. 파일 복사 +docker cp {검사할 파일} mermaid-cli:${TEMP_FILE} + +# 3. 문법 검사 (Puppeteer 설정 파일 사용) +docker exec mermaid-cli sh -c "cd /home/mermaidcli && node_modules/.bin/mmdc -i ${TEMP_FILE} -o /tmp/output.svg -p /tmp/puppeteer-config.json -q" + +# 4. 임시 파일 삭제 +docker exec mermaid-cli rm -f ${TEMP_FILE} /tmp/output.svg +``` + +**주의**: Puppeteer 설정 파일(`/tmp/puppeteer-config.json`)이 있어야 합니다. 없다면 위의 "최초 컨테이너 생성 후 필수 설정"을 먼저 실행하세요. + +### 검사 결과 해석 + +| 출력 | 의미 | 대응 방법 | +|------|------|-----------| +| "Success: Mermaid syntax is valid!" | 문법 오류 없음 ✅ | 정상, 렌더링 가능 | +| "Parse error on line X" | X번째 줄 구문 오류 ❌ | 해당 라인 문법 확인 | +| "Expecting 'XXX'" | 예상 토큰 오류 ❌ | 누락된 문법 요소 추가 | +| "Syntax error" | 일반 문법 오류 ❌ | 전체 구조 재검토 | + +## Mermaid 다이어그램 타입별 주의사항 + +### 1. Graph/Flowchart +```mermaid +graph TB + %% 올바른 사용법 ✅ + A[Node A] --> B[Node B] + C[Node C] -.-> D[Node D] + E[Node E] ==> F[Node F] + + %% 주의사항 + %% - 노드 ID에 공백 불가 (대신 [Label] 사용) + %% - subgraph와 end 개수 일치 필요 + %% - 따옴표 안에서 특수문자 주의 +``` + +### 2. Sequence Diagram +```mermaid +sequenceDiagram + %% 올바른 사용법 ✅ + participant A as Service A + participant B as Service B + + A->>B: Request + B-->>A: Response + A->>+B: Call with activation + B-->>-A: Return with deactivation + + %% 주의사항 + %% - participant 선언 권장 + %% - 활성화(+)/비활성화(-) 쌍 맞추기 + %% - Note 블록 종료 확인 +``` + +### 3. Class Diagram +```mermaid +classDiagram + %% 올바른 사용법 ✅ + class Animal { + +String name + +int age + +makeSound() void + } + + class Dog { + +String breed + +bark() void + } + + Animal <|-- Dog : inherits + + %% 주의사항 + %% - 메서드 괄호 필수 + %% - 관계 표현 정확히 + %% - 접근 제한자 기호 확인 +``` + +### 4. State Diagram +```mermaid +stateDiagram-v2 + %% 올바른 사용법 ✅ + [*] --> Idle + Idle --> Processing : start + Processing --> Completed : finish + Processing --> Error : error + Error --> Idle : reset + Completed --> [*] + + %% 주의사항 + %% - [*]는 시작/종료 상태 + %% - 상태 이름에 공백 불가 + %% - 전이 레이블 콜론(:) 사용 +``` + +## 일반적인 오류와 해결 방법 + +### 1. 괄호 불균형 +```mermaid +%% 잘못된 예 ❌ +graph TB + A[Node (with parenthesis)] %% 괄호 안에 괄호 + +%% 올바른 예 ✅ +graph TB + A[Node with parenthesis] +``` + +### 2. 특수 문자 이스케이프 +```mermaid +%% 잘못된 예 ❌ +graph TB + A[Security & Management] %% & 문자 직접 사용 + +%% 올바른 예 ✅ +graph TB + A[Security & Management] %% HTML 엔티티 사용 +``` + +### 3. subgraph/end 불일치 +```mermaid +%% 잘못된 예 ❌ +graph TB + subgraph One + A --> B + subgraph Two + C --> D + end %% Two만 닫힘, One은 안 닫힘 + +%% 올바른 예 ✅ +graph TB + subgraph One + A --> B + subgraph Two + C --> D + end + end %% 모든 subgraph 닫기 +``` + +### 4. 노드 참조 오류 +```mermaid +%% 잘못된 예 ❌ +graph TB + A --> UnknownNode %% 정의되지 않은 노드 + +%% 올바른 예 ✅ +graph TB + A[Node A] --> B[Node B] %% 모든 노드 정의 +``` + +## 컨테이너 관리 + +### 컨테이너 중지 및 삭제 +```bash +# 컨테이너 중지 +docker stop mermaid-cli + +# 컨테이너 삭제 +docker rm mermaid-cli + +# 한 번에 중지 및 삭제 +docker stop mermaid-cli && docker rm mermaid-cli +``` + +### 컨테이너 재시작 +```bash +# 컨테이너 재시작 +docker restart mermaid-cli +``` + +## 성능 최적화 팁 + +1. **컨테이너 유지**: 검사 후 컨테이너를 중지하지 않고 유지하여 다음 검사 시 빠르게 실행 +2. **배치 검사**: 여러 파일을 연속으로 검사할 때 컨테이너 재시작 없이 진행 +3. **로컬 파일 사용**: 네트워크 경로보다 로컬 파일 경로 사용 권장 + +## 문제 해결 + +### Docker 관련 오류 +```bash +# Docker 데몬 실행 확인 +docker ps + +# Docker Desktop 시작 (Windows/Mac) +# Docker 서비스 시작 (Linux) +sudo systemctl start docker +``` + +### 권한 오류 +```bash +# Linux/Mac에서 스크립트 실행 권한 +chmod +x tools/check-mermaid.sh + +# Docker 권한 (Linux) +sudo usermod -aG docker $USER +``` + +### 컨테이너 이미지 오류 +```bash +# 이미지 재다운로드 +docker pull minlag/mermaid-cli:latest + +# 기존 컨테이너 삭제 후 재생성 +docker stop mermaid-cli && docker rm mermaid-cli +``` \ No newline at end of file diff --git a/design/pattern/architecture-pattern.md b/design/pattern/architecture-pattern.md new file mode 100644 index 0000000..c34c2ca --- /dev/null +++ b/design/pattern/architecture-pattern.md @@ -0,0 +1,1274 @@ +# 클라우드 아키텍처 패턴 적용 방안 + +## 문서 정보 +- **작성일**: 2025-10-21 +- **작성자**: 아키텍트 팀 +- **버전**: 1.0 +- **프로젝트**: 회의록 작성 및 공유 개선 서비스 + +--- + +## 1. 요구사항 분석 결과 + +### 1.1 기능적 요구사항 + +#### 핵심 기능 +1. **실시간 회의록 작성 및 협업** + - 여러 참석자의 동시 수정 및 실시간 동기화 + - 충돌 감지 및 해결 (Last Write Wins) + - 버전 관리 및 변경 이력 추적 + - WebSocket 기반 3-5초 간격 업데이트 + +2. **AI 기반 회의록 자동 생성** + - STT 음성-텍스트 변환 (1초 이내 지연) + - LLM 기반 구조화된 회의록 작성 + - Todo 자동 추출 및 담당자 식별 + - 프롬프팅 기반 다양한 형식 변환 + +3. **맥락 기반 용어 설명 (RAG)** + - 전문용어 자동 감지 및 하이라이트 + - 과거 회의록/사내 문서 기반 실용적 설명 + - 벡터 유사도 검색 및 관련 문서 연결 + +4. **Todo 실시간 연동** + - AI 추출 Todo 자동 할당 + - 회의록과 양방향 실시간 연결 + - Todo 완료 시 회의록 자동 반영 + - 캘린더 자동 등록 및 리마인더 + +#### 서비스 간 연계 +- **Meeting ↔ STT**: 음성 녹음 → 텍스트 변환 +- **STT ↔ AI**: 텍스트 → 회의록 자동 생성 +- **AI ↔ RAG**: 용어 감지 → 맥락 기반 설명 +- **Meeting ↔ Todo**: 회의록 확정 → Todo 추출/할당 +- **Collaboration**: 모든 변경사항 실시간 동기화 + +### 1.2 비기능적 요구사항 + +#### 성능 요구사항 +| 지표 | 목표 | 근거 | +|------|------|------| +| STT 발언 인식 지연 | 1초 이내 | 유저스토리 UFR-STT-010 | +| STT 변환 정확도 | 60% 이상 | 유저스토리 UFR-STT-020 | +| 화자 식별 정확도 | 90% 이상 | 유저스토리 UFR-STT-010 | +| 실시간 동기화 간격 | 3-5초 | 유저스토리 UFR-AI-010 | +| AI 회의록 생성 | 실시간 업데이트 | 유저스토리 UFR-AI-010 | +| RAG 검색 응답시간 | 2초 이내 | 사용자 경험 | +| Todo 할당 알림 | 즉시 발송 | 유저스토리 UFR-TODO-010 | + +#### 가용성 및 신뢰성 +- **회의 중 서비스 중단 불가**: 99.9% uptime 목표 +- **장애 격리**: 한 서비스 장애가 전체 시스템에 영향 최소화 +- **데이터 손실 방지**: 모든 회의록 변경사항 영구 저장 + +#### 확장성 +- **동시 회의 처리**: MVP 100명 → Phase 2: 1,000명 → Phase 3: 10,000명 +- **대용량 데이터**: 장시간 회의 (3시간+) 안정적 처리 +- **글로벌 확장**: 다중 리전 배포 준비 (Phase 3) + +#### 보안 +- **사용자 인증**: LDAP 연동 SSO +- **권한 관리**: 회의록 접근 권한 제어 +- **데이터 보호**: 민감한 회의 내용 암호화 저장 + +#### 데이터 일관성 +- **Todo ↔ 회의록 동기화**: 실시간 양방향 연결 +- **버전 관리**: 모든 수정사항 이력 추적 +- **충돌 해결**: 동시 수정 시 일관성 보장 + +### 1.3 기술적 도전과제 + +#### 1. 실시간 협업 처리 +**문제**: +- 여러 참석자의 동시 수정으로 인한 충돌 +- WebSocket 연결 관리 및 메시지 전송 부하 +- 3-5초 간격 실시간 업데이트 요구 + +**영향**: +- 사용자 경험 저하 (수정 내용 손실, 충돌) +- 서버 부하 증가 (다수 WebSocket 연결) + +#### 2. 대용량 데이터 처리 +**문제**: +- 음성 녹음 파일 (장시간 회의 시 GB 단위) +- STT 변환 처리 시간 증가 +- 장시간 회의록 (수만 자 텍스트) + +**영향**: +- 응답 시간 지연 +- 저장소 비용 증가 + +#### 3. AI/LLM 통합 복잡성 +**문제**: +- LLM API 호출 시간 (수 초 ~ 수십 초) +- API 비용 (토큰 기반 과금) +- API 장애 시 서비스 중단 + +**영향**: +- 사용자 대기 시간 증가 +- 운영 비용 상승 +- 가용성 저하 + +#### 4. RAG 시스템 성능 +**문제**: +- 벡터 DB 검색 성능 (대량 회의록 축적 시) +- 관련 문서 추출 정확도 +- 맥락 기반 설명 생성 시간 + +**영향**: +- 용어 설명 응답 지연 +- 검색 정확도 저하 + +#### 5. 서비스 간 의존성 관리 +**문제**: +- Meeting → STT → AI 순차 의존성 +- Todo ↔ Meeting 양방향 의존성 +- 한 서비스 장애 시 전체 기능 마비 + +**영향**: +- 장애 전파 +- 가용성 저하 + +#### 6. 데이터 일관성 보장 +**문제**: +- Todo 완료 → 회의록 반영 시 동기화 +- 실시간 수정 충돌 해결 +- 분산 트랜잭션 관리 + +**영향**: +- 데이터 불일치 +- 사용자 혼란 + +--- + +## 2. 패턴 선정 및 평가 + +### 2.1 평가 기준 + +| 기준 | 가중치 | 평가 내용 | +|------|--------|-----------| +| **기능 적합성** | 35% | 요구사항을 직접 해결하는 능력 | +| **성능 효과** | 25% | 응답시간 및 처리량 개선 효과 | +| **운영 복잡도** | 20% | 구현 및 운영의 용이성 (낮을수록 좋음) | +| **확장성** | 15% | 미래 요구사항에 대한 대응력 | +| **비용 효율성** | 5% | 개발/운영 비용 대비 효과 (ROI) | + +**평가 척도**: 1-10점 (10점이 가장 우수) + +### 2.2 패턴 평가 매트릭스 + +| 패턴 | 기능 적합성
(35%) | 성능 효과
(25%) | 운영 복잡도
(20%) | 확장성
(15%) | 비용 효율성
(5%) | **총점** | Phase | +|------|:---:|:---:|:---:|:---:|:---:|:---:|:---:| +| **API Gateway** | 9 × 0.35 = 3.15 | 8 × 0.25 = 2.0 | 8 × 0.20 = 1.6 | 9 × 0.15 = 1.35 | 8 × 0.05 = 0.4 | **8.50** | MVP | +| **Queue-Based Load Leveling** | 9 × 0.35 = 3.15 | 9 × 0.25 = 2.25 | 7 × 0.20 = 1.4 | 8 × 0.15 = 1.2 | 7 × 0.05 = 0.35 | **8.35** | MVP | +| **Cache-Aside** | 8 × 0.35 = 2.8 | 9 × 0.25 = 2.25 | 9 × 0.20 = 1.8 | 7 × 0.15 = 1.05 | 9 × 0.05 = 0.45 | **8.35** | MVP | +| **Publisher-Subscriber** | 9 × 0.35 = 3.15 | 7 × 0.25 = 1.75 | 8 × 0.20 = 1.6 | 9 × 0.15 = 1.35 | 8 × 0.05 = 0.4 | **8.25** | MVP | +| **Asynchronous Request-Reply** | 9 × 0.35 = 3.15 | 8 × 0.25 = 2.0 | 7 × 0.20 = 1.4 | 8 × 0.15 = 1.2 | 7 × 0.05 = 0.35 | **8.10** | MVP | +| **Gateway Offloading** | 8 × 0.35 = 2.8 | 6 × 0.25 = 1.5 | 9 × 0.20 = 1.8 | 7 × 0.15 = 1.05 | 8 × 0.05 = 0.4 | **7.55** | MVP | +| **Federated Identity** | 8 × 0.35 = 2.8 | 5 × 0.25 = 1.25 | 9 × 0.20 = 1.8 | 6 × 0.15 = 0.9 | 8 × 0.05 = 0.4 | **7.15** | MVP | +| **Circuit Breaker** | 8 × 0.35 = 2.8 | 6 × 0.25 = 1.5 | 8 × 0.20 = 1.6 | 7 × 0.15 = 1.05 | 8 × 0.05 = 0.4 | **7.35** | Phase 2 | +| **CQRS** | 7 × 0.35 = 2.45 | 8 × 0.25 = 2.0 | 5 × 0.20 = 1.0 | 8 × 0.15 = 1.2 | 6 × 0.05 = 0.3 | **6.95** | Phase 2 | +| **Retry** | 7 × 0.35 = 2.45 | 6 × 0.25 = 1.5 | 8 × 0.20 = 1.6 | 6 × 0.15 = 0.9 | 8 × 0.05 = 0.4 | **6.85** | Phase 2 | +| **Materialized View** | 6 × 0.35 = 2.1 | 8 × 0.25 = 2.0 | 6 × 0.20 = 1.2 | 7 × 0.15 = 1.05 | 7 × 0.05 = 0.35 | **6.70** | Phase 2 | +| **Event Sourcing** | 7 × 0.35 = 2.45 | 7 × 0.25 = 1.75 | 4 × 0.20 = 0.8 | 9 × 0.15 = 1.35 | 5 × 0.05 = 0.25 | **6.60** | Phase 3 | +| **Saga** | 7 × 0.35 = 2.45 | 6 × 0.25 = 1.5 | 4 × 0.20 = 0.8 | 8 × 0.15 = 1.2 | 5 × 0.05 = 0.25 | **6.20** | Phase 3 | +| **Bulkhead** | 6 × 0.35 = 2.1 | 6 × 0.25 = 1.5 | 7 × 0.20 = 1.4 | 6 × 0.15 = 0.9 | 7 × 0.05 = 0.35 | **6.25** | Phase 2 | +| **Valet Key** | 5 × 0.35 = 1.75 | 7 × 0.25 = 1.75 | 8 × 0.20 = 1.6 | 5 × 0.15 = 0.75 | 8 × 0.05 = 0.4 | **6.25** | Phase 2 | +| **Priority Queue** | 5 × 0.35 = 1.75 | 6 × 0.25 = 1.5 | 7 × 0.20 = 1.4 | 6 × 0.15 = 0.9 | 6 × 0.05 = 0.3 | **5.85** | Phase 3 | +| **Health Endpoint Monitoring** | 7 × 0.35 = 2.45 | 4 × 0.25 = 1.0 | 9 × 0.20 = 1.8 | 5 × 0.15 = 0.75 | 8 × 0.05 = 0.4 | **6.40** | MVP | +| **External Configuration Store** | 6 × 0.35 = 2.1 | 4 × 0.25 = 1.0 | 8 × 0.20 = 1.6 | 6 × 0.15 = 0.9 | 8 × 0.05 = 0.4 | **6.00** | Phase 3 | + +### 2.3 선정 패턴 및 근거 + +#### MVP Phase (총 8개 패턴) +1. **API Gateway (8.50점)** ⭐ 최고점 + - 단일 진입점으로 모든 클라이언트 요청 처리 + - 서비스 라우팅 중앙화 + - 높은 기능 적합성과 확장성 + +2. **Queue-Based Load Leveling (8.35점)** + - STT/AI 비동기 처리 필수 + - 부하 분산으로 성능 안정화 + - AI API 호출 최적화 + +3. **Cache-Aside (8.35점)** + - RAG 검색 결과 캐싱으로 성능 향상 + - 구현 용이, 높은 비용 효율성 + - 60% 검색 비용 절감 예상 + +4. **Publisher-Subscriber (8.25점)** + - Todo 상태 변경 이벤트 + - 회의록 공유 알림 + - 실시간 알림 발송 + +5. **Asynchronous Request-Reply (8.10점)** + - AI 회의록 생성 비동기 처리 + - 사용자 대기 시간 단축 + - 장시간 작업 효율적 처리 + +6. **Gateway Offloading (7.55점)** + - 인증(LDAP), 로깅, SSL 처리 + - 서비스 복잡도 감소 + - 핵심 비즈니스 로직에 집중 + +7. **Federated Identity (7.15점)** + - LDAP SSO 연동 + - 사용자 관리 효율화 + - 보안 강화 + +8. **Health Endpoint Monitoring (6.40점)** + - 서비스 상태 점검 + - 장애 조기 발견 + - 운영 안정성 + +#### Phase 2 - 확장 (총 6개 패턴 추가) +9. **Circuit Breaker (7.35점)** + - AI/STT API 장애 격리 + - 장애 복구 시간 90% 단축 + - 가용성 99.9% 달성 + +10. **CQRS (6.95점)** + - 회의록 읽기/쓰기 분리 + - 읽기 성능 70% 향상 + - 확장성 개선 + +11. **Retry (6.85점)** + - 일시적 오류 자동 복구 + - Circuit Breaker와 통합 + - 안정성 향상 + +12. **Materialized View (6.70점)** + - 회의록 목록, 요약 뷰 + - 조회 성능 80% 향상 + - 사용자 경험 개선 + +13. **Bulkhead (6.25점)** + - 서비스 격리로 장애 전파 방지 + - 리소스 풀 분리 + - 안정성 강화 + +14. **Valet Key (6.25점)** + - 음성 파일 직접 다운로드 + - 네트워크 대역폭 절감 + - Azure Storage SAS 토큰 활용 + +#### Phase 3 - 고도화 (총 4개 패턴 추가) +15. **Event Sourcing (6.60점)** + - 완벽한 변경 이력 추적 + - 감사 추적 (Audit Trail) + - 데이터 복원 가능 + +16. **Saga (6.20점)** + - Todo 할당 분산 트랜잭션 + - 데이터 일관성 보장 + - 보상 트랜잭션 + +17. **Priority Queue (5.85점)** + - VIP 회의 우선 처리 + - 중요 회의 응답시간 50% 단축 + - 비즈니스 가치 향상 + +18. **External Configuration Store (6.00점)** + - 동적 설정 관리 + - 재배포 없이 설정 변경 + - 운영 효율성 + +--- + +## 3. 서비스별 패턴 적용 설계 + +### 3.1 서비스별 패턴 매핑 + +#### API Gateway Layer +- **API Gateway**: 모든 요청 진입점, 라우팅 +- **Gateway Offloading**: LDAP 인증, 로깅, SSL 종료 +- **Rate Limiting**: 사용자당 100 req/min + +#### User Service +- **Federated Identity**: LDAP SSO 연동 +- **Cache-Aside**: 사용자 정보 캐싱 (TTL 30분) +- **Health Endpoint**: /actuator/health + +#### Meeting Service +- **CQRS**: 읽기(조회)/쓰기(작성) 모델 분리 +- **Materialized View**: 회의록 목록, 대시보드 요약 +- **Event Sourcing**: 회의록 변경 이력 (Phase 3) +- **Publisher-Subscriber**: 회의록 공유 이벤트 +- **Cache-Aside**: 회의록 목록 (TTL 5분) + +#### STT Service +- **Queue-Based Load Leveling**: 음성 변환 큐 처리 +- **Asynchronous Request-Reply**: 변환 결과 비동기 반환 +- **Valet Key**: Azure Blob Storage 음성 파일 직접 업로드 +- **Circuit Breaker**: Azure Speech API 장애 격리 +- **Retry**: STT API 일시적 오류 (최대 3회) +- **Priority Queue**: 중요 회의 우선 처리 (Phase 3) + +#### AI Service +- **Queue-Based Load Leveling**: LLM 요청 큐 (배치 처리) +- **Asynchronous Request-Reply**: AI 생성 비동기 응답 +- **Circuit Breaker**: OpenAI/Azure OpenAI API 장애 격리 +- **Retry**: LLM API 오류 재시도 (Exponential Backoff) +- **Priority Queue**: VIP 회의 우선 처리 (Phase 3) +- **Cache-Aside**: 프롬프트 템플릿 캐싱 + +#### RAG Service +- **Cache-Aside**: 벡터 검색 결과 캐싱 (TTL 1시간) +- **Materialized View**: 용어 사전 인덱스 +- **Circuit Breaker**: 벡터 DB 장애 격리 +- **Retry**: 검색 실패 재시도 + +#### Collaboration Service +- **Publisher-Subscriber**: 실시간 동기화 이벤트 (WebSocket) +- **Event Sourcing**: 수정 이력 관리 (Phase 3) +- **Bulkhead**: WebSocket 연결 풀 격리 + +#### Todo Service +- **Saga**: Todo 할당 → 알림 → 캘린더 등록 (Phase 3) +- **Publisher-Subscriber**: Todo 상태 변경 이벤트 +- **Cache-Aside**: Todo 목록 캐싱 (TTL 5분) +- **Asynchronous Request-Reply**: 캘린더 등록 비동기 + +#### Notification Service +- **Queue-Based Load Leveling**: 알림 발송 큐 +- **Competing Consumers**: 병렬 알림 처리 (이메일/푸시) +- **Retry**: 알림 발송 실패 재시도 + +#### 공통 적용 +- **Health Endpoint Monitoring**: 모든 서비스 +- **External Configuration Store**: 환경 설정 중앙 관리 (Phase 3) +- **Bulkhead**: 서비스별 리소스 풀 격리 + +### 3.2 전체 시스템 아키텍처 + +```mermaid +graph TB + subgraph "Client Layer" + Web[Web Client] + Mobile[Mobile App] + end + + subgraph "API Gateway Layer" + Gateway[API Gateway
+ Gateway Offloading
+ Rate Limiting] + end + + subgraph "Authentication" + LDAP[LDAP Server
Federated Identity] + end + + subgraph "Microservices" + User[User Service
Cache-Aside] + Meeting[Meeting Service
CQRS + Event Sourcing] + STT[STT Service
Queue + Async] + AI[AI Service
Queue + Circuit Breaker] + RAG[RAG Service
Cache-Aside] + Collab[Collaboration Service
Pub-Sub + WebSocket] + Todo[Todo Service
Saga + Pub-Sub] + Notif[Notification Service
Queue + Competing Consumers] + end + + subgraph "Data Layer" + Cache[(Redis Cache
Cache-Aside)] + UserDB[(User DB)] + MeetingDB[(Meeting DB)] + STTDB[(STT DB)] + AIDB[(AI DB)] + RAGDB[(Vector DB)] + TodoDB[(Todo DB)] + end + + subgraph "Messaging Layer" + Queue[Message Queue
RabbitMQ/Kafka
Queue-Based Load Leveling] + EventBus[Event Bus
Publisher-Subscriber] + end + + subgraph "External Services" + AzureSpeech[Azure Speech API
Circuit Breaker] + OpenAI[OpenAI API
Circuit Breaker] + AzureBlob[Azure Blob Storage
Valet Key] + Email[Email Service] + end + + Web --> Gateway + Mobile --> Gateway + + Gateway --> LDAP + Gateway --> User + Gateway --> Meeting + Gateway --> STT + Gateway --> AI + Gateway --> RAG + Gateway --> Collab + Gateway --> Todo + + User --> Cache + User --> UserDB + + Meeting --> Cache + Meeting --> MeetingDB + Meeting --> EventBus + + STT --> Queue + STT --> AzureSpeech + STT --> AzureBlob + STT --> STTDB + + AI --> Queue + AI --> OpenAI + AI --> Cache + AI --> AIDB + + RAG --> Cache + RAG --> RAGDB + + Collab --> EventBus + + Todo --> EventBus + Todo --> TodoDB + + Notif --> Queue + Notif --> Email + + Queue --> STT + Queue --> AI + Queue --> Notif + + EventBus --> Meeting + EventBus --> Collab + EventBus --> Todo + EventBus --> Notif +``` + +### 3.3 실시간 협업 플로우 + +```mermaid +sequenceDiagram + participant Client1 as 참석자1 + participant Client2 as 참석자2 + participant Gateway as API Gateway + participant Collab as Collaboration Service + participant EventBus as Event Bus
(Pub-Sub) + participant Meeting as Meeting Service + participant Cache as Redis Cache + + Note over Client1,Client2: WebSocket 연결 + Client1->>Gateway: WebSocket Connect + Gateway->>Collab: Establish Connection + Client2->>Gateway: WebSocket Connect + Gateway->>Collab: Establish Connection + + Note over Client1,EventBus: 회의록 수정 + Client1->>Collab: 회의록 수정 (Delta) + Collab->>Meeting: 수정 내용 저장 + Meeting->>Cache: 캐시 무효화 + Meeting->>EventBus: 수정 이벤트 발행
(Publisher) + + Note over EventBus,Client2: 실시간 동기화 + EventBus->>Collab: 수정 이벤트 전달
(Subscriber) + Collab->>Client2: WebSocket Push (Delta) + Client2->>Client2: 화면 실시간 업데이트 + + Note over Client1,Meeting: 충돌 처리 (Last Write Wins) + Client1->>Collab: 동시 수정 시도 + Client2->>Collab: 동시 수정 시도 + Collab->>Meeting: 충돌 감지 + Meeting->>Meeting: Last Write Wins 적용 + Meeting->>EventBus: 최종 수정 이벤트 + EventBus->>Collab: 동기화 + Collab->>Client1: 최종 버전 전송 + Collab->>Client2: 최종 버전 전송 +``` + +### 3.4 AI/STT 비동기 처리 플로우 + +```mermaid +sequenceDiagram + participant Client as Web Client + participant Gateway as API Gateway + participant Meeting as Meeting Service + participant STTQueue as STT Queue
(Queue-Based) + participant STT as STT Service
(Circuit Breaker) + participant AzureSpeech as Azure Speech API + participant AIQueue as AI Queue
(Queue-Based) + participant AI as AI Service
(Circuit Breaker) + participant OpenAI as OpenAI API + participant RAG as RAG Service
(Cache-Aside) + participant Cache as Redis Cache + + Note over Client,Meeting: 음성 녹음 시작 + Client->>Gateway: 음성 녹음 업로드 + Gateway->>Meeting: 녹음 데이터 전달 + Meeting->>STTQueue: 변환 요청 적재
(Async Request-Reply) + Meeting-->>Client: 202 Accepted (즉시 응답) + + Note over STTQueue,AzureSpeech: STT 비동기 처리 + STTQueue->>STT: 큐에서 메시지 가져오기 + STT->>AzureSpeech: 음성-텍스트 변환 요청 + + alt API 정상 + AzureSpeech-->>STT: 변환 결과 + STT->>AIQueue: AI 회의록 작성 요청 + else API 장애 + AzureSpeech--xSTT: 오류 + STT->>STT: Circuit Breaker OPEN + STT->>STT: Retry (최대 3회) + alt Retry 성공 + STT->>AIQueue: AI 요청 + else Retry 실패 + STT->>Meeting: 실패 알림 + Meeting->>Client: WebSocket Push (오류) + end + end + + Note over AIQueue,OpenAI: AI 비동기 처리 + AIQueue->>AI: 큐에서 메시지 가져오기 + AI->>Cache: 프롬프트 템플릿 조회 + Cache-->>AI: 캐시된 템플릿 + AI->>OpenAI: 회의록 생성 요청 + + alt API 정상 + OpenAI-->>AI: 회의록 초안 + AI->>RAG: 용어 설명 요청 + RAG->>Cache: 검색 결과 조회 + + alt 캐시 적중 + Cache-->>RAG: 캐시된 설명 + else 캐시 미스 + RAG->>RAG: 벡터 검색 수행 + RAG->>Cache: 결과 캐싱 (TTL 1시간) + end + + RAG-->>AI: 용어 설명 + AI->>Meeting: 최종 회의록 전달 + Meeting->>Client: WebSocket Push (결과) + else API 장애 + OpenAI--xAI: 오류 + AI->>AI: Circuit Breaker OPEN + AI->>AI: Retry (Exponential Backoff) + end +``` + +### 3.5 Todo 실시간 연동 플로우 (Saga 패턴) + +```mermaid +sequenceDiagram + participant Client as Web Client + participant Gateway as API Gateway + participant Meeting as Meeting Service + participant AI as AI Service + participant Todo as Todo Service
(Saga Orchestrator) + participant EventBus as Event Bus
(Pub-Sub) + participant Notif as Notification Service + participant Calendar as Calendar API + + Note over Client,AI: 회의록 확정 및 Todo 추출 + Client->>Gateway: 회의록 최종 확정 + Gateway->>Meeting: 확정 요청 + Meeting->>AI: Todo 자동 추출 요청 + AI->>AI: LLM 분석
(액션 아이템 추출) + AI-->>Meeting: 추출된 Todo 목록 + + Note over Meeting,Todo: Saga 시작 (Phase 3) + Meeting->>Todo: Todo 할당 요청 (Saga Start) + + Note over Todo,Calendar: Saga Step 1: Todo 등록 + Todo->>Todo: Todo 데이터 저장 + Todo->>EventBus: TodoCreated 이벤트
(Publisher) + + Note over Todo,Calendar: Saga Step 2: 알림 발송 + EventBus->>Notif: TodoCreated 수신
(Subscriber) + Notif->>Notif: 이메일 발송 + + alt 알림 성공 + Notif->>EventBus: NotificationSent 이벤트 + else 알림 실패 + Notif->>EventBus: NotificationFailed 이벤트 + EventBus->>Todo: 보상 트랜잭션
(Todo 상태 변경: 알림 실패) + end + + Note over Todo,Calendar: Saga Step 3: 캘린더 등록 + EventBus->>Todo: NotificationSent 수신 + Todo->>Calendar: 일정 등록 요청 (비동기) + + alt 캘린더 등록 성공 + Calendar-->>Todo: 성공 + Todo->>EventBus: TodoCompleted 이벤트
(Saga 완료) + else 캘린더 등록 실패 + Calendar--xTodo: 실패 + Todo->>Todo: 보상 트랜잭션
(Todo 상태: 캘린더 미등록) + Todo->>EventBus: SagaCompensated 이벤트 + end + + Note over EventBus,Meeting: 회의록 실시간 반영 + EventBus->>Meeting: Todo 이벤트 수신 + Meeting->>Meeting: 회의록에 Todo 링크 추가 + Meeting->>EventBus: MeetingUpdated 이벤트 + EventBus->>Client: WebSocket Push (Todo 상태) + Client->>Client: 화면 업데이트 + + Note over Client,Meeting: Todo 완료 처리 + Client->>Todo: Todo 완료 요청 + Todo->>Todo: 완료 시간 기록 + Todo->>EventBus: TodoCompleted 이벤트 + EventBus->>Meeting: Todo 완료 수신 + Meeting->>Meeting: 회의록에 완료 표시 + Meeting->>EventBus: MeetingUpdated 이벤트 + EventBus->>Client: WebSocket Push (완료 상태) +``` + +--- + +## 4. Phase별 구현 로드맵 + +### 4.1 Phase 1: MVP (3개월) + +#### 목표 +- 핵심 기능 구현 (회의록 작성, STT, AI, Todo) +- 안정적 서비스 출시 +- 100명 동시 사용자 지원 + +#### 적용 패턴 (8개) +1. API Gateway +2. Gateway Offloading +3. Queue-Based Load Leveling +4. Cache-Aside +5. Publisher-Subscriber +6. Asynchronous Request-Reply +7. Federated Identity +8. Health Endpoint Monitoring + +#### 마일스톤 +| 주차 | 작업 내용 | 산출물 | +|------|-----------|--------| +| 1-2주 | 인프라 구축 | API Gateway, Redis, RabbitMQ 설정 | +| 3-4주 | User/Meeting 서비스 개발 | 인증, 회의 관리 API | +| 5-6주 | STT 서비스 개발 | 음성 녹음, 변환 API | +| 7-8주 | AI 서비스 개발 | 회의록 자동 생성, Todo 추출 | +| 9-10주 | RAG/Collaboration 서비스 | 용어 설명, 실시간 동기화 | +| 11-12주 | 통합 테스트 및 배포 | 프로덕션 배포, 모니터링 | + +#### 예상 성과 +- **성능**: + - STT 변환: 1초 이내 ✓ + - AI 회의록 생성: 10초 이내 + - RAG 검색: 2초 (캐시 적중 0.1초) + - 실시간 동기화: 3-5초 간격 +- **가용성**: 99% uptime +- **동시 사용자**: 100명 +- **비용**: 월 $500 (Azure 인프라) + +### 4.2 Phase 2: 확장 (6개월, MVP 이후) + +#### 목표 +- 성능 최적화 (CQRS, Materialized View) +- 안정성 강화 (Circuit Breaker, Retry, Bulkhead) +- 1,000명 동시 사용자 지원 + +#### 추가 패턴 (6개) +9. CQRS +10. Circuit Breaker +11. Retry +12. Materialized View +13. Bulkhead +14. Valet Key + +#### 마일스톤 +| 월 | 작업 내용 | 성과 지표 | +|----|-----------|-----------| +| 1-2개월 | CQRS 적용 (Meeting 서비스) | 읽기 성능 70% 향상 | +| 3-4개월 | Circuit Breaker/Retry 적용 | 장애 복구 시간 90% 단축 | +| 5개월 | Materialized View 구현 | 목록 조회 80% 빠름 | +| 6개월 | 부하 테스트 및 최적화 | 1,000명 동시 사용자 | + +#### 예상 성과 +- **성능 개선**: + - 읽기 응답시간: 70% 단축 (CQRS) + - 목록 조회: 80% 빠름 (Materialized View) + - RAG 캐시 적중률: 80% +- **가용성**: 99.9% uptime (Circuit Breaker) +- **동시 사용자**: 1,000명 (10배 증가) +- **비용**: 월 $2,000 (Auto-scaling) + +### 4.3 Phase 3: 고도화 (12개월, Phase 2 이후) + +#### 목표 +- 대규모 확장 (10,000명 동시 사용자) +- 완벽한 감사 추적 (Event Sourcing) +- 글로벌 배포 (다중 리전) + +#### 추가 패턴 (4개) +15. Event Sourcing +16. Saga +17. Priority Queue +18. External Configuration Store + +#### 마일스톤 +| 분기 | 작업 내용 | 성과 지표 | +|------|-----------|-----------| +| Q1 | Event Sourcing 구현 | 완벽한 변경 이력 | +| Q2 | Saga 패턴 적용 (Todo) | 분산 트랜잭션 일관성 | +| Q3 | Priority Queue 도입 | VIP 회의 50% 빠름 | +| Q4 | 다중 리전 배포 | 글로벌 확장 | + +#### 예상 성과 +- **성능**: + - Priority Queue: VIP 회의 응답시간 50% 단축 + - Event Sourcing: 완벽한 감사 추적 +- **가용성**: 99.99% uptime (다중 리전) +- **동시 사용자**: 10,000명 +- **글로벌**: 3개 리전 (한국, 미국, 유럽) +- **비용**: 월 $10,000 (글로벌 인프라) + +### 4.4 비용 효율성 분석 + +| Phase | 인프라 비용 | 예상 절감 | ROI | +|-------|------------|----------|-----| +| MVP | $500/월 | - | - | +| Phase 2 | $2,000/월 | Cache-Aside: RAG 비용 60% 절감
Async: AI API 30% 절감
Auto-scaling: 유휴 자원 80% 절감 | **총 50% 절감** | +| Phase 3 | $10,000/월 | 글로벌 확장으로 사용자 10배 증가
비용은 5배만 증가 (효율성 2배) | **비용 대비 2배 효율** | + +--- + +## 5. 구현 시 고려사항 + +### 5.1 API Gateway 구현 + +**기술 스택**: Spring Cloud Gateway + +**설정**: +```yaml +spring: + cloud: + gateway: + routes: + - id: user-service + uri: lb://user-service + predicates: + - Path=/api/users/** + filters: + - name: RequestRateLimiter + args: + redis-rate-limiter.replenishRate: 100 + redis-rate-limiter.burstCapacity: 200 + - id: meeting-service + uri: lb://meeting-service + predicates: + - Path=/api/meetings/** +``` + +**Gateway Offloading**: +- LDAP 인증: Spring Security LDAP +- 로깅: Spring Cloud Sleuth + Zipkin +- SSL 종료: Let's Encrypt 인증서 + +**Rate Limiting**: +- 사용자당: 100 req/min +- 익명 사용자: 10 req/min +- VIP: 500 req/min + +### 5.2 Queue 설정 + +**기술 스택**: RabbitMQ (MVP), Kafka (Phase 2) + +**Queue 구성**: +```yaml +queues: + stt: + name: stt-conversion-queue + type: priority # Priority Queue (Phase 3) + durable: true + ttl: 1800000 # 30분 + dead-letter-exchange: stt-dlx + + ai: + name: ai-generation-queue + type: priority + durable: true + ttl: 1800000 + dead-letter-exchange: ai-dlx + + notification: + name: notification-queue + durable: true + ttl: 300000 # 5분 +``` + +**Dead Letter Queue**: +- 실패한 메시지 3회 재시도 후 DLQ로 이동 +- DLQ 메시지 수동 확인 및 재처리 + +**메시지 우선순위** (Phase 3): +- VIP 회의: Priority 9 +- 일반 회의: Priority 5 +- 배치 작업: Priority 1 + +### 5.3 Cache 전략 + +**기술 스택**: Redis Cluster (고가용성) + +**TTL 설정**: +```yaml +cache: + rag-search: + ttl: 3600 # 1시간 + max-size: 10000 + + user-info: + ttl: 1800 # 30분 + max-size: 5000 + + meeting-list: + ttl: 300 # 5분 + max-size: 1000 + + todo-list: + ttl: 300 # 5분 + max-size: 2000 +``` + +**캐시 무효화**: +- 쓰기 작업 시 즉시 무효화 +- 회의록 수정 → 해당 회의 캐시 삭제 +- Todo 상태 변경 → Todo 목록 캐시 삭제 + +**캐시 워밍**: +- 애플리케이션 시작 시 인기 회의록 사전 로드 +- 스케줄러: 매일 오전 6시 캐시 갱신 + +### 5.4 WebSocket 최적화 + +**기술 스택**: SockJS + STOMP + +**설정**: +```yaml +websocket: + heartbeat: + client: 30000 # 30초 + server: 30000 + + message-size-limit: 1048576 # 1MB + + connection: + max-per-user: 5 + timeout: 300000 # 5분 +``` + +**재연결 정책**: +- Exponential Backoff: 1초, 2초, 4초, 8초, 16초 +- 최대 재시도: 5회 + +**메시지 전송 최적화**: +- Delta 전송: 전체 내용이 아닌 변경 부분만 +- 압축: gzip 압축 (1KB 이상 메시지) +- 배치: 100ms 내 변경사항 묶어서 전송 + +### 5.5 AI/LLM 최적화 + +**기술 스택**: Azure OpenAI Service + +**배치 처리**: +```python +# 여러 요청 묶어서 처리 +batch_requests = [] +for i in range(batch_size): + request = queue.pop() + batch_requests.append(request) + +# 한 번에 처리 +responses = openai.ChatCompletion.create_batch(batch_requests) +``` + +**스트리밍 응답**: +- 긴 회의록 생성 시 스트리밍 +- 클라이언트에 실시간 전달 (WebSocket) + +**프롬프트 캐싱**: +- 동일 템플릿 재사용 +- Redis에 프롬프트 템플릿 저장 + +**비용 최적화**: +- 토큰 제한: 요약 시 최대 500 토큰 +- 모델 선택: GPT-3.5 (일반), GPT-4 (중요 회의) + +### 5.6 Circuit Breaker 설정 + +**기술 스택**: Resilience4j + +**설정**: +```yaml +resilience4j: + circuitbreaker: + instances: + azure-speech: + failure-rate-threshold: 50 # 50% 실패 시 OPEN + wait-duration-in-open-state: 30s + sliding-window-size: 10 + minimum-number-of-calls: 5 + + openai: + failure-rate-threshold: 50 + wait-duration-in-open-state: 60s # 1분 + sliding-window-size: 20 + + retry: + instances: + azure-speech: + max-attempts: 3 + wait-duration: 1s + retry-exceptions: + - java.net.SocketTimeoutException + - org.springframework.web.client.HttpServerErrorException +``` + +**Fallback 전략**: +- STT 실패 → 수동 입력 안내 +- AI 실패 → 기본 템플릿 제공 +- RAG 실패 → 일반 용어 설명 + +### 5.7 CQRS 구현 (Phase 2) + +**Read Model** (조회): +```java +@Service +public class MeetingQueryService { + @Cacheable("meeting-list") + public List getMeetingList(Long userId) { + // Materialized View 조회 + return materializedViewRepository.findByUserId(userId); + } +} +``` + +**Write Model** (쓰기): +```java +@Service +public class MeetingCommandService { + @CacheEvict(value = "meeting-list", key = "#userId") + public void updateMeeting(Long meetingId, MeetingUpdateRequest request) { + // DB 갱신 + meetingRepository.update(meetingId, request); + + // 이벤트 발행 + eventBus.publish(new MeetingUpdatedEvent(meetingId)); + } +} +``` + +**Materialized View 갱신**: +- 이벤트 기반 비동기 갱신 +- 배치 작업: 매 10분마다 동기화 + +### 5.8 Event Sourcing 구현 (Phase 3) + +**Event Store**: +```java +@Entity +public class MeetingEvent { + @Id + private UUID eventId; + private Long aggregateId; // Meeting ID + private String eventType; // CREATED, UPDATED, SHARED + private String eventData; // JSON + private LocalDateTime timestamp; + private Long userId; +} +``` + +**이벤트 재생**: +```java +public Meeting rebuildFromEvents(Long meetingId) { + List events = eventStore.findByAggregateId(meetingId); + Meeting meeting = new Meeting(); + for (MeetingEvent event : events) { + meeting.apply(event); + } + return meeting; +} +``` + +**스냅샷** (성능 최적화): +- 100개 이벤트마다 스냅샷 생성 +- 재생 시 최신 스냅샷부터 시작 + +### 5.9 모니터링 및 운영 + +**Health Endpoint**: +```yaml +management: + endpoints: + web: + exposure: + include: health, metrics, prometheus + health: + circuitbreakers: + enabled: true + redis: + enabled: true + db: + enabled: true +``` + +**Metrics** (Prometheus + Grafana): +- 서비스 응답시간 (p50, p95, p99) +- 요청 처리량 (req/s) +- 에러율 (%) +- Circuit Breaker 상태 +- 캐시 적중률 + +**분산 추적** (Zipkin): +- 요청 전체 흐름 추적 +- 병목 구간 식별 + +**로그 중앙화** (ELK Stack): +- Elasticsearch: 로그 저장 +- Logstash: 로그 수집 및 파싱 +- Kibana: 로그 검색 및 시각화 + +**알림** (Phase 2): +- 에러율 5% 초과 → Slack 알림 +- Circuit Breaker OPEN → 즉시 알림 +- 디스크 사용량 80% → 경고 + +### 5.10 보안 + +**HTTPS 강제**: +- Let's Encrypt 무료 인증서 +- HTTP → HTTPS 자동 리다이렉트 + +**CORS 설정**: +```yaml +spring: + web: + cors: + allowed-origins: + - https://meeting.example.com + allowed-methods: GET, POST, PUT, DELETE + allowed-headers: "*" + allow-credentials: true +``` + +**SQL Injection 방지**: +- JPA/Hibernate PreparedStatement 사용 +- 동적 쿼리 금지 + +**XSS 방지**: +- Input Sanitization (OWASP Java Encoder) +- Output Encoding + +**민감 정보 암호화**: +- DB 암호화: AES-256 +- 전송 암호화: TLS 1.3 + +--- + +## 6. 예상 성과 지표 + +### 6.1 Phase별 성과 비교 + +| 지표 | MVP (Phase 1) | Phase 2 (확장) | Phase 3 (고도화) | +|------|---------------|----------------|------------------| +| **성능** | | | | +| STT 변환 | 1초 이내 | 0.8초 | 0.5초 | +| AI 회의록 생성 | 10초 | 7초 (배치 처리) | 5초 (스트리밍) | +| RAG 검색 (캐시 미스) | 2초 | 1.5초 | 1초 | +| RAG 검색 (캐시 적중) | 0.1초 | 0.1초 | 0.1초 | +| 실시간 동기화 | 3-5초 | 2-3초 | 1-2초 | +| 회의록 목록 조회 | 500ms | 100ms (Materialized View) | 50ms | +| **가용성** | | | | +| Uptime | 99% | 99.9% | 99.99% | +| MTTR (평균 복구 시간) | 30분 | 3분 (Circuit Breaker) | 1분 | +| **확장성** | | | | +| 동시 사용자 | 100명 | 1,000명 | 10,000명 | +| 회의당 최대 참석자 | 10명 | 50명 | 100명 | +| 일일 회의 처리 | 500건 | 5,000건 | 50,000건 | +| **비용** | | | | +| 인프라 비용 | $500/월 | $2,000/월 | $10,000/월 | +| 사용자당 비용 | $5/월 | $2/월 (2.5배 절감) | $1/월 (5배 절감) | + +### 6.2 패턴별 기대 효과 + +#### Cache-Aside +- **RAG 검색 비용**: 60% 절감 + - 캐시 미스: 2초 → 캐시 적중: 0.1초 + - 캐시 적중률: 80% (Phase 2) +- **API 호출 감소**: 외부 API 호출 80% 감소 +- **비용 절감**: 월 $500 → $200 (RAG API 비용) + +#### Queue-Based Load Leveling +- **처리량 향상**: 동시 요청 100 → 1,000 (10배) +- **응답 안정성**: 피크 시간대 응답시간 편차 50% 감소 +- **자원 효율**: CPU 사용률 평준화 (80% → 50%) + +#### Asynchronous Request-Reply +- **사용자 대기 시간**: 10초 → 즉시 응답 (202 Accepted) +- **사용자 경험**: 응답 대기 중 다른 작업 가능 +- **AI API 최적화**: 배치 처리로 30% 비용 절감 + +#### CQRS (Phase 2) +- **읽기 성능**: 응답시간 70% 단축 (500ms → 150ms) +- **쓰기 성능**: 독립적 최적화 가능 +- **확장성**: 읽기/쓰기 DB 독립 스케일링 + +#### Circuit Breaker (Phase 2) +- **장애 복구**: MTTR 30분 → 3분 (90% 단축) +- **장애 격리**: 한 서비스 장애가 전체 영향 없음 +- **가용성**: 99% → 99.9% uptime + +#### Event Sourcing (Phase 3) +- **감사 추적**: 100% 변경 이력 보존 +- **데이터 복원**: 임의 시점 상태 복원 가능 +- **규제 준수**: 완벽한 감사 로그 + +#### Priority Queue (Phase 3) +- **VIP 회의**: 응답시간 50% 단축 (10초 → 5초) +- **비즈니스 가치**: 중요 회의 우선 처리 +- **자원 활용**: 일반 회의는 유휴 시간 활용 + +### 6.3 비용 효율성 분석 + +#### Phase 1 (MVP) +- **인프라**: $500/월 + - API Gateway: $100 + - Redis: $50 + - RabbitMQ: $50 + - DB (PostgreSQL): $100 + - 컴퓨팅 (VM): $200 +- **외부 API**: $300/월 + - Azure Speech: $100 + - OpenAI: $200 +- **총 비용**: $800/월 +- **사용자**: 100명 +- **사용자당 비용**: $8/월 + +#### Phase 2 (확장) +- **인프라**: $2,000/월 (4배 증가) +- **외부 API**: $600/월 (2배 증가) + - Cache-Aside로 60% 절감 → $240 절감 + - Async 배치 처리로 30% 절감 → $60 절감 + - 실제 비용: $600 - $300 = $300 +- **총 비용**: $2,300/월 +- **사용자**: 1,000명 (10배 증가) +- **사용자당 비용**: $2.3/월 (71% 절감) + +#### Phase 3 (고도화) +- **인프라**: $10,000/월 (글로벌 배포) +- **외부 API**: $1,000/월 +- **총 비용**: $11,000/월 +- **사용자**: 10,000명 +- **사용자당 비용**: $1.1/월 (86% 절감 대비 MVP) + +**ROI 분석**: +- Phase 2: 투자 대비 2.5배 효율 (사용자 10배, 비용 4배) +- Phase 3: 투자 대비 7배 효율 (사용자 100배, 비용 14배) + +--- + +## 7. 결론 + +### 7.1 핵심 성과 + +본 아키텍처 패턴 적용 방안은 회의록 작성 및 공유 개선 서비스의 기술적 도전과제를 체계적으로 해결합니다: + +1. **실시간 협업 처리**: Publisher-Subscriber + WebSocket으로 3-5초 실시간 동기화 달성 +2. **대용량 데이터 처리**: Queue-Based Load Leveling으로 안정적 비동기 처리 +3. **AI/LLM 통합**: Asynchronous Request-Reply + Circuit Breaker로 안정성과 사용자 경험 보장 +4. **RAG 성능**: Cache-Aside로 80% 캐시 적중률, 60% 비용 절감 +5. **서비스 격리**: Circuit Breaker + Bulkhead로 99.9% 가용성 달성 +6. **데이터 일관성**: Saga + Event Sourcing으로 완벽한 일관성 보장 + +### 7.2 차별화 포인트 실현 + +아키텍처 패턴 적용으로 서비스 차별화 포인트를 강화합니다: + +- **맥락 기반 용어 설명**: RAG + Cache-Aside로 2초 이내 실용적 정보 제공 +- **강화된 Todo 연결**: Saga 패턴으로 Todo ↔ 회의록 실시간 양방향 연동 +- **프롬프팅 기반 회의록 개선**: Async Request-Reply로 즉시 응답, 백그라운드 생성 + +### 7.3 단계별 추진 전략 + +**Phase 1 (MVP)**: 핵심 패턴 8개로 안정적 출시 +- API Gateway, Queue, Cache, Pub-Sub 중심 +- 100명 사용자, 99% 가용성 목표 + +**Phase 2 (확장)**: 성능 최적화 및 안정성 강화 +- CQRS, Circuit Breaker, Materialized View 추가 +- 1,000명 사용자, 99.9% 가용성 목표 +- 70% 성능 향상, 90% 장애 복구 시간 단축 + +**Phase 3 (고도화)**: 대규모 확장 및 글로벌 배포 +- Event Sourcing, Saga, Priority Queue 적용 +- 10,000명 사용자, 99.99% 가용성 목표 +- 완벽한 감사 추적, 글로벌 3개 리전 + +### 7.4 비용 효율성 + +- **Phase 1**: 사용자당 $8/월 +- **Phase 2**: 사용자당 $2.3/월 (71% 절감) +- **Phase 3**: 사용자당 $1.1/월 (86% 절감) + +**투자 대비 수익**: +- Phase 2: 2.5배 효율 (사용자 10배 증가, 비용 4배 증가) +- Phase 3: 7배 효율 (사용자 100배 증가, 비용 14배 증가) + +### 7.5 리스크 및 대응 + +| 리스크 | 영향 | 대응 패턴 | +|--------|------|-----------| +| AI/STT API 장애 | 서비스 중단 | Circuit Breaker + Retry | +| 동시 수정 충돌 | 데이터 손실 | Last Write Wins + Event Sourcing | +| 대용량 트래픽 | 응답 지연 | Queue-Based Load Leveling + Auto-scaling | +| 캐시 불일치 | 데이터 정합성 | Write-through + TTL 관리 | +| 분산 트랜잭션 실패 | 데이터 불일치 | Saga + 보상 트랜잭션 | + +### 7.6 다음 단계 + +1. **MVP 개발 착수** (즉시) + - API Gateway, Queue, Cache 인프라 구축 + - User/Meeting 서비스 개발 시작 + +2. **프로토타입 검증** (1개월 내) + - 핵심 패턴 PoC 구현 + - 성능 및 안정성 테스트 + +3. **단계별 출시** (3-12개월) + - Phase 1: 3개월 MVP 출시 + - Phase 2: 6개월 성능 최적화 + - Phase 3: 12개월 글로벌 확장 + +--- + +## 부록 + +### A. 참고 문서 +- [유저스토리](../userstory.md) +- [클라우드 디자인 패턴 개요](../../claude/cloud-design-patterns.md) +- [아키텍처 패턴 선정 가이드](../../claude/architecture-patterns.md) + +### B. 기술 스택 +- **API Gateway**: Spring Cloud Gateway +- **Message Queue**: RabbitMQ (MVP), Kafka (Phase 2) +- **Cache**: Redis Cluster +- **Database**: PostgreSQL (주 DB), MongoDB (Event Store) +- **WebSocket**: SockJS + STOMP +- **Circuit Breaker**: Resilience4j +- **모니터링**: Prometheus + Grafana, Zipkin, ELK Stack +- **외부 API**: Azure Speech, Azure OpenAI, Azure Blob Storage + +### C. 용어 정의 +- **STT**: Speech-to-Text (음성-텍스트 변환) +- **LLM**: Large Language Model (대규모 언어 모델) +- **RAG**: Retrieval-Augmented Generation (검색 증강 생성) +- **CQRS**: Command Query Responsibility Segregation (명령 쿼리 책임 분리) +- **Saga**: 분산 트랜잭션 관리 패턴 +- **Event Sourcing**: 이벤트 기반 데이터 저장 패턴 +- **Circuit Breaker**: 장애 격리 패턴 +- **Pub-Sub**: Publisher-Subscriber (발행-구독) 패턴 + +### D. Mermaid 다이어그램 검증 +모든 Mermaid 다이어그램은 https://mermaid.live/edit 에서 검증 완료되었습니다. + +--- + +**문서 버전**: 1.0 +**최종 수정**: 2025-10-21 +**작성자**: 아키텍트 팀 (길동) diff --git a/tools/check-mermaid.ps1 b/tools/check-mermaid.ps1 new file mode 100644 index 0000000..49327a5 --- /dev/null +++ b/tools/check-mermaid.ps1 @@ -0,0 +1,96 @@ +# Mermaid Syntax Checker using Docker Container +# Similar to PlantUML checker - keeps container running for better performance + +param( + [Parameter(Mandatory=$true, Position=0)] + [string]$FilePath +) + +# Check if file exists +if (-not (Test-Path $FilePath)) { + Write-Host "Error: File not found: $FilePath" -ForegroundColor Red + exit 1 +} + +# Get absolute path +$absolutePath = (Resolve-Path $FilePath).Path +$fileName = Split-Path $absolutePath -Leaf + +Write-Host "`nChecking Mermaid syntax for: $fileName" -ForegroundColor Cyan +Write-Host ("=" * 60) -ForegroundColor Gray + +# Check if mermaid container is running +$containerRunning = docker ps --filter "name=mermaid-cli" --format "{{.Names}}" 2>$null + +if (-not $containerRunning) { + Write-Host "Error: Mermaid CLI container is not running." -ForegroundColor Red + Write-Host "Please follow the setup instructions in the Mermaid guide to start the container." -ForegroundColor Yellow + Write-Host "`nQuick setup commands:" -ForegroundColor Cyan + Write-Host "" + Write-Host "# 1. Start container with root privileges (port 48080)" -ForegroundColor Green + Write-Host "docker run -d --rm --name mermaid-cli -u root -p 48080:8080 --entrypoint sh minlag/mermaid-cli:latest -c `"while true;do sleep 3600; done`"" -ForegroundColor White + Write-Host "" + Write-Host "# 2. Install Chromium and dependencies" -ForegroundColor Green + Write-Host "docker exec mermaid-cli sh -c `"apk add --no-cache chromium chromium-chromedriver nss freetype harfbuzz ca-certificates ttf-freefont`"" -ForegroundColor White + Write-Host "" + Write-Host "# 3. Create Puppeteer configuration" -ForegroundColor Green + Write-Host "docker exec mermaid-cli sh -c `"echo '{```"executablePath```": ```"/usr/bin/chromium-browser```", ```"args```": [```"--no-sandbox```", ```"--disable-setuid-sandbox```", ```"--disable-dev-shm-usage```"]}' > /tmp/puppeteer-config.json`"" -ForegroundColor White + Write-Host "" + exit 1 +} + +# Set Puppeteer configuration file path +$puppeteerConfigFile = "/tmp/puppeteer-config.json" + +# Generate unique temp filename +$timestamp = Get-Date -Format "yyyyMMddHHmmss" +$processId = $PID +$tempFile = "/tmp/mermaid_${timestamp}_${processId}.mmd" +$outputFile = "/tmp/mermaid_${timestamp}_${processId}.svg" + +try { + # Copy file to container + Write-Host "Copying file to container..." -ForegroundColor Gray + docker cp "$absolutePath" "mermaid-cli:$tempFile" 2>&1 | Out-Null + + if ($LASTEXITCODE -ne 0) { + Write-Host "Error: Failed to copy file to container" -ForegroundColor Red + exit 1 + } + + # Run syntax check with Puppeteer configuration + Write-Host "Running syntax check..." -ForegroundColor Gray + $output = docker exec mermaid-cli sh -c "cd /home/mermaidcli && node_modules/.bin/mmdc -i '$tempFile' -o '$outputFile' -p '$puppeteerConfigFile' -q" 2>&1 + $exitCode = $LASTEXITCODE + + if ($exitCode -eq 0) { + Write-Host "`nSuccess: Mermaid syntax is valid!" -ForegroundColor Green + } else { + Write-Host "`nError: Mermaid syntax validation failed!" -ForegroundColor Red + Write-Host "`nError details:" -ForegroundColor Red + + # Parse and display error messages + $errorLines = $output -split "`n" + foreach ($line in $errorLines) { + if ($line -match "Error:|Parse error|Expecting|Syntax error") { + Write-Host " $line" -ForegroundColor Red + } elseif ($line -match "line \d+|at line") { + Write-Host " $line" -ForegroundColor Yellow + } elseif ($line.Trim() -ne "") { + Write-Host " $line" -ForegroundColor DarkRed + } + } + + exit 1 + } + +} finally { + # Clean up temp files + Write-Host "`nCleaning up..." -ForegroundColor Gray + docker exec mermaid-cli rm -f "$tempFile" "$outputFile" 2>&1 | Out-Null +} + +Write-Host "`nValidation complete!" -ForegroundColor Cyan + +# Note: Container is kept running for subsequent checks +# To stop: docker stop mermaid-cli && docker rm mermaid-cli \ No newline at end of file