Core (Ktor) 개요

truloop-core는 truloop의 핵심 비즈니스 로직을 담당하는 메인 API 서버입니다. Hexagonal Architecture를 적용하여 도메인 로직과 인프라 의존성을 철저히 분리합니다.

---

기술 스택

항목	기술	버전
언어	Kotlin	2.3.20-RC2
JDK	Amazon Corretto	21
빌드 도구	Gradle	9.4
웹 프레임워크	Ktor (Netty)	3.4.1
직렬화	kotlinx-serialization	-
비동기	kotlinx-coroutines	-
ORM	Exposed	0.61.0
Connection Pool	HikariCP	7.0.2
DI	Koin + Koin Annotations	4.2.0-RC1
테스트	Kotest + MockK	6.1.4 / 1.14.9
정적 분석	Detekt, Ktlint	1.23.8, 14.0.1
커버리지	Kover	-
컨테이너화	Jib	-
에러 추적	Sentry	-
메트릭	Micrometer	-
로깅	Logback + Logstash	-
API 문서	ktor-openapi + ktor-swagger-ui	-

---

주요 외부 연동

서비스	용도
AWS S3	파일 저장소
AWS SQS	미디어 이벤트 큐 (업로드/완료), 리캡 생성 큐
AWS SNS	SMS 발송 (국제)
AWS Pinpoint SMS Voice V2	SMS 발송 (EUM 풀 기반)
AWS Rekognition	얼굴 인식/매칭 (선택적)
Firebase FCM	푸시 알림 발송
Sendbird	채팅 채널/메시지 관리
Redis (Lettuce)	캐싱, LiveActivity 토큰, 추천 캐시 (선택적)
RevenueCat	구독/가상화폐 관리 (선택적)
Branch	딥링크 생성
Segment	이벤트 분석 (선택적)
NHN SMS	문자 발송 (한국 국내)

---

개발 명령어

# 테스트 실행
./gradlew test

# 코드 포맷 및 정적 분석
./gradlew ktlintFormat ktlintCheck detekt

# 로컬 실행 (DB 터널 필요)
./gradlew :bootstrap:run

# Fat JAR 빌드
./gradlew :bootstrap:buildFatJar

# Docker 이미지 빌드
./gradlew :bootstrap:jibDockerBuild    # 로컬 데몬
./gradlew :bootstrap:jib               # 배포용

# 커버리지 리포트
./gradlew koverHtmlReport

---

패키지 네임스페이스

모든 코드는 co.butbeautiful.truloop.* 패키지 하위에 위치합니다.

co.butbeautiful.truloop.
├── common/              # :common 모듈
├── domain/              # :domain 모듈
├── application/         # :application 모듈
├── adapter/
│   ├── persistence/     # :adapter:persistence 모듈
│   ├── external/        # :adapter:external 모듈
│   └── web/             # :adapter:web 모듈
└── bootstrap/           # :bootstrap 모듈

---

Git Workflow

Trunk-Based Development를 따릅니다.

• Trunk: main (단일 진실 공급원)
• Feature 브랜치: 단기 수명 (목표: 1-2일)
• 네이밍: feat/BKD-XXX/description, fix/BKD-XXX/description
• Dev 배포: main push 시 자동 배포
• Prod 배포: GitHub Actions workflow_dispatch (수동)

---

변경 이력

날짜	내용
2026-03-12	기술 스택에 ktor-openapi + ktor-swagger-ui 추가
2026-03-10	기술 스택 버전 업데이트 (Kotlin 2.3.20-RC2, Gradle 9.4, Ktor 3.4.1 등), 외부 연동 서비스 목록 보강 (Rekognition, Pinpoint, SNS 등)