Church Pastor Mono

AI 기반 설교 콘텐츠 관리 및 검색을 위한 풀스택 애플리케이션입니다.

프로젝트 개요

Church Pastor Mono는 AI 기반 의미론적 검색을 사용하여 설교 콘텐츠를 관리하고 검색하는 애플리케이션입니다. Yarn Workspaces 모노레포로 구성되어 있습니다.

아키텍처

apps/
├── backend/     # NestJS API 서버 (TypeScript)
├── admin/       # Admin 대시보드 (Vite SPA)
├── app/         # React Native 모바일 앱 (Expo)
├── api/         # OpenAPI 클라이언트 생성 패키지
├── chat-web/    # Next.js 채팅 웹
├── ai-server/   # Python ML 서비스 (설교 처리)
├── prisma/      # Prisma schema
└── docker/      # Dockerfiles / Compose
packages/
├── typescript-config/  # 공유 TypeScript 설정
└── eslint-config/      # 공유 ESLint 규칙

데이터 흐름

1. ai-server: YouTube 비디오 다운로드, Whisper로 전사, 텍스트 청킹, 임베딩 생성
2. backend: PostgreSQL + pgvector에 설교 데이터 저장, 의미론적 검색 API 제공
3. app: 설교 콘텐츠 검색 및 조회를 위한 모바일 클라이언트

주요 기술

• 데이터베이스: PostgreSQL 16 with pgvector extension (1536차원 벡터)
• ORM: Prisma with 모듈형 스키마 (packages/prisma/prisma/models/*.prisma)
• 임베딩: OpenAI text-embedding-3-small (backend 검색용), Sentence Transformers (ai-server용)
• 인증: JWT with Passport (local + JWT strategies)

시작하기

개발 환경 설정

# 의존성 설치
yarn install

# PostgreSQL + Redis 컨테이너 시작
yarn docker:dev

Backend (NestJS)

yarn backend dev                # Watch 모드로 실행 (포트 3000)
yarn backend build              # TypeScript 컴파일
yarn backend lint               # ESLint 실행 (자동 수정)
yarn backend test               # Jest 테스트 실행
yarn backend test:watch         # Watch 모드로 테스트 실행
yarn backend test:e2e           # E2E 테스트 실행
yarn backend prisma:migrate     # 데이터베이스 마이그레이션 실행
yarn backend prisma:generate    # Prisma 클라이언트 생성
yarn backend prisma:seed        # 데이터베이스 시드

Mobile App (Expo)

yarn app start                  # Expo 개발 클라이언트 시작
yarn app android                # Android에서 실행
yarn app ios                    # iOS에서 실행
yarn app web                    # 웹 버전 실행
yarn app lint                   # ESLint 검사
yarn app storybook              # Storybook 실행 (컴포넌트 개발용)

AI Server (Python)

cd apps/ai-server
python -m venv venv && source venv/bin/activate
pip install -r requirements.txt
python main.py                  # YouTube 설교 처리 (main.py에서 URL 수정)

데이터베이스 관리

덤프 및 복원 스크립트

프로젝트 루트의 scripts/ 디렉토리에 데이터베이스 관리 스크립트가 있습니다.

데이터베이스 덤프 생성

# 데이터베이스를 SQL 덤프 파일로 내보내기
./scripts/db_dump.sh

• 덤프 파일은 scripts/dump/ 디렉토리에 저장됩니다
• 파일명 형식: churchpastor_YYYYMMDD_HHMMSS.sql.gz
• Docker 컨테이너 내부의 pg_dump를 사용하여 버전 호환성 문제를 해결합니다

데이터베이스 복원

# 가장 최신 덤프 파일로 복원
./scripts/db_store.sh

# 특정 덤프 파일로 복원
./scripts/db_store.sh churchpastor_20260124_181148.sql.gz

• 복원 전 확인 메시지가 표시됩니다
• 압축된 덤프 파일(.gz)은 자동으로 압축 해제됩니다
• Docker 컨테이너 내부의 psql을 사용하여 복원합니다

주의: 복원 작업은 기존 데이터베이스를 덮어씁니다. 중요한 데이터는 미리 백업하세요.

데이터베이스 스키마

packages/prisma/prisma/models/의 주요 모델:

• Sermon: Pastor와 연결된 주요 설교 엔티티
• SermonMedia: YouTube 비디오 메타데이터
• SermonTimeline: Whisper로 생성된 타임스탬프가 있는 음성 세그먼트
• SermonChunk: 메타데이터(요약, 주제, 키워드, 중요도)가 있는 텍스트 청크
• SermonChunkVector: 의미론적 검색을 위한 pgvector 임베딩

벡터 검색은 1536차원 임베딩에서 코사인 거리(<=> 연산자)를 사용합니다.

환경 변수

Backend (.env)

DATABASE_URL=postgresql://churchpastor:churchpastor@localhost:5432/churchpastor
SERVER_PORT=3000
SERVER_JWT_SECRET=<secret>
SERVER_OPENAI_API_KEY=<key>
SERVER_GEMINI_API_KEY=<key>
DATABASE_REDIS_HOST=localhost
DATABASE_REDIS_PORT=6379

AI Server (.env)

GOOGLE_API_KEY=<youtube-api-key>
WHISPER_MODEL=base  # base, small, medium, large

API

Backend API 접두사: /api/v1 Swagger 문서: /api/v1/docs (실행 중일 때)

빌드 및 배포

Docker 이미지 빌드

프로젝트는 멀티 스테이지 빌드를 사용하여 최적화된 Docker 이미지를 생성합니다.

빌드 스크립트 사용 (권장)

# 모든 앱 빌드 (기존 node-base 사용)
yarn build:images

# node-base 재빌드 후 모든 앱 빌드
yarn build:images --update-base
yarn build:images -u

# 특정 타겟만 빌드
yarn build:images --target admin
yarn build:images -t admin

# 여러 타겟 빌드
yarn build:images --target admin --target backend
yarn build:images -t admin -t backend

# node-base 재빌드 + 특정 타겟 빌드
yarn build:images -u -t admin -t backend

사용 가능한 타겟:

• backend - NestJS API 서버
• admin - Admin 대시보드 (Vite SPA)
• app - Web 앱 (Expo web)
• ai-server - Python ML 서비스

수동 빌드

# 1. node-base 이미지 먼저 빌드 (필수)
docker build -f apps/docker/Dockerfile.node-base -t churchpastor/node-base:latest .

# 2. 각 앱 이미지 빌드
docker build -f apps/docker/Dockerfile.backend -t churchpastor/backend:prod .
docker build -f apps/docker/Dockerfile.admin -t churchpastor/admin:prod .
docker build -f apps/docker/Dockerfile.app -t churchpastor/app:prod .
docker build -f apps/docker/Dockerfile.ai-server -t churchpastor/ai-server:prod .

프로덕션 배포

전체 스택 배포

# 1. 이미지 빌드
yarn build:images

# 2. Docker Compose로 전체 스택 시작
docker compose -f apps/docker/docker-compose.prod.yml up -d

특정 서비스만 재배포

# 특정 서비스만 재빌드 및 재시작
docker compose -f apps/docker/docker-compose.prod.yml up -d --build <서비스명>

# 예시
docker compose -f apps/docker/docker-compose.prod.yml up -d --build admin
docker compose -f apps/docker/docker-compose.prod.yml up -d --build backend
docker compose -f apps/docker/docker-compose.prod.yml up -d --build app
docker compose -f apps/docker/docker-compose.prod.yml up -d --build ai-server

# 여러 서비스 동시 재배포
docker compose -f apps/docker/docker-compose.prod.yml up -d --build admin backend

컨테이너 관리

# 컨테이너 상태 확인
docker compose -f apps/docker/docker-compose.prod.yml ps

# 특정 서비스 로그 확인
docker compose -f apps/docker/docker-compose.prod.yml logs -f <서비스명>

# 특정 서비스 재시작 (이미지 재빌드 없이)
docker compose -f apps/docker/docker-compose.prod.yml restart <서비스명>

# 전체 스택 중지
docker compose -f apps/docker/docker-compose.prod.yml down

# 전체 스택 중지 및 볼륨 제거
docker compose -f apps/docker/docker-compose.prod.yml down -v

빌드 최적화

프로젝트는 멀티 스테이지 빌드를 사용하여 빌드 시간을 최적화합니다:

1. node-base 이미지: 모든 Node.js 앱의 공통 의존성(yarn install)을 포함
2. 앱별 이미지: node-base를 베이스로 사용하여 소스 코드만 복사하고 빌드

이 구조의 장점:

• 의존성이 변경되지 않으면 node-base 레이어 재사용
• 빌드 시간 단축
• 일관된 의존성 버전 보장

환경 변수 설정

프로덕션 배포 전 각 앱의 .env.production 파일을 설정해야 합니다:

# Backend 환경 변수
apps/backend/.env.production

# Admin 환경 변수
apps/admin/.env.production

# App 환경 변수
apps/app/.env.production

# AI Server 환경 변수
apps/ai-server/.env.production

각 앱의 환경 변수 요구사항은 해당 앱의 문서를 참조하세요.