feat: springboot integration

inventory-orders-service/.sdkmanrc

@@ -1 +1 @@
-java=17.0.2-open
+java=17.0.8-graal

inventory-orders-service/CLAUDE.md

@@ -0,0 +1,87 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+This is an example project demonstrating Flamingock, a Change-as-Code execution engine. It simulates an e-commerce inventory & orders service that coordinates versioned changes across multiple target systems: MongoDB, Kafka Schema Registry, and LaunchDarkly (used here as an external configuration system, not runtime flag evaluation).
+
+**What Flamingock is:** A Change-as-Code execution engine that safely, deterministically, and auditably applies versioned changes to external systems at application startup. The goal is to ensure that all dependent external systems evolve in a synchronized and auditable way with the application. Think "Liquibase for all external systems, with auditability and safety as first-class constraints."
+
+**What Flamingock is NOT:** Not a database migration tool, not Infrastructure-as-Code (Terraform/Pulumi), not a CI/CD pipeline, not runtime feature flagging.
+
+## Build Commands
+
+```bash
+./gradlew build          # Build the project
+./gradlew run            # Run the application (executes pending changes at startup)
+./gradlew test           # Run integration tests with Testcontainers (no external services needed)
+./gradlew clean          # Clean build artifacts
+```
+
+## Running the Application
+
+**Option 1: With Docker Compose (for manual execution)**
+```bash
+docker-compose up -d     # Start MongoDB, Kafka, Schema Registry, LaunchDarkly mock
+./gradlew run            # Execute pending changes
+```
+
+**Option 2: With Testcontainers (for testing)**
+```bash
+./gradlew test           # Starts all containers automatically via Testcontainers
+```
+
+## Architecture
+
+### Flamingock Core Concepts
+
+- **Change** - The atomic unit of change. Defines what system it targets, what version it represents, and how it is applied. Changes are versioned, ordered, immutable once applied, and should be idempotent.
+- **Audit Store** - Records execution state (STARTED, COMPLETED). Intentionally separate from target systems to enable safe retries, manual intervention, and cross-system governance.
+- **Target System** - The external system being modified. Flamingock does not assume target systems are transactional; safety is enforced via execution tracking.
+
+### This Project's Setup
+
+- Entry point: `InventoryOrdersApp.java` with `@EnableFlamingock` annotation
+- Changes discovered from `io.flamingock.examples.inventory.changes` package
+- Uses compile-time annotation processing via `flamingock-processor`
+
+### Target Systems (defined in `TargetSystems.java`)
+1. **mongodb-inventory** - MongoDB operations (also used as Audit Store in this example; in real setups, the Audit Store may be a dedicated system)
+2. **kafka-inventory** - Kafka Schema Registry operations
+3. **toggle-inventory** - LaunchDarkly as external configuration system (not runtime flag evaluation)
+
+### Change Naming Convention
+In this example repository, changes follow the pattern: `_NNNN__[target]_[description].java`
+- Example: `_0001__mongodb_addDiscountCodeFieldToOrders.java`
+- Auto-ordered by numeric prefix
+- Each change class has an `@Apply` method and may optionally define a `@Rollback` for reconciliation or manual recovery
+
+### Utility Classes (`util/` package)
+- `MongoDBUtil` - MongoDB connection string builder
+- `KafkaSchemaManager` - Schema Registry REST operations
+- `LaunchDarklyClient` - Feature flag CRUD via REST API
+- `ConfigFileManager` - YAML config file handling
+
+## Technology Stack
+- Java 17
+- Flamingock v1.0.0-beta.5
+- MongoDB Driver Sync v5.5.1
+- Apache Kafka v3.7.0 with Avro v1.11.3
+- Confluent Schema Registry Client v7.5.0
+- OkHttp3 v4.12.0 (for REST calls)
+- Testcontainers v2.0.2 (for integration tests)
+
+## Infrastructure Services (docker-compose.yml)
+| Service           | Port  | Purpose                                       |
+|-------------------|-------|-----------------------------------------------|
+| MongoDB           | 27017 | Target system & Audit Store (in this example) |
+| Kafka             | 9092  | Event streaming                               |
+| Schema Registry   | 8081  | Avro schema management                        |
+| LaunchDarkly Mock | 8765  | External configuration system simulation      |
+
+## Testing
+Integration tests use Testcontainers to spin up isolated Docker containers:
+- `SuccessExecutionTest.java` tests all 7 changes
+- Tests verify MongoDB documents, Kafka schemas, and audit log entries
+- No external Docker Compose required for tests

inventory-orders-service/META-INF/MANIFEST.MF

@@ -0,0 +1,3 @@
+Manifest-Version: 1.0
+Main-Class: io.flamingock.examples.inventory.InventoryOrdersApp
+

inventory-orders-service/README.md

@@ -9,15 +9,15 @@ ___
 
 This example simulates an **e-commerce service** that manages inventory and orders. It demonstrates how Flamingock coordinates multiple target systems in lockstep using the **Change-as-Code** approach.
 
-The story begins when the **marketing team** launches a promotional campaign that requires support for **discount codes**.  
+The story begins when the **marketing team** launches a promotional campaign that requires support for **discount codes**.
 To implement this feature safely, the product and engineering teams plan a sequence of deployments, each introducing incremental changes in a controlled, auditable way.
 
-As development progresses, the **sales team** also requests the ability to quickly search and report on orders by discount code.  
+As development progresses, the **sales team** also requests the ability to quickly search and report on orders by discount code.
 This leads the engineers to add an index on the new field as part of the rollout, ensuring the system remains both functional and performant.
 
 ### Lifecycle of the feature rollout
 
-1. **Initial deployment**  <a id="initial-deployment"></a>  
+1. **Initial deployment**  <a id="initial-deployment"></a>
    *Business driver:* prepare the system for discounts while keeping the feature hidden.
    - Add the `discountCode` field to the `orders` collection in **MongoDB**.
    - Update the `OrderCreated` schema in **Kafka** to include the same field.
@@ -28,7 +28,7 @@ This leads the engineers to add an index on the new field as part of the rollout
       - [`UpdateOrderCreatedSchema`](#updateordercreatedschema)
       - [`AddFeatureFlagDiscounts`](#addfeatureflagdiscounts)
 
-2. **Second deployment** <a id="second-deployment"></a>  
+2. **Second deployment** <a id="second-deployment"></a>
    *Business driver:* ensure existing and new orders remain consistent.
    - Backfill existing orders with a default `discountCode` (e.g. `"NONE"`).
    - Application logic begins to populate the field for new orders, still hidden behind the flag.
@@ -37,7 +37,7 @@ This leads the engineers to add an index on the new field as part of the rollout
       - [`BackfillDiscountsForExistingOrders`](#backfilldiscountsforexistingorders)
       - [`AddIndexOnDiscountCode`](#addindexondiscountcode)
 
-3. **Runtime activation (no deployment)** <a id="runtime-activation"></a>  
+3. **Runtime activation (no deployment)** <a id="runtime-activation"></a>
    *Business driver:* marketing activates discounts for customers.
    - The feature flag is enabled at runtime using a feature-flag tool (e.g. Unleash, LaunchDarkly).
    - No redeployment is required — the system is already prepared.
@@ -67,6 +67,9 @@ This example showcases Flamingock’s ability to:
 - [Prerequisites](#prerequisites)
 - [Dependencies](#dependencies)
 - [How to Run this Example](#how-to-run-this-example)
+   - [Option 1: Run the Application (Recommended)](#option-1-run-the-application-recommended)
+   - [Option 2: Run Tests](#option-2-run-tests)
+   - [Option 3: Run with GraalVM Native Image (Optional)](#option-3-run-with-graalvm-native-image-optional)
 - [Proven Functionalities](#proven-functionalities)
 - [Implemented Changes](#implemented-changes)
 - [Contributing](#contributing)
@@ -196,7 +199,7 @@ curl http://localhost:8081/subjects/order-created-value/versions
 
 Check the audit logs in MongoDB:
 ```bash
-docker exec -it inventory-mongodb mongosh inventory --eval 'db.flamingockAuditLogs.find().pretty()'
+docker exec -it inventory-mongodb mongosh inventory --eval 'db.flamingockAuditLog.find().pretty()'
 ```
 
 5. **Clean up when done:**
@@ -211,6 +214,97 @@ Run the integration tests with Testcontainers (no Docker Compose needed):
 ./gradlew test
 ```
 
+### Option 3: Run with GraalVM Native Image (Optional)
+
+If you want to showcase Flamingock running as a GraalVM native image, you can follow these **optional** steps. The regular JVM flow above still works as-is.
+
+For full details, see the official docs: https://docs.flamingock.io/frameworks/graalvm
+
+#### 1. Use a GraalVM Java distribution
+
+Using SDKMAN:
+
+```bash
+sdk env install   # uses .sdkmanrc in this folder
+sdk use java 17.0.8-graal  # or any installed GraalVM distribution compatible with your setup
+```
+
+The default `.sdkmanrc` included with this example already uses Java 17 with GraalVM.
+
+#### 2. Ensure GraalVM support dependencies are present
+
+This example already includes the Flamingock GraalVM integration and resource configuration:
+
+- `build.gradle.kts` contains (commented):
+   - `implementation("io.flamingock:flamingock-graalvm:$flamingockVersion")`
+- `resource-config.json` in the project root includes:
+   - `META-INF/flamingock/metadata.json` resources required at native-image time
+
+If you copy this example to your own project, make sure you add the same pieces (or follow the docs linked above).
+
+#### 3. Build the fat (uber) JAR
+
+First build the application as usual, which also creates a **fat / uber JAR** bundling all runtime dependencies and a `Main-Class` manifest entry:
+
+```bash
+./gradlew clean build
+```
+
+The `jar` task in `build.gradle.kts` is configured like this:
+
+```kotlin
+tasks.named<Jar>("jar") {
+   manifest {
+      attributes["Main-Class"] = "io.flamingock.examples.inventory.InventoryOrdersApp"
+   }
+
+   duplicatesStrategy = DuplicatesStrategy.EXCLUDE
+
+   from(sourceSets.main.get().output)
+
+   from({
+      configurations.runtimeClasspath.get().map { if (it.isDirectory) it else zipTree(it) }
+   })
+}
+```
+
+This produces an executable uber JAR under `build/libs/` (for example `build/libs/inventory-orders-service-1.0-SNAPSHOT.jar`).
+
+> **Why this matters for GraalVM**
+>
+> GraalVM's `native-image -jar` mode expects a JAR that:
+> - has a valid `Main-Class` manifest attribute, and
+> - contains all the classes and dependencies reachable from that entry point.
+>
+> The fat/uber JAR configuration above ensures those requirements are met, which is essential for the native-image step to work reliably.
+
+#### 4. Create the native image
+
+From the project root, run (adjust the JAR name and output binary name if needed):
+
+```bash
+native-image \
+   --no-fallback \
+   --features=io.flamingock.graalvm.RegistrationFeature \
+   -H:ResourceConfigurationFiles=resource-config.json \
+   -H:+ReportExceptionStackTraces \
+   --initialize-at-build-time=org.slf4j.simple \
+   -jar build/libs/inventory-orders-service-1.0-SNAPSHOT.jar \
+   inventory-orders-service
+```
+
+This uses Flamingock's GraalVM feature to automatically register all required reflection metadata.
+
+#### 5. Run the native image
+
+With Docker Compose infrastructure already running (see [Option 1](#option-1-run-the-application-recommended)), start the native binary:
+
+```bash
+./inventory-orders-service
+```
+
+The application will execute the same Flamingock migrations as when running on the regular JVM, but with GraalVM-native startup and footprint characteristics.
+
 ## Troubleshooting
 
 ### Schema Registry Connection Issues
@@ -270,23 +364,23 @@ This example demonstrates the following Flamingock capabilities:
 ## Implemented Changes
 
 
-| Deployment Step                | Change Name                                                                         | Target Systems        | Operation                         | Description                                                                                  |  
-|--------------------------------|-------------------------------------------------------------------------------------|-----------------------|-----------------------------------|----------------------------------------------------------------------------------------------|  
-| [Initial](#initial-deployment) | <a id="adddiscountcodefieldtoorders"></a>`AddDiscountCodeFieldToOrders`             | MongoDB               | Alter collection / add field      | Adds `discountCode` (nullable) to the orders collection                                      |  
-| [Initial](#initial-deployment) | <a id="updateordercreatedschema"></a>`UpdateOrderCreatedSchema`                     | Kafka Schema Registry | Register new schema version       | Publishes a new version of the OrderCreated event schema including discountCode              |  
+| Deployment Step                | Change Name                                                                         | Target Systems        | Operation                         | Description                                                                                  |
+|--------------------------------|-------------------------------------------------------------------------------------|-----------------------|-----------------------------------|----------------------------------------------------------------------------------------------|
+| [Initial](#initial-deployment) | <a id="adddiscountcodefieldtoorders"></a>`AddDiscountCodeFieldToOrders`             | MongoDB               | Alter collection / add field      | Adds `discountCode` (nullable) to the orders collection                                      |
+| [Initial](#initial-deployment) | <a id="updateordercreatedschema"></a>`UpdateOrderCreatedSchema`                     | Kafka Schema Registry | Register new schema version       | Publishes a new version of the OrderCreated event schema including discountCode              |
 | [Initial](#initial-deployment) | <a id="addfeatureflagdiscounts"></a>`AddFeatureFlagDiscounts`                       | LaunchDarkly API       | Create flags                      | Creates feature flags for discount functionality using LaunchDarkly Management API           |
 | [Second](#second-deployment)   | <a id="backfilldiscountsforexistingorders"></a>`BackfillDiscountsForExistingOrders` | MongoDB               | Update                            | Updates existing orders with discountCode = "NONE"                                           |
 | [Second](#second-deployment)   | <a id="addindexondiscountcode"></a>`AddIndexOnDiscountCode`                         | MongoDB               | Create index                      | Creates an index on discountCode to support reporting and efficient lookups                  |
 | [Final](#final-deployment)     | <a id="cleanupfeatureflagdiscounts"></a>`CleanupFeatureFlagDiscounts`               | LaunchDarkly API       | Archive flags                     | Archives temporary feature flags once the feature is permanent and code guards are removed  |
-| [Final](#final-deployment)     | <a id="cleanupoldschemaversion"></a>`CleanupOldSchemaVersion`                       | Kafka Schema Registry | Disable/delete old schema version | Removes outdated schema once all consumers have migrated to the new version                  |  
+| [Final](#final-deployment)     | <a id="cleanupoldschemaversion"></a>`CleanupOldSchemaVersion`                       | Kafka Schema Registry | Disable/delete old schema version | Removes outdated schema once all consumers have migrated to the new version                  |
 
 ## Example Output
 
 After running the migrations, you'll see:
 - Orders in MongoDB with discount fields populated
 - Two schema versions in Schema Registry (V1 and V2)
 - LaunchDarkly Management API calls for feature flag creation/archival via mock server
-- Complete audit trail in the flamingockAuditLogs collection
+- Complete audit trail in the flamingockAuditLog collection
 
 ## Architecture Notes
 
@@ -323,4 +417,4 @@ This repository is licensed under the [Apache License 2.0](../LICENSE.md).
 
 ## Explore, experiment, and empower your projects with Flamingock!
 
-Let us know what you think or where you'd like to see Flamingock used next.
+Let us know what you think or where you'd like to see Flamingock used next.

inventory-orders-service/build.gradle.kts

@@ -5,6 +5,8 @@ plugins {
     java
     application
     idea
+    id("org.springframework.boot") version "3.2.0"
+    id("io.spring.dependency-management") version "1.1.4"
 }
 
 java {
@@ -26,7 +28,7 @@ repositories {
 group = "io.flamingock"
 version = "1.0-SNAPSHOT"
 
-val flamingockVersion = "1.0.0-beta.1"
+val flamingockVersion = "1.0.0-beta.5"
 logger.lifecycle("Building with flamingock version: $flamingockVersion")
 
 val mongodbVersion = "5.5.1"
@@ -39,6 +41,13 @@ dependencies {
 //    Flamingock Dependencies
     implementation(platform("io.flamingock:flamingock-community-bom:$flamingockVersion"))
     implementation("io.flamingock:flamingock-community")
+    implementation("io.flamingock:flamingock-springboot-integration")
+
+
+    // Optional: enable GraalVM native image support for Flamingock
+    // See: https://docs.flamingock.io/frameworks/graalvm
+    // Uncomment
+    // implementation("io.flamingock:flamingock-graalvm:$flamingockVersion")
     annotationProcessor("io.flamingock:flamingock-processor:$flamingockVersion")
 
 //    MongoDB dependencies
@@ -58,21 +67,38 @@ dependencies {
 //    HTTP client for LaunchDarkly Management API
     implementation("com.squareup.okhttp3:okhttp:4.12.0")
 
+//    Spring Boot
+    implementation("org.springframework.boot:spring-boot-starter-web")
+
 //    Others dependencies needed for this example
-    implementation("org.slf4j:slf4j-simple:2.0.6")
+//    implementation("org.slf4j:slf4j-simple:2.0.6")  // Commented out - Spring Boot provides logging
 
     testImplementation("org.junit.jupiter:junit-jupiter-api:5.9.2")
     testRuntimeOnly("org.junit.jupiter:junit-jupiter-engine:5.9.2")
 
-    testImplementation("org.testcontainers:mongodb:1.21.3")
-    testImplementation("org.testcontainers:kafka:1.21.3")
-    testImplementation("org.testcontainers:junit-jupiter:1.21.3")
+    testImplementation("org.testcontainers:testcontainers-mongodb:2.0.2")
+    testImplementation("org.testcontainers:testcontainers-kafka:2.0.2")
+    testImplementation("org.testcontainers:testcontainers-junit-jupiter:2.0.2")
 }
 
 application {
     mainClass = "io.flamingock.examples.inventory.InventoryOrdersApp"
 }
 
+tasks.named<Jar>("jar") {
+    manifest {
+        attributes["Main-Class"] = "io.flamingock.examples.inventory.InventoryOrdersApp"
+    }
+
+    duplicatesStrategy = DuplicatesStrategy.EXCLUDE
+
+    from(sourceSets.main.get().output)
+
+    from({
+        configurations.runtimeClasspath.get().map { if (it.isDirectory) it else zipTree(it) }
+    })
+}
+
 tasks.withType<JavaCompile> {
     options.compilerArgs.add("-parameters")
 }

inventory-orders-service/resource-config.json

@@ -0,0 +1,7 @@
+{
+  "resources": {
+    "includes": [
+      { "pattern": "META-INF/flamingock/metadata.json" }
+    ]
+  }
+}