Bluetape4k Ecosystem at a Glance

Bluetape4k is not one large framework. It is a Kotlin/JVM backend ecosystem that Spring Boot 4 and Ktor 3 services can adopt one boundary at a time.

Bluetape4k can look large at first. There are separate repositories for projects, exposed, aws, image, text, leader, javers, graph, and dependencies, and each repository contains multiple modules. This first introduction post is a map: where to start, which layer owns which responsibility, and how the repositories fit together.

The core structure is simple. Spring Boot 4 or Ktor 3 owns the application boundary. Bluetape4k fills the domain capability, data, infrastructure, and foundation layers underneath. A service does not pull in everything. It picks the modules that match the boundary it actually touches.

Overall Layer Map

Layer	Role	Representative repositories and modules
Application	Spring Boot 4 and Ktor 3 application boundary	spring-boot/*, *-ktor, examples
Domain Capability	Feature groups close to service domains	Leader, JaVers, Image, Text, Graph
Data	JDBC, R2DBC, Exposed, and document/wide-column database helpers	Exposed, data/*, GraphDB adapters
Infrastructure	Cloud, messaging, cache, observability, and resilience	AWS, Kafka, NATS, Redis, Micrometer, OpenTelemetry, Resilience4j
Foundation	Shared Kotlin/JVM foundation	core, coroutines, logging, testing, BOM

This table is more of a reading order than a dependency graph. Start with the foundation, then choose data, infrastructure, and domain-capability modules based on the boundary your service actually touches.

Application Layer

The application layer belongs to Spring Boot 4 or Ktor 3. Bluetape4k does not try to replace those frameworks. It provides the repeated auto-configuration, coroutine data access, Redis/cache, cloud integration, and examples that sit inside them.

Spring Boot 4

The Spring Boot 4 modules connect Bluetape4k data, cache, infrastructure, and testing modules into a Spring application.

Key modules:

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

These modules keep coroutine, R2DBC, Redis, MongoDB, and Cassandra boundaries wired consistently inside Spring Boot applications.

Ktor 3

Ktor modules focus on suspend APIs and coroutine clients. They are useful when a service wants a lighter runtime than Spring Boot but still needs AWS, leader election, or graph database integration.

Key modules:

• aws-ktor: AWS SDK integration for Ktor services
• leader-ktor: leader election integration for Ktor applications
• graph-ktor: graph database integration for Ktor boundaries
• examples/aws-ktor-*: examples combining AWS, leader election, and graph database modules

Ktor 3 modules do not create a new framework. They provide an adoption path for using Bluetape4k modules inside Ktor services.

Domain Capability Layer

The domain capability layer contains feature groups that are close to service-domain problems: leader election, audit trails, image processing, text processing, and graph databases.

Leader

Leader modules let distributed services assign batch jobs, schedulers, polling workers, and migration gates to one node or a limited group of nodes.

Key modules:

• leader-core: leader election APIs and execution model
• leader-redis-lettuce, leader-redis-redisson: Redis-backed implementations
• leader-hazelcast, leader-mongodb, leader-zookeeper: distributed backend variants
• leader-exposed-jdbc, leader-exposed-r2dbc: database-backed implementations
• leader-spring-boot, leader-ktor: application framework integration

The main features are runIfLeader(), blocking/CompletableFuture/coroutine/Virtual Threads execution models, and LeaderGroupElector for multi-leader work.

JaVers

JaVers modules handle audit trails for aggregate and domain-object changes.

Key modules:

• javers-core: JaVers helpers, codecs, and cache-backed repository support
• javers-persistence-redis: Redis Lettuce/Redisson snapshot storage
• javers-persistence-kafka: Kafka event-stream persistence
• bom: JaVers dependency version alignment

The main features are aggregate/domain object history, Redis or Kafka-backed audit storage, and DDD-style diff, snapshot, and history lookup.

Image

Image modules let a service choose between ordinary JVM image processing and libvips-backed high throughput processing.

Key modules:

• images: Scrimage-based pure JVM image processing
• images-vips-api: libvips abstraction and common 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 and benchmarks

The main features are resize, crop, filter, encode, and batch processing. A service can start with pure JVM image work and move high-volume thumbnail or resize pipelines to libvips.

Text

Text modules provide Korean/Japanese tokenization, language detection, and keyword search for Kotlin services.

Key modules:

• tokenizer-core: common request/response models and dictionary utilities
• tokenizer-korean: Korean normalization, POS tokenization, and phrase extraction
• tokenizer-japanese: Japanese tokenization with Kuromoji IPAdic
• lingua: language detection through Lingua
• text-search: Aho-Corasick search, replacement, and word filtering

The main features are Korean/Japanese text analysis, mixed-language detection, forbidden-word or keyword search, and replacement pipelines.

Data Layer

The data layer covers persistence and database integration: Exposed DSL, JDBC/R2DBC repositories, document database helpers, and graph database adapters.

Exposed

Exposed modules provide a Kotlin DSL-oriented persistence model and let JDBC and R2DBC follow a similar repository pattern.

Key modules:

• exposed-core: common repositories, query helpers, and DSL support
• exposed-jdbc, exposed-r2dbc: JDBC and R2DBC adapters
• cache, JSON, encryption, and dialect-extension modules
• Spring Boot JDBC/R2DBC integration

The main features are type-safe SQL, JDBC repositories, R2DBC coroutine repositories, CTE/recursive CTE/batch/measured-query helpers, JSON columns, encrypted columns, and database-specific extensions.

GraphDB

GraphDB modules reduce API differences across graph databases and provide a common API for services where graph data is a major part of the model.

Key modules:

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

The main features are common access to Neo4j, Memgraph, AGE, TinkerGraph, and FalkorDB; node/edge batch insert; merge/upsert; schema and index management; transaction blocks; weighted paths; graph algorithm operations; and bulk I/O with CSV, NDJSON, GraphML, and OkIO streams.

General Data Modules

Some data helpers are not tied to Exposed or GraphDB.

• data/hibernate: Hibernate persistence utilities
• data/r2dbc: common R2DBC helpers
• data/jdbc: JDBC data-access utilities
• data/mongodb: MongoDB integration helpers
• data/cassandra: Cassandra integration helpers

These modules reduce repeated repository, transaction, serialization, and Spring Boot data integration patterns for relational, document, and wide-column databases.

Infrastructure Layer

The infrastructure layer is close to production operations: cloud, messaging, cache, observability, and resilience.

AWS

AWS modules wrap AWS Java SDK v2 and AWS Kotlin SDK patterns for service code.

Key modules:

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

The main features are coroutine-friendly access to S3, DynamoDB, and SQS, plus local integration testing through LocalStack/FLOCI.

Messaging

Messaging modules reduce repeated setup for event pipelines and async integration.

• infra/kafka, infra/kafka4: Kafka client integration
• infra/kafka-logback: application logging through Kafka event pipelines
• infra/nats: NATS messaging integration
• infra/pulsar: Pulsar messaging integration

The main features are Kafka/NATS/Pulsar client configuration and application logging or event pipeline integration.

Cache and Redis

Cache and Redis modules cover local cache, distributed cache, and Redis client integration.

• infra/redis, infra/lettuce, infra/redisson: Redis clients and distributed primitives
• cache/cache-core: common cache abstraction
• cache/cache-lettuce, cache/cache-redisson: Redis-backed cache backends
• cache/cache-hazelcast: Hazelcast distributed cache backend
• cache/hibernate-cache-lettuce: Hibernate second-level cache integration

The main features are local cache with Caffeine, distributed cache with Redis or Hazelcast, repository cache, Hibernate cache, application cache, near-cache, and 2-tier cache patterns.

Observability and Resilience

Production services need metrics, tracing, resilience, and rate limiting.

• infra/micrometer: Micrometer metrics integration
• infra/opentelemetry: OpenTelemetry tracing
• infra/resilience4j: retry, circuit breaker, and rate-limiter integration
• infra/bucket4j: rate-limiting support
• utils/measured: measurement and logging helpers

These modules keep metric, tracing, and retry boilerplate out of application code and turn them into shared operational patterns.

Foundation Layer

The foundation layer is the shared Kotlin/JVM base used across most Bluetape4k modules.

Core and Utilities

• bluetape4k/core: guards, validation, extensions, and common types
• bluetape4k/annotations: API maturity opt-in annotations
• bluetape4k/logging: Kotlin-friendly logging
• utils/*: frequently used utility modules

These modules provide shared types and utilities so service code does not rebuild the same validation, logging, and extension patterns.

Coroutines and Virtual Threads

Coroutine and Virtual Threads modules handle the execution model between Kotlin coroutines and Java Virtual Threads.

• bluetape4k/coroutines: coroutine helpers and suspend-friendly utilities
• virtualthread/api: common API for Virtual Threads abstraction
• virtualthread/jdk21: Java 21 Virtual Threads support
• virtualthread/jdk25: Java 25 Virtual Threads support

The main features are suspend APIs, coroutine execution helpers, and a migration path for running blocking SDKs or JDBC work on Virtual Threads.

Testing

Testing modules provide assertions, JUnit 5 helpers, Testcontainers launchers, and mock servers.

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

The main features are assertion helpers, coroutine test support, Redis/database/messaging Testcontainers launchers, and HTTP/WebFlux mock servers.

BOM and Version Governance

When the ecosystem is split across many repositories, dependency version drift becomes a real cost. BOMs and the dependency catalog reduce that drift.

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

The main features are aligned dependency sets for Kotlin, Spring Boot, Exposed, AWS SDK, Testcontainers, and related libraries across different repository release cadences.

How to Read the Ecosystem

For a new team, the easiest starting point is the application boundary: Spring Boot 4 or Ktor 3. Then read the foundation layer for core utilities, coroutines, testing, and BOM alignment. After that, add data and infrastructure modules based on the boundary your service actually touches. If the problem is leader election, audit trails, image processing, text processing, or graph data, move into the domain capability layer.

Bluetape4k is not one large framework. It is an ecosystem of small modules that can be added gradually to existing Spring Boot 4 or Ktor 3 services. The next posts will break the layers down further and look at representative repositories, architecture, and usage examples.