hgzero/design/backend/logical/logical-architecture.md

# 논리 아키텍처 설계서

## 1. 개요

### 1.1 문서 목적
본 문서는 회의록 작성 및 공유 개선 서비스의 논리적 아키텍처를 정의합니다. 마이크로서비스 간의 관계, 통신 패턴, 데이터 흐름을 명확히 하여 시스템 구현의 기반을 제공합니다.

### 1.2 설계 원칙

#### 핵심 설계 원칙
- **서비스 독립성**: 각 마이크로서비스는 독립적인 데이터베이스를 가지며 자율적으로 배포 가능
- **캐시 우선 전략**: Redis를 통한 성능 최적화 및 서비스 간 직접 의존성 최소화
- **선택적 비동기 처리**: 장시간 작업(STT, AI 처리)만 비동기로 처리
- **이벤트 기반 통신**: Pub/Sub 패턴을 통한 느슨한 결합
- **확장성 우선**: 수평 확장이 가능한 Stateless 아키텍처

#### 클라우드 디자인 패턴 적용
- **API Gateway**: 단일 진입점을 통한 인증, 라우팅, Rate Limiting
- **Queue-Based Load Leveling**: 메시지 큐를 통한 부하 분산
- **Cache-Aside**: 캐시 우선 조회로 DB 부하 감소
- **Publisher-Subscriber**: 이벤트 기반 서비스 간 통신
- **Asynchronous Request-Reply**: 장시간 작업의 비동기 처리
- **Health Endpoint Monitoring**: 서비스 상태 모니터링 및 자동 복구

### 1.3 핵심 컴포넌트 정의

#### 클라이언트 레이어
- **웹 애플리케이션**: React/Vue 기반 SPA (Single Page Application)
- **모바일 앱** (선택): 향후 확장 고려

#### API Gateway 레이어
- **Kong Gateway** 또는 **Spring Cloud Gateway**
- 주요 기능:
  - JWT 기반 인증/인가
  - Rate Limiting (사용자별 요청 제한)
  - 서비스 라우팅
  - Request/Response 로깅
  - CORS 처리

#### 마이크로서비스 레이어 (5개 서비스)

| 서비스 | 책임 | 주요 기능 |
|--------|------|----------|
| **User Service** | 사용자 인증 | - 사용자 인증 (LDAP 연동)<br/>- JWT 토큰 발급 및 검증 |
| **Meeting Service** | 회의, 회의록, Todo, 실시간 협업 관리 | - 회의 예약/시작/종료<br/>- 회의록 관리 (생성/수정/공유)<br/>- 회의 템플릿 관리<br/>- Todo 관리 및 진행 상황 추적<br/>- 실시간 동기화 (WebSocket)<br/>- 버전 관리 및 충돌 해결<br/>- 회의 통계 |
| **STT Service** | 음성 인식 | - 음성 녹음 관리<br/>- 음성-텍스트 변환 (Azure Speech)<br/>- 화자 식별 |
| **AI Service** | AI 기반 자동화 및 지능형 검색 | - 회의록 자동 작성 (LLM)<br/>- Todo 자동 추출<br/>- 프롬프팅 기반 회의록 개선<br/>- 전문용어 감지 및 맥락 기반 설명 (RAG)<br/>- 관련 회의록 자동 연결 |
| **Notification Service** | 알림 관리 | - 알림 발송 (이메일/SMS)<br/>- 리마인더 관리<br/>- 알림 큐 관리 |

#### 인프라 레이어

**데이터 저장소**
- **PostgreSQL**: 각 서비스별 독립 데이터베이스 (5개)
  - User DB, Meeting DB, STT DB, AI DB, Notification DB
- **Redis**: 분산 캐시
  - 회의 정보, Todo 목록 캐싱
  - 비동기 작업 상태 저장

**메시지 브로커**
- **RabbitMQ**: 이벤트 기반 통신 및 작업 큐
  - Topic Exchange를 통한 Pub/Sub 패턴
  - 작업 큐를 통한 부하 분산

**외부 서비스**
- **Azure Speech**: STT (Speech-to-Text) 엔진
- **AI Model Server**: LLM 기반 회의록 자동 작성
- **Email/SMS Service**: 알림 발송

---

## 2. 서비스 아키텍처

### 2.1 서비스별 책임

#### User Service
**핵심 책임**: 사용자 인증

**주요 기능**:
- LDAP 연동 사용자 인증
- JWT 토큰 발급 및 검증

**데이터 관리**:
- User 엔티티: 사용자 기본 정보 (사번, 이름, 이메일)
- Session 엔티티: 활성 세션 관리

**역할 변경**:
- 프론트엔드에서 사용자 정보(userId, userName, email)를 모든 API 요청에 포함하여 전송
- User Service는 인증 토큰 발급/검증만 담당
- 다른 서비스는 User Service를 동기 호출하지 않음 (성능 향상, 의존성 제거)

---

#### Meeting Service
**핵심 책임**: 회의, 회의록, Todo, 실시간 협업 통합 관리

**주요 기능**:
- **회의 관리**: 회의 예약, 시작, 종료
- **회의록 관리**: 회의록 생성, 수정, 확정, 공유
- **Todo 관리**: Todo 할당, 진행 상황 추적, 회의록 양방향 연결
- **실시간 협업**: WebSocket 기반 실시간 동기화, 버전 관리, 충돌 해결
- **템플릿 관리**: 회의록 템플릿 관리
- **통계 생성**: 회의 및 Todo 통계

**데이터 관리**:
- Meeting 엔티티: 회의 정보 (제목, 일시, 장소, 참석자)
- Transcript 엔티티: 회의록 (내용, 상태, 버전)
- Todo 엔티티: Todo 정보 (내용, 담당자, 마감일, 상태)
- TranscriptVersion 엔티티: 회의록 버전 정보
- CollaborationEvent 엔티티: 수정 이벤트 (수정자, 시간, 변경 내용)
- MeetingTemplate 엔티티: 회의록 템플릿
- TodoProgress 엔티티: 진행 상황 (시작 시간, 완료 시간)

**이벤트 발행**:
- `MeetingCreated`: 회의 생성 시
- `MeetingStarted`: 회의 시작 시
- `MeetingEnded`: 회의 종료 시
- `TranscriptCreated`: 회의록 생성 완료 시
- `TranscriptShared`: 회의록 공유 시
- `TodoCreated`: Todo 생성 시
- `TodoCompleted`: Todo 완료 시

**실시간 동기화**:
- WebSocket을 통해 수정 델타 전송 (전체 데이터 대신)
- AI 분석 결과 통합 전송 (정리된 회의록, 전문용어, 관련 자료)
- 모든 참석자에게 실시간 반영

**캐싱 전략**:
- 회의 기본 정보: TTL 10분
- 회의 참여자 목록: TTL 10분
- 회의 템플릿: TTL 1시간
- Todo 목록: TTL 5분
- Todo 통계: TTL 5분

---

#### STT Service
**핵심 책임**: 음성 녹음 및 텍스트 변환

**주요 기능**:
- 음성 녹음 관리
- Azure Speech API를 통한 음성-텍스트 변환
- 화자 자동 식별

**데이터 관리**:
- AudioRecord 엔티티: 음성 파일 정보 (URL, 시간, 크기)
- TranscriptSegment 엔티티: 변환된 텍스트 (화자, 타임스탬프, 내용)

**비동기 처리**:
- Queue를 통한 STT 변환 요청 수신
- 변환 완료 시 `TranscriptReady` 이벤트 발행

**성능 요구사항**:
- 발언 인식 지연 시간: < 1초
- 화자 식별 정확도: > 90%
- STT 변환 정확도: > 95%

---

#### AI Service
**핵심 책임**: AI 기반 회의록 자동화, Todo 추출, 지능형 검색 (RAG 통합)

**주요 기능**:
- LLM 기반 회의록 자동 작성
- Todo 자동 추출 및 담당자 식별
- 프롬프팅 기반 회의록 개선 (1Page 요약, 핵심 요약 등)
- 관련 회의록 자동 연결 (벡터 유사도 검색)
- 전문용어 자동 감지 및 맥락 기반 설명 생성 (RAG)
- 과거 회의록 및 사내 문서 검색
- 업무 이력 통합

**데이터 관리**:
- AiTaskStatus 엔티티: 비동기 작업 상태 (PENDING, PROCESSING, COMPLETED, FAILED)
- TranscriptSummary 엔티티: AI 생성 요약
- TermGlossary 엔티티: 용어 사전
- DocumentEmbedding 엔티티: 문서 벡터 임베딩
- TermExplanation 엔티티: 생성된 용어 설명

**비동기 처리**:
- Queue를 통한 AI 처리 요청 수신
- Redis에 작업 상태 저장 (Async Request-Reply 패턴)
- 처리 완료 시 이벤트 발행

**이벤트 발행**:
- `TodoExtracted`: Todo 추출 완료 시
- `TranscriptSummaryCreated`: 요약 생성 완료 시

**검색 전략**:
- 벡터 유사도 기반 관련 문서 검색
- 관련도 70% 이상만 반환
- 최대 5개 문서 선택

**성능 목표**:
- AI 회의록 작성: < 30초
- Todo 추출: < 10초
- 프롬프팅 기반 개선: < 1분
- 용어 검색 및 설명 생성: < 5초

**차별화 포인트**:
- 단순 정의가 아닌 조직 내 실제 사용 맥락 제공
- 업무 지식 없이도 실질적인 도움 제공

---

#### Notification Service
**핵심 책임**: 알림 발송 및 리마인더 관리

**주요 기능**:
- 이메일 알림 발송
- SMS 알림 발송 (선택)
- 리마인더 자동 발송
- 알림 큐 관리

**데이터 관리**:
- Notification 엔티티: 알림 정보 (수신자, 내용, 발송 상태)
- NotificationTemplate 엔티티: 알림 템플릿

**비동기 처리**:
- Queue를 통한 알림 발송 요청 수신
- 대량 알림 발송 시 부하 분산

**알림 유형**:
- 회의 생성/시작/종료 알림
- Todo 할당/완료 알림
- 회의록 생성/공유 알림
- 리마인더 (회의 30분 전, Todo 마감 3일 전)

---

### 2.2 서비스 간 통신 전략

#### 동기 통신 (REST API)
**적용 대상**: 없음 (서비스 간 동기 의존성 제거)

**변경 사항**:
- 프론트엔드가 모든 API 요청에 사용자 정보(userId, userName, email) 포함
- User Service 동기 참조 완전 제거 → 성능 향상, 장애 격리
- Meeting Service 내에서 Todo, Collaboration 기능 통합 → 내부 메서드 호출로 처리

---

#### 비동기 통신 (Message Queue - Pub/Sub)
**적용 대상**: 이벤트 기반 통신, 느슨한 결합

**이벤트 발행/구독 매트릭스**:

| 이벤트 | 발행자 | 구독자 | 목적 |
|--------|--------|--------|------|
| **MeetingCreated** | Meeting Service | Notification Service<br/>AI Service | 참석자 알림 발송<br/>회의 분석 준비 |
| **MeetingStarted** | Meeting Service | STT Service | 음성 녹음 시작 준비 |
| **MeetingEnded** | Meeting Service | STT Service<br/>AI Service<br/>Notification Service | 음성 녹음 종료<br/>AI 분석 종료<br/>종료 알림 |
| **TranscriptReady** | STT Service | AI Service | AI 회의록 분석 (5초 배치) |
| **TranscriptSummaryCreated** | AI Service | Meeting Service | 회의록 최종 저장 및 동기화 |
| **TodoCreated** | Meeting Service | Notification Service | 담당자 알림 발송 |
| **TodoCompleted** | Meeting Service | Notification Service | 완료 알림 |
| **TranscriptShared** | Meeting Service | Notification Service | 회의록 공유 알림 |

**RabbitMQ Exchange/Queue 구성**:
- **Topic Exchange**: `meeting.events`, `transcript.events`, `todo.events`
- **Queue 네이밍**: `{service}.{event-category}.queue`
- **Routing Key 패턴**: `{event}.{action}` (예: `meeting.ended`, `todo.created`)

---

#### 캐시를 통한 간접 참조 (Cache-Aside)
**적용 대상**: 자주 조회되는 읽기 전용 데이터

**캐싱 대상 및 전략**:

| 데이터 유형 | TTL | 캐시 키 패턴 | 무효화 시점 |
|------------|-----|--------------|------------|
| 사용자 프로필 | 30분 | `user:profile:{userId}` | 프로필 수정 시 |
| 사용자 권한 | 1시간 | `user:auth:{userId}` | 권한 변경 시 |
| 회의 정보 | 10분 | `meeting:info:{meetingId}` | 회의 수정 시 |
| 회의 참여자 | 10분 | `meeting:participants:{meetingId}` | 참여자 변경 시 |
| 회의 템플릿 | 1시간 | `meeting:template:{templateId}` | 템플릿 수정 시 |
| Todo 목록 | 5분 | `todo:user:{userId}` | Todo 상태 변경 시 |
| Todo 통계 | 5분 | `todo:stats:{userId}` | Todo 완료 시 |

**캐시 처리 플로우**:
1. 조회 요청 → Redis 캐시 확인
2. Cache Hit → 캐시 데이터 반환
3. Cache Miss → DB 조회 → Redis 저장 (TTL 설정) → 데이터 반환
4. 데이터 수정 시 → DB 업데이트 → Redis 캐시 무효화

---

#### 비동기 요청-응답 (Asynchronous Request-Reply)
**적용 대상**: 장시간 실행 작업

**처리 대상 작업**:

| 작업 | 예상 시간 | 처리 방식 | 상태 조회 |
|------|----------|----------|----------|
| STT 음성 변환 | 1분 ~ 10분 | Queue + Worker | Redis 상태 폴링 |
| AI 회의록 작성 | 30초 ~ 2분 | Queue + Worker | Redis 상태 폴링 |
| AI 일정 생성 | 30초 ~ 2분 | Queue + Worker | Redis 상태 폴링 |
| 대량 회의 분석 | 5분 ~ 30분 | Queue + Worker | Redis 상태 폴링 |

**처리 플로우**:
1. Client → Service: 작업 요청
2. Service → Redis: 작업 상태 저장 (PENDING), 작업 ID 생성
3. Service → Queue: 작업 메시지 발행
4. Service → Client: 작업 ID 즉시 반환 (202 Accepted)
5. Worker: Queue에서 메시지 소비 → 처리 시작
6. Worker → Redis: 상태 업데이트 (PROCESSING)
7. Worker: 작업 완료
8. Worker → Redis: 상태 업데이트 (COMPLETED) + 결과 저장
9. Client: 5초마다 상태 폴링 (GET /tasks/{taskId})
10. Client: COMPLETED 확인 → 결과 획득

**작업 상태**:
- `PENDING`: 대기 중
- `PROCESSING`: 처리 중
- `COMPLETED`: 완료
- `FAILED`: 실패

---

## 3. 주요 사용자 플로우

### 3.1 회의 예약 및 시작 플로우

```
[사용자] → [Web App] → [API Gateway] → [Meeting Service]
                                            ↓
                                      회의 생성 (DB 저장)
                                            ↓
                                      MeetingCreated 이벤트 발행
                                            ↓
                        ┌───────────────────┴───────────────────┐
                        ↓                                       ↓
                [Notification Service]                   [AI Service]
                참석자 초대 알림 발송                     회의 분석 준비
```

**단계별 처리**:
1. 사용자가 회의 정보 입력 (제목, 날짜/시간, 장소, 참석자)
2. Meeting Service: 회의 생성 및 DB 저장
3. Meeting Service: Redis 캐시 저장 (`meeting:info:{meetingId}`)
4. Meeting Service: `MeetingCreated` 이벤트 발행
5. Notification Service: 참석자 전원에게 초대 이메일 발송
6. AI Service: 회의 일정 분석 준비

---

### 3.2 회의 진행 및 회의록 작성 플로우

```
[회의 시작]
    ↓
[STT Service] → 음성 녹음 및 텍스트 변환
    ↓ (TranscriptReady 이벤트 - 5초 배치)
[AI Service] → 병렬 처리
    ├─ 회의록 내용 정리 (LLM)
    ├─ 전문용어 추출 및 설명 생성 (RAG)
    └─ 관련 자료 검색 (벡터 검색)
    ↓ (TranscriptSummaryCreated 이벤트)
[Meeting Service] → 회의록 데이터 저장 및 실시간 동기화 (WebSocket)
    ↓
[참석자들] → 정리된 회의록 확인 및 수정 (실시간 협업)
```

**단계별 처리**:
1. STT Service: 음성 녹음 시작 → 텍스트 변환 (Azure Speech)
2. STT Service: `TranscriptReady` 이벤트 발행 (5초 간격 배치)
3. AI Service (병렬 처리):
   - 회의록 내용 정리: 주제별 분류, 핵심 내용 요약
   - 전문용어 추출: 자동 감지 → 벡터 임베딩 → 맥락 기반 설명
   - 관련 자료 검색: 유사도 기반 문서 검색 (관련도 70%+)
4. AI Service: 처리 결과 저장 (AI DB) → `TranscriptSummaryCreated` 이벤트 발행
5. Meeting Service: 회의록 데이터 저장 (Meeting DB) → WebSocket으로 통합 결과 전송
6. 참석자: 정리된 회의록 확인 및 수정 (실시간 반영)

---

### 3.3 회의 종료 및 회의록 확정 플로우

```
[회의 종료 버튼 클릭]
    ↓
[Meeting Service] → MeetingEnded 이벤트 발행
    ↓
┌───┴───┬───────┬────────┐
↓       ↓       ↓        ↓
STT     AI      Notify   Meeting
음성    Todo    종료     Todo
종료    추출    알림     생성
```

**단계별 처리**:
1. Meeting Service: 회의 종료 처리 (종료 시간 기록, 통계 생성)
2. Meeting Service: `MeetingEnded` 이벤트 발행
3. **STT Service** (구독):
   - 음성 녹음 중지
   - 최종 STT 변환 완료 확인
4. **AI Service** (구독):
   - 최종 회의록 분석
   - Todo 자동 추출 및 담당자 식별
   - 추출된 Todo 정보를 Meeting Service에 전송
5. **Meeting Service**:
   - Todo 생성 및 할당 (내부 처리)
   - 회의록 섹션 링크 연결
   - `TodoCreated` 이벤트 발행
   - 섹션별 검증 완료 처리 (내부 처리)
   - 회의록 확정 (확정 버전 생성)
6. **Notification Service** (구독):
   - 회의 종료 알림 발송
   - Todo 할당 알림 발송

---

### 3.4 Todo 관리 및 회의록 반영 플로우

```
[Todo 완료 처리]
    ↓
[Meeting Service] → TodoCompleted 이벤트 발행
    ↓
Notification
완료 알림
```

**단계별 처리**:
1. 담당자: Todo 완료 버튼 클릭
2. Meeting Service: Todo 상태 업데이트 (완료 시간, 완료자 기록)
3. Meeting Service: 관련 회의록에 완료 상태 자동 반영 (내부 처리)
4. Meeting Service: Redis 캐시 무효화 (`meeting:info:{meetingId}`)
5. Meeting Service: `TodoCompleted` 이벤트 발행
6. **Notification Service** (구독):
   - 회의록 작성자에게 완료 알림 발송
   - 모든 Todo 완료 시 전체 완료 알림 발송

**차별화 포인트**:
- Todo 완료가 회의록에 즉시 반영 (동일 서비스 내 처리)
- 회의 결과 추적 용이

---

### 3.5 회의록 공유 플로우

```
[회의록 확정] → [공유 버튼 클릭]
    ↓
[Meeting Service] → 공유 링크 생성
    ↓
[Notification Service] → 참석자 알림 발송
    ↓
[Meeting Service] → 다음 회의 일정 자동 등록 (언급된 경우)
```

**단계별 처리**:
1. 회의록 작성자: 공유 대상 및 권한 설정
2. Meeting Service: 공유 링크 생성 (고유 URL)
3. Meeting Service: 공유 정보 DB 저장 (공유 시간, 대상, 권한)
4. Meeting Service: Redis 캐시 무효화
5. Notification Service: 참석자 전원에게 이메일 알림 발송
6. Meeting Service: 다음 회의 일정이 언급된 경우 캘린더 자동 등록

---

## 4. 데이터 흐름 및 캐싱 전략

### 4.1 데이터 흐름

#### 조회 플로우 (Cache-Aside)
```
Client → API Gateway → Service
                         ↓
                    Redis 캐시 조회
                         ↓
                    ┌────┴────┐
            Cache Hit       Cache Miss
                 ↓               ↓
            캐시 반환        DB 조회
                                ↓
                          Redis 저장 (TTL)
                                ↓
                           데이터 반환
```

#### 수정 플로우 (Write-Through)
```
Client → API Gateway → Service
                         ↓
                    DB 업데이트
                         ↓
                    Redis 캐시 무효화
                         ↓
                    응답 반환
```

---

### 4.2 캐싱 전략

#### 캐시 정책 요약

| 서비스 | 캐싱 대상 | TTL | 무효화 트리거 |
|--------|----------|-----|--------------|
| Meeting Service | 회의 정보 | 10분 | 회의 수정 |
| Meeting Service | 회의 참여자 | 10분 | 참여자 변경 |
| Meeting Service | 회의 템플릿 | 1시간 | 템플릿 수정 |
| Meeting Service | Todo 목록 | 5분 | Todo 상태 변경 |
| Meeting Service | Todo 통계 | 5분 | Todo 완료 |

#### 캐시 무효화 전략
- **즉시 무효화**: 데이터 변경 시 즉시 캐시 삭제
- **TTL 기반 자동 만료**: 설정된 시간 경과 후 자동 삭제
- **명시적 삭제 API**: 관리자용 캐시 삭제 API 제공

#### 캐시 Stampede 방지
- **Lock 기반 갱신**: 동시 다발적 Cache Miss 발생 시 첫 번째 요청만 DB 조회
- **Early Expiration**: TTL의 90% 시점에 백그라운드 갱신

---

### 4.3 데이터 일관성 전략

#### 서비스별 독립 DB
- 각 마이크로서비스는 자신의 데이터를 완전히 소유
- 다른 서비스의 DB에 직접 접근 금지
- 데이터 공유는 API 또는 이벤트를 통해서만 가능

#### 이벤트 기반 최종 일관성 (Eventual Consistency)
- 강한 일관성이 필요하지 않은 경우 이벤트 기반 동기화
- 예: Todo 완료 → 회의록 반영 (수 초 지연 허용)

#### 트랜잭션 경계
- 단일 서비스 내에서만 ACID 트랜잭션 보장
- 서비스 간 트랜잭션은 Saga 패턴 (필요 시 향후 적용)

---

## 5. 확장성 및 성능 고려사항

### 5.1 수평 확장 전략

#### Stateless 설계
- 모든 마이크로서비스는 Stateless로 설계
- 세션 정보는 Redis에 저장
- Pod 수 증설로 처리량 증가 가능

#### Auto Scaling 정책
```yaml
HPA (Horizontal Pod Autoscaler) 설정:
  - CPU 사용률 > 70%: Pod 증설
  - Memory 사용률 > 80%: Pod 증설
  - 최소 Pod 수: 2
  - 최대 Pod 수: 10
```

---

### 5.2 부하 분산 전략

#### Queue-Based Load Leveling
**적용 대상**: 장시간 작업, 트래픽 급증 가능 작업

| 서비스 | 큐 이름 | Worker 수 | 목적 |
|--------|---------|----------|------|
| STT Service | `stt.processing.queue` | 3-10 | 음성 변환 부하 분산 |
| AI Service | `ai.processing.queue` | 2-5 | AI 처리 부하 분산 |
| Notification Service | `notification.queue` | 3-10 | 대량 알림 발송 |

**Queue 설정**:
- Max Length: 1000-2000 메시지
- Message TTL: 1-2시간
- Consumer Concurrency: 동적 조정 (2-10)

---

### 5.3 성능 최적화

#### 캐시 우선 전략
- **목표 Cache Hit Rate**: > 70%
- **캐시 메모리 관리**: Eviction Policy (LRU)
- **Hot Key 분산**: 자주 조회되는 데이터는 캐시 TTL 증가

#### 비동기 처리
- STT 변환, AI 처리는 Queue 기반 비동기
- 사용자는 작업 ID 받고 폴링으로 결과 조회

#### 실시간 동기화 최적화
- WebSocket으로 전체 데이터 대신 델타만 전송
- 변경 영역 하이라이트 (3초간)

---

### 5.4 성능 목표

| 지표 | 목표 | 측정 방법 |
|------|------|----------|
| API 응답 시간 (P95) | < 500ms | Prometheus |
| Cache Hit Rate | > 70% | Redis Metrics |
| 회의록 생성 시간 | < 2분 | 비동기 작업 추적 |
| AI 일정 생성 시간 | < 1분 | 비동기 작업 추적 |
| 시스템 가용성 | > 99.5% | Health Check |

---

## 6. 보안 고려사항

### 6.1 인증 및 인가

#### API Gateway 계층
- **JWT 기반 인증**: 모든 API 요청에 JWT 토큰 필수
- **토큰 검증**: API Gateway에서 일괄 검증
- **Rate Limiting**: 사용자별 요청 제한 (분당 100건)

#### 서비스 계층
- **내부 서비스 간 통신**: mTLS (Mutual TLS) 적용
- **회의 참여자 권한 검증**: Meeting Service에서 권한 확인
- **회의록 수정 권한**: 작성자 및 참여자만 수정 가능

---

### 6.2 데이터 보안

#### 전송 중 암호화
- **HTTPS/TLS**: 모든 외부 통신 암호화
- **RabbitMQ TLS**: 메시지 브로커 연결 암호화

#### 저장 암호화
- **민감 정보 암호화**: 사용자 인증 정보, 비밀번호
- **회의록 접근 제어**:
  - 참석자만 조회 가능
  - 작성자만 수정 가능
  - 공유 링크 보안 (비밀번호, 유효기간)

---

### 6.3 감사 로그

#### 로깅 대상
- 모든 API 요청 (요청자, 시간, 엔드포인트)
- 회의록 수정 이력 (수정자, 수정 시간, 변경 내용)
- 보안 이벤트 (인증 실패, 권한 위반)

#### 로그 관리
- **중앙화된 로그 수집**: ELK Stack (Elasticsearch, Logstash, Kibana)
- **로그 보관 기간**: 6개월
- **로그 검색 및 분석**: Kibana 대시보드

---

## 7. 논리 아키텍처 다이어그램

논리 아키텍처 다이어그램은 별도 파일로 제공됩니다:
- **파일 경로**: `design/backend/logical/logical-architecture.mmd`
- **렌더링**: [Mermaid Live Editor](https://mermaid.live/)에서 확인 가능

### 다이어그램 주요 요소

#### 레이어 구조
1. **클라이언트 레이어**: 웹 애플리케이션
2. **API Gateway 레이어**: 단일 진입점, 인증/라우팅
3. **마이크로서비스 레이어**: 5개 독립 서비스 (User, Meeting, STT, AI, Notification)
4. **인프라 레이어**: Redis, RabbitMQ, 외부 서비스

#### 통신 방식 표현
- **실선 (→)**: 동기적 의존성 (REST API)
- **점선 (-.->)**: 캐시 조회, 외부 시스템 호출, WebSocket 연결
- **굵은 화살표 (==>)**: 이벤트 발행/구독

#### 색상 구분
- **파란색**: 클라이언트
- **노란색**: API Gateway
- **초록색**: 핵심 서비스 (User, Meeting)
- **분홍색**: 전문 서비스 (STT, AI)
- **보라색**: 지원 서비스 (Notification)
- **하늘색**: 인프라 (Redis)
- **주황색**: 메시지 브로커 (RabbitMQ)
- **회색**: 외부 서비스

---

## 8. 유저스토리 매핑

### 8.1 유저스토리 커버리지

| 유저스토리 ID | 기능 | 담당 서비스 | 상태 |
|--------------|------|-------------|------|
| AFR-USER-010 | 사용자 인증 | User Service | ✅ |
| AFR-USER-020 | 대시보드 조회 | User, Meeting, Todo Services | ✅ |
| UFR-MEET-010 | 회의 예약 | Meeting, Notification Services | ✅ |
| UFR-MEET-020 | 템플릿 선택 | Meeting Service | ✅ |
| UFR-MEET-030 | 회의 시작 | Meeting, STT Services | ✅ |
| UFR-MEET-040 | 회의 종료 | Meeting Service | ✅ |
| UFR-MEET-050 | 최종 확정 | Meeting, AI Services | ✅ |
| UFR-MEET-046 | 회의록 목록 조회 | Meeting Service | ✅ |
| UFR-MEET-047 | 회의록 상세 조회 | Meeting Service | ✅ |
| UFR-MEET-055 | 회의록 수정 | Meeting, Collaboration Services | ✅ |
| UFR-MEET-060 | 회의록 공유 | Meeting, Notification Services | ✅ |
| UFR-STT-010 | 음성 녹음 인식 | STT Service | ✅ |
| UFR-STT-020 | 텍스트 변환 | STT Service | ✅ |
| UFR-AI-010 | 회의록 자동 작성 | AI Service | ✅ |
| UFR-AI-020 | Todo 자동 추출 | AI Service | ✅ |
| UFR-AI-030 | 회의록 개선 | AI Service | ✅ |
| UFR-AI-040 | 관련 회의록 연결 | AI Service | ✅ |
| UFR-RAG-010 | 전문용어 감지 | AI Service | ✅ |
| UFR-RAG-020 | 맥락 기반 용어 설명 | AI Service | ✅ |
| UFR-COLLAB-010 | 회의록 수정 동기화 | Meeting Service | ✅ |
| UFR-COLLAB-020 | 충돌 해결 | Meeting Service | ✅ |
| UFR-COLLAB-030 | 검증 완료 | Meeting Service | ✅ |
| UFR-TODO-010 | Todo 할당 | Meeting, Notification Services | ✅ |
| UFR-TODO-030 | Todo 완료 처리 | Meeting, Notification Services | ✅ |

**커버리지**: 24/24 (100%)

---

## 9. 다음 단계

### 9.1 설계 다음 단계
1. **API 설계**: 각 서비스별 API 명세 작성 (OpenAPI 3.0)
2. **외부 시퀀스 설계**: 주요 사용자 플로우별 서비스 간 시퀀스
3. **내부 시퀀스 설계**: 각 서비스 내부 처리 흐름
4. **클래스 설계**: 엔티티, DTO, 서비스 클래스 설계
5. **데이터 설계**: 각 서비스별 데이터베이스 스키마 설계

### 9.2 구현 로드맵
1. **1단계 (Week 1-2)**: 기본 인프라 구축 (API Gateway, Health Monitoring, RabbitMQ, Redis)
2. **2단계 (Week 3-4)**: 성능 최적화 (Cache-Aside, Queue-Based Load Leveling)
3. **3단계 (Week 5-6)**: 이벤트 기반 아키텍처 (Pub-Sub, Async Request-Reply)
4. **4단계 (Week 7-8)**: 모니터링 및 안정화 (Prometheus, Grafana, 부하 테스트)

---

## 10. 참고 자료

- [유저스토리](../../userstory.md)
- [아키텍처 패턴 적용 방안](../../pattern/architecture-pattern.md)
- [클라우드 디자인 패턴 요약](../../../claude/cloud-design-patterns.md)
- [공통 설계 원칙](../../../claude/common-principles.md)

---

## 11. 문서 이력

| 버전 | 작성일 | 작성자 | 변경 내용 |
|------|--------|--------|----------|
| 1.0 | 2025-01-22 | 길동 (Architect) | 초안 작성 |

---

## 부록 A. 용어 정의

| 용어 | 정의 |
|------|------|
| **Stateless** | 서버가 클라이언트의 상태 정보를 저장하지 않는 설계 방식 |
| **Cache-Aside** | 애플리케이션이 캐시를 직접 관리하는 패턴 |
| **Pub/Sub** | Publisher-Subscriber 패턴, 이벤트 발행자와 구독자가 느슨하게 결합 |
| **Queue** | 메시지 큐, 비동기 작업 처리를 위한 메시지 저장소 |
| **TTL** | Time To Live, 캐시 데이터의 유효 시간 |
| **Async Request-Reply** | 비동기 요청-응답 패턴, 장시간 작업의 비동기 처리 |
| **WebSocket** | 양방향 실시간 통신 프로토콜 |
| **LLM** | Large Language Model, 대규모 언어 모델 |
| **RAG** | Retrieval-Augmented Generation, 검색 증강 생성 |
| **STT** | Speech-to-Text, 음성-텍스트 변환 |

---

## 부록 B. 아키텍처 결정 기록 (ADR)

### ADR-001: 마이크로서비스 아키텍처 선택
**날짜**: 2025-01-22
**상태**: 수정됨 (ADR-007로 대체)
**결정**: ~~7개~~ → **5개 마이크로서비스**로 분리
**이유**:
- 독립 배포 및 확장 가능
- 팀별 책임 명확화
- 기술 스택 다양화 가능
- 서비스 통합으로 운영 복잡도 감소 (Meeting + Collaboration + Todo)

**대안**:
- 모놀리식: 초기 개발 속도는 빠르나 확장성 제한
- 서비스 수 증가 (7개 이상): 운영 복잡도 과도

---

### ADR-002: RabbitMQ 선택
**날짜**: 2025-01-22
**상태**: 승인
**결정**: 메시지 브로커로 RabbitMQ 사용
**이유**:
- Pub/Sub 및 Queue 패턴 모두 지원
- 성숙한 기술, 안정적 운영
- Spring AMQP와 원활한 통합

**대안**:
- Apache Kafka: 고처리량이지만 운영 복잡도 높음
- AWS SQS: 클라우드 종속성 발생

---

### ADR-003: Redis 캐싱 전략
**날짜**: 2025-01-22
**상태**: 승인
**결정**: Cache-Aside 패턴 사용
**이유**:
- 애플리케이션이 캐시 제어
- 캐시 실패 시 DB 직접 조회로 복구
- 유연한 무효화 전략

**대안**:
- Write-Through: 모든 쓰기 작업에서 캐시 업데이트 필요, 성능 저하
- Read-Through: 캐시 미스 시 캐시가 DB 조회, 복잡도 증가

---

### ADR-004: RAG Service를 AI Service에 통합
**날짜**: 2025-01-22
**상태**: 승인
**결정**: RAG Service를 독립 서비스가 아닌 AI Service에 통합
**이유**:
- RAG와 AI 모두 LLM 기반 처리로 긴밀하게 연동
- 서비스 개수 감소로 운영 복잡도 감소 (8개 → 7개)
- 동일한 벡터 임베딩 모델 및 LLM 공유 가능
- 회의록 자동 작성 시 용어 설명이 필요하므로 통합이 효율적

**대안**:
- RAG 독립 서비스: 서비스 수 증가, 네트워크 호출 증가, 운영 부담

---

### ADR-005: Collaboration → Meeting 통신을 REST API로 변경
**날짜**: 2025-01-22
**상태**: 승인
**결정**: 섹션 검증 완료 시 MQ 이벤트가 아닌 REST API 동기 호출
**이유**:
- 검증 완료 상태를 Meeting Service DB에 즉시 반영 필요
- 실패 시 재시도 및 오류 처리가 명확
- 이벤트 기반보다 동기 통신이 더 적합한 사례

**대안**:
- MQ 이벤트: 비동기 처리로 인한 일관성 지연, 실패 추적 어려움

---

### ADR-006: 실시간 텍스트 표시 제거 및 AI 분석 결과 통합 전송
**날짜**: 2025-01-22
**상태**: 승인
**결정**: STT 변환 텍스트를 실시간으로 표시하지 않고, AI 분석 완료 후 통합 결과만 표시
**이유**:
- 실시간 텍스트는 정확도가 낮고 오타가 많아 사용자 혼란 유발
- AI 분석된 정리된 회의록이 더 높은 가치 제공 (주제별 분류, 요약, 전문용어 설명)
- 사용자는 정리된 회의록 + 전문용어 + 관련 자료를 통합하여 확인
- 처리 시간 단축: ~~15초~~ → **13초** (실시간 텍스트 동기화 단계 제거)
- Collaboration Service의 역할 단순화: AI 분석 결과 통합 전송에 집중

**처리 흐름**:
1. STT Service: TranscriptReady 이벤트 발행 (5초 배치)
2. AI Service: 병렬 분석 (회의록 정리 + 전문용어 + 관련 자료)
3. AI Service: TranscriptSummaryCreated 이벤트 발행
4. Meeting Service: 회의록 저장 → Collaboration Service에 REST API 호출
5. Collaboration Service: WebSocket으로 통합 결과 전송

**대안**:
- 실시간 텍스트 표시 유지: 낮은 정확도, 높은 네트워크 트래픽, 사용자 혼란

---

### ADR-007: 서비스 통합 및 동기 의존성 제거
**날짜**: 2025-01-22
**상태**: 승인
**결정**: Meeting, Collaboration, Todo 서비스를 Meeting Service로 통합하고, User Service 동기 참조 제거

**이유**:
- **복잡도 감소**: 7개 → 5개 서비스로 단순화, 운영 부담 감소
- **성능 향상**: 
  - User Service 동기 호출 제거 → 네트워크 지연 제거
  - Todo/Collaboration 내부 메서드 호출 → 서비스 간 통신 오버헤드 제거
- **장애 격리**: User Service 장애가 Meeting Service에 영향 없음
- **일관성 향상**: Todo와 회의록이 동일 트랜잭션 내에서 처리 가능
- **개발 효율성**: 하나의 서비스 내에서 회의록, Todo, 실시간 협업 기능 통합 개발

**변경 사항**:
1. **Meeting Service 통합**:
   - Collaboration 기능 통합: WebSocket, 버전 관리, 충돌 해결
   - Todo 기능 통합: Todo CRUD, 진행 상황 추적, 회의록 연동
   - 데이터베이스: Meeting DB에 Todo, TranscriptVersion, CollaborationEvent 테이블 추가

2. **User Service 역할 변경**:
   - 인증 전용: LDAP 인증, JWT 토큰 발급/검증만 담당
   - 프론트엔드 책임: 모든 API 요청에 사용자 정보(userId, userName, email) 포함
   - 동기 참조 제거: 다른 서비스는 User Service를 호출하지 않음

3. **이벤트 변경**:
   - TodoCreated, TodoCompleted 발행자: ~~Todo Service~~ → **Meeting Service**
   - TodoExtracted 제거: AI Service가 Meeting Service에 직접 Todo 정보 전송

**성능 개선**:
- User Service 동기 호출 제거: ~100ms 지연 제거
- Todo 처리: 서비스 간 통신 → 내부 메서드 호출 (10배 빠름)
- 실시간 동기화: Collaboration Service → Meeting Service REST API 제거

**트레이드오프**:
- **Risk**: 프론트엔드에서 사용자 정보 조작 가능 → JWT 토큰 검증으로 완화
- **복잡도 증가**: Meeting Service 코드 복잡도 증가 → 명확한 레이어 분리로 완화
- **확장성 제한**: Meeting Service 단일 확장 → Stateless 설계로 수평 확장 가능

**대안**:
- 서비스 분리 유지: 운영 복잡도 높음, 네트워크 지연 존재
- API Composition 패턴: 여전히 네트워크 호출 필요, 복잡도 증가