Bluetape4k 생태계 한눈에 보기

Bluetape4k는 하나의 거대한 framework가 아니라, Spring Boot 4와 Ktor 3 서비스가 필요한 경계부터 골라 붙일 수 있는 Kotlin/JVM backend module 생태계입니다.

Bluetape4k를 처음 보면 저장소가 많다. projects, exposed, aws, image, text, leader, javers, graph, dependencies가 따로 있고, 각 저장소 안에도 여러 module이 있다. 그래서 첫 글은 “무엇을 어디서부터 읽어야 하는가”를 위한 지도에 가깝게 쓰는 편이 낫다.

핵심 구조는 단순하다. Spring Boot 4나 Ktor 3가 application boundary를 맡고, Bluetape4k는 그 아래의 domain capability, data, infrastructure, foundation layer를 채운다. 서비스가 모든 module을 가져오는 방식이 아니라, 필요한 경계에 맞춰 작게 고르는 방식이다.

전체 Layer Map

Layer	역할	대표 저장소와 module
Application	Spring Boot 4, Ktor 3 application boundary	spring-boot/*, *-ktor, examples
Domain Capability	서비스 도메인에 가까운 기능 묶음	Leader, JaVers, Image, Text, Graph
Data	JDBC, R2DBC, Exposed, document/wide-column database helper	Exposed, data/*, GraphDB adapter
Infrastructure	cloud, messaging, cache, observability, resilience	AWS, Kafka, NATS, Redis, Micrometer, OpenTelemetry, Resilience4j
Foundation	Kotlin/JVM 공통 기반	core, coroutines, logging, testing, BOM

이 표는 dependency graph라기보다 읽는 순서다. 처음에는 foundation을 보고, 서비스가 실제로 만나는 boundary에 따라 data, infrastructure, domain capability를 고르면 된다.

Application Layer

Application layer는 Spring Boot 4나 Ktor 3가 담당한다. Bluetape4k는 application framework를 대체하려고 하지 않는다. 대신 framework 안에서 반복되는 auto-configuration, coroutine data access, Redis/cache, cloud integration, 예제 구성을 제공한다.

Spring Boot 4

개발 목적은 Spring Boot 4 application에서 Bluetape4k data, cache, infrastructure, testing module을 자연스럽게 연결하는 것이다.

주요 module은 다음과 같다.

• spring-boot/core: Spring Boot auto-configuration과 공통 property binding
• spring-boot/r2dbc: R2DBC 기반 coroutine data access integration
• spring-boot/redis: Redis/Lettuce 기반 application cache와 Redis integration
• spring-boot/mongodb, spring-boot/cassandra: document/wide-column database integration
• spring-boot/hibernate-lettuce: Hibernate second-level cache와 Lettuce cache integration

대표 기능은 coroutine, R2DBC, Redis, MongoDB, Cassandra 같은 service boundary를 Spring Boot 안에서 일관되게 연결하는 것이다. application이 framework wiring을 반복해서 직접 쓰지 않도록 돕는다.

Ktor 3

Ktor 쪽은 suspend API와 coroutine client를 중심으로 한 application boundary를 맡는다. Spring Boot보다 가벼운 runtime을 원하는 서비스가 AWS, leader election, graph database 같은 기능을 붙일 때 쓴다.

주요 module은 다음과 같다.

• aws-ktor: Ktor service에서 AWS SDK helper를 쓰기 위한 integration
• leader-ktor: Ktor application에서 leader election을 연결하는 integration
• graph-ktor: graph database 기능을 Ktor boundary에 연결하는 integration
• examples/aws-ktor-*: AWS, leader election, graph database 기능을 함께 보여주는 예제

Ktor 3 module은 “framework를 새로 만든다”기보다, Ktor service 안에서 Bluetape4k module을 쓰는 adoption path를 제공한다.

Domain Capability Layer

Domain capability layer는 서비스 도메인에 가까운 기능을 맡는다. leader election, audit trail, image processing, text processing, graph database처럼 foundation utility만으로 설명하기 어려운 영역이다.

Leader

Leader module의 목적은 분산 환경에서 batch, scheduler, polling worker, migration gate 같은 작업을 안전하게 한 노드 또는 일부 노드에 맡기는 것이다.

주요 module은 다음과 같다.

• leader-core: leader election API와 execution model
• leader-redis-lettuce, leader-redis-redisson: Redis 기반 backend
• leader-hazelcast, leader-mongodb, leader-zookeeper: 다양한 distributed backend
• leader-exposed-jdbc, leader-exposed-r2dbc: database-backed backend
• leader-spring-boot, leader-ktor: application framework integration

대표 기능은 runIfLeader() API, blocking/CompletableFuture/coroutine/Virtual Threads 실행 모델, LeaderGroupElector 기반 multi-leader 처리다. 단일 leader만 필요한 작업부터 여러 worker를 제한적으로 선발해야 하는 작업까지 다룬다.

JaVers

JaVers module은 aggregate와 domain object의 변경 이력을 저장하고 조회하는 audit trail 영역을 맡는다.

주요 module은 다음과 같다.

• javers-core: JaVers helper, codec, cache-backed repository support
• javers-persistence-redis: Redis Lettuce/Redisson 기반 snapshot storage
• javers-persistence-kafka: Kafka event-stream 기반 persistence
• bom: JaVers 관련 dependency version alignment

대표 기능은 aggregate/domain object 단위 변경 이력, Redis 또는 Kafka 기반 audit trail 저장소, DDD 모델에서 diff/snapshot/history를 조회하는 기능이다.

Image

Image module은 일반적인 JVM image processing과 libvips 기반 대량 처리를 같은 생태계 안에서 선택할 수 있게 한다.

주요 module은 다음과 같다.

• images: Scrimage 기반 pure JVM image processing
• images-vips-api: libvips abstraction과 공통 API
• images-vips-java21: Java 21 JVips/JNI backend
• images-vips-java25: Java 25 FFM/Panama backend
• images-spring-boot, images-benchmark: Spring Boot integration과 benchmark

대표 기능은 resize, crop, filter, encode, batch processing이다. 일반적인 image 작업은 pure JVM으로 시작하고, 대량 thumbnail/resize pipeline은 libvips backend로 옮길 수 있다.

Text

Text module은 한국어/일본어 중심 tokenizer, language detection, keyword search를 Kotlin service에서 재사용할 수 있게 한다.

주요 module은 다음과 같다.

• tokenizer-core: tokenizer 공통 request/response model과 dictionary utility
• tokenizer-korean: 한국어 normalization, POS tokenization, phrase extraction
• tokenizer-japanese: Kuromoji IPAdic 기반 일본어 tokenization
• lingua: Lingua 기반 language detection
• text-search: Aho-Corasick search, replacement, word filtering

대표 기능은 한국어/일본어 텍스트 분석, 다국어 language detection, 금칙어/키워드 검색, replacement pipeline 구성이다.

Data Layer

Data layer는 persistence와 database integration을 맡는다. Exposed DSL, JDBC/R2DBC repository, document database helper, graph database adapter가 여기에 들어간다.

Exposed

Exposed module은 JPA 스타일보다 Kotlin DSL에 가까운 persistence model을 제공하고, JDBC와 R2DBC를 같은 repository pattern으로 다루기 위한 module이다.

주요 module은 다음과 같다.

• exposed-core: 공통 repository, query helper, DSL support
• exposed-jdbc, exposed-r2dbc: JDBC/R2DBC adapter
• cache, JSON, encryption, dialect extension 관련 module
• Spring Boot JDBC/R2DBC integration

대표 기능은 type-safe SQL 작성, JDBC repository와 R2DBC coroutine repository, CTE/recursive CTE/batch/ measured query helper, JSON column, encrypted column, database-specific extension이다.

GraphDB

GraphDB module은 graph database별 API 차이를 줄이고, graph 비중이 큰 서비스를 공통 API로 다루기 위한 영역이다.

주요 module은 다음과 같다.

• graph-core: graph model, repository abstraction, blocking/coroutine API
• graph-neo4j, graph-memgraph, graph-age, graph-tinkerpop, graph-falkordb: database adapter
• graph-io/core, graph-io/csv, graph-io/graphml, graph-io/jackson2, graph-io/jackson3, graph-io/okio: import/export와 serialization
• graph-spring-boot, graph-ktor: application framework integration
• examples/*-graph-examples: code graph, knowledge graph, fraud detection, recommendation 예제

대표 기능은 Neo4j, Memgraph, AGE, TinkerGraph, FalkorDB를 공통 API로 접근하고, node/edge batch insert, merge/upsert, schema/index management, transaction block, weighted path, graph algorithm 작업을 지원하는 것이다. CSV, NDJSON, GraphML, OkIO stream 기반 bulk I/O도 제공한다.

General Data Modules

Exposed나 GraphDB 외에도 서비스에서 자주 쓰는 data access helper가 있다.

• data/hibernate: Hibernate 기반 persistence utility
• data/r2dbc: R2DBC 공통 helper
• data/jdbc: JDBC 기반 data access utility
• data/mongodb: MongoDB integration helper
• data/cassandra: Cassandra integration helper

이 module들은 relational, document, wide-column database를 사용할 때 반복되는 repository, transaction, serialization, Spring Boot data integration 패턴을 줄여 준다.

Infrastructure Layer

Infrastructure layer는 cloud, messaging, cache, observability, resilience처럼 application 운영 경계와 가까운 기능을 맡는다.

AWS

AWS module은 AWS Java SDK v2와 AWS Kotlin SDK를 서비스 코드에서 쓰기 쉽게 감싼다.

주요 module은 다음과 같다.

• aws: AWS Java SDK v2 helper
• aws-kotlin: AWS Kotlin SDK coroutine-first helper
• aws-spring-boot: Spring Boot 4 integration
• aws-ktor: Ktor 3 integration
• examples/aws-*: S3, DynamoDB, SQS, LocalStack/FLOCI 예제

대표 기능은 S3, DynamoDB, SQS 같은 AWS service를 coroutine 친화적으로 쓰고, local integration test를 LocalStack/FLOCI 기반으로 구성하는 것이다.

Messaging

Messaging module은 event pipeline과 async integration에서 반복되는 설정을 줄인다.

• infra/kafka, infra/kafka4: Kafka client integration
• infra/kafka-logback: application logging을 Kafka event pipeline으로 연결
• infra/nats: NATS messaging integration
• infra/pulsar: Pulsar messaging integration

대표 기능은 Kafka/NATS/Pulsar 기반 messaging client 구성과 application logging/event pipeline integration이다.

Cache and Redis

Cache와 Redis module은 local cache, distributed cache, Redis client integration을 맡는다.

• infra/redis, infra/lettuce, infra/redisson: Redis client와 distributed primitive
• cache/cache-core: 공통 cache abstraction
• cache/cache-lettuce, cache/cache-redisson: Redis 기반 cache backend
• cache/cache-hazelcast: Hazelcast distributed cache backend
• cache/hibernate-cache-lettuce: Hibernate second-level cache integration

대표 기능은 Caffeine/local cache와 Redis/Hazelcast distributed cache를 함께 쓰는 구조, repository cache, Hibernate cache, application cache, near-cache와 2-tier cache 구성이다.

Observability and Resilience

운영 환경에서는 metrics, tracing, resilience, rate limiting이 필요하다.

• infra/micrometer: Micrometer metrics integration
• infra/opentelemetry: OpenTelemetry tracing
• infra/resilience4j: retry, circuit breaker, rate limiter integration
• infra/bucket4j: rate limiting support
• utils/measured: 측정과 logging helper

이 module들은 application 코드 곳곳에 metric/tracing/retry boilerplate를 흩뿌리지 않고, 공통 패턴으로 운영 관측성과 회복성을 붙일 수 있게 한다.

Foundation Layer

Foundation layer는 거의 모든 module이 기대는 Kotlin/JVM 공통 기반이다.

Core and Utilities

• bluetape4k/core: guard, validation, extension, common type
• bluetape4k/annotations: API maturity opt-in annotation
• bluetape4k/logging: Kotlin-friendly logging
• utils/*: 자주 쓰는 utility module

상위 module이 공유하는 공통 type과 utility를 제공한다. service code가 같은 validation, logging, extension 패턴을 반복해서 새로 만들지 않게 하는 역할이다.

Coroutines and Virtual Threads

Coroutine과 Virtual Threads module은 Kotlin coroutine과 Java Virtual Threads 사이의 실행 모델을 다룬다.

• bluetape4k/coroutines: coroutine helper와 suspend-friendly utility
• virtualthread/api: Virtual Threads abstraction의 공통 API
• virtualthread/jdk21: Java 21 Virtual Threads support
• virtualthread/jdk25: Java 25 Virtual Threads support

대표 기능은 suspend API, coroutine execution model, blocking SDK/JDBC를 Virtual Threads 위에서 운용하는 migration path다. coroutine-first 코드와 blocking ecosystem 사이를 잇는 역할을 한다.

Testing

Testing module은 assertion, JUnit 5, Testcontainers, mock server를 한곳에서 제공한다.

• testing/assertions: bluetape4k assertion helper
• testing/junit5: JUnit 5 test utility
• testing/testcontainers: Testcontainers singleton launcher
• testing/mock-web-server: HTTP client test support
• testing/mock-webflux-server: WebFlux/WebClient test support

대표 기능은 assertion과 coroutine test helper, Redis/database/messaging Testcontainers launcher, HTTP/WebFlux mock server다.

BOM and Version Governance

생태계가 여러 repository로 나뉘면 dependency version drift가 쉽게 생긴다. BOM과 dependency catalog는 이 문제를 줄이기 위한 layer다.

• bluetape4k-dependencies: ecosystem-wide dependency alignment
• bluetape4k/bom: core repository alignment
• repository-local BOMs: AWS, Exposed, Image, JaVers, Leader, Text, Graph alignment

대표 기능은 Kotlin, Spring Boot, Exposed, AWS SDK, Testcontainers 같은 dependency 조합을 맞추고, 각 repository가 서로 다른 release cadence로 발전해도 application이 안정적인 version set을 가져가게 하는 것이다.

어떻게 읽으면 좋은가

처음 보는 팀이라면 Spring Boot 4나 Ktor 3 application boundary에서 시작하는 것이 편하다. 그 다음 Foundation layer에서 core, coroutine, testing, BOM을 보고, 실제 서비스가 만나는 문제에 따라 Data layer와 Infrastructure layer를 붙인다. leader election, audit trail, image processing, text processing, graph database처럼 특정 도메인 문제가 있다면 Domain Capability layer로 내려가면 된다.

Bluetape4k는 하나의 거대한 framework가 아니다. 이미 쓰고 있는 Spring Boot 4/Ktor 3 서비스에 필요한 module을 점진적으로 얹는 생태계다. 다음 글부터는 각 layer를 더 작게 나누어, 대표 저장소의 architecture와 실제 사용 예제를 살펴본다.