shared-dg05-coffeeQuokka/hgzero
1
0
Fork 0
mirror of https://github.com/hwanny1128/HGZero.git synced 2025-12-06 16:06:23 +00:00
Code Issues Packages Projects Releases Wiki Activity
hgzero/README.md
ondal 72419c320a docs: README.md 최종 수정 
🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
2025-10-30 20:28:39 +09:00

377 lines
14 KiB
Markdown
Raw Blame History

# HGZero - AI 기반 회의록 작성 및 이력 관리 개선 서비스
## 1. 소개
HGZero는 업무지식이 부족한 회의록 작성자도 누락 없이 정확하게 회의록을 작성하여 공유할 수 있는 AI 기반 서비스입니다.
사용자는 실시간 음성 변환(STT), AI 요약, 용어 설명, Todo 자동 추출 등의 기능을 통해 회의록 작성 업무를 효율적으로 수행할 수 있습니다.
### 1.1 핵심 기능
- **실시간 STT**: Azure Speech Services 기반 실시간 음성-텍스트 변환
- **AI 요약**: 안건별 2-3문장 자동 요약 (GPT-4o, 2-5초 처리)
- **맥락 기반 용어 설명**: 관련 회의록과 업무이력 기반 실용 정보 제공
- **Todo 자동 추출**: 회의록에서 액션 아이템 자동 추출 및 배정
- **지능형 회의 진행 지원**: 회의 패턴 분석, 안건 추천, 효율성 분석
- **실시간 협업**: WebSocket 기반 실시간 회의록 편집 및 동기화
### 1.2 MVP 산출물
- **발표자료**: {발표자료 링크}
- **설계결과**:
- [유저스토리](design/userstory.md)
- [논리 아키텍처](design/backend/logical/logical-architecture.md)
- [API 설계서](design/backend/api/API설계서.md)
- **Git Repo**:
- **메인**: https://gitea.cbiz.kubepia.net/shared-dg05-coffeeQuokka/hgzero.git
- **프론트엔드**: {프론트엔드 Repository 링크}
- **manifest**: {Manifest Repository 링크}
- **시연 동영상**: {시연 동영상 링크}
## 2. 시스템 아키텍처
### 2.1 전체 구조
마이크로서비스 아키텍처 기반 클라우드 네이티브 애플리케이션
```
┌─────────────────────────────────────────────────────────────┐
│ Frontend │
│ React 18 + TypeScript │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ NGINX Ingress │
└─────────────────────────────────────────────────────────────┘
│
┌─────────────────────┼─────────────────────┐
│ │ │
┌───────────────┐ ┌───────────────┐ ┌───────────────┐
│ User Service │ │Meeting Service│ │ STT Service │
│ (Java) │ │ (Java) │ │ (Java) │
│ :8081 │ │ :8081/:8082 │ │ :8083 │
└───────────────┘ └───────────────┘ └───────────────┘
│ │ │
│ │ │
┌───────────────┐ ┌───────────────┐ ┌───────────────┐
│ AI Service │ │ RAG Service │ │Notification │
│ (Java) │ │ (Python) │ │ (Java) │
│ :8083 │ │ :8000 │ │ :8084 │
└───────────────┘ └───────────────┘ └───────────────┘
│ │
└───────────────────┤
│
┌───────────────────┐
│ Event Hub │
│ (Pub/Sub MQ) │
└───────────────────┘
│
┌─────────┼─────────┐
│ │ │
┌──────────┐ ┌────────┐ ┌─────────────┐
│PostgreSQL│ │ Redis │ │ OpenAI │
│ (6 DB) │ │ Cache │ │ │
└──────────┘ └────────┘ └─────────────┘
```
### 2.2 마이크로서비스 구성
- **User 서비스**: 사용자 인증 (LDAP, JWT) 및 프로필 관리
- **Meeting 서비스**: 회의/회의록/Todo 통합 관리, 실시간 동기화 (WebSocket)
- **STT 서비스**: 음성 스트리밍, 실시간 STT 변환 (Azure Speech Services)
- **AI 서비스**: 회의록 자동요약, Todo 추출, 안건별 AI 요약
- **RAG 서비스**: 용어집 검색, 관련자료 검색, 회의록 유사도 검색 (Python/FastAPI)
- **Notification 서비스**: 이메일 알림 (회의 시작, 회의록 확정, Todo 배정)
### 2.3 기술 스택
- **프론트엔드**: React 18, TypeScript, React Context API
- **백엔드**: Spring Boot 3.2.x, Java 17, FastAPI, Python 3.11+
- **인프라**: Azure Kubernetes Service (AKS), Azure Container Registry (ACR)
- **CI/CD**: GitHub Actions (CI), ArgoCD (CD - GitOps)
- **모니터링**: Prometheus, Grafana, Spring Boot Actuator
- **백킹 서비스**:
- **Database**: PostgreSQL 15 (Database per Service - 6개 독립 DB)
- **Message Queue**: Azure Event Hub (AMQP over TLS)
- **Cache**: Azure Redis Cache (Redis 7.x)
- **AI/ML**: Azure OpenAI (GPT-4o, text-embedding-3-large), Azure Speech Services, Azure AI Search
## 3. 백킹 서비스 설치
### 3.1 Database 설치
PostgreSQL 15 설치 (각 서비스별 독립 데이터베이스)
```bash
# Helm 저장소 추가
helm repo add bitnami https://charts.bitnami.com/bitnami
helm repo update
# User 서비스용 DB
helm install hgzero-user bitnami/postgresql \
--set global.postgresql.auth.postgresPassword=Passw0rd \
--set global.postgresql.auth.username=hgzerouser \
--set global.postgresql.auth.password=Passw0rd \
--set global.postgresql.auth.database=userdb \
--namespace hgzero
# Meeting 서비스용 DB
helm install hgzero-meeting bitnami/postgresql \
--set global.postgresql.auth.postgresPassword=Passw0rd \
--set global.postgresql.auth.username=hgzerouser \
--set global.postgresql.auth.password=Passw0rd \
--set global.postgresql.auth.database=meetingdb \
--namespace hgzero
# STT 서비스용 DB
helm install hgzero-stt bitnami/postgresql \
--set global.postgresql.auth.postgresPassword=Passw0rd \
--set global.postgresql.auth.username=hgzerouser \
--set global.postgresql.auth.password=Passw0rd \
--set global.postgresql.auth.database=sttdb \
--namespace hgzero
# AI 서비스용 DB
helm install hgzero-ai bitnami/postgresql \
--set global.postgresql.auth.postgresPassword=Passw0rd \
--set global.postgresql.auth.username=hgzerouser \
--set global.postgresql.auth.password=Passw0rd \
--set global.postgresql.auth.database=aidb \
--namespace hgzero
# RAG 서비스용 DB
helm install hgzero-rag bitnami/postgresql \
--set global.postgresql.auth.postgresPassword=Passw0rd \
--set global.postgresql.auth.username=hgzerouser \
--set global.postgresql.auth.password=Passw0rd \
--set global.postgresql.auth.database=ragdb \
--namespace hgzero
# Notification 서비스용 DB
helm install hgzero-notification bitnami/postgresql \
--set global.postgresql.auth.postgresPassword=Passw0rd \
--set global.postgresql.auth.username=hgzerouser \
--set global.postgresql.auth.password=Passw0rd \
--set global.postgresql.auth.database=notificationdb \
--namespace hgzero
```
**접속 정보 확인**:
```bash
# 각 서비스별 DB 접속 정보
# User DB: hgzero-user-postgresql.hgzero.svc.cluster.local:5432
# Meeting DB: hgzero-meeting-postgresql.hgzero.svc.cluster.local:5432
# STT DB: hgzero-stt-postgresql.hgzero.svc.cluster.local:5432
# AI DB: hgzero-ai-postgresql.hgzero.svc.cluster.local:5432
# RAG DB: hgzero-rag-postgresql.hgzero.svc.cluster.local:5432
# Notification DB: hgzero-notification-postgresql.hgzero.svc.cluster.local:5432
```
### 3.2 Cache 설치
Redis 설치
```bash
# Helm으로 Redis 설치
helm install hgzero-redis bitnami/redis \
--set auth.password=Passw0rd \
--set master.persistence.enabled=true \
--set master.persistence.size=8Gi \
--namespace hgzero
# 접속 정보 확인
export REDIS_PASSWORD=$(kubectl get secret --namespace hgzero hgzero-redis -o jsonpath="{.data.redis-password}" | base64 -d)
echo "Redis Password: $REDIS_PASSWORD"
echo "Redis Host: hgzero-redis-master.hgzero.svc.cluster.local"
echo "Redis Port: 6379"
```
**Azure Redis Cache 사용 (프로덕션)**:
```bash
# Azure Portal에서 Redis Cache 생성 후 연결 정보 사용
# 또는 Azure CLI 사용
az redis create \
--name hgzero-redis \
--resource-group your-resource-group \
--location koreacentral \
--sku Basic \
--vm-size c0
```
### 3.3 Message Queue 설치
Azure Event Hub 설정
```bash
# Azure CLI를 통한 Event Hub 생성
az eventhubs namespace create \
--name hgzero-eventhub-ns \
--resource-group your-resource-group \
--location koreacentral \
--sku Standard
az eventhubs eventhub create \
--name hgzero-events \
--namespace-name hgzero-eventhub-ns \
--resource-group your-resource-group \
--partition-count 4 \
--message-retention 7
# 연결 문자열 확인
az eventhubs namespace authorization-rule keys list \
--resource-group your-resource-group \
--namespace-name hgzero-eventhub-ns \
--name RootManageSharedAccessKey \
--query primaryConnectionString \
--output tsv
```
## 4. 빌드 및 배포
### 4.1 프론트엔드 빌드 및 배포
#### 1. 애플리케이션 빌드
```bash
cd frontend
npm install
npm run build
```
#### 2. 컨테이너 이미지 빌드
```bash
docker build \
--build-arg REACT_APP_API_URL="http://api.hgzero.com" \
--build-arg REACT_APP_WS_URL="ws://api.hgzero.com/ws" \
-f deployment/container/Dockerfile-frontend \
-t acrdigitalgarage02.azurecr.io/hgzero/frontend:latest .
```
#### 3. 이미지 푸시
```bash
docker push acrdigitalgarage02.azurecr.io/hgzero/frontend:latest
```
#### 4. Kubernetes 배포
```bash
kubectl apply -f deployment/k8s/frontend/frontend-deployment.yaml -n hgzero
```
### 4.2 백엔드 빌드 및 배포
#### 1. 애플리케이션 빌드
```bash
# 전체 프로젝트 빌드
./gradlew clean build -x test
# 또는 개별 서비스 빌드
./gradlew :user:clean :user:build -x test
./gradlew :meeting:clean :meeting:build -x test
./gradlew :stt:clean :stt:build -x test
./gradlew :ai:clean :ai:build -x test
./gradlew :notification:clean :notification:build -x test
```
#### 2. 컨테이너 이미지 빌드 (각 서비스별로 수행)
```bash
# User 서비스
docker build \
--build-arg BUILD_LIB_DIR="user/build/libs" \
--build-arg ARTIFACTORY_FILE="user.jar" \
-f deployment/container/Dockerfile-user \
-t acrdigitalgarage02.azurecr.io/hgzero/user-service:latest .
# Meeting 서비스
docker build \
--build-arg BUILD_LIB_DIR="meeting/build/libs" \
--build-arg ARTIFACTORY_FILE="meeting.jar" \
-f deployment/container/Dockerfile-meeting \
-t acrdigitalgarage02.azurecr.io/hgzero/meeting-service:latest .
# STT 서비스
docker build \
--build-arg BUILD_LIB_DIR="stt/build/libs" \
--build-arg ARTIFACTORY_FILE="stt.jar" \
-f deployment/container/Dockerfile-stt \
-t acrdigitalgarage02.azurecr.io/hgzero/stt-service:latest .
# AI 서비스
docker build \
--build-arg BUILD_LIB_DIR="ai/build/libs" \
--build-arg ARTIFACTORY_FILE="ai.jar" \
-f deployment/container/Dockerfile-ai \
-t acrdigitalgarage02.azurecr.io/hgzero/ai-service:latest .
# Notification 서비스
docker build \
--build-arg BUILD_LIB_DIR="notification/build/libs" \
--build-arg ARTIFACTORY_FILE="notification.jar" \
-f deployment/container/Dockerfile-notification \
-t acrdigitalgarage02.azurecr.io/hgzero/notification-service:latest .
```
#### 3. RAG 서비스 빌드 (Python)
```bash
docker build \
-f deployment/container/Dockerfile-rag \
-t acrdigitalgarage02.azurecr.io/hgzero/rag-service:latest \
./rag
```
#### 4. 이미지 푸시
```bash
docker push acrdigitalgarage02.azurecr.io/hgzero/user-service:latest
docker push acrdigitalgarage02.azurecr.io/hgzero/meeting-service:latest
docker push acrdigitalgarage02.azurecr.io/hgzero/stt-service:latest
docker push acrdigitalgarage02.azurecr.io/hgzero/ai-service:latest
docker push acrdigitalgarage02.azurecr.io/hgzero/rag-service:latest
docker push acrdigitalgarage02.azurecr.io/hgzero/notification-service:latest
```
#### 5. Kubernetes 배포
```bash
# Namespace 생성
kubectl create namespace hgzero
# Secret 생성 (환경 변수)
kubectl apply -f deployment/k8s/backend/secrets/ -n hgzero
# 서비스 배포
kubectl apply -f deployment/k8s/backend/user-service.yaml -n hgzero
kubectl apply -f deployment/k8s/backend/meeting-service.yaml -n hgzero
kubectl apply -f deployment/k8s/backend/stt-service.yaml -n hgzero
kubectl apply -f deployment/k8s/backend/ai-service.yaml -n hgzero
kubectl apply -f deployment/k8s/backend/rag-service.yaml -n hgzero
kubectl apply -f deployment/k8s/backend/notification-service.yaml -n hgzero
# Ingress 설정
kubectl apply -f deployment/k8s/ingress.yaml -n hgzero
```
### 4.3 테스트
#### 1) 프론트엔드 페이지 주소 구하기
```bash
# Namespace 설정
kubens hgzero
# Service 확인
kubectl get svc
# Ingress 확인
kubectl get ingress
```
#### 2) API 테스트
**Swagger UI 접근**:
- User Service: http://{INGRESS_URL}/user/swagger-ui.html
- Meeting Service: http://{INGRESS_URL}/meeting/swagger-ui.html
- STT Service: http://{INGRESS_URL}/stt/swagger-ui.html
- AI Service: http://{INGRESS_URL}/ai/swagger-ui.html
- RAG Service: http://{INGRESS_URL}/rag/docs
- Notification Service: http://{INGRESS_URL}/notification/swagger-ui.html
#### 3) 로그인 테스트
- ID: user-005, user2@example.com
- PW: 8자리
## 5. 팀
- 유동희 "야보" - Product Owner
- 조민서 "다람지" - AI Specialist
- 김주환 "블랙" - Architect
- 김종희 "페퍼" - Frontend Developer
- 문효종 "카누" - Frontend Developer / DevOps Engineer
- 전대웅 "맥심" - Backend Developer
- 조윤진 "쿼카" - Backend Developer
Reference in New Issue View Git Blame Copy Permalink