ACT – Server
채팅 기반 AI 업무관리 플랫폼의 백엔드 시스템 — NestJS + TypeScript + PostgreSQL
프로젝트 개요
ACT Server는 iOS/Android 클라이언트를 위한 엔터프라이즈급 백엔드 시스템입니다. NestJS v11 + TypeScript를 기반으로, 32개의 API 모듈, 실시간 WebSocket 통신, 멀티모델 AI 파이프라인, 비동기 작업 큐를 갖춘 대규모 모놀리식 서비스 아키텍처입니다.
Bun 런타임 위에서 동작하며, PostgreSQL + pgvector를 데이터 레이어로, Redis를 캐시 및 작업 큐로 활용합니다. 클라이언트의 모든 채팅, 태스크, 노트, AI 기능의 서버 측 로직이 이 프로젝트에 구현되어 있습니다.
1. 시스템 아키텍처
NestJS의 모듈 시스템과 의존성 주입(DI)을 활용한 계층형 아키텍처를 적용했습니다. Controller → Service → Repository(TypeORM) 패턴으로, 각 도메인이 독립적인 모듈로 분리되어 있습니다.
32개 API 모듈
| 영역 | 모듈 |
|---|---|
| 핵심 | Auth, Users, Devices, Products, Subscriptions |
| 커뮤니케이션 | Channels, ChannelUsers, Messages, Mentions |
| 콘텐츠 | Notes, NoteAttachments, NoteHistories, VoiceMemos, VoiceMemoHistories |
| 태스크 | Tasks, TaskEvents, RecommendedTasks |
| 유틸리티 | Favorites, InviteLinks, ReadMessages, AddressBooks, Roles, UserRoles, RecordItems |
| AI | AiService (중앙 허브) |
| 로그 | AppLogs, SubscriptionNotificationLogs |
| 실시간 | VoiceRooms, Realtime Gateway |
미들웨어 & 인터셉터 체인
모든 HTTP 요청은 다음 파이프라인을 거칩니다:
- LoggingMiddleware — 요청 메서드, URL, 파라미터 로깅
- ClsMiddleware — nestjs-cls 기반 요청 컨텍스트 격리 (멀티테넌시 지원)
- AuthGuard — JWT 토큰 검증, 사용자 컨텍스트 추출
- ValidationPipe — DTO 기반 요청 데이터 검증
- ResponseInterceptor — 표준 응답 포맷 래핑, camelCase 변환
- ErrorsInterceptor — PostgreSQL 에러 코드 → HTTP 상태 코드 매핑
2. 데이터 레이어
PostgreSQL + pgvector
PostgreSQL을 주 데이터베이스로 사용하며, pgvector 확장을 통해 AI 벡터 검색(RAG)을 지원합니다. TypeORM을 ORM으로 활용하고, Master-Slave 레플리케이션과 커넥션 풀링(10~12 connections)을 지원합니다.
멀티 데이터소스를 지원합니다:
- 기본 PostgreSQL — 직접 설치형, 완전한 제어 가능
- Supabase — PostgreSQL 호환, 환경변수 전환으로 선택 가능
엔티티와 마이그레이션이 데이터소스별로 분리되어 있어, 설치 환경에 따라 유연하게 전환할 수 있습니다.
Redis
Bull 작업 큐의 영속 스토어, Refresh Token 저장소, 캐시 레이어로 활용합니다. 프로덕션 환경에서는 TLS를 활성화합니다.
AWS S3
모든 파일(노트 첨부, 인포그래픽, PPT, 보이스 메모 녹음)을 S3에 저장합니다. Cognito Identity Pool 기반의 임시 자격증명과 Presigned URL(1시간 만료)로 보안을 유지합니다.
주요 엔티티
| 엔티티 | 역할 |
|---|---|
| User / AuthUser | 사용자 인증 및 프로필 |
| Channel | 대화방 (AI / GENERAL 타입) |
| Message | 채팅 메시지, 첨부파일, 시스템 이벤트 |
| Task / TaskEvent | 할일 관리, 리마인더, 상태 추적, 감사 로그 |
| Note / NoteAttachment | 노트 (AI/일반), 첨부파일, 버전 이력 |
| VoiceMemo | 음성 메모, STT 변환, 요약 |
| RecordItem | Note/VoiceMemo 공통 베이스 (상태, 인포그래픽/PPT 생성 추적) |
| Subscription / UserGenaiUsage | 구독 관리, AI 월간 사용량 추적 |
| VoiceRoom | 실시간 음성 통화 방 |
3. 실시간 이벤트 아키텍처 (Socket.IO)
Socket.IO WebSocket Gateway를 통해 10종 이상의 실시간 이벤트 스트림을 제공합니다. 클라이언트는 리소스별 Room에 구독(subscribe)하고, 서버 측 서비스가 DB 변경 후 이벤트를 emit합니다. TypeORM Subscriber를 통한 변경 컬럼 감지와 INSERT/UPDATE/DELETE 이벤트 분류를 자동으로 수행합니다.
| 이벤트 스트림 | 용도 |
|---|---|
| messageStream | 새 메시지, 수정, 삭제 |
| taskStream | 태스크 상태 변경, 생성 |
| noteStream | 노트 생성, 수정 |
| voiceMemoStream | 보이스 메모 업데이트 |
| voiceRoomStream | 음성 통화 방 참여/퇴장 |
| attachmentStream | 첨부파일 업로드 완료 |
| recommendedTaskStream | AI 추천 태스크 |
| subscriptionStream | 구독 상태 변경 |
| channelUserStream | 채널 멤버 변경 |
| channelListStream | 채널 목록 변경 |
4. AI 처리 파이프라인
ACT Server의 AI 기능은 Bull Queue 기반의 비동기 작업 큐로 처리됩니다. API 엔드포인트가 작업을 큐에 넣고 즉시 응답하며, AI Processor가 백그라운드에서 처리한 뒤 WebSocket으로 결과를 클라이언트에 전달합니다.
멀티모델 AI 통합
| AI 모델 | 용도 |
|---|---|
| OpenAI GPT-4/3.5 | 텍스트 요약, 태스크 추천, 채팅 응답, RAG 질의 |
| OpenAI Whisper | 음성 → 텍스트 변환 (STT) |
| Google Gemini | 인포그래픽 레이아웃 설계, 시각화 |
| Eleven Labs | 텍스트 → 음성 변환 (TTS) |
| LangChain + pgvector | RAG 오케스트레이션, 벡터 유사도 검색, 문서 임베딩 |
| Ollama | 온프레미스 추론 서버 (선택적) |
AI 작업 유형
- audio-transcriptions — 음성 파일(S3) → Whisper STT → GPT 요약(문체/간결도 조절) → 노트 저장 → 클라이언트 알림
- generate-infographic — 노트/보이스메모 → Gemini 레이아웃 → SVG 생성 → PNG 렌더 → S3 업로드 → 알림
- generate-ppt — 노트 콘텐츠 → GPT 아웃라인 → PPTX 빌드 → S3 업로드 → 알림
- handle-gpt-chat (RAG) — 사용자 질의 → pgvector 벡터 검색 → LangChain 컨텍스트 구성 → GPT 응답 스트리밍
- generate-ai-note — 오디오 전사 + 요약의 통합 파이프라인
- add/remove-documents — RAG 문서 인덱싱, @Cron 12시간 주기 자동 갱신
AI 쿼터 관리
UserGenaiUsage 테이블을 통해 사용자별 월간 AI 사용량을 추적합니다. 비용이 발생하는 AI 작업 실행 전 assertGenaiQuota()로 잔여 크레딧을 검증하며, 구독 시작일 + 1개월 주기로 자동 리셋됩니다.
5. 인증 시스템
- JWT 기반 인증 — Access Token(1시간) + Refresh Token(7일, Redis 저장)
- 디바이스 추적 — Refresh Token에 userId:osType:deviceToken 키로 디바이스별 세션 관리
- 3종 소셜 로그인 — Email/Password (bcryptjs 해싱), Google OAuth2, Apple Sign-In
- 이메일 인증 — SMTP 기반 인증 토큰 발송, AuthGuard에서 이메일 확인 상태 검증
- @Public() 데코레이터 — 인증 불필요 엔드포인트 선언
6. 구독 & 결제 시스템
- Apple StoreKit — iOS 인앱 구매, 서버 간 웹훅 수신 및 서명 검증
- Google Play Billing — Android 인앱 구매
- 구독 생명주기 — ACTIVE → CANCELED → EXPIRED → PENDING_RENEWAL 상태 관리
- 크레딧 시스템 — 구독 티어별 aiMinute, genaiLimit 할당
- 알림 로그 — SubscriptionNotificationLog로 모든 결제 이벤트 감사 추적
7. 작업 큐 & 백그라운드 처리
| 큐 | 용도 |
|---|---|
| ai-service-queue | 모든 AI 작업 (STT, 요약, 인포그래픽, PPT, RAG, 문서 인덱싱) |
| task-queue | 태스크 리마인더, 스케줄 작업 |
| common-queue | 하우스키핑 (6개월 이상 소프트 삭제 레코드 정리) |
Bull Board 대시보드(/bull-board)를 통해 큐 상태, 작업 이력, 실패 작업을 실시간으로 모니터링할 수 있습니다.
8. CI/CD & 배포
- GitLab CI/CD — Test → Integration Test → E2E Test → Build → Deploy 파이프라인
- Docker — 멀티스테이지 빌드 (oven/bun:1-debian 기반)
- 개발 서버 — Synology NAS, Docker Compose (PostgreSQL + pgvector, Redis, NestJS, Autoheal)
- 프로덕션 — AWS ECS (Fargate), ECR 레지스트리, 자동 마이그레이션
- 테스트 — Jest 단위/통합/E2E 테스트, 실제 AI API 호출 E2E 테스트 (수동 트리거)
기술 스택 요약
| 구분 | 기술 |
|---|---|
| 런타임 | Bun + Node.js |
| 프레임워크 | NestJS v11 (TypeScript 5.9) |
| 아키텍처 | Layered Monolith + CQRS (Queue) + Event-Driven |
| 데이터베이스 | PostgreSQL + pgvector (TypeORM, Master-Slave Replication) |
| 캐시/큐 | Redis + Bull Queue (3개 큐, Bull Board) |
| 실시간 | Socket.IO WebSocket Gateway (10+ Event Streams) |
| AI 모델 | OpenAI GPT, Whisper, Google Gemini, Eleven Labs, Ollama |
| RAG | LangChain + pgvector (벡터 유사도 검색, 문서 임베딩) |
| 인증 | JWT + bcryptjs + Google OAuth2 + Apple Sign-In |
| 파일 저장 | AWS S3 + Cognito (Presigned URL) |
| 음성 통화 | Twilio WebRTC + Mediasoup |
| 푸시 알림 | Firebase Cloud Messaging + Apple Push Notification (VoIP) |
| 결제 | Apple StoreKit + Google Play Billing (서버 웹훅) |
| ORM | TypeORM (마이그레이션, 멀티 데이터소스, Soft Delete) |
| 다국어 | 한국어, 영어, 일본어 |
| 컨테이너 | Docker (멀티스테이지 빌드) |
| CI/CD | GitLab CI → AWS ECR/ECS (Fargate) |
| 모니터링 | Bull Board (큐), Logging Middleware |
이 프로젝트가 보여주는 우리의 역량
ACT Server 개발을 통해 다음과 같은 기술적 역량을 확보하고 있습니다.
- 엔터프라이즈급 NestJS 서버 설계 — 32개 API 모듈, 계층형 아키텍처, 의존성 주입, 글로벌 미들웨어/인터셉터 체인을 갖춘 대규모 NestJS 백엔드를 설계하고 운영할 수 있습니다.
- 멀티모델 AI 파이프라인 — OpenAI, Gemini, Whisper, Eleven Labs, LangChain, Ollama 등 6종의 AI 모델을 Bull Queue 기반 비동기 파이프라인으로 통합하고, 쿼터 관리까지 포함한 상용 수준의 AI 백엔드를 구축할 수 있습니다.
- RAG 시스템 구현 — pgvector 벡터 데이터베이스와 LangChain을 활용한 문서 임베딩, 유사도 검색, 컨텍스트 기반 AI 응답 시스템을 구현할 수 있습니다.
- 실시간 WebSocket 아키텍처 — Socket.IO 기반 10종 이상의 이벤트 스트림, Room 기반 구독 시스템, TypeORM Subscriber 연동 변경 감지를 구현할 수 있습니다.
- 자체 채팅 엔진 서버 — mintChatEngine의 서버 측 구현으로, 메시지 송수신, 읽음 확인, 채널 관리, 멤버십, 실시간 동기화를 포함한 완전한 채팅 백엔드를 구축할 수 있습니다.
- 멀티 데이터소스 지원 — PostgreSQL 직접 설치형과 Supabase 호환형을 환경변수 전환으로 선택할 수 있는 유연한 데이터 레이어를 설계할 수 있습니다.
- 인앱 결제 서버 — Apple StoreKit, Google Play Billing의 서버 간 웹훅을 처리하고, 구독 생명주기와 크레딧 기반 과금 체계를 서버에서 관리할 수 있습니다.
- 프로덕션 배포 파이프라인 — GitLab CI/CD → Docker → AWS ECS(Fargate) 자동 배포와, 단위/통합/E2E 테스트를 포함한 완전한 배포 파이프라인을 구축할 수 있습니다.
실시간 협업 백엔드, AI 통합 서버, 채팅 엔진, SaaS 과금 시스템 등 유사한 프로젝트를 수행하고자 합니다. 관련 과제가 있으시면 언제든 연락 주세요.