From b98db59c7cedaba12e3fb0561dfdd87b9c16ebf2 Mon Sep 17 00:00:00 2001 From: ondal Date: Tue, 21 Oct 2025 13:33:34 +0900 Subject: [PATCH] =?UTF-8?q?=EB=85=BC=EB=A6=AC=EC=95=84=ED=82=A4=ED=85=8D?= =?UTF-8?q?=EC=B2=98=EC=84=A4=EA=B3=84?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .claude/settings.local.json | 13 +- claude/common-principles.md | 197 +++++ claude/logical-architecture-design.md | 64 ++ .../backend/logical/logical-architecture.md | 706 ++++++++++++++++++ .../backend/logical/logical-architecture.mmd | 119 +++ tools/check-mermaid.sh | 107 +++ 6 files changed, 1203 insertions(+), 3 deletions(-) create mode 100644 claude/common-principles.md create mode 100644 claude/logical-architecture-design.md create mode 100644 design/backend/logical/logical-architecture.md create mode 100644 design/backend/logical/logical-architecture.mmd create mode 100644 tools/check-mermaid.sh diff --git a/.claude/settings.local.json b/.claude/settings.local.json index a0f0877..b053c98 100644 --- a/.claude/settings.local.json +++ b/.claude/settings.local.json @@ -23,9 +23,16 @@ "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(curl -s https://raw.githubusercontent.com/cna-bootcamp/clauding-guide/refs/heads/main/guides/design/architecture-patterns.md -o claude/architecture-patterns.md)", - "Bash(cp:*)", - "Bash(git commit -m \"$(cat <<''EOF''\n아키텍처 패턴 설계서 업데이트 및 백업\n\n- 클라우드 아키텍처 패턴 적용 방안 재작성\n- 기존 버전을 architecture-pattern_bk.md로 백업\n- .claude/settings.local.json 설정 업데이트\n\n🤖 Generated with [Claude Code](https://claude.com/claude-code)\n\nCo-Authored-By: Claude \nEOF\n)\")", - "Bash(git commit:*)" + "Bash(curl -s \"https://raw.githubusercontent.com/cna-bootcamp/clauding-guide/refs/heads/main/references/Cloud%20Design%20Patterns(%EA%B0%9C%EC%9A%94).md\" -o claude/cloud-design-patterns.md)", + "Bash(curl -s https://raw.githubusercontent.com/cna-bootcamp/clauding-guide/refs/heads/main/guides/tools/mermaid-guide.md -o claude/mermaid-guide.md)", + "Bash(curl -s https://raw.githubusercontent.com/cna-bootcamp/clauding-guide/refs/heads/main/guides/tools/check-mermaid.ps1 -o tools/check-mermaid.ps1)", + "Bash(git add:*)", + "Bash(git commit:*)", + "Bash(curl -s https://raw.githubusercontent.com/cna-bootcamp/clauding-guide/refs/heads/main/guides/design/common-principles.md -o claude/common-principles.md)", + "Bash(curl -s https://raw.githubusercontent.com/cna-bootcamp/clauding-guide/refs/heads/main/guides/design/logical-architecture-design.md -o claude/logical-architecture-design.md)", + "Bash(curl:*)", + "Bash(chmod:*)", + "Bash(./tools/check-mermaid.sh:*)" ], "deny": [], "ask": [] diff --git a/claude/common-principles.md b/claude/common-principles.md new file mode 100644 index 0000000..31b8354 --- /dev/null +++ b/claude/common-principles.md @@ -0,0 +1,197 @@ +# 공통설계원칙 + +모든 설계 단계에서 공통으로 적용되는 핵심 원칙과 전략 + +## 🎯 핵심 원칙 + +### 1. 🚀 실행 우선 원칙 +- **프롬프트 우선**: 바로 실행할 수 있는 프롬프트로 작업 시작 +- **가이드 학습**: 원리와 방법론은 가이드로 깊이 있게 학습 +- **점진적 이해**: 실행 → 결과 확인 → 원리 학습 순서 + +### 2. 🔄 병렬 처리 전략 +- **서브 에이전트 활용**: Task 도구로 서비스별 동시 작업 +- **의존성 기반 그룹화**: 의존 관계에 따른 순차/병렬 처리 결정 +- **통합 검증**: 병렬 작업 완료 후 전체적 일관성 검증 + +### 3. 🏗️ 마이크로서비스 설계 원칙 +- **서비스 독립성**: 캐시를 통한 직접 의존성 최소화 +- **선택적 비동기**: 장시간 작업(AI 일정 생성)만 비동기 처리 +- **캐시 우선**: Redis를 통한 성능 최적화 +- **독립 배포**: 서비스별 독립적 배포 가능한 구조 + +### 4. 📝 표준화 원칙 +- **PlantUML**: 모든 다이어그램 표준 (`!theme mono`) +- **OpenAPI 3.0**: API 명세 표준 +- **자동 검증**: PlantUML, OpenAPI 문법 검사 필수 +- **일관된 네이밍**: kebab-case 파일명, 표준화된 스키마명 + +### 5. ✅ 검증 우선 원칙 +- **각 단계마다 자동 검증**: 품질 보장 +- **실시간 피드백**: 오류 조기 발견 및 수정 +- **CI/CD 통합**: 자동화된 검증 프로세스 +- **PlantUML 스크립트 파일 생성 즉시 검사 실행**: 'PlantUML 문법 검사 가이드' 준용 + +### 6. 🚀 점진적 구현 원칙 +- **MVP → 확장 → 고도화**: 단계별 접근 +- **YAGNI 적용**: 꼭 필요한 기능만 구현(YAGNI원칙:You aren't gonna need it) +- **지속적 개선**: 피드백 기반 점진적 발전 + +## 🔧 의존성 분석 및 병렬 처리 + +### 의존성 분석 방법 + +1. **서비스 간 의존성 파악** + ``` + 일정 서비스 → 프로파일 서비스 (멤버/여행 정보 조회) + 일정 서비스 → 장소 서비스 (장소 정보 조회) + 장소 서비스: 독립적 (외부 API만 사용) + ``` + +2. **의존성 기반 그룹화** + ``` + Group A (순차 처리): 프로파일 → 일정 서비스 + Group B (독립 처리): 장소 서비스 + ``` + +3. **에이전트 할당 및 병렬 처리** + ``` + Agent 1: Group A 담당 + - 프로파일 서비스 설계 + - 일정 서비스 설계 (프로파일 참조) + + Agent 2: Group B 담당 + - 장소 서비스 설계 (독립적) + ``` + +### 병렬 처리 적용 가이드 + +#### API 설계 단계 +- **독립 서비스**: 각각 별도 에이전트 +- **의존 서비스**: 동일 에이전트 내 순차 처리 +- **공통 검증**: 모든 에이전트 완료 후 swagger-cli 검증 + +#### 시퀀스 설계 단계 +- **외부 시퀀스**: 플로우별 병렬 처리 (각 플로우는 독립적) +- **내부 시퀀스**: 서비스별 병렬 처리 (서비스 내부는 독립적) + +#### 클래스/데이터 설계 단계 +- **의존성 그룹별**: 참조 관계가 있는 서비스들은 순차 처리 +- **독립 서비스**: 병렬 처리 +- **공통 클래스**: 모든 서비스 설계 완료 후 마지막 처리 + +## 🎨 PlantUML 작성 표준 + +### 기본 템플릿 +```plantuml +@startuml +!theme mono + +title [다이어그램 제목] + +' 다이어그램 내용 +@enduml +``` + +### 필수 검증 +- **각 파일 생성 직후 PlantUML 문법 검사 수행** +- **파이프 방식 권장**: `cat "파일" | docker exec -i plantuml ...` +- **화살표 문법 주의**: sequence diagram에서 `..>` 사용 금지 + +### 스타일 가이드 +- **폰트 크기**: 적절한 가독성 확보 +- **색상 구분**: 서비스별, 레이어별 색상 구분 +- **설명 추가**: note를 활용한 상세 설명 + +## 🔌 API 설계 표준 + +### 파일 구조 +``` +design/backend/api/{service-name}-api.yaml +``` + +### 필수 필드 +```yaml +paths: + /endpoint: + get: + summary: API 목적 설명 + operationId: 고유 식별자 + x-user-story: 유저스토리 ID + x-controller: 담당 컨트롤러 + tags: [API 그룹] +``` + +### 스키마 원칙 +- **서비스별 독립**: 각 서비스 파일에 모든 스키마 포함 +- **중복 허용**: 초기에는 중복을 허용하고 점진적으로 공통화 +- **명확한 네이밍**: Request/Response DTO 네이밍 표준 + +## 🔄 시퀀스 설계 표준 + +### 외부 시퀀스 (서비스 간) +- **참여 서비스만**: 해당 플로우에 참여하는 서비스만 표시 +- **API 호출 중심**: 서비스 간 API 호출 순서 표현 +- **한글 설명**: 각 호출의 목적을 한글로 명시 + +### 내부 시퀀스 (서비스 내부) +- **모든 API 표시**: 해당 서비스의 모든 API 포함 +- **내부 처리 흐름**: 컨트롤러 → 서비스 → 레포지토리 플로우 +- **기술적 세부사항**: 캐시, DB 접근 등 포함 + +### 동기/비동기 구분 +- **실선 (→)**: 동기 호출 +- **점선 (->>)**: 비동기 호출 +- **양방향**: 필요시에만 사용 + +## 📊 클래스 설계 표준 + +### 아키텍처 적용 +- **Clean Architecture**: Port/Adapter 용어 대신 표준 Clean 용어 사용 +- **멀티프로젝트**: 서비스별 독립 모듈 +- **패키지 구조 표준**: 일관된 패키지 구조 적용 + +### 관계 표현 +- **Generalization**: 상속 관계 +- **Realization**: 인터페이스 구현 +- **Dependency**: 의존 관계 +- **Association**: 연관 관계 +- **Aggregation/Composition**: 집약/합성 관계 + +### 상세 정보 +- **프로퍼티와 메소드**: 모두 명시 +- **접근 제한자**: 적절한 가시성 설정 +- **타입 정보**: 정확한 데이터 타입 명시 + +## 🗄️ 데이터 설계 표준 + +### 서비스별 DB 분리 +- **각 서비스마다 독립적인 데이터베이스** +- **서비스 간 데이터 공유 최소화** +- **캐시를 통한 성능 최적화** + +### 클래스 설계와 일치 +- **Entity 클래스와 테이블 매핑** +- **일관된 네이밍 컨벤션** +- **적절한 정규화 수준** + +## 🚨 주의사항 + +### PlantUML 문법 +- **sequence diagram에서 `..>` 사용 금지** +- **비동기는 `->>` 또는 `-->>` 사용** +- **테마는 반드시 `mono` 사용** + +### 병렬 처리 +- **의존성 분석 선행**: 병렬 처리 전 반드시 의존성 파악 +- **순차 처리 필요시**: 무리한 병렬화보다는 안전한 순차 처리 +- **검증 단계 필수**: 병렬 처리 후 통합 검증 + +### API 설계 +- **유저스토리 ID 필수**: x-user-story 필드 누락 금지 +- **Controller 명시**: x-controller 필드로 담당 컨트롤러 명시 +- **스키마 완전성**: 모든 Request/Response 스키마 정의 + +--- + +💡 **이 원칙들은 모든 설계 단계에서 일관되게 적용되어야 하며, 각 단계별 세부 가이드에서 구체적으로 구현됩니다.** \ No newline at end of file diff --git a/claude/logical-architecture-design.md b/claude/logical-architecture-design.md new file mode 100644 index 0000000..ca4d2ba --- /dev/null +++ b/claude/logical-architecture-design.md @@ -0,0 +1,64 @@ +# 논리아키텍처설계가이드 + +[요청사항] +- <작성원칙>을 준용하여 설계 +- <작성순서>에 따라 설계 +- [결과파일] 안내에 따라 파일 작성 +- 완료 후 mermaid 스크립트 테스트 방법 안내 + - https://mermaid.live/edit 에 접근 + - 스크립트 내용을 붙여넣어 확인 + +[가이드] +<작성원칙> +- **유저스토리와 매칭**되어야 함. **불필요한 추가 설계 금지** +- UI/UX설계서의 '사용자 플로우'참조하여 설계 +- '아키텍처패턴'에 선정된 클라우드 디자인 패턴을 적용하여 설계 +- 사용자 관점의 컴포넌트 다이어그램 작성 +- Context Map 스타일로 서비스 내부 구조는 생략하고 서비스 간 관계에 집중 +- 클라이언트에서 API Gateway로는 단일 연결선으로 표현 +<작성순서> +- 준비: + - 유저스토리, UI/UX설계서, 아키텍처패턴 분석 및 이해 + - "@analyze --play" 프로토타입이 있는 경우 웹브라우저에서 실행하여 서비스 이해 +- 실행: + - 논리아키텍처 설계서(logical-architecture.md) 작성: 아래 항목은 필수 포함하고 필요 시 항목 추가 + - 개요: 설계 원칙, 핵심 컴포넌트 정의 + - 서비스 아키텍처 + - 서비스별 책임 + - 서비스 간 통신 전략 + - 주요 사용자 플로우 + - 데이터 흐름 및 캐싱 전략 + - 확장성 및 성능 고려사항 + - 보안 고려사항 + - 논리아키텍처 다이어그램 + - Mermaid 형식으로 작성하며 별도 파일로 작성: logical-architecture.mmd + - <통신전략>과 <의존성 표현 방법>을 준수 + - **Mermaid 스크립트 파일 검사 실행**: 'Mermaid문법검사가이드' 준용 +- 검토: + - <작성원칙> 준수 검토 + - 스쿼드 팀원 리뷰: 누락 및 개선 사항 검토 + - 수정 사항 선택 및 반영 +<통신 전략> +- **동기 통신**: 즉시 응답이 필요한 단순 조회 +- **캐시 우선**: 자주 사용되는 데이터는 캐시에서 직접 읽기 +- **비동기 처리**: 외부 API 다중 호출 등 장시간 작업 +<의존성 표현 방법> +- 실선 화살표(→): 동기적 의존성 (필수) +- 비동기 화살표(->>): 비동기 의존성 (fire-and-forget) +- 점선 화살표(-->): 선택적 의존성 또는 느슨한 결합 +- 양방향 화살표(↔): 상호 의존성 +- 의존성 레이블에 목적 명시 (예: "멤버 정보 조회") +- 플로우 라벨 형식: [요청서비스약어]액션 (예: [Trip]AI 일정 생성 요청) + +[참고자료] +- 유저스토리 +- UI/UX설계서 +- 프로토타입 +- 아키텍처패턴 + +[예시] +- 논리아키텍처 다이어그램: https://raw.githubusercontent.com/cna-bootcamp/clauding-guide/refs/heads/main/samples/sample-논리아키텍처.mmd + +[결과파일] +- design/backend/logical/logical-architecture.md +- design/backend/logical/logical-architecture.mmd diff --git a/design/backend/logical/logical-architecture.md b/design/backend/logical/logical-architecture.md new file mode 100644 index 0000000..f79b943 --- /dev/null +++ b/design/backend/logical/logical-architecture.md @@ -0,0 +1,706 @@ +# 논리 아키텍처 설계서 + +## 1. 개요 + +### 1.1 목적 +회의록 작성 및 공유 개선 서비스의 논리 아키텍처를 정의하고, 마이크로서비스 간 통신 전략과 클라우드 디자인 패턴 적용 방안을 제시합니다. + +### 1.2 설계 원칙 + +#### 1.2.1 마이크로서비스 설계 원칙 +- **서비스 독립성**: 각 서비스는 독립적으로 배포 가능하며, 서비스 간 직접 의존성 최소화 +- **단일 책임**: 각 서비스는 명확한 비즈니스 책임을 가지며, 하나의 도메인 영역에 집중 +- **느슨한 결합**: 이벤트 기반 통신을 통한 서비스 간 결합도 최소화 +- **캐시 우선**: Redis를 통한 성능 최적화 및 서비스 간 데이터 공유 최소화 + +#### 1.2.2 통신 전략 +- **동기 통신**: 즉시 응답이 필요한 단순 조회 (REST API) +- **비동기 통신**: 장시간 작업 및 이벤트 기반 통신 (RabbitMQ) +- **캐시 우선**: 자주 사용되는 데이터는 Redis 캐시에서 직접 읽기 +- **API Gateway**: 모든 클라이언트 요청의 단일 진입점 + +#### 1.2.3 클라우드 디자인 패턴 적용 +- **API Gateway**: 라우팅, 인증, Rate Limiting +- **Queue-Based Load Leveling**: 부하 분산 및 비동기 처리 +- **Cache-Aside**: 성능 최적화 및 DB 부하 감소 +- **Publisher-Subscriber**: 이벤트 기반 통신 +- **Asynchronous Request-Reply**: 장시간 작업 비동기 처리 +- **Health Endpoint Monitoring**: 서비스 상태 모니터링 + +### 1.3 핵심 컴포넌트 + +#### 1.3.1 클라이언트 레이어 +- **Web Application**: 브라우저 기반 SPA (Single Page Application) +- **Mobile Application**: iOS/Android 네이티브 앱 (향후 확장) + +#### 1.3.2 API Gateway +- **Kong Gateway** 또는 **Spring Cloud Gateway** +- 역할: 라우팅, 인증/인가, Rate Limiting, 로깅 + +#### 1.3.3 백엔드 서비스 (8개) +1. **User Service**: 사용자 인증 및 권한 관리 +2. **Meeting Service**: 회의 관리, 회의록 생성 및 관리, 회의록 공유 +3. **STT Service**: 음성 녹음 관리, 음성-텍스트 변환, 화자 식별 +4. **AI Service**: LLM 기반 회의록 자동 작성, Todo 자동 추출, 프롬프팅 기반 회의록 개선 +5. **RAG Service**: 맥락 기반 용어 설명, 관련 문서 검색 및 연결, 업무 이력 통합 +6. **Collaboration Service**: 실시간 동기화, 버전 관리, 충돌 해결 +7. **Todo Service**: Todo 할당 및 관리, 진행 상황 추적, 회의록 실시간 연동 +8. **Notification Service**: 알림 발송 및 리마인더 관리 + +#### 1.3.4 인프라 컴포넌트 +- **PostgreSQL**: 각 서비스별 독립 데이터베이스 +- **Redis**: 분산 캐시 및 세션 관리 +- **RabbitMQ**: 메시지 큐 및 이벤트 버스 +- **Azure Storage**: 음성 파일 저장 +- **Azure Speech API**: STT(Speech-to-Text) 엔진 +- **LLM API**: AI 회의록 자동 작성 엔진 + +--- + +## 2. 서비스 아키텍처 + +### 2.1 서비스별 책임 + +#### 2.1.1 User Service +**책임**: 사용자 인증 및 권한 관리 +- LDAP 연동 인증 +- JWT 토큰 발급 및 검증 +- 사용자 프로필 관리 +- 권한 관리 + +**데이터**: +- 사용자 정보 (user_db) +- 세션 정보 (Redis 캐시) + +**외부 의존성**: +- LDAP 서버 + +--- + +#### 2.1.2 Meeting Service +**책임**: 회의 관리, 회의록 생성 및 관리, 회의록 공유 +- 회의 예약 및 참석자 초대 +- 회의 템플릿 관리 +- 회의 시작/종료 관리 +- 회의록 조회 및 수정 +- 회의록 공유 설정 +- 회의 통계 생성 + +**데이터**: +- 회의 정보 (meeting_db) +- 회의 템플릿 정보 +- 회의록 메타데이터 +- 회의 참석자 정보 + +**주요 이벤트**: +- **발행**: MeetingCreated, MeetingStarted, MeetingEnded, MeetingCancelled +- **구독**: TranscriptCreated, TodoCompleted + +**통신 전략**: +- **동기**: User Service (사용자 정보 조회 - Redis 캐시 우선) +- **비동기**: STT Service (회의록 생성 요청 - Queue), Notification Service (알림 발송 - Event) + +--- + +#### 2.1.3 STT Service +**책임**: 음성 녹음 관리, 음성-텍스트 변환, 화자 식별 +- 음성 녹음 시작/중지 +- 음성 파일 Azure Storage 저장 +- Azure Speech API 연동 STT 처리 +- 화자 자동 식별 +- 텍스트 변환 결과 저장 + +**데이터**: +- 음성 파일 메타데이터 (transcript_db) +- 텍스트 변환 결과 + +**외부 의존성**: +- Azure Speech API (STT 엔진) +- Azure Storage (음성 파일 저장) + +**주요 이벤트**: +- **구독**: MeetingEnded +- **통신**: AI Service (회의록 자동 작성 요청 - Queue) + +--- + +#### 2.1.4 AI Service +**책임**: LLM 기반 회의록 자동 작성, Todo 자동 추출, 프롬프팅 기반 회의록 개선 +- 회의록 자동 작성 (구조화, 문장 다듬기, 요약) +- Todo 자동 추출 및 담당자 식별 +- 프롬프팅 기반 회의록 개선 (1Page 요약, 핵심 요약 등) +- 관련 회의록 자동 연결 (벡터 유사도 검색) + +**데이터**: +- AI 처리 이력 (ai_db) +- 비동기 작업 상태 (Redis) + +**외부 의존성**: +- LLM API (OpenAI, Azure OpenAI 등) + +**주요 이벤트**: +- **구독**: TranscriptCreated +- **통신**: Todo Service (Todo 할당 요청 - Queue), RAG Service (관련 문서 검색 - 동기) + +**비동기 작업**: +- AI 일정 생성 (Asynchronous Request-Reply 패턴 적용) +- AI 회의록 요약 생성 + +--- + +#### 2.1.5 RAG Service +**책임**: 맥락 기반 용어 설명, 관련 문서 검색 및 연결, 업무 이력 통합 +- 전문용어 자동 감지 +- 벡터 유사도 검색을 통한 관련 문서 검색 +- 과거 회의록 및 사내 문서에서 맥락 기반 설명 생성 +- 용어 사전 관리 + +**데이터**: +- 벡터 DB (관련 문서 임베딩) +- 용어 사전 (rag_db) + +**외부 의존성**: +- 사내 문서 저장소 (위키, 매뉴얼 등) + +**통신 전략**: +- **동기**: AI Service (관련 문서 검색 요청 시) + +--- + +#### 2.1.6 Collaboration Service +**책임**: 실시간 동기화, 버전 관리, 충돌 해결 +- 회의록 실시간 수정 동기화 (WebSocket) +- 회의록 버전 관리 +- 동시 수정 충돌 감지 및 해결 +- 회의록 섹션 검증 완료 처리 + +**데이터**: +- 회의록 버전 정보 (collaboration_db) +- 수정 이력 + +**주요 이벤트**: +- **발행**: TranscriptUpdated, SectionVerified + +**통신 전략**: +- **WebSocket**: 실시간 동기화 (클라이언트 ↔ Collaboration Service) +- **비동기**: Notification Service (검증 완료 알림 - Event) + +--- + +#### 2.1.7 Todo Service +**책임**: Todo 할당 및 관리, 진행 상황 추적, 회의록 실시간 연동 +- Todo 생성 및 할당 +- Todo 진행 상황 추적 +- Todo 완료 처리 +- 회의록과 Todo 실시간 양방향 연동 +- 캘린더 연동 + +**데이터**: +- Todo 정보 (todo_db) +- Todo 진행 상황 + +**주요 이벤트**: +- **발행**: TodoCreated, TodoStatusChanged, TodoCompleted +- **구독**: MeetingEnded (AI Service를 통한 Todo 자동 추출) + +**통신 전략**: +- **동기**: Meeting Service (회의록 Todo 섹션 업데이트 - REST API) +- **비동기**: Notification Service (Todo 알림 - Event) + +--- + +#### 2.1.8 Notification Service +**책임**: 알림 발송 및 리마인더 관리 +- 이메일 알림 발송 +- SMS 알림 발송 (선택) +- 리마인더 관리 (회의 시작 30분 전, Todo 마감일 3일 전 등) +- 알림 발송 큐 처리 + +**데이터**: +- 알림 발송 이력 (notification_db) + +**외부 의존성**: +- SMTP 서버 (이메일) +- SMS 서비스 (선택) + +**주요 이벤트**: +- **구독**: MeetingCreated, MeetingEnded, TranscriptCreated, TodoCreated, TodoCompleted, SectionVerified + +--- + +### 2.2 서비스 간 통신 전략 + +#### 2.2.1 동기 통신 (REST API) +**사용 시나리오**: 즉시 응답이 필요한 조회 작업 + +| 요청 서비스 | 대상 서비스 | 목적 | 캐시 전략 | +|-----------|-----------|------|---------| +| Meeting Service | User Service | 사용자 정보 조회 | Redis 캐시 우선 (TTL: 30분) | +| Todo Service | Meeting Service | 회의록 Todo 섹션 업데이트 | 즉시 반영 | +| AI Service | RAG Service | 관련 문서 검색 | 캐시 없음 (검색 결과는 매번 변경 가능) | + +**특징**: +- Cache-Aside 패턴 적용 (User 정보, Meeting 정보 등) +- API Gateway를 통한 라우팅 및 인증 + +--- + +#### 2.2.2 비동기 통신 (Message Queue) +**사용 시나리오**: 장시간 작업 또는 즉시 응답 불필요 + +| 발행 서비스 | 큐 이름 | 구독 서비스 | 목적 | +|-----------|---------|-----------|------| +| Meeting Service | transcript.creation.queue | STT Service | 회의록 생성 요청 | +| STT Service | ai.processing.queue | AI Service | 회의록 자동 작성 요청 | +| AI Service | todo.extraction.queue | Todo Service | Todo 추출 및 할당 | +| 모든 서비스 | notification.queue | Notification Service | 알림 발송 요청 | + +**특징**: +- Queue-Based Load Leveling 패턴 적용 +- Consumer Concurrency 조정으로 부하 분산 +- Dead Letter Queue를 통한 실패 메시지 관리 + +--- + +#### 2.2.3 이벤트 기반 통신 (Pub-Sub) +**사용 시나리오**: 하나의 이벤트를 여러 서비스가 구독 + +| 이벤트 | 발행 서비스 | 구독 서비스 | 목적 | +|-------|-----------|-----------|------| +| MeetingCreated | Meeting Service | Notification Service, AI Service | 회의 생성 알림, AI 분석 준비 | +| MeetingEnded | Meeting Service | STT Service, Notification Service, Todo Service | 회의록 생성, 종료 알림, Todo 추출 | +| TranscriptCreated | STT Service | Notification Service, Meeting Service, AI Service | 회의록 생성 완료 알림, 상태 업데이트, AI 분석 | +| TodoCreated | Todo Service | Notification Service | Todo 할당 알림 | +| TodoCompleted | Todo Service | Notification Service, Meeting Service | Todo 완료 알림, 회의록 업데이트 | +| SectionVerified | Collaboration Service | Notification Service | 검증 완료 알림 | + +**특징**: +- Publisher-Subscriber 패턴 적용 +- RabbitMQ Topic Exchange 사용 +- 서비스 간 느슨한 결합 + +--- + +#### 2.2.4 비동기 작업 처리 (Asynchronous Request-Reply) +**사용 시나리오**: 장시간 실행되는 작업 (1분 이상) + +| 서비스 | 작업 | 예상 시간 | 상태 저장 | +|-------|------|----------|---------| +| AI Service | AI 일정 생성 | 30초 ~ 2분 | Redis (taskId 기반) | +| AI Service | AI 회의록 요약 생성 | 1분 ~ 5분 | Redis (taskId 기반) | +| STT Service | 음성 파일 STT 변환 | 1분 ~ 10분 | Redis (taskId 기반) | + +**처리 플로우**: +1. 클라이언트 → API Gateway → 서비스: 작업 요청 +2. 서비스: taskId 생성 → Redis 상태 저장 (PENDING) → Queue 발행 +3. 서비스 → 클라이언트: 202 Accepted + taskId 즉시 반환 +4. Worker: Queue 소비 → 상태 업데이트 (PROCESSING) → 작업 처리 → 상태 업데이트 (COMPLETED) +5. 클라이언트: GET /tasks/{taskId}로 상태 폴링 또는 WebSocket Push + +**특징**: +- Asynchronous Request-Reply 패턴 적용 +- Redis를 통한 작업 상태 관리 (TTL: 24시간) +- 폴링 또는 WebSocket을 통한 결과 조회 + +--- + +#### 2.2.5 실시간 통신 (WebSocket) +**사용 시나리오**: 실시간 협업 및 즉시 알림 + +| 사용 케이스 | 서비스 | 클라이언트 | +|----------|-------|----------| +| 회의록 실시간 동기화 | Collaboration Service | Frontend | +| AI 작업 완료 Push (옵션) | AI Service | Frontend | + +**특징**: +- WebSocket 기반 양방향 통신 +- 수정 델타만 전송하여 네트워크 효율 최적화 +- 충돌 감지 및 해결 (Last Write Wins 또는 수동 병합) + +--- + +## 3. 주요 사용자 플로우 + +### 3.1 회의 생성 및 예약 플로우 + +``` +1. 사용자 → Frontend: 회의 예약 정보 입력 +2. Frontend → API Gateway → Meeting Service: POST /api/meetings +3. Meeting Service: + - 회의 정보 저장 (meeting_db) + - MeetingCreated 이벤트 발행 +4. Notification Service (구독): + - 참석자에게 초대 이메일 발송 + - 캘린더 일정 등록 +5. AI Service (구독): + - 회의 일정 분석 준비 (비동기) +6. Frontend ← Meeting Service: 회의 정보 반환 +``` + +**적용 패턴**: +- API Gateway: 라우팅 및 인증 +- Publisher-Subscriber: MeetingCreated 이벤트 +- Queue-Based Load Leveling: 알림 발송 큐 + +--- + +### 3.2 회의 진행 및 회의록 생성 플로우 + +``` +1. 사용자 → Frontend: 회의 시작 버튼 클릭 +2. Frontend → API Gateway → Meeting Service: POST /api/meetings/{id}/start +3. Meeting Service: + - 회의 상태 '진행중'으로 업데이트 + - 회의 세션 생성 + - MeetingStarted 이벤트 발행 +4. STT Service: + - 음성 녹음 시작 + - 실시간 STT 처리 (Azure Speech API) + - 텍스트 변환 결과 저장 +5. AI Service: + - 텍스트 변환 결과 수신 + - 실시간 회의록 자동 작성 (구조화, 문장 다듬기) +6. Collaboration Service: + - 회의록 실시간 동기화 (WebSocket) + - 참석자 화면에 실시간 반영 +7. 사용자 → Frontend: 회의 종료 버튼 클릭 +8. Frontend → API Gateway → Meeting Service: POST /api/meetings/{id}/end +9. Meeting Service: + - 회의 상태 '종료'로 업데이트 + - 회의 통계 생성 + - MeetingEnded 이벤트 발행 +10. STT Service (구독): + - 음성 녹음 중지 + - 음성 파일 Azure Storage 저장 +11. Notification Service (구독): + - 참석자에게 회의 종료 알림 +12. Todo Service (구독): + - AI Service를 통한 Todo 자동 추출 요청 (비동기) +``` + +**적용 패턴**: +- API Gateway: 라우팅 및 인증 +- Publisher-Subscriber: MeetingStarted, MeetingEnded 이벤트 +- Queue-Based Load Leveling: Todo 추출 큐 +- WebSocket: 실시간 회의록 동기화 + +--- + +### 3.3 AI 기반 Todo 자동 추출 및 할당 플로우 + +``` +1. Todo Service (MeetingEnded 이벤트 구독): + - AI Service에 Todo 추출 요청 (Queue) +2. AI Service Worker: + - 회의록 텍스트 분석 + - Todo 항목 추출 (LLM API) + - 담당자 자동 식별 + - Todo 정보 생성 +3. AI Service → Todo Service: + - Todo 정보 전달 (Queue) +4. Todo Service: + - Todo 생성 및 저장 (todo_db) + - TodoCreated 이벤트 발행 + - 회의록 Todo 섹션 업데이트 (Meeting Service REST API 호출) +5. Notification Service (구독): + - 담당자에게 Todo 할당 알림 (이메일) + - 마감일 3일 전 리마인더 일정 생성 +6. Meeting Service: + - 회의록 Todo 섹션 업데이트 + - Redis 캐시 무효화 +``` + +**적용 패턴**: +- Publisher-Subscriber: MeetingEnded, TodoCreated 이벤트 +- Queue-Based Load Leveling: AI 처리 큐, Todo 할당 큐 +- Cache-Aside: 회의록 캐시 무효화 + +--- + +### 3.4 맥락 기반 용어 설명 플로우 + +``` +1. Frontend: 회의록 작성 중 전문용어 감지 (클라이언트 측) +2. Frontend → API Gateway → RAG Service: POST /api/rag/terms/explain +3. RAG Service: + - 용어 사전 확인 + - 벡터 유사도 검색 (과거 회의록, 사내 문서) + - 관련 문서 추출 (최대 5개) + - LLM을 통한 맥락 기반 설명 생성 +4. RAG Service → Frontend: + - 용어 정의 + - 맥락 기반 상세 설명 + - 실제 사용 사례 + - 관련 프로젝트/이슈 + - 과거 회의록 링크 (최대 3개) +5. Frontend: + - 툴팁 또는 사이드 패널로 설명 표시 +``` + +**적용 패턴**: +- API Gateway: 라우팅 및 인증 +- Cache-Aside: 용어 사전 캐싱 + +--- + +### 3.5 AI 일정 생성 (비동기 작업) 플로우 + +``` +1. Frontend → API Gateway → AI Service: POST /api/ai/schedules +2. AI Service: + - taskId 생성 (UUID) + - Redis 상태 저장 (PENDING) + - Queue에 작업 메시지 발행 + - 202 Accepted + taskId 즉시 반환 +3. AI Worker (비동기): + - Queue 소비 + - Redis 상태 업데이트 (PROCESSING) + - LLM API 호출하여 일정 생성 (1분 소요) + - Redis 상태 업데이트 (COMPLETED) + 결과 저장 +4. Frontend (폴링): + - GET /api/ai/tasks/{taskId}를 5초마다 호출 + - status가 COMPLETED일 때 결과 획득 +``` + +**적용 패턴**: +- Asynchronous Request-Reply: 비동기 작업 처리 +- Queue-Based Load Leveling: AI 처리 큐 +- Redis: 작업 상태 관리 + +--- + +### 3.6 회의록 실시간 협업 플로우 + +``` +1. 참석자 A → Frontend: 회의록 수정 +2. Frontend → Collaboration Service (WebSocket): 수정 델타 전송 +3. Collaboration Service: + - 수정 권한 확인 + - 수정 이력 저장 (collaboration_db) + - 버전 관리 + - 충돌 감지 (동일 위치 동시 수정 시) +4. Collaboration Service → 모든 참석자 (WebSocket): + - 수정 델타 실시간 브로드캐스트 + - 수정 영역 하이라이트 (3초간) +5. 참석자 B, C Frontend: + - 실시간으로 수정 내용 반영 +6. 충돌 발생 시: + - Last Write Wins (기본) 또는 수동 병합 UI 제공 +``` + +**적용 패턴**: +- WebSocket: 실시간 양방향 통신 +- Queue-Based Load Leveling: 알림 발송 큐 (수정 알림) + +--- + +### 3.7 회의록 검증 완료 플로우 + +``` +1. 참석자 → Frontend: 섹션 검증 완료 버튼 클릭 +2. Frontend → API Gateway → Collaboration Service: POST /api/collaboration/sections/{id}/verify +3. Collaboration Service: + - 검증자 정보 기록 + - 검증 상태 업데이트 (검증 완료) + - 회의 생성자만 섹션 잠금 가능 (선택) + - SectionVerified 이벤트 발행 +4. Notification Service (구독): + - 전체 참석자에게 검증 완료 알림 (이메일) +5. Collaboration Service → Frontend (WebSocket): + - 검증 완료 상태 실시간 동기화 + - 검증 배지 표시 (체크 아이콘) +``` + +**적용 패턴**: +- Publisher-Subscriber: SectionVerified 이벤트 +- WebSocket: 실시간 상태 동기화 +- Queue-Based Load Leveling: 알림 발송 큐 + +--- + +## 4. 데이터 흐름 및 캐싱 전략 + +### 4.1 데이터베이스 구성 +- **서비스별 독립 데이터베이스**: 각 서비스마다 독립적인 PostgreSQL 데이터베이스 +- **서비스 간 데이터 공유 최소화**: 캐시 또는 이벤트를 통한 데이터 공유 + +| 서비스 | 데이터베이스 | 주요 테이블 | +|-------|-----------|----------| +| User Service | user_db | users, roles, permissions | +| Meeting Service | meeting_db | meetings, templates, participants, transcripts_metadata | +| STT Service | transcript_db | audio_files, stt_results, speakers | +| AI Service | ai_db | ai_tasks, ai_results, related_transcripts | +| RAG Service | rag_db | terms_dictionary, document_embeddings | +| Collaboration Service | collaboration_db | transcript_versions, edit_history, conflicts | +| Todo Service | todo_db | todos, todo_status_history | +| Notification Service | notification_db | notifications, notification_templates | + +--- + +### 4.2 캐싱 전략 (Cache-Aside 패턴) + +#### 4.2.1 캐싱 대상 데이터 + +| 서비스 | 캐시 데이터 | TTL | 무효화 트리거 | +|-------|----------|-----|-------------| +| User Service | 사용자 프로필 정보 | 30분 | 사용자 정보 업데이트 | +| User Service | 사용자 권한 정보 | 1시간 | 권한 변경 | +| Meeting Service | 회의 기본 정보 | 10분 | 회의 정보 수정 | +| Meeting Service | 회의 참여자 목록 | 10분 | 참여자 변경 | +| Meeting Service | 회의 템플릿 목록 | 1시간 | 템플릿 생성/수정 | +| STT Service | 회의록 조회 | 30분 | 회의록 수정 | +| Todo Service | 사용자별 Todo 목록 | 5분 | Todo 상태 변경 | +| Todo Service | Todo 진행 상태 통계 | 5분 | Todo 완료 | + +#### 4.2.2 캐시 정책 + +**읽기 집중 데이터** (Cache-Aside): +- 패턴: Lazy Loading +- 전략: 캐시 미스 시 DB 조회 → 캐시 저장 +- 예: 사용자 프로필, 회의 정보 조회 + +**쓰기 빈도 높은 데이터** (Write-Through + Cache-Aside): +- 패턴: 업데이트 시 캐시 무효화 +- 전략: DB 업데이트 → 캐시 삭제 → 다음 조회 시 재생성 +- 예: Todo 상태 변경, 회의 정보 수정 + +**캐시 무효화**: +- 데이터 변경 시 즉시 무효화 (Cache Eviction) +- TTL 기반 자동 만료 +- 명시적 삭제 API 제공 (관리자용) + +--- + +### 4.3 비동기 작업 상태 관리 (Redis) + +**작업 상태 저장**: +- Key: `task:{taskId}` +- Value: `{ taskId, status, createdAt, startedAt, completedAt, result, errorMessage }` +- TTL: 24시간 + +**상태 흐름**: +1. PENDING: 요청 접수 직후 +2. PROCESSING: Worker가 작업 시작 +3. COMPLETED: 작업 성공 완료 +4. FAILED: 작업 실패 + +--- + +## 5. 확장성 및 성능 고려사항 + +### 5.1 수평 확장 전략 + +#### 5.1.1 Stateless 서비스 설계 +- **모든 백엔드 서비스는 Stateless**: 세션 정보는 Redis에 저장 +- **수평 확장 가능**: Kubernetes 기반 Pod Auto Scaling +- **Load Balancer**: Kubernetes Service (ClusterIP)를 통한 부하 분산 + +#### 5.1.2 서비스별 확장 전략 + +| 서비스 | 확장 전략 | Auto Scaling 기준 | +|-------|---------|-----------------| +| API Gateway | 수평 확장 (최소 2개) | CPU > 70% 또는 RPS > 1000 | +| User Service | 수평 확장 | CPU > 70% | +| Meeting Service | 수평 확장 | CPU > 70% 또는 메모리 > 80% | +| STT Service | 수평 확장 + Worker 증설 | Queue 길이 > 100 | +| AI Service | 수평 확장 + Worker 증설 | Queue 길이 > 50 | +| Notification Service | 수평 확장 + Worker 증설 | Queue 길이 > 200 | +| Todo Service | 수평 확장 | CPU > 70% | +| Collaboration Service | 수평 확장 (WebSocket) | 동시 연결 > 500 | + +--- + +### 5.2 성능 최적화 + +#### 5.2.1 캐싱 최적화 +- **Cache Hit Rate 목표**: 70% 이상 +- **Hot Key 문제 대응**: 자주 조회되는 데이터는 로컬 캐시 + 분산 캐시 병행 +- **Cache Stampede 방지**: Singleflight 패턴 적용 (동시 다발적 Cache Miss 방지) + +#### 5.2.2 데이터베이스 최적화 +- **Connection Pool**: HikariCP 설정 최적화 (maxPoolSize: 10-20) +- **인덱스 최적화**: 자주 조회되는 필드에 인덱스 생성 +- **Read Replica**: 읽기 부하 분산 (필요 시) + +#### 5.2.3 메시지 큐 최적화 +- **Consumer Concurrency**: 서비스별 동시 처리 워커 수 조정 (3-10) +- **Prefetch Count**: RabbitMQ Prefetch 설정 최적화 +- **Dead Letter Queue**: 실패 메시지 별도 처리 + +--- + +### 5.3 성능 목표 + +| 지표 | 목표 | +|------|------| +| API 응답 시간 (P95) | < 500ms | +| 회의록 생성 시간 | < 2분 | +| AI 일정 생성 시간 | < 1분 | +| Cache Hit Rate | > 70% | +| 시스템 가용성 | > 99.5% | +| 동시 사용자 수 | 10,000명 | +| 동시 진행 회의 수 | 1,000개 | +| 일일 처리 회의 수 | 100,000개 | + +--- + +## 6. 보안 고려사항 + +### 6.1 인증 및 인가 + +#### 6.1.1 인증 전략 +- **LDAP 연동**: 사내 LDAP 서버와 연동한 사용자 인증 +- **JWT 토큰**: 인증 후 JWT 토큰 발급 (만료 시간: 1시간) +- **Refresh Token**: 장기 세션 유지 (만료 시간: 7일) +- **Token 검증**: API Gateway에서 JWT 토큰 검증 (모든 요청) + +#### 6.1.2 인가 전략 +- **역할 기반 접근 제어 (RBAC)**: 사용자 역할에 따른 권한 관리 +- **회의 참여자 검증**: 회의 참여자만 회의록 접근 가능 +- **회의록 작성자 권한**: 수정, 삭제 권한은 작성자에게만 부여 + +--- + +### 6.2 데이터 보안 + +#### 6.2.1 암호화 +- **전송 중 암호화**: HTTPS/TLS (API Gateway) +- **저장 시 암호화**: PostgreSQL Transparent Data Encryption (TDE) +- **민감 정보 암호화**: 사용자 비밀번호는 bcrypt 해싱 + +#### 6.2.2 데이터 접근 제어 +- **데이터베이스 접근**: 서비스별 독립 계정, 최소 권한 원칙 +- **Redis 접근**: Password 인증 + ACL 설정 +- **RabbitMQ 접근**: 서비스별 독립 계정, 큐별 권한 관리 + +--- + +### 6.3 보안 모니터링 + +#### 6.3.1 로깅 +- **API Gateway**: 모든 요청/응답 로깅 (사용자 ID, 엔드포인트, 응답 시간) +- **인증 실패 로깅**: 반복적인 인증 실패 시 경고 +- **민감 정보 마스킹**: 로그에서 비밀번호, 토큰 등 마스킹 + +#### 6.3.2 보안 이벤트 모니터링 +- **이상 접근 탐지**: 짧은 시간 내 과도한 요청 (Rate Limiting) +- **권한 없는 접근 시도**: 403 Forbidden 응답 모니터링 +- **보안 패치**: 정기적인 보안 업데이트 및 취약점 점검 + +--- + +## 7. 논리 아키텍처 다이어그램 + +논리 아키텍처 다이어그램은 별도 파일로 작성되었습니다. + +**파일**: [logical-architecture.mmd](logical-architecture.mmd) + +**온라인 확인**: https://mermaid.live/edit + +--- + +## 8. 문서 이력 + +| 버전 | 작성일 | 작성자 | 변경 내용 | +|------|--------|--------|----------| +| 1.0 | 2025-01-20 | 준호 | 초안 작성 | diff --git a/design/backend/logical/logical-architecture.mmd b/design/backend/logical/logical-architecture.mmd new file mode 100644 index 0000000..641b185 --- /dev/null +++ b/design/backend/logical/logical-architecture.mmd @@ -0,0 +1,119 @@ +graph TB + %% 클라이언트 레이어 + Client[Web/Mobile Application] + + %% API Gateway + APIGateway[API Gateway Kong/Spring Cloud Gateway 라우팅, 인증, Rate Limiting] + + %% 백엔드 서비스 + UserService[User Service 사용자 인증 및 권한 관리] + MeetingService[Meeting Service 회의 관리, 회의록 관리] + STTService[STT Service 음성 녹음, STT 처리] + AIService[AI Service 회의록 자동 작성, Todo 추출] + RAGService[RAG Service 맥락 기반 용어 설명] + CollabService[Collaboration Service 실시간 동기화, 버전 관리] + TodoService[Todo Service Todo 관리, 진행 추적] + NotifyService[Notification Service 알림 발송, 리마인더] + + %% 인프라 컴포넌트 + Redis[(Redis 분산 캐시, 세션, 작업 상태)] + RabbitMQ[RabbitMQ 메시지 큐, 이벤트 버스] + + %% 데이터베이스 + UserDB[(PostgreSQL user_db)] + MeetingDB[(PostgreSQL meeting_db)] + STTDB[(PostgreSQL transcript_db)] + AIDB[(PostgreSQL ai_db)] + RAGDB[(PostgreSQL rag_db + Vector DB)] + CollabDB[(PostgreSQL collaboration_db)] + TodoDB[(PostgreSQL todo_db)] + NotifyDB[(PostgreSQL notification_db)] + + %% 외부 시스템 + LDAP[LDAP Server] + AzureStorage[Azure Storage 음성 파일] + AzureSpeech[Azure Speech API STT 엔진] + LLMAPI[LLM API OpenAI/Azure OpenAI] + SMTP[SMTP Server 이메일] + + %% 클라이언트 → API Gateway + Client -->|HTTPS| APIGateway + + %% API Gateway → 서비스 (라우팅) + APIGateway -->|/api/users/**| UserService + APIGateway -->|/api/meetings/**| MeetingService + APIGateway -->|/api/transcripts/**| STTService + APIGateway -->|/api/ai/**| AIService + APIGateway -->|/api/rag/**| RAGService + APIGateway -->|/api/collaboration/**| CollabService + APIGateway -->|/api/todos/**| TodoService + APIGateway -->|/api/notifications/**| NotifyService + + %% 서비스 → Redis (캐시) + UserService -.->|Cache: 사용자 프로필| Redis + MeetingService -.->|Cache: 회의 정보| Redis + TodoService -.->|Cache: Todo 목록| Redis + AIService -.->|작업 상태 저장| Redis + + %% 서비스 → 데이터베이스 + UserService --> UserDB + MeetingService --> MeetingDB + STTService --> STTDB + AIService --> AIDB + RAGService --> RAGDB + CollabService --> CollabDB + TodoService --> TodoDB + NotifyService --> NotifyDB + + %% 동기 통신 (REST API) + MeetingService -.->|Meeting 사용자 정보 조회 Cache 우선| UserService + TodoService -->|Todo 회의록 Todo 섹션 업데이트| MeetingService + AIService -->|AI 관련 문서 검색| RAGService + + %% 비동기 통신 (Queue) + MeetingService -->|Meeting 회의록 생성 요청| RabbitMQ + RabbitMQ -->|transcript.creation.queue| STTService + + STTService -->|STT 회의록 자동 작성 요청| RabbitMQ + RabbitMQ -->|ai.processing.queue| AIService + + AIService -->|AI Todo 추출 요청| RabbitMQ + RabbitMQ -->|todo.extraction.queue| TodoService + + MeetingService -->|Meeting 알림 발송| RabbitMQ + STTService -->|STT 알림 발송| RabbitMQ + TodoService -->|Todo 알림 발송| RabbitMQ + CollabService -->|Collab 알림 발송| RabbitMQ + RabbitMQ -->|notification.queue| NotifyService + + %% 이벤트 기반 통신 (Pub-Sub) + MeetingService -->|MeetingCreated MeetingEnded| RabbitMQ + STTService -->|TranscriptCreated| RabbitMQ + TodoService -->|TodoCreated TodoCompleted| RabbitMQ + CollabService -->|SectionVerified| RabbitMQ + + %% WebSocket (실시간 통신) + Client <-.->|WebSocket 실시간 회의록 동기화| CollabService + + %% 외부 시스템 연동 + UserService -->|인증| LDAP + STTService -->|음성 파일 저장| AzureStorage + STTService -->|STT 처리| AzureSpeech + AIService -->|회의록 자동 작성 Todo 추출| LLMAPI + RAGService -->|용어 설명 생성| LLMAPI + NotifyService -->|이메일 발송| SMTP + + %% 스타일링 + classDef clientStyle fill:#e1f5ff,stroke:#01579b,stroke-width:2px + classDef gatewayStyle fill:#fff3e0,stroke:#e65100,stroke-width:3px + classDef serviceStyle fill:#f3e5f5,stroke:#4a148c,stroke-width:2px + classDef infraStyle fill:#e8f5e9,stroke:#1b5e20,stroke-width:2px + classDef dbStyle fill:#fff9c4,stroke:#f57f17,stroke-width:2px + classDef externalStyle fill:#fce4ec,stroke:#880e4f,stroke-width:2px + + class Client clientStyle + class APIGateway gatewayStyle + class UserService,MeetingService,STTService,AIService,RAGService,CollabService,TodoService,NotifyService serviceStyle + class Redis,RabbitMQ infraStyle + class UserDB,MeetingDB,STTDB,AIDB,RAGDB,CollabDB,TodoDB,NotifyDB dbStyle + class LDAP,AzureStorage,AzureSpeech,LLMAPI,SMTP externalStyle diff --git a/tools/check-mermaid.sh b/tools/check-mermaid.sh new file mode 100644 index 0000000..abb29cb --- /dev/null +++ b/tools/check-mermaid.sh @@ -0,0 +1,107 @@ +#!/bin/bash +# Mermaid Syntax Checker using Docker Container +# Similar to PlantUML checker - keeps container running for better performance + +# Colors for output +RED='\033[0;31m' +GREEN='\033[0;32m' +YELLOW='\033[0;33m' +CYAN='\033[0;36m' +GRAY='\033[0;90m' +NC='\033[0m' # No Color + +# Check if file path is provided +if [ -z "$1" ]; then + echo -e "${RED}Error: No file path provided${NC}" + echo "Usage: $0 " + exit 1 +fi + +FILE_PATH="$1" + +# Check if file exists +if [ ! -f "$FILE_PATH" ]; then + echo -e "${RED}Error: File not found: $FILE_PATH${NC}" + exit 1 +fi + +# Get absolute path +ABSOLUTE_PATH=$(realpath "$FILE_PATH") +FILE_NAME=$(basename "$ABSOLUTE_PATH") + +echo -e "\n${CYAN}Checking Mermaid syntax for: $FILE_NAME${NC}" +echo -e "${GRAY}$(printf '=%.0s' {1..60})${NC}" + +# Check if mermaid container is running +CONTAINER_RUNNING=$(docker ps --filter "name=mermaid-cli" --format "{{.Names}}" 2>/dev/null) + +if [ -z "$CONTAINER_RUNNING" ]; then + echo -e "${RED}Error: Mermaid CLI container is not running.${NC}" + echo -e "${YELLOW}Please follow the setup instructions in the Mermaid guide to start the container.${NC}" + echo -e "\n${CYAN}Quick setup commands:${NC}" + echo "" + echo -e "${GREEN}# 1. Start container with root privileges (port 48080)${NC}" + echo -e "${NC}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\"${NC}" + echo "" + echo -e "${GREEN}# 2. Install Chromium and dependencies${NC}" + echo -e "${NC}docker exec mermaid-cli sh -c \"apk add --no-cache chromium chromium-chromedriver nss freetype harfbuzz ca-certificates ttf-freefont\"${NC}" + echo "" + echo -e "${GREEN}# 3. Create Puppeteer configuration${NC}" + echo -e "${NC}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\"${NC}" + echo "" + exit 1 +fi + +# Set Puppeteer configuration file path +PUPPETEER_CONFIG_FILE="/tmp/puppeteer-config.json" + +# Generate unique temp filename +TIMESTAMP=$(date +"%Y%m%d%H%M%S") +PID=$$ +TEMP_FILE="/tmp/mermaid_${TIMESTAMP}_${PID}.mmd" +OUTPUT_FILE="/tmp/mermaid_${TIMESTAMP}_${PID}.svg" + +# Copy file to container +echo -e "${GRAY}Copying file to container...${NC}" +docker cp "$ABSOLUTE_PATH" "mermaid-cli:$TEMP_FILE" >/dev/null 2>&1 + +if [ $? -ne 0 ]; then + echo -e "${RED}Error: Failed to copy file to container${NC}" + exit 1 +fi + +# Run syntax check with Puppeteer configuration +echo -e "${GRAY}Running syntax check...${NC}" +OUTPUT=$(docker exec mermaid-cli sh -c "cd /home/mermaidcli && node_modules/.bin/mmdc -i '$TEMP_FILE' -o '$OUTPUT_FILE' -p '$PUPPETEER_CONFIG_FILE' -q" 2>&1) +EXIT_CODE=$? + +if [ $EXIT_CODE -eq 0 ]; then + echo -e "\n${GREEN}Success: Mermaid syntax is valid!${NC}" +else + echo -e "\n${RED}Error: Mermaid syntax validation failed!${NC}" + echo -e "\n${RED}Error details:${NC}" + + # Parse and display error messages + while IFS= read -r line; do + if [[ $line == *"Error:"* ]] || [[ $line == *"Parse error"* ]] || [[ $line == *"Expecting"* ]] || [[ $line == *"Syntax error"* ]]; then + echo -e " ${RED}$line${NC}" + elif [[ $line == *"line"* ]] && [[ $line =~ [0-9]+ ]]; then + echo -e " ${YELLOW}$line${NC}" + elif [[ ! -z "$line" ]]; then + echo -e " ${RED}$line${NC}" + fi + done <<< "$OUTPUT" + + # Clean up and exit with error + docker exec mermaid-cli rm -f "$TEMP_FILE" "$OUTPUT_FILE" >/dev/null 2>&1 + exit 1 +fi + +# Clean up temp files +echo -e "\n${GRAY}Cleaning up...${NC}" +docker exec mermaid-cli rm -f "$TEMP_FILE" "$OUTPUT_FILE" >/dev/null 2>&1 + +echo -e "\n${CYAN}Validation complete!${NC}" + +# Note: Container is kept running for subsequent checks +# To stop: docker stop mermaid-cli && docker rm mermaid-cli \ No newline at end of file