mirror of
https://github.com/hwanny1128/HGZero.git
synced 2025-12-06 11:26:25 +00:00
docs: README.md 작성 완료
- README_sample.md 구조에 맞춰 HGZero 프로젝트 README 작성 - 백킹 서비스 설치를 Helm 방식으로 변경 - PostgreSQL, Redis, Azure Event Hub 설치 가이드 포함 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
ondal
parent
b8942c9e04
commit
a27f4dc95d
376
README.md
376
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
|
||||
Loading…
x
Reference in New Issue
Block a user