truloop Wiki

다크 모드

백엔드 전체 개요 ​

truloop 백엔드는 5개의 독립적인 서비스로 구성됩니다. 4개의 상시 서비스가 AWS ECS Fargate에서 컨테이너로 운영되고, 1개의 서버리스 서비스가 AWS Lambda로 운영됩니다.

서비스 비교 ​

항목truloop-coretruloop-media-servicetruloop-ai-servertruloop-assistanttruloop-functions
역할핵심 비즈니스 API미디어 업로드/처리AI 콘텐츠 생성AI 대화형 비서서버리스 트리거 디스패치
언어Kotlin 2.3Go 1.24Python 3.11Python 3.14Python 3.13
프레임워크Ktor 3.4net/http (표준 라이브러리)FastAPIFastAPI + pydantic-aistdlib only (Lambda)
아키텍처Hexagonal (Ports & Adapters)Handler/Service/WorkerService LayerAgent-basedSingle Handler
DBAurora PostgreSQL (Exposed ORM)-Aurora PostgreSQL (SQLAlchemy)--
캐시ElastiCache Redis (Lettuce)Redis (go-redis)Redis/ValkeyRedis-
비동기 처리Kotlin Coroutines + EventBusGoroutine Worker PoolCelery (Redis broker)asyncio + Background TasksLambda async retry (2회)
인증JWT + Internal API KeyJWT + Internal API-JWT + Sendbird WebhookBearer API Key (Core Internal)
DIKoin 4.2 (Annotations)수동 주입FastAPI DependsFastAPI Depends-
테스트Kotest 6.1, MockKGo testing (71.7% coverage)pytest (진행 중)pydantic-evals-
모니터링Sentry, MicrometerSentry, PrometheusSentry, PrometheusLogfire, SentryCloudWatch Logs
JVM/런타임Semeru OpenJ9 25 (ARM64)---Python 3.13 (Lambda)
빌드/배포Gradle + JibDocker multi-stageDocker multi-stageDocker multi-stagePulumi FileArchive

서비스 개요 ​

truloop-core ​

truloop의 핵심 비즈니스 로직을 담당하는 메인 API 서버입니다. 사용자 관리, 룹 생성/참여, 리캡(내부명: Story), 채팅 연동, 푸시 알림 등 모든 비즈니스 기능을 처리합니다. Hexagonal Architecture(Ports & Adapters)를 적용하여 도메인 로직과 외부 의존성을 분리합니다.

주요 특징:

  • 7개 Gradle 모듈로 구성된 Hexagonal Architecture
  • Koin Annotation 기반 DI로 자동 의존성 주입
  • Domain Event 시스템 (SharedFlow 기반 EventBus)
  • CQS(Command/Query Separation) 패턴의 Repository 설계

truloop-media-service ​

대용량 미디어 업로드와 비동기 처리를 전담하는 서비스입니다. 최대 2GB 파일을 스트리밍 방식으로 처리하며, 이미지/비디오의 최적화된 변환 파이프라인을 제공합니다.

주요 특징:

  • Streaming 기반 S3 multipart 업로드 (5MB 청크)
  • 동적 Worker Pool을 활용한 병렬 처리
  • 202 Accepted 패턴으로 즉각적인 클라이언트 응답
  • 이미지 WebP 변환, 비디오 H.264 압축

truloop-ai-server ​

AI 기반 콘텐츠 생성을 담당합니다. 이미지 분석, 콘텐츠 템플릿 기반 생성, 포스터 생성 등의 기능을 Celery 비동기 태스크로 처리합니다.

주요 특징:

  • Celery + Redis를 활용한 비동기 태스크 큐
  • OpenRouter를 통한 다중 LLM 프로바이더 통합
  • 콘텐츠 템플릿 기반 다국어 생성
  • SQLAlchemy 기반 PostgreSQL 연동 (truloop-core와 DB 공유)

truloop-assistant ​

AI 대화형 비서 서비스입니다. Sendbird 채팅을 통해 사용자와 대화하며, pydantic-ai Agent 패턴으로 도구(Tool)를 활용한 지능적인 응답을 생성합니다.

주요 특징:

  • pydantic-ai Agent 기반 아키텍처
  • Deferred Tool 시스템 (Human-in-the-Loop, JSON-RPC 2.0)
  • Sendbird Webhook 통합
  • RAG (Retrieval-Augmented Generation) 지원
  • 다중 봇 페르소나 지원

truloop-functions ​

서버리스 Lambda 함수 레포지토리입니다. EventBridge Scheduler가 호출하는 Lambda 함수가 truloop-core Internal API에서 트리거 대상을 조회하고, SQS를 통해 소비자 서비스로 이벤트를 라우팅합니다.

주요 특징:

  • Python 3.13 표준 라이브러리만 사용 (외부 의존성 없음)
  • EventBridge → Core API → SQS 디스패치 파이프라인
  • 트리거 타입별 SQS 큐 라우팅 (현재 truloop-assistant 대상)
  • 커서 기반 페이지네이션으로 대량 대상 처리
  • Pulumi IaC (TypeScript)로 인프라 관리

서비스 간 통신 ​

API 경로 규칙 ​

서비스Base Path예시
truloop-core/core/core/api/v1/users, /core/api/v3/loops
truloop-media-service/media/media/api/v1/upload
truloop-ai-server/ai/ai/api/content-generation
truloop-assistant/assistant/assistant/api/v1/agent/tool-message

모든 서비스는 ALB 뒤에서 Base Path 기반으로 라우팅됩니다.

변경 이력 ​

날짜내용
2026-03-11truloop-core JVM 런타임 행 추가 (Semeru OpenJ9 25, ARM64 Graviton), truloop-functions 서비스 추가 (서비스 비교표, 개요, 통신 다이어그램)
2026-03-10ai-server Python 버전 명시 (3.x → 3.11), 빌드 방식 수정 (Docker → Docker multi-stage)