Bluetape4k AWS Part 1: Repository Overview and Mental Model
This is Part 1 of the bluetape4k-aws series. The series starts with
Part 1: repository overview and mental model. Part 2
covers core modules and service coverage, Part 3 follows Spring Boot 4, Ktor 3, and working
examples, Part 4 compares the approach with Spring Cloud AWS, and Part 5 walks through real
examples from examples/ and bluetape4k-workshop/aws.
AWS already has the AWS SDK for Java v2 and the
AWS SDK for Kotlin. Both are powerful, official
starting points for AWS APIs. Application code usually wants a smaller, service-shaped interface:
suspend functions, coroutine-friendly async bridges, framework-specific configuration, local
emulators, and version alignment through a BOM.
bluetape4k-aws sits in that space. It does not replace the AWS SDKs. It builds on Java SDK v2 and
the Kotlin SDK, then provides reusable helpers for integration code Kotlin/JVM services otherwise
repeat across applications. Plain Kotlin services
should be able to stay framework-neutral. Spring Boot 4 and Ktor 3 services should get framework
wiring that feels native to those stacks. The central question is not “should bluetape4k make a new
SDK?” It is “how should service code use the SDKs without carrying every integration detail itself?”
bluetape4k-aws keeps the BOM, SDK wrappers, framework adapters, examples, and local verification model aligned.Mental Model
Section titled “Mental Model”The repository is easiest to read as three layers.
First, there are core SDK wrappers. bluetape4k-aws-java works with AWS Java SDK v2 sync and async
clients, plus coroutine extensions. Java SDK v2 has broad service coverage and a stable production
API, but its async model needs a Kotlin-friendly bridge in coroutine services. For high-throughput
S3 transfer paths, the design also allows AWS CRT runtime dependencies and CRT-backed S3AsyncClient
beans so Spring auto-configuration can build the transfer manager on the optimized client.
bluetape4k-aws-kotlin is closer to the AWS Kotlin SDK side: native suspend helpers and DSL
builders for code that wants to stay on the Kotlin SDK path.
Second, the core stays framework-neutral. S3, SQS, SNS, DynamoDB, KMS, SES, CloudWatch, Kinesis, and STS helpers should not force a web framework into plain service code. That lets the same helper interface work from CLI tools, workers, Spring Boot services, and Ktor services.
Third, the edges become framework-aware. bluetape4k-aws-spring-boot owns Spring Boot 4
auto-configuration, templates, repositories, listeners, and property binding. bluetape4k-aws-ktor
owns Ktor 3 SigV4 signing, coroutine S3 REST clients, SQS consumer runtime, and DynamoDB server
repository helpers. The core remains portable; the edge speaks the framework’s language.
Module Map
Section titled “Module Map”The project provides these module families. The Spring module started from the kind of Spring-friendly AWS integration experience Spring Cloud AWS popularized, but targets Spring Boot 4 with coroutine-oriented bluetape4k helpers. The same core helpers then extend into Ktor 3, so the Spring Boot and Ktor modules are not competing stacks; they are framework adapters over the same AWS wrapper interface.
| Area | Representative module | Responsibility |
|---|---|---|
| BOM | bluetape4k-aws-bom | Align versions for io.github.bluetape4k.aws:* modules |
| Java SDK bridge | bluetape4k-aws-java | AWS Java SDK v2 wrappers, async/coroutine extensions, CRT-backed S3 transfers, broad service coverage |
| Kotlin SDK helpers | bluetape4k-aws-kotlin | AWS Kotlin SDK suspend helpers and DSL builders |
| Shared persistence | bluetape4k-aws-exposed | Exposed JDBC foundation for AWS-backed configuration |
| Spring Boot edge | bluetape4k-aws-spring-boot | Spring Cloud AWS-inspired Spring Boot 4 auto-config, S3 transfer, SES sender, SNS parser, SQS listener, DynamoDB/KMS/Secrets Manager/Parameter Store |
| Ktor edge | bluetape4k-aws-ktor | Ktor 3 extension of the same core helpers: SigV4, coroutine S3 client, SQS runtime, DynamoDB server repository |
| Examples | examples/* | Runnable Ktor and Spring Boot integrations for DynamoDB, S3, SQS, and Exposed |
The model is selective adoption. Pulling in a Spring Boot module should not drag a Ktor runtime with it. The BOM aligns versions, core modules handle SDK and coroutine boundaries, and framework adapters remove application wiring where they are useful.
Local Development Model
Section titled “Local Development Model”AWS integration code gets expensive when the only faithful test environment is a real account.
bluetape4k-aws therefore treats the local verification model as part of the repository, not as an
afterthought.
The README describes integration tests backed by Testcontainers-based AWS emulators. Production
runtime points at AWS, while development and CI can attach an emulator behind the same SDK clients.
Tests can choose the emulator with options such as -Dbluetape4k.aws.emulator=.... The recent
direction is Floci-first with LocalStack as a fallback; MiniStack is treated as a comparison
candidate rather than the default target.
The value is straightforward. Service code calls the same wrapper, and the runtime endpoint changes under test. DynamoDB tables, S3 buckets, and SQS queues do not have to be provisioned in a real AWS account just to verify Spring Boot or Ktor wiring and coroutine behavior.
Source Links
Section titled “Source Links”- Repository: bluetape4k-aws
- README: README.md
- Korean README: README.ko.md
- BOM README: bom/README.md
- README diagrams: docs/assets/readme-diagrams
Closing
Section titled “Closing”bluetape4k-aws is not an AWS SDK reimplementation. It is a Kotlin/JVM integration layer over the official
AWS SDKs, combining coroutine helpers, framework adapters, local emulator verification, and BOM
alignment. Plain Kotlin services can use the wrapper layer directly, Spring Boot 4 and Ktor 3
services get native wiring, and tests can reduce account dependency through LocalStack, Floci, and
Testcontainers.
Next, we will look more closely at aws-java, aws-kotlin, aws-exposed, and service coverage.
Knowing where each AWS service belongs is the first step toward not building a custom SDK client
factory in every service.
Comments
Leave a note or reaction with your GitHub account.