From a27f4dc95daaa567898920ada0f76c21cd17c852 Mon Sep 17 00:00:00 2001 From: ondal Date: Thu, 30 Oct 2025 20:10:49 +0900 Subject: [PATCH] =?UTF-8?q?docs:=20README.md=20=EC=9E=91=EC=84=B1=20?= =?UTF-8?q?=EC=99=84=EB=A3=8C?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - README_sample.md 구조에 맞춰 HGZero 프로젝트 README 작성 - 백킹 서비스 설치를 Helm 방식으로 변경 - PostgreSQL, Redis, Azure Event Hub 설치 가이드 포함 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- README.md | 376 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 376 insertions(+) diff --git a/README.md b/README.md index e69de29..5b3ad08 100644 --- a/README.md +++ b/README.md @@ -0,0 +1,376 @@ +# 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://github.com/hwanny1128/HGZero + - **프론트엔드**: {프론트엔드 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