DEV Community: Markus

AI Coding Governance for Real Software Teams

Markus — Thu, 18 Jun 2026 06:08:11 +0000

The slide I care about most from my recent JCon keynote only had six words on it: code is cheap, software isn’t.

If you want the full talk, the recording is here and you can find the slides here. This article is the shorter version I would hand to a team before they let an agent loose in a real repository.

The exciting part of AI coding is obvious. You ask for a REST endpoint, a refactor, a migration sketch, or a first-pass UI, and the blank page disappears. That part is real. I use these tools too. They save time, remove some boring work, and make it easier to try things quickly.

The problem starts when people confuse easier code generation with easier software engineering.

Real systems are full of hidden contracts. Authorization rules, deployment assumptions, stale docs, weird integration edges, and business logic nobody wrote down but everybody now depends on. A model can infer some of that from nearby code. It cannot infer all of it just because the prompt sounded confident.

That is still the main lesson for me after the last 18 months. AI can draft a lot of syntax. It does not automatically understand the software around it.

Prompting is not the hard part

I keep seeing teams treat AI coding as a prompting problem. Write better prompts. Add more detail. Find the right magic spell. That helps a bit, but it is not the part I trust.

The bigger lever is context.

If the agent does not know your architecture constraints, your business boundary, your non-negotiable tests, or the parts of the repository it should not touch, it will make something up. That is not a moral failure. That is how the system works. Statistical tools fill gaps with likely-looking answers.

So I would spend less time chasing clever wording and more time building context the model can actually use.

That means repository rules. It means ADRs. It means decision logs. It means tests that define behavior clearly enough that the agent has something better than vibes. It also means being selective. Dumping a pile of stale internal docs into the context window is not context engineering. It is just a different way to confuse the model.

The real question is not “how much context can I fit?” It is “which context changes the quality of the decision?”

Big tasks still fail for familiar reasons

AI has not rescued us from decomposition.

If a change is too messy to explain in two or three clear sentences, it is probably too messy to hand to an agent as one job. The tool may still produce a lot of output. That is not the same as producing a controlled result.

This is one place where the AI discourse sometimes sounds weirdly ahistorical. We already know big-bang rewrites fail. We already know broad “clean this whole area up while you are there” work spreads risk faster than teams can review it. Why would an agent be the magical exception?

The pattern that keeps holding up is still the old one:

Smaller tasks
Tight boundaries
Fast verification
Easy rollback
Explicit ownership

That is less glamorous than “fully autonomous development,” but it is much closer to how production teams stay sane.

I also think local git matters more than people admit. When an agent goes off the rails, the difference between a useful experiment and an annoying afternoon is often whether you can inspect the diff quickly, throw it away, and try again with a narrower request.

The useful tooling exposes systems, not just text

One reason I care about MCP and similar tool surfaces is that they shift the interaction away from pure guessing.

A model is much more useful when it can inspect runtime state, read the logs that matter, query the system you are actually changing, or reach structured docs instead of paraphrasing what it half-remembers. That does not make the model magical. It just gives it better ground to stand on.

For me, that is the real promise of this layer. Not “the model can use tools” as a demo trick. The better promise is that the model can stop pretending text alone is enough to understand a live system.

The same rule still applies, though: more tools are not automatically better. Tool sprawl creates its own tax. A giant tool catalog, a huge context payload, and 10 overlapping ways to do the same thing can make the session worse, not better. Good AI workflows need a shaped surface just as much as they need a capable model.

The bill comes back during review

This is the part I think teams still underestimate.

AI output is fast to produce and often expensive to verify. That cost does not show up in the demo. It shows up when a senior engineer has to read a clean-looking diff and decide whether the system still deserves trust.

That review load is real work. You are checking hidden assumptions, edge cases, failure paths, auth behavior, operational risk, naming drift, and whether the tests prove anything useful or just mirror the implementation. If the change touches infrastructure, security, or business rules, the cognitive bill gets even higher.

This is why I do not trust raw productivity claims that stop at code generation speed. A fast draft plus a slow, exhausting review loop is not automatically a win. Sometimes it is. Sometimes it is just a different queue.

The failure mode is subtle because tired reviewers still look productive from the outside. Files changed. The pull request is large. CI passed. Everybody feels movement. But fatigue is not the same as confidence, and momentum is not the same as understanding.

If I had to keep one professional rule from all of this, it would be simple: if you do not understand an AI-generated change well enough to explain its failure mode, do not merge it.

Java is in a stronger position than the hype suggests

A lot of AI coding conversation still defaults to Python because the AI ecosystem grew up around Python-first tooling. That does not mean Python teams are automatically in a better engineering position.

Java has a very practical advantage here. The code is explicit. Types are visible. Contracts are clearer. Framework conventions are stronger. Build and runtime boundaries are easier to follow than in many loosely structured stacks. That kind of shape helps humans review faster, and it helps models stay closer to the rails.

I do not mean Java makes AI safe. It does not. I mean Java gives both the model and the reviewer more structure to work with, which is one reason I think enterprise Java teams are better positioned for this transition than the public AI narrative suggests.

If anything, Java teams should lean into that advantage on purpose. Strong tests, typed config, explicit boundaries, and boring conventions are not old habits the AI era made irrelevant. They are what make the AI era survivable.

What I would actually tell a team

If I had to compress the whole keynote into one short working agreement, it would look like this:

Give the model better context, not just longer prompts.
Keep tasks small enough that verification stays cheap.
Use tools that expose real system state when the task depends on real system state.
Treat review load as part of the cost, not as free cleanup after the model is done.
Keep a human owner attached to every production change.

That is not a revolutionary message. It is mostly software engineering refusing to disappear just because the draft got cheaper.

AI is changing how we build. I do not think that part is controversial anymore. The part people still keep relearning is that faster code generation does not remove the expensive parts of software. Intent is still expensive. Architecture is still expensive. Verification is still expensive. Ownership is still expensive.

That is why the sentence on the slide still holds up.

Code is cheap. Software isn’t.

Subscribe now

Quarkus AWS Lambda HTTP: Live-Code Serverless on Localhost

Markus — Sat, 13 Jun 2026 06:08:26 +0000

Serverless tutorials often ask you to slow down before you write anything useful. Install SAM. Start Docker. Generate some YAML. Wait for a container. Change one line. Start again.

That is fine when you want full Lambda emulation. It is annoying when you just want to build an HTTP endpoint and keep the edit-save-refresh loop you already have with Quarkus.

The useful part of Quarkus AWS Lambda HTTP is not only the deployment packaging. It is the local development model. In dev and test mode, Quarkus starts a mock event server that converts normal HTTP requests into API Gateway events and feeds them into the Lambda poll loop. You still hit http://localhost:8080, but under the hood Quarkus is already pretending to be API Gateway and Lambda. The AWS Lambda HTTP guide documents that local flow, the raw /_lambda_ endpoint, and the AWS event types you can inject directly.

So we build a small quote API, run it through the mock event server, push a handcrafted API Gateway V2 event into /_lambda_, test the whole thing, and package it into the ZIP and SAM files you would actually hand to AWS.

What we build

We build a Quarkus app called lambda-http-localhost with two normal REST endpoints:

GET /quotes/{destination} for a quick quote driven by path, query, and header data
POST /quotes/preview for the same quote flow with a JSON body

Then we do four things that matter for this topic:

Run the app in dev mode and call it like an ordinary HTTP service on localhost:8080
Read Lambda-specific request metadata through APIGatewayV2HTTPEvent.RequestContext
POST a raw API Gateway HTTP API event to /_lambda_
Package the app into function.zip, sam.jvm.yaml, and sam.native.yaml

The sample is intentionally small. The point is the Lambda HTTP adapter and the local loop, not the business domain.

What you need

JDK 21 or newer
Maven 3.9+
Optional: AWS SAM CLI and Podman if you want the final container-based local run
About one ☕️

There is one version detail worth calling out: As of June 7, 2026, the official AWS Lambda runtime list includes both java21 and java25. On this sample, Quarkus still generated Runtime: java21 in target/sam.jvm.yaml, so I pinned maven.compiler.release to 21 to keep the generated ZIP compatible with that template. If your generated project already targets 21, keep it. If you want to move the Lambda runtime to 25, own that change explicitly instead of hoping the defaults agree.

Create the project

Generate the project with REST plus the Lambda HTTP adapter or grab the full copy from my Github repository:

mvn io.quarkus.platform:quarkus-maven-plugin:create \
  -DprojectGroupId=com.mainthread \
  -DprojectArtifactId=lambda-http-localhost \
  -Dextensions='rest-jackson,amazon-lambda-http' \
  -DnoCode

cd lambda-http-localhost

The generated pom.xml is close to normal Quarkus application wiring. For this walkthrough, make sure the compiler target stays on Java 21:

<properties>
    <maven.compiler.release>21</maven.compiler.release>
    <quarkus.platform.version>3.36.1</quarkus.platform.version>
</properties>

The only two application dependencies we need are these:

<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-rest-jackson</artifactId>
</dependency>
<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-amazon-lambda-http</artifactId>
</dependency>

quarkus-rest-jackson gives us normal Quarkus REST JSON endpoints. quarkus-amazon-lambda-http is the bridge that turns those endpoints into something AWS Lambda plus API Gateway HTTP API can invoke.

Add the quote model

Start with plain records for the request and response plus one small error payload:

package com.mainthread.lambdahttp;

public record ShippingQuoteRequest(String destination, int weightGrams, String speed, String customerTier) {
}

package com.mainthread.lambdahttp;

public record ShippingQuoteResponse(
        String destination,
        String speed,
        String customerTier,
        int weightGrams,
        int quotedCents,
        int estimatedBusinessDays,
        String fulfillmentRegion,
        String gatewayRequestId,
        String stage) {
}

package com.mainthread.lambdahttp;

public record ErrorResponse(String message) {
}

I keep the response a little more verbose than a real quote API would. That is deliberate. We want to see Lambda-specific metadata like gatewayRequestId and stage in the output.

The speed model is a tiny enum:

package com.mainthread.lambdahttp;

import java.util.Arrays;

enum ShippingSpeed {
    STANDARD("standard", 4, 0),
    EXPRESS("express", 2, 350),
    OVERNIGHT("overnight", 1, 900);

    private final String value;
    private final int estimatedBusinessDays;
    private final int surchargeCents;

    ShippingSpeed(String value, int estimatedBusinessDays, int surchargeCents) {
        this.value = value;
        this.estimatedBusinessDays = estimatedBusinessDays;
        this.surchargeCents = surchargeCents;
    }

    String value() {
        return value;
    }

    int estimatedBusinessDays() {
        return estimatedBusinessDays;
    }

    int surchargeCents() {
        return surchargeCents;
    }

    static ShippingSpeed from(String rawSpeed) {
        String normalized = rawSpeed == null ? "" : rawSpeed.trim().toLowerCase();
        return Arrays.stream(values())
                .filter(speed -> speed.value.equals(normalized))
                .findFirst()
                .orElseThrow(() -> new IllegalArgumentException("Unsupported speed '" + rawSpeed
                        + "'. Use standard, express, or overnight."));
    }
}

Nothing Lambda-specific yet. That is the point. Most of the code should still look like a normal Quarkus app.

Add the pricing service

The service does four practical things:

normalizes destination and customer tier input
validates a simple weight range
calculates the quote
fills in fallback Lambda metadata when the request context does not provide values

Create src/main/java/com/mainthread/lambdahttp/ShippingQuoteService.java:

package com.mainthread.lambdahttp;

import java.util.Locale;
import java.util.Set;

import jakarta.enterprise.context.ApplicationScoped;

@ApplicationScoped
public class ShippingQuoteService {

    private static final Set<String> EU_DESTINATIONS = Set.of(
            "amsterdam", "barcelona", "berlin", "lisbon", "madrid", "paris", "porto", "rome", "vienna");

    public ShippingQuoteResponse preview(String destination,
            int weightGrams,
            String rawSpeed,
            String rawCustomerTier,
            String gatewayRequestId,
            String stage) {
        String normalizedDestination = normalizeDestination(destination);
        ShippingSpeed speed = ShippingSpeed.from(rawSpeed);
        String customerTier = normalizeCustomerTier(rawCustomerTier);
        int normalizedWeight = normalizeWeight(weightGrams);
        int quotedCents = quoteCents(normalizedWeight, speed, customerTier);

        return new ShippingQuoteResponse(
                normalizedDestination.toUpperCase(Locale.ROOT),
                speed.value(),
                customerTier,
                normalizedWeight,
                quotedCents,
                speed.estimatedBusinessDays(),
                fulfillmentRegion(normalizedDestination),
                defaultIfBlank(gatewayRequestId, "mock-event"),
                defaultIfBlank(stage, "$default"));
    }

    private String normalizeDestination(String destination) {
        if (destination == null || destination.isBlank()) {
            throw new IllegalArgumentException("Destination is required.");
        }
        return destination.trim().toLowerCase(Locale.ROOT);
    }

    private int normalizeWeight(int weightGrams) {
        if (weightGrams < 100 || weightGrams > 5000) {
            throw new IllegalArgumentException("weightGrams must be between 100 and 5000.");
        }
        return weightGrams;
    }

    private String normalizeCustomerTier(String rawCustomerTier) {
        String normalized = defaultIfBlank(rawCustomerTier, "standard").toLowerCase(Locale.ROOT);
        return switch (normalized) {
            case "standard", "silver", "gold" -> normalized;
            default -> throw new IllegalArgumentException(
                    "Unsupported customer tier '" + rawCustomerTier + "'. Use standard, silver, or gold.");
        };
    }

    private int quoteCents(int weightGrams, ShippingSpeed speed, String customerTier) {
        int base = 700;
        int weightCharge = Math.max(0, weightGrams - 500) / 100 * 45;
        int tierDiscount = switch (customerTier) {
            case "silver" -> 120;
            case "gold" -> 240;
            default -> 0;
        };
        return base + weightCharge + speed.surchargeCents() - tierDiscount;
    }

    private String fulfillmentRegion(String destination) {
        return EU_DESTINATIONS.contains(destination) ? "eu-central" : "global-export";
    }

    private String defaultIfBlank(String value, String fallback) {
        return value == null || value.isBlank() ? fallback : value;
    }
}

The only thing here that belongs to the Lambda story is the fallback for gatewayRequestId and stage. In normal localhost requests, the mock event server supplies those values. In a direct raw event post, we can set them ourselves. The service just keeps the final output stable.

Add the Lambda-aware REST resource

Now wire the REST endpoints in QuoteResource.java:

package com.mainthread.lambdahttp;

import com.amazonaws.services.lambda.runtime.events.APIGatewayV2HTTPEvent;

import jakarta.ws.rs.Consumes;
import jakarta.ws.rs.DefaultValue;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.HeaderParam;
import jakarta.ws.rs.POST;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.PathParam;
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.QueryParam;
import jakarta.ws.rs.core.Context;
import jakarta.ws.rs.core.MediaType;

import org.jboss.resteasy.reactive.RestResponse;
import org.jboss.resteasy.reactive.server.ServerExceptionMapper;

@Path("/quotes")
@Produces(MediaType.APPLICATION_JSON)
@Consumes(MediaType.APPLICATION_JSON)
public class QuoteResource {

    private final ShippingQuoteService shippingQuoteService;

    public QuoteResource(ShippingQuoteService shippingQuoteService) {
        this.shippingQuoteService = shippingQuoteService;
    }

    @GET
    @Path("/{destination}")
    public ShippingQuoteResponse previewFromRequest(
            @PathParam("destination") String destination,
            @QueryParam("speed") @DefaultValue("standard") String speed,
            @QueryParam("weightGrams") @DefaultValue("500") int weightGrams,
            @HeaderParam("X-Customer-Tier") @DefaultValue("standard") String customerTier,
            @Context APIGatewayV2HTTPEvent.RequestContext requestContext) {
        return shippingQuoteService.preview(
                destination,
                weightGrams,
                speed,
                customerTier,
                requestId(requestContext),
                stage(requestContext));
    }

    @POST
    @Path("/preview")
    public ShippingQuoteResponse previewFromBody(
            ShippingQuoteRequest request,
            @Context APIGatewayV2HTTPEvent.RequestContext requestContext) {
        return shippingQuoteService.preview(
                request.destination(),
                request.weightGrams(),
                request.speed(),
                request.customerTier(),
                requestId(requestContext),
                stage(requestContext));
    }

    @ServerExceptionMapper
    RestResponse<ErrorResponse> mapIllegalArgument(IllegalArgumentException exception) {
        return RestResponse.status(RestResponse.Status.BAD_REQUEST, new ErrorResponse(exception.getMessage()));
    }

    private String requestId(APIGatewayV2HTTPEvent.RequestContext requestContext) {
        return requestContext == null ? null : requestContext.getRequestId();
    }

    private String stage(APIGatewayV2HTTPEvent.RequestContext requestContext) {
        return requestContext == null ? null : requestContext.getStage();
    }
}

This is the line that makes the article worth writing:

@Context APIGatewayV2HTTPEvent.RequestContext requestContext

The Quarkus guide documents that for the HTTP API adapter you can inject Context, APIGatewayV2HTTPEvent, or APIGatewayV2HTTPEvent.RequestContext directly into Quarkus REST resources. That means you can keep writing REST endpoints and still inspect Lambda or API Gateway metadata when you need it.

Run it in dev mode

Start Quarkus dev mode:

./mvnw quarkus:dev

The interesting log lines are the Lambda ones:

Mock Lambda Event Server Started
The amazon-lambda dev service is ready to accept connections on localhost:8080/_lambda_
Listening on: http://localhost:8080/_lambda_/2018-06-01/runtime/invocation/next

You still call localhost:8080, but Quarkus is already routing through the Lambda event server.

Call the GET endpoint:

curl -s 'http://localhost:8080/quotes/lisbon?speed=express&weightGrams=900' \
  -H 'X-Customer-Tier: gold' | jq

You should see:

{
  "destination": "LISBON",
  "speed": "express",
  "customerTier": "gold",
  "weightGrams": 900,
  "quotedCents": 990,
  "estimatedBusinessDays": 2,
  "fulfillmentRegion": "eu-central",
  "gatewayRequestId": "mock-event",
  "stage": "$default"
}

The business fields are ours. gatewayRequestId and stage come from the Lambda-shaped request context Quarkus synthesized locally.

Call the POST path too:

curl -s http://localhost:8080/quotes/preview \
  -H 'Content-Type: application/json' \
  -d '{
    "destination": "Chicago",
    "weightGrams": 1200,
    "speed": "overnight",
    "customerTier": "silver"
  }' | jq

Expected response:

{
  "destination": "CHICAGO",
  "speed": "overnight",
  "customerTier": "silver",
  "weightGrams": 1200,
  "quotedCents": 1795,
  "estimatedBusinessDays": 1,
  "fulfillmentRegion": "global-export",
  "gatewayRequestId": "mock-event",
  "stage": "$default"
}

Prove the live-coding part

Change one line in ShippingQuoteService while dev mode is still running:

case "gold" -> 240;

Set it to:

case "gold" -> 300;

Save the file and run the first curl again. The quote drops from 990 to 930 without a restart because Quarkus recompiles the class and the mock event server keeps feeding requests through the same Lambda development loop. Change it back after the experiment so the rest of this walkthrough still matches.

That is the real value here. You keep the same local speed as a normal Quarkus REST app, but the request path is already Lambda-shaped.

Push a raw API Gateway V2 event into `/_lambda_`

Normal localhost requests are enough most of the time. The raw /_lambda_ path is for the cases where you want to simulate a more exact event shape.

Create an event.json file like this:

{
  "version": "2.0",
  "routeKey": "$default",
  "rawPath": "/quotes/porto",
  "rawQueryString": "speed=overnight&weightGrams=900",
  "headers": {
    "X-Customer-Tier": "gold"
  },
  "requestContext": {
    "routeKey": "$default",
    "stage": "qa",
    "apiId": "local-test",
    "domainName": "localhost",
    "requestId": "req-raw-42",
    "http": {
      "method": "GET",
      "path": "/quotes/porto",
      "protocol": "HTTP/1.1",
      "sourceIp": "127.0.0.1",
      "userAgent": "curl"
    }
  }
}

Now POST it to the mock event server:

curl -s -X POST http://localhost:8080/_lambda_ \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  --data @event.json | jq

The response looks different:

{
  "statusCode": 200,
  "headers": {
    "content-length": "206",
    "Content-Type": "application/json;charset=UTF-8"
  },
  "multiValueHeaders": null,
  "cookies": null,
  "body": "{\"destination\":\"PORTO\",\"speed\":\"overnight\",\"customerTier\":\"gold\",\"weightGrams\":900,\"quotedCents\":1540,\"estimatedBusinessDays\":1,\"fulfillmentRegion\":\"eu-central\",\"gatewayRequestId\":\"req-raw-42\",\"stage\":\"qa\"}",
  "isBase64Encoded": false
}

When you hit /_lambda_, you are no longer talking to your REST endpoint directly. You are talking to the Lambda adapter, so you get an API Gateway-style response object back. Your business JSON is in the body field.

This is also where the @Context APIGatewayV2HTTPEvent.RequestContext injection is visible. The response now shows gatewayRequestId as req-raw-42 and stage as qa, because those came from the handcrafted event instead of the default mock values.

Test the same flow in Quarkus

Quarkus starts the mock event server in test mode too. The guide documents the default test port as 8081, and REST Assured is wired to it automatically in @QuarkusTest.

The normal endpoint tests look like this:

package com.mainthread.lambdahttp;

import static io.restassured.RestAssured.given;
import static org.hamcrest.Matchers.containsString;
import static org.hamcrest.Matchers.equalTo;

import org.junit.jupiter.api.Test;

import io.quarkus.test.common.http.TestHTTPEndpoint;
import io.quarkus.test.junit.QuarkusTest;
import io.restassured.http.ContentType;

@QuarkusTest
@TestHTTPEndpoint(QuoteResource.class)
class QuoteResourceTest {

    @Test
    void shouldPreviewQuoteThroughMockEventServer() {
        given()
                .header("X-Customer-Tier", "gold")
                .queryParam("speed", "express")
                .queryParam("weightGrams", 900)
                .when()
                .get("/lisbon")
                .then()
                .statusCode(200)
                .body("destination", equalTo("LISBON"))
                .body("speed", equalTo("express"))
                .body("customerTier", equalTo("gold"))
                .body("weightGrams", equalTo(900))
                .body("quotedCents", equalTo(990))
                .body("estimatedBusinessDays", equalTo(2))
                .body("fulfillmentRegion", equalTo("eu-central"));
    }

    @Test
    void shouldPreviewQuoteFromJsonBody() {
        String payload = """
                {
                  "destination": "Chicago",
                  "weightGrams": 1200,
                  "speed": "overnight",
                  "customerTier": "silver"
                }
                """;

        given()
                .contentType(ContentType.JSON)
                .body(payload)
                .when()
                .post("/preview")
                .then()
                .statusCode(200)
                .body("destination", equalTo("CHICAGO"))
                .body("speed", equalTo("overnight"))
                .body("customerTier", equalTo("silver"))
                .body("weightGrams", equalTo(1200))
                .body("quotedCents", equalTo(1795))
                .body("estimatedBusinessDays", equalTo(1))
                .body("fulfillmentRegion", equalTo("global-export"));
    }

    @Test
    void shouldRejectUnsupportedSpeed() {
        given()
                .queryParam("speed", "teleport")
                .when()
                .get("/porto")
                .then()
                .statusCode(400)
                .body("message", containsString("Unsupported speed"));
    }
}

The raw event test hits /_lambda_ directly:

package com.mainthread.lambdahttp;

import static io.restassured.RestAssured.given;
import static org.hamcrest.Matchers.containsString;
import static org.hamcrest.Matchers.equalTo;

import java.util.Map;

import org.junit.jupiter.api.Test;

import com.amazonaws.services.lambda.runtime.events.APIGatewayV2HTTPEvent;

import io.quarkus.test.junit.QuarkusTest;
import io.restassured.http.ContentType;

@QuarkusTest
class LambdaEventServerTest {

    @Test
    void shouldAcceptRawApiGatewayEvent() {
        APIGatewayV2HTTPEvent event = new APIGatewayV2HTTPEvent();
        event.setVersion("2.0");
        event.setRouteKey("$default");
        event.setRawPath("/quotes/porto");
        event.setRawQueryString("speed=overnight&weightGrams=900");
        event.setHeaders(Map.of("X-Customer-Tier", "gold"));

        APIGatewayV2HTTPEvent.RequestContext.Http http = new APIGatewayV2HTTPEvent.RequestContext.Http();
        http.setMethod("GET");
        http.setPath("/quotes/porto");
        http.setProtocol("HTTP/1.1");
        http.setSourceIp("127.0.0.1");
        http.setUserAgent("rest-assured");

        APIGatewayV2HTTPEvent.RequestContext requestContext = new APIGatewayV2HTTPEvent.RequestContext();
        requestContext.setHttp(http);
        requestContext.setRequestId("req-raw-42");
        requestContext.setRouteKey("$default");
        requestContext.setStage("qa");
        requestContext.setApiId("local-test");
        requestContext.setDomainName("localhost");

        event.setRequestContext(requestContext);

        given()
                .contentType(ContentType.JSON)
                .accept(ContentType.JSON)
                .body(event)
                .when()
                .post("/_lambda_")
                .then()
                .statusCode(200)
                .body("statusCode", equalTo(200))
                .body("body", containsString("\"gatewayRequestId\":\"req-raw-42\""))
                .body("body", containsString("\"stage\":\"qa\""))
                .body("body", containsString("\"quotedCents\":1540"));
    }
}

Run the tests with:

./mvnw test

If you also want the packaged-app path, add small integration test shells that extend the JVM tests:

@QuarkusIntegrationTest
class QuoteResourceIT extends QuoteResourceTest {
}

@QuarkusIntegrationTest
class LambdaEventServerIT extends LambdaEventServerTest {
}

The Quarkus guide calls out that the mock event server works for @QuarkusIntegrationTest too, which is the practical reason these tiny extension-style IT classes are worth keeping around.

Package it for Lambda

Build the project:

./mvnw package -DskipTests

On this sample, the build produced these files:

ls -lh target/function.zip target/sam.jvm.yaml target/sam.native.yaml

-rw-r--r-- 1 you staff 17M target/function.zip
-rw-r--r-- 1 you staff 873B target/sam.jvm.yaml
-rw-r--r-- 1 you staff 945B target/sam.native.yaml

The generated JVM SAM file is the more interesting one:

AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31
Description: AWS Serverless Quarkus HTTP - lambda-http-localhost-1.0.0-SNAPSHOT

Resources:
  LambdaHttpLocalhost:
    Type: AWS::Serverless::Function
    Properties:
      Handler: io.quarkus.amazon.lambda.runtime.QuarkusStreamHandler::handleRequest
      Runtime: java21
      CodeUri: function.zip
      MemorySize: 512
      Timeout: 15

That Handler value is the Quarkus bridge. Do not change it unless you are deliberately replacing the runtime path the extension generated for you.

The native SAM template switches runtime and adds one environment variable:

Runtime: provided.al2023
Environment:
  Variables:
    DISABLE_SIGNAL_HANDLERS: true

That matches the current Quarkus AWS Lambda HTTP guide, which calls out both the Java runtime handler and the native runtime signal-handler setting.

Run the packaged Lambda with SAM CLI

The mock event server is the fast inner loop. sam local start-api is the heavier proof step that shows the packaged artifact running behind a local Lambda plus API Gateway simulation instead of the Quarkus dev loop.

For this section you need two extra tools:

AWS SAM CLI installed
A Docker-compatible container backend (Podman)

The current Quarkus AWS Lambda HTTP guide documents this flow as Docker-backed. In my local run for this article, I used SAM CLI 1.161.1 on macOS with Podman 5.8.2 because the machine already exposed a Docker-compatible socket at /var/run/docker.sock. Podman’s own installation docs say that macOS Podman can listen for Docker API clients, which is the part SAM needs.

If you are on Podman instead of Docker Desktop, check these two things before you blame SAM:

podman machine list
ls -l /var/run/docker.sock

On my machine, that socket was a symlink to the Podman machine socket, and SAM worked without extra flags.

Build the Lambda artifacts first:

./mvnw package -DskipTests

Then start the local API Gateway plus Lambda simulation from the generated SAM template:

sam local start-api --template target/sam.jvm.yaml

SAM prints the mounted endpoint and then waits on port 3000. In my run, the first invoke pulled the Java 21 Lambda emulation image and started the Quarkus function inside that container.

When SAM is ready, call the same route through the local API endpoint on port 3000:

curl -s 'http://127.0.0.1:3000/quotes/lisbon?speed=express&weightGrams=900' \
  -H 'X-Customer-Tier: gold' | jq

You should see the same business response shape as in dev mode:

{
  "destination": "LISBON",
  "speed": "express",
  "customerTier": "gold",
  "weightGrams": 900,
  "quotedCents": 990,
  "estimatedBusinessDays": 2,
  "fulfillmentRegion": "eu-central",
  "gatewayRequestId": "mock-event",
  "stage": "$default"
}

This response can be locally verified against the packaged Lambda. In my run, the gatewayRequestId value was generated by SAM and looked like this:

{
  "destination": "LISBON",
  "speed": "express",
  "customerTier": "gold",
  "weightGrams": 900,
  "quotedCents": 990,
  "estimatedBusinessDays": 2,
  "fulfillmentRegion": "eu-central",
  "gatewayRequestId": "4693c4af-047d-4f06-b58a-81194d4cbb16",
  "stage": "$default"
}

One small Podman-specific wrinkle showed up in the SAM logs:

Unknown 404 - Unable to check if base image is current.
Possible incompatible Docker engine clone employed.

That warning did not block execution. The request still returned 200 OK. It is a compatibility warning about image freshness checks, not proof that the Lambda failed to run.

At that point the tutorial shows two different local truths:

Quarkus dev mode with the mock event server is the fast coding loop
SAM CLI is the packaging-level check that the generated Lambda service still answers correctly

One replaces friction during development. The other reduces hand-waving before you get to AWS.

A few honest boundaries

This adapter is useful, but I would keep a few things in mind:

The current Quarkus AWS Lambda HTTP guide still marks this extension as preview.
The mock event server is very good for API Gateway event shape, header behavior, and local code flow. It is not a full substitute for IAM, Cognito, networking, and deployment validation in a real AWS account.
Runtime alignment matters. If your generated SAM template says java21, do not quietly ship Java 25 bytecode into it.
Security mapping is off by default. If you want Quarkus to translate API Gateway security metadata into a principal, enable quarkus.lambda-http.enable-security=true and test with richer raw events.

None of that weakens the local development story. It just keeps the promise honest.

Close the loop

We started with the usual serverless complaint: the local loop gets worse the moment Lambda enters the room. With Quarkus AWS Lambda HTTP, that does not have to be true.

We built a normal Quarkus REST app, ran it through localhost:8080, injected API Gateway V2 metadata into the resource with @Context, pushed a raw event into /_lambda_, tested both paths, and packaged the app into the files AWS tooling expects. The useful mental model is simple: during development, localhost is not just your HTTP server anymore. With the mock event server in front, it is already pretending to be API Gateway and Lambda.

Subscribe now

Quarkus JFR: Find Performance Bugs Before Users Do

Markus — Wed, 10 Jun 2026 06:08:59 +0000

CPU charts do their job. They show CPU. The problem starts when we ask them why a request feels bad.

An endpoint can feel terrible to users while CPU still looks calm. A request might be waiting on a lock, sleeping inside a fake refresh, or burning memory on temporary objects that die young. Logs usually tell you the request was slow. Metrics tell you the average or the percentile moved. Neither tells you what shape the slowdown had.

That is where Java Flight Recorder helps. It is built into the JDK, Quarkus has a JFR extension, and one recording lets you line up request timing, thread behavior, allocations, GC, and startup. After that, you can stop guessing whether the problem was CPU, waiting, or memory churn.

So we build a deliberately suspicious Quarkus service and use JFR to answer a very normal production question: why an endpoint feels slow even though CPU still looks fine.

What we build

We build requestwatch-jfr, a small Quarkus 3.36.1 service on Java 25 with four interesting paths:

GET /requests/fast as the boring control case
GET /requests/blocking as the bad path that holds a global lock while it waits
GET /requests/blocking-fixed as the same work with the slow part moved outside the lock
GET /requests/allocating as the path that creates too many temporary buffers

The app also does one bad thing at startup on purpose, because I want a recording from JVM boot to show more than steady-state traffic.

When you finish, you will know what to look for in JFR when:

latency is high but CPU is not
one request path allocates far more than its neighbors
startup hides work before the first real request

This is not a JVM internals lecture. We are going to look for a few useful signals and stop there.

What you need

You want a recent JDK, Maven, and enough Quarkus comfort to read a REST resource and a small service class. The sample is tiny on purpose. The point is runtime shape, not framework archaeology.

JDK 25
Maven 3.9+
JDK Mission Control if you want the visual recording walkthrough
Podman if you want to follow the container section
About ☕️☕️☕️

Create the project

Start with a plain Quarkus app that has REST, JFR, and the Podman container image extension:

mvn io.quarkus.platform:quarkus-maven-plugin:create \
  -DprojectGroupId=com.requestwatch \
  -DprojectArtifactId=requestwatch-jfr \
  -Dextensions="rest-jackson,jfr,container-image-podman" \
  -DnoCode

cd requestwatch-jfr

The generated project I got here uses Quarkus 3.36.1 and maven.compiler.release 25.

Why these extensions:

quarkus-rest-jackson gives us JSON endpoints on Quarkus REST
quarkus-jfr adds Quarkus events to the recording so request and startup activity are easier to place
quarkus-container-image-podman gives us a direct path to a Podman-built JVM image through the container image guide

The code stays small on purpose. I want the recording to do the heavy lifting here.

Build the sample

The bad behavior is deliberate. I am not trying to build a realistic service in every detail. I want a small app that produces the same JFR shapes you get from real mistakes.

Add typed config

First, add a typed config mapping in src/main/java/com/requestwatch/RequestWatchConfig.java:

package com.requestwatch;

import io.smallrye.config.ConfigMapping;
import io.smallrye.config.WithDefault;

@ConfigMapping(prefix = "requestwatch")
public interface RequestWatchConfig {

    Blocking blocking();

    Allocation allocation();

    Startup startup();

    interface Blocking {

        @WithDefault("150")
        long delayMillis();
    }

    interface Allocation {

        @WithDefault("768")
        int buffers();

        @WithDefault("8192")
        int bufferSizeBytes();
    }

    interface Startup {

        @WithDefault("true")
        boolean enabled();

        @WithDefault("400")
        long delayMillis();

        @WithDefault("256")
        int buffers();

        @WithDefault("16384")
        int bufferSizeBytes();
    }
}

I use @ConfigMapping because it keeps the demo honest. The numbers that drive blocking, allocation, and startup behavior stay in one place instead of hiding in magic constants.

Keep the response types boring

Keep the response types boring. Add these three records under src/main/java/com/requestwatch/:

package com.requestwatch;

public record FastResponse(String endpoint, String threadName, String quoteVersion, int priceCents) {
}

package com.requestwatch;

public record BlockingResponse(
        String endpoint,
        String threadName,
        String quoteVersion,
        int priceCents,
        long simulatedDelayMs,
        long elapsedMs) {
}

package com.requestwatch;

public record AllocationResponse(
        String endpoint,
        String threadName,
        int bufferCount,
        int bufferSizeBytes,
        long allocatedBytes,
        long checksum,
        long elapsedMs) {
}

The DTOs are plain on purpose. If the response model starts becoming the story, we already drifted away from the real problem.

Add the blocking and fixed paths

Now add the part we actually care about in src/main/java/com/requestwatch/PricingService.java:

package com.requestwatch;

import jakarta.enterprise.context.ApplicationScoped;
import jakarta.inject.Inject;

@ApplicationScoped
class PricingService {

    private final RequestWatchConfig config;
    private final Object refreshLock = new Object();

    private volatile SupplierQuote latestQuote = new SupplierQuote("startup", 1299);

    @Inject
    PricingService(RequestWatchConfig config) {
        this.config = config;
    }

    FastResponse fast() {
        SupplierQuote quote = latestQuote;
        return new FastResponse("fast", Thread.currentThread().getName(), quote.version(), quote.priceCents());
    }

    BlockingResponse blocking() {
        long start = System.nanoTime();
        SupplierQuote quote;
        synchronized (refreshLock) {
            quote = refreshQuote();
            latestQuote = quote;
        }
        return new BlockingResponse(
                "blocking",
                Thread.currentThread().getName(),
                quote.version(),
                quote.priceCents(),
                config.blocking().delayMillis(),
                elapsedMillis(start));
    }

    BlockingResponse blockingFixed() {
        long start = System.nanoTime();
        SupplierQuote quote = refreshQuote();
        synchronized (refreshLock) {
            latestQuote = quote;
        }
        return new BlockingResponse(
                "blocking-fixed",
                Thread.currentThread().getName(),
                quote.version(),
                quote.priceCents(),
                config.blocking().delayMillis(),
                elapsedMillis(start));
    }

    private SupplierQuote refreshQuote() {
        sleep(config.blocking().delayMillis());
        return new SupplierQuote("quote-" + System.nanoTime(), 1299);
    }

    private static long elapsedMillis(long start) {
        return (System.nanoTime() - start) / 1_000_000L;
    }

    private static void sleep(long delayMillis) {
        try {
            Thread.sleep(delayMillis);
        } catch (InterruptedException e) {
            Thread.currentThread().interrupt();
            throw new IllegalStateException("Quote refresh interrupted", e);
        }
    }

    private record SupplierQuote(String version, int priceCents) {
    }
}

This is the first thing I want to show. The bad path is slow, but not because it computes much. It holds a global lock and then sleeps. Real code does this with downstream HTTP calls, JDBC work, cache refreshes, or synchronized wrappers that looked harmless in review.

The fixed path does the same slow work, but it does not hold the lock during that wait. Under parallel traffic, that difference matters far more than the method names.

These endpoints return plain objects, so Quarkus REST treats them as blocking by signature and runs them off the IO thread by default. That is fine for this demo because the whole point is to make the waiting visible.

Add the allocation-heavy path

We also want one path that burns too much memory. Add src/main/java/com/requestwatch/AllocationService.java:

package com.requestwatch;

import java.util.ArrayList;
import java.util.List;

import jakarta.enterprise.context.ApplicationScoped;
import jakarta.inject.Inject;

@ApplicationScoped
class AllocationService {

    private final RequestWatchConfig config;

    @Inject
    AllocationService(RequestWatchConfig config) {
        this.config = config;
    }

    AllocationResponse allocating() {
        long start = System.nanoTime();
        List<byte[]> buffers = new ArrayList<>(config.allocation().buffers());
        long checksum = 0;
        long allocatedBytes = 0;

        for (int i = 0; i < config.allocation().buffers(); i++) {
            byte[] buffer = new byte[config.allocation().bufferSizeBytes()];
            buffer[0] = (byte) i;
            buffer[buffer.length - 1] = (byte) (i * 31);
            buffers.add(buffer);
            checksum += Byte.toUnsignedLong(buffer[0]) + Byte.toUnsignedLong(buffer[buffer.length - 1]);
            allocatedBytes += buffer.length;
        }

        return new AllocationResponse(
                "allocating",
                Thread.currentThread().getName(),
                buffers.size(),
                config.allocation().bufferSizeBytes(),
                allocatedBytes,
                checksum,
                elapsedMillis(start));
    }

    private static long elapsedMillis(long start) {
        return (System.nanoTime() - start) / 1_000_000L;
    }
}

This one allocates 768 x 8192 bytes , so a single request creates 6,291,456 bytes of temporary heap data. That is enough to show up clearly in allocation events without turning the tutorial into an OOM story.

Add one ugly startup path

Startup deserves one bad example too. Add src/main/java/com/requestwatch/StartupWarmup.java:

package com.requestwatch;

import java.util.ArrayList;
import java.util.List;

import jakarta.enterprise.context.ApplicationScoped;
import jakarta.enterprise.event.Observes;
import jakarta.inject.Inject;

import org.jboss.logging.Logger;

import io.quarkus.runtime.StartupEvent;

@ApplicationScoped
class StartupWarmup {

    private static final Logger LOG = Logger.getLogger(StartupWarmup.class);

    private final RequestWatchConfig config;

    @Inject
    StartupWarmup(RequestWatchConfig config) {
        this.config = config;
    }

    void onStart(@Observes StartupEvent ignored) {
        if (!config.startup().enabled()) {
            return;
        }

        List<byte[]> buffers = new ArrayList<>(config.startup().buffers());
        long allocatedBytes = 0;
        for (int i = 0; i < config.startup().buffers(); i++) {
            byte[] buffer = new byte[config.startup().bufferSizeBytes()];
            buffer[0] = (byte) i;
            buffers.add(buffer);
            allocatedBytes += buffer.length;
        }

        sleep(config.startup().delayMillis());
        LOG.infof("Startup warmup allocated %,d bytes across %d buffers", allocatedBytes, buffers.size());
    }

    private static void sleep(long delayMillis) {
        try {
            Thread.sleep(delayMillis);
        } catch (InterruptedException e) {
            Thread.currentThread().interrupt();
            throw new IllegalStateException("Startup warmup interrupted", e);
        }
    }
}

I like having one startup smell in the same sample because people often think only about request latency. JFR is also good at showing work that happens before the first request exists.

Expose the endpoints

Finally, expose the paths in src/main/java/com/requestwatch/RequestWatchResource.java:

package com.requestwatch;

import jakarta.inject.Inject;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.core.MediaType;

@Path("/requests")
@Produces(MediaType.APPLICATION_JSON)
public class RequestWatchResource {

    private final PricingService pricingService;
    private final AllocationService allocationService;

    @Inject
    public RequestWatchResource(PricingService pricingService, AllocationService allocationService) {
        this.pricingService = pricingService;
        this.allocationService = allocationService;
    }

    @GET
    @Path("/fast")
    public FastResponse fast() {
        return pricingService.fast();
    }

    @GET
    @Path("/blocking")
    public BlockingResponse blocking() {
        return pricingService.blocking();
    }

    @GET
    @Path("/blocking-fixed")
    public BlockingResponse blockingFixed() {
        return pricingService.blockingFixed();
    }

    @GET
    @Path("/allocating")
    public AllocationResponse allocating() {
        return allocationService.allocating();
    }
}

The extra /blocking-fixed endpoint is not how I would ship a real feature, obviously. It is there so we can compare the bad and good shapes in the same sample without turning the article into a branch-management exercise.

Configure the sample

Set the sample values in src/main/resources/application.properties:

requestwatch.blocking.delay-millis=150
requestwatch.allocation.buffers=768
requestwatch.allocation.buffer-size-bytes=8192
requestwatch.startup.enabled=true
requestwatch.startup.delay-millis=400
requestwatch.startup.buffers=256
requestwatch.startup.buffer-size-bytes=16384

quarkus.container-image.group=requestwatch
quarkus.container-image.name=requestwatch-jfr
quarkus.container-image.tag=1.0.0

The startup warmup allocates a little more than 4 MB and waits 400 ms. The blocking delay is 150 ms. Those numbers are big enough to show up clearly in a recording without making local feedback painful.

Set requestwatch.startup.enabled=false when you only care about request paths and want faster test boots. Just remember that choice removes the startup story from the recording entirely, which is an easy miss when you are trying to explain slow first boots.

Prove it with tests

Then prove the shape with src/test/java/com/requestwatch/RequestWatchResourceTest.java:

package com.requestwatch;

import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertTrue;

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;
import java.util.List;
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.Executors;
import java.util.stream.IntStream;

import org.junit.jupiter.api.Test;

import io.quarkus.test.common.http.TestHTTPEndpoint;
import io.quarkus.test.common.http.TestHTTPResource;
import io.quarkus.test.junit.QuarkusTest;
import io.restassured.RestAssured;
import io.restassured.path.json.JsonPath;

@QuarkusTest
@TestHTTPEndpoint(RequestWatchResource.class)
class RequestWatchResourceTest {

    @TestHTTPResource
    URI baseUri;

    @Test
    void fastEndpointReturnsCachedQuote() {
        RestAssured.get("fast")
                .then()
                .statusCode(200)
                .body("endpoint", org.hamcrest.Matchers.is("fast"))
                .body("priceCents", org.hamcrest.Matchers.is(1299));
    }

    @Test
    void allocatingEndpointReportsTemporaryBuffers() {
        RestAssured.get("allocating")
                .then()
                .statusCode(200)
                .body("endpoint", org.hamcrest.Matchers.is("allocating"))
                .body("bufferCount", org.hamcrest.Matchers.is(768))
                .body("bufferSizeBytes", org.hamcrest.Matchers.is(8192))
                .body("allocatedBytes", org.hamcrest.Matchers.is(6_291_456));
    }

    @Test
    void fixedEndpointAvoidsSerializedLatency() throws Exception {
        List<Long> blockingTimes = sampleElapsedTimes("blocking");
        List<Long> fixedTimes = sampleElapsedTimes("blocking-fixed");

        long slowestBlocking = blockingTimes.stream().mapToLong(Long::longValue).max().orElseThrow();
        long slowestFixed = fixedTimes.stream().mapToLong(Long::longValue).max().orElseThrow();

        assertTrue(slowestBlocking >= 500, "blocking endpoint should serialize parallel requests");
        assertTrue(slowestFixed < 350, "fixed endpoint should avoid serialized latency");
        assertTrue(slowestBlocking - slowestFixed >= 200, "fixed endpoint should be meaningfully faster");
    }

    private List<Long> sampleElapsedTimes(String path) throws Exception {
        try (var executor = Executors.newVirtualThreadPerTaskExecutor()) {
            HttpClient client = HttpClient.newBuilder()
                    .connectTimeout(Duration.ofSeconds(2))
                    .executor(executor)
                    .build();

            URI requestUri = URI.create(baseUri.toString() + "/" + path);
            List<CompletableFuture<Long>> futures = IntStream.range(0, 4)
                    .mapToObj(ignored -> send(client, requestUri))
                    .toList();

            return futures.stream().map(CompletableFuture::join).toList();
        }
    }

    private CompletableFuture<Long> send(HttpClient client, URI requestUri) {
        HttpRequest request = HttpRequest.newBuilder(requestUri)
                .timeout(Duration.ofSeconds(5))
                .GET()
                .build();

        return client.sendAsync(request, HttpResponse.BodyHandlers.ofString())
                .thenApply(response -> {
                    assertEquals(200, response.statusCode());
                    return JsonPath.from(response.body()).getLong("elapsedMs");
                });
    }
}

Run the suite:

./mvnw test

On this sample, the bad path stays above 500 ms for the slowest request when four calls hit it together, while the fixed path stays below 350 ms. Your exact numbers will move. The shape should stay the same.

Record the app in dev mode

The Quarkus JFR guide shows the key startup flag. We use the same pattern here, but I prefer settings=profile so the recording carries enough allocation and lock detail to be useful.

Start dev mode with JFR enabled from JVM startup:

./mvnw quarkus:dev \
  -Djvm.args="-XX:StartFlightRecording=name=requestwatch,settings=profile,dumponexit=true,filename=target/requestwatch-dev.jfr"

Because JFR starts with the JVM, the recording sees both the startup warmup and the later HTTP traffic. That matters. If you attach too late, you miss the bad startup story entirely.

In another terminal, trigger the paths:

curl -s http://localhost:8080/requests/fast

for i in 1 2 3 4; do
  curl -s http://localhost:8080/requests/blocking &
done
wait

curl -s http://localhost:8080/requests/allocating

for i in 1 2 3 4; do
  curl -s http://localhost:8080/requests/blocking-fixed &
done
wait

Then stop the app with q or Ctrl+C. The recording lands in target/requestwatch-dev.jfr.

Read the recording without guessing

I start with the jfr CLI. It is faster than opening a UI when you only want to confirm that the recording captured something useful.

Get the high-level picture:

jfr summary target/requestwatch-dev.jfr

See the Quarkus-specific events the extension added:

jfr print --categories quarkus target/requestwatch-dev.jfr

Look directly at the waiting side of the blocking path:

jfr print \
  --events jdk.ThreadSleep,jdk.JavaMonitorEnter \
  target/requestwatch-dev.jfr

Look at the allocation side:

jfr print \
  --events jdk.ObjectAllocationInNewTLAB,jdk.ObjectAllocationOutsideTLAB \
  target/requestwatch-dev.jfr

That gives you the text view. After that, open the same file in JDK Mission Control for the visual pass.

The Quarkus JFR guide points out one easy miss: the default thread view does not show Quarkus lanes. In JMC, open the Threads view, edit the thread activity lanes, and add a Quarkus lane. After that, request and startup activity stop blending into generic JVM noise.

Fast endpoint

This is the control case. It should be dull. Short request activity, no obvious allocation spike, no queue of waiting threads. Boring is the point. You need one path that does not smell.

Blocking endpoint

This path answers the opening question.

You should see several requests overlap in time, but one worker thread keeps the lock while it sleeps. The others stack up behind it. CPU is not the star here because the time is mostly waiting time. In the thread view and event list, the interesting words are things like sleep, monitor enter, and longer request duration, not hot arithmetic.

That is the payoff JFR gives you that a latency metric alone does not: the request is not slow because it computes too much. It is slow because it waits while holding the wrong lock.

Allocation-heavy endpoint

This one should jump out in the allocation views. byte[] allocations dominate, and you may see GC activity tighten around the request. The endpoint code is still simple, which is useful. You do not need a large system to learn the difference between CPU work and allocation pressure.

Startup

At the beginning of the recording, before traffic matters, StartupWarmup.onStart shows up with both allocation and sleep. This is the part teams often miss because the app “eventually starts fine.” JFR makes startup cost concrete instead of anecdotal.

If you only remember one reading rule from this article, make it this one:

When latency is bad and CPU is calm, start by looking for waiting and contention before you start arguing about optimization.

Fix one issue and compare before and after

The bad method keeps the slow refresh inside the synchronized block:

BlockingResponse blocking() {
    long start = System.nanoTime();
    SupplierQuote quote;
    synchronized (refreshLock) {
        quote = refreshQuote();
        latestQuote = quote;
    }
    return new BlockingResponse(
            "blocking",
            Thread.currentThread().getName(),
            quote.version(),
            quote.priceCents(),
            config.blocking().delayMillis(),
            elapsedMillis(start));
}

The fixed method does the wait first and locks only for the state update:

BlockingResponse blockingFixed() {
    long start = System.nanoTime();
    SupplierQuote quote = refreshQuote();
    synchronized (refreshLock) {
        latestQuote = quote;
    }
    return new BlockingResponse(
            "blocking-fixed",
            Thread.currentThread().getName(),
            quote.version(),
            quote.priceCents(),
            config.blocking().delayMillis(),
            elapsedMillis(start));
}

That is not a big fix simple enough to make a real difference. Like in many situations.

Run the same parallel traffic against both endpoints and compare the returned elapsedMs values:

for i in 1 2 3 4; do
  curl -s http://localhost:8080/requests/blocking &
done
wait

for i in 1 2 3 4; do
  curl -s http://localhost:8080/requests/blocking-fixed &
done
wait

On this sample, the bad path crosses 500 ms for the slowest concurrent request. The fixed path stays below 350 ms. In JFR, the stacked waiting shape shrinks with it.

That is the before-and-after loop I want from a tutorial like this. We did not just say “JFR is useful.” We used it to point at one mistake, changed the code, and confirmed the shape changed.

Run the same workflow in a Podman container

The Quarkus container image guide says to build with quarkus.container-image.build=true. With quarkus-container-image-podman on the classpath, that build path uses Podman.

Build the image:

./mvnw install -Dquarkus.container-image.build=true

Now run it and write the recording to a host-mounted directory:

mkdir -p recordings

podman run --rm -p 8080:8080 \
  -v "$(pwd)/recordings:/recordings" \
  -e JAVA_OPTS_APPEND="-XX:StartFlightRecording=name=requestwatch,settings=profile,dumponexit=true,filename=/recordings/requestwatch-container.jfr" \
  requestwatch/requestwatch-jfr:1.0.0

That JAVA_OPTS_APPEND trick works because the generated JVM Dockerfile uses Red Hat’s run-java.sh launcher. It appends your extra JVM flags instead of making you replace the whole startup command.

Drive the same endpoints, stop the container, and open recordings/requestwatch-container.jfr in JMC or with the jfr CLI. The workflow stays the same. That is the nice part.

Close the loop

I do not think the lesson here is “install one more observability tool.” The useful part is seeing that performance problems have different shapes, and logs plus coarse metrics often flatten those shapes into one vague latency number. In one Quarkus recording we lined up a fast control path, lock-bound waiting, allocation pressure, and startup work that should not hide from you. That is enough to make JFR practical. You do not need to turn into a JVM specialist. You need to know what you are looking for when a request is slow and CPU still looks calm.

The full source for requestwatch-jfr is on my GitHub.

Subscribe now

Model Routing in Quarkus LangChain4j with Ollama

Markus — Wed, 03 Jun 2026 06:08:24 +0000

ForgeCI’s on-call queue looked fine until someone opened the inference bill. “What flag disables cache?” and “why does my pipeline OOM only on cached arm64 builds?” both hit the same model at the same per-token rate. The cheap questions subsidized the expensive ones.

This tutorial fixes that. We build ForgeAssist : a Quarkus service that classifies each incoming prompt, routes it to the cheapest Ollama model that can plausibly handle it, and logs the routing decision without blocking the HTTP response. The sample stays small: one enum, one AI service, one router, one observer, and one REST endpoint.

What you will be able to do

By the end you can:

Configure multiple named Ollama model instances in one Quarkus application.
Declare a structured-output AiService that returns a Java enum from an LLM.
Inject named ChatModel beans programmatically and pick between them at runtime.
Fire a CDI event to make routing decisions observable without polluting the response path.
Write a @QuarkusTest that asserts routing behavior instead of answer quality.

What we build

ForgeAssist exposes POST /assist with a plain-text question body. Every request flows through a classifier on the fast lane (qwen2.5:0.5b), then dispatches to either the fast lane or the power lane (llama3.2) based on a Complexity enum. A CDI observer logs the decision asynchronously.

The request lands on the REST resource, the router asks the classifier on the fast model, then it picks a lane, returns the answer, and fires an async routing event on the way out.

[

](https://substackcdn.com/image/fetch/$s_!XOgX!,f_auto,q_auto:good,fl_progressive:steep/https%3A%2F%2Fsubstack-post-media.s3.amazonaws.com%2Fpublic%2Fimages%2F1b40f15d-b0b6-40de-b88c-bbbc317f4a2c_6355x2520.png)

Named model — a second configuration block in application.properties, distinguished by a string identifier.

AiService — a Java interface Quarkus implements at build time by calling an LLM.

Structured output — the return type drives schema-aware parsing; you do not hand-parse enum strings.

@ModelName — a LangChain4j CDI qualifier that selects which named model bean to inject.

CDI event — decoupled notification; fire() is synchronous, fireAsync() is asynchronous.

What you need

You have written @QuarkusTest before and know what a LangChain4j AI service interface looks like.

JDK 25 (java -version)
Maven 3.9+ (mvn -version)
Ollama installed and running (ollama serve)
Models pulled: ollama pull qwen2.5:0.5b and ollama pull llama3.2
Quarkus CLI installed (quarkus --version) — optional; Maven wrapper works fine
About two ☕️☕️

Project setup

quarkus create app dev.forgeassist:forgeassist-routing \
  --package-name=dev.forgeassist \
  --extension='quarkus-rest,quarkus-langchain4j-ollama,quarkus-arc' \
  --java=25 \
  --no-code
cd forgeassist-routing

When you add the Ollama extension, the generator also adds quarkus-langchain4j-bom to dependencyManagement.

Add test dependencies to pom.xml:

 <dependency>
            <groupId>io.quarkus</groupId>
            <artifactId>quarkus-junit-mockito</artifactId>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>io.rest-assured</groupId>
            <artifactId>rest-assured</artifactId>
            <scope>test</scope>
        </dependency>

Run a quick sanity check before business logic:

quarkus dev

Quarkus should start and Dev UI should be at http://localhost:8080/q/dev. No model call happens yet. We are only confirming the extension graph wires up.

Configure two Ollama models

This block is the spine of the tutorial. Misread it and you will debug phantom CDI issues for an hour.

src/main/resources/application.properties:

quarkus.application.name=forgeassist-routing

# Explicit host Ollama — Dev Services off for teaching clarity
quarkus.langchain4j.ollama.devservices.enabled=false
quarkus.langchain4j.ollama.base-url=http://localhost:11434

# Power lane (default unnamed bean)
quarkus.langchain4j.ollama.chat-model.model-id=llama3.2
quarkus.langchain4j.ollama.chat-model.temperature=0.7
quarkus.langchain4j.timeout=60s

# Fast lane (named "fast")
quarkus.langchain4j.fast.chat-model.provider=ollama
quarkus.langchain4j.ollama.fast.base-url=${quarkus.langchain4j.ollama.base-url}
quarkus.langchain4j.ollama.fast.chat-model.model-id=qwen2.5:0.5b
quarkus.langchain4j.ollama.fast.chat-model.temperature=0.0
quarkus.langchain4j.ollama.fast.timeout=15s

Named model config has two parts: quarkus.langchain4j.<name>.* at the provider level and quarkus.langchain4j.ollama.<name>.* for Ollama-specific settings. Leave <name> out and you configure the default bean. Add fast and CDI gets a second bean exposed through @ModelName("fast"). The quarkus.langchain4j.fast.chat-model.provider=ollama line matters; skip it and the named lane does not resolve cleanly.

Temperature 0.0 on the fast model is deliberate. The classifier must be deterministic; a stochastic classifier that occasionally says SIMPLE when it means COMPLEX defeats the purpose.

Dev Services is off on purpose. Quarkus LangChain4j can auto-start Ollama and pull models in dev mode, which is convenient locally and bad for a tutorial that is supposed to show the real endpoint and the real failure path.

One quick sanity check before you move on: if Dev Services is off and Ollama is unreachable, or qwen2.5:0.5b is missing, what does the first AI request do? Make the prediction, then try it. That is the failure you want to recognize later when the logs are less friendly.

The complexity enum

I use a binary enum rather than SIMPLE / MODERATE / COMPLEX. More tiers need more calibration and prompt tuning, and they only help when you have three meaningfully different models to route to. Start with two lanes; extend later if the economics justify it.

src/main/java/dev/forgeassist/Complexity.java:

package dev.forgeassist;

public enum Complexity {

    /**
     * Factual lookups, single-step how-tos, definitional questions.
     * Examples: "What does --dry-run do?", "List the ForgeCI environment
     * variables."
     */
    SIMPLE,

    /**
     * Multi-step reasoning, debugging with context, architectural trade-offs,
     * ambiguous or environment-specific problems.
     * Examples: "Why does my pipeline OOM only on cached arm64 builds?"
     */
    COMPLEX
}

The classifier AiService

Quarkus LangChain4j can return Java types from an AiService method, not just String. With an enum return type, the framework injects the enum schema into the prompt and deserializes the response, so there is no hand-rolled parsing code. The trade-off is still real: a confused model can return something unparseable. For a two-lane classifier with a small context window, I think that risk is low enough.

src/main/java/dev/forgeassist/PromptClassifier.java:

package dev.forgeassist;

import dev.langchain4j.service.SystemMessage;
import dev.langchain4j.service.UserMessage;
import io.quarkiverse.langchain4j.RegisterAiService;

@RegisterAiService(modelName = "fast")
public interface PromptClassifier {

    @SystemMessage("""
            You are a prompt complexity classifier for ForgeCI, a CI/CD platform.
            Classify the user's question into exactly one of: SIMPLE, COMPLEX.

            SIMPLE: factual lookups, flag definitions, single-step how-tos,
                    questions answerable from documentation alone.

            COMPLEX: debugging with environment context, multi-step reasoning,
                     architectural trade-offs, questions that require inference
                     beyond what documentation states.

            Respond with ONLY the enum value. No punctuation. No explanation.
            """)
    Complexity classify(@UserMessage String prompt);
}

modelName = "fast" on the classifier matters. Classification is already the cheap job. Using the power model to decide whether to use the power model is circular and a little silly.

The system prompt uses ForgeCI-flavored examples on purpose. Generic “SIMPLE: short questions” prompts look tidy and perform worse once you hit the awkward edge cases.

At the wire, a simple flag question looks like this:

{
  "model": "qwen2.5:0.5b",
  "messages": [
    {
      "role": "system",
      "content": "You are a prompt complexity classifier..."
    },
    {
      "role": "user",
      "content": "What does the --no-cache flag do in forge build?"
    }
  ]
}

Response: SIMPLE

Routing decision record

We define the record first so the fireAsync line later is moving a real type, not a mystery blob.

src/main/java/dev/forgeassist/RoutingDecision.java:

package dev.forgeassist;

import java.time.Instant;

/**
 * Immutable record of a single model routing decision.
 * Fired as a CDI event; consumed by observers for logging and metrics.
 */
public record RoutingDecision(
        String prompt,
        Complexity complexity,
        String selectedModel,
        long classificationMillis,
        Instant timestamp) {

    public RoutingDecision(
            String prompt, Complexity complexity, String selectedModel, long classificationMillis) {
        this(prompt, complexity, selectedModel, classificationMillis, Instant.now());
    }
}

Records give you immutability for free. The CDI event keeps the routing decision decoupled from whoever wants to watch it, so the router does not care whether you only log today or add metrics tomorrow.

The routing event observer

src/main/java/dev/forgeassist/RoutingEventObserver.java:

package dev.forgeassist;

import org.jboss.logging.Logger;

import jakarta.enterprise.context.ApplicationScoped;
import jakarta.enterprise.event.ObservesAsync;

@ApplicationScoped
public class RoutingEventObserver {

    private static final Logger LOG = Logger.getLogger(RoutingEventObserver.class);

    public void onRoutingDecision(@ObservesAsync RoutingDecision decision) {
        LOG.infof(
                "[ROUTING] complexity=%s model=%s classificationMs=%d prompt=\"%s\"",
                decision.complexity(),
                decision.selectedModel(),
                decision.classificationMillis(),
                truncate(decision.prompt(), 80));
    }

    private static String truncate(String s, int max) {
        return s.length() <= max ? s : s.substring(0, max) + "…";
    }
}

That separation is the whole point: the observer does not know about the router, the router does not know about the observer, and adding a Micrometer counter later does not require another pass through ModelRouter.

The model router

This is the center of the sample, so we build it in layers.

Shell and injections

@ModelName is a Quarkus LangChain4j qualifier — not @Named. Injection without a qualifier resolves to the default (unnamed) bean, which is the power model here.

package dev.forgeassist;

import dev.langchain4j.model.chat.ChatModel;
import io.quarkiverse.langchain4j.ModelName;
import jakarta.enterprise.context.ApplicationScoped;
import jakarta.enterprise.event.Event;
import jakarta.inject.Inject;

@ApplicationScoped
public class ModelRouter {

    private final PromptClassifier classifier;
    private final ChatModel fastModel;
    private final ChatModel powerModel;
    private final Event<RoutingDecision> routingEvents;

    @Inject
    public ModelRouter(
            PromptClassifier classifier,
            @ModelName("fast") ChatModel fastModel,
            ChatModel powerModel,
            Event<RoutingDecision> routingEvents) {
        this.classifier = classifier;
        this.fastModel = fastModel;
        this.powerModel = powerModel;
        this.routingEvents = routingEvents;
    }

    // route() follows below
}

Classification and timing

At this point in execution, only the fast model has run (via the classifier AiService). The power model has done nothing.

public String route(String userPrompt) {
        long start = System.currentTimeMillis();
        Complexity complexity = classifier.classify(userPrompt);
        long classificationMillis = System.currentTimeMillis() - start;

        // dispatch continues below
    }

Dispatch and event

Once the target model changes at runtime, drop down to the raw LangChain4j ChatModel.chat(ChatRequest) API instead of wrapping another AiService around it.

        ChatModel selected = switch (complexity) {
            case SIMPLE -> fastModel;
            case COMPLEX -> powerModel;
        };

        ChatRequest request = ChatRequest.builder().messages(UserMessage.from(userPrompt)).build();

        String response = selected.chat(request).aiMessage().text();

        routingEvents.fireAsync(
                new RoutingDecision(
                        userPrompt,
                        complexity,
                        complexity == Complexity.SIMPLE ? "qwen2.5:0.5b" : "llama3.2",
                        classificationMillis));

        return response;
    }

Complete ModelRouter.java with imports:

package dev.forgeassist;

import dev.langchain4j.data.message.UserMessage;
import dev.langchain4j.model.chat.ChatModel;
import dev.langchain4j.model.chat.request.ChatRequest;
import io.quarkiverse.langchain4j.ModelName;
import jakarta.enterprise.context.ApplicationScoped;
import jakarta.enterprise.event.Event;
import jakarta.inject.Inject;

@ApplicationScoped
public class ModelRouter {

    private final PromptClassifier classifier;
    private final ChatModel fastModel;
    private final ChatModel powerModel;
    private final Event<RoutingDecision> routingEvents;

    @Inject
    public ModelRouter(
            PromptClassifier classifier,
            @ModelName("fast") ChatModel fastModel,
            ChatModel powerModel,
            Event<RoutingDecision> routingEvents) {
        this.classifier = classifier;
        this.fastModel = fastModel;
        this.powerModel = powerModel;
        this.routingEvents = routingEvents;
    }

    public String route(String userPrompt) {
        long start = System.currentTimeMillis();
        Complexity complexity = classifier.classify(userPrompt);
        long classificationMillis = System.currentTimeMillis() - start;

        ChatModel selected = switch (complexity) {
            case SIMPLE -> fastModel;
            case COMPLEX -> powerModel;
        };

        ChatRequest request = ChatRequest.builder().messages(UserMessage.from(userPrompt)).build();

        String response = selected.chat(request).aiMessage().text();

        routingEvents.fireAsync(
                new RoutingDecision(
                        userPrompt,
                        complexity,
                        complexity == Complexity.SIMPLE ? "qwen2.5:0.5b" : "llama3.2",
                        classificationMillis));

        return response;
    }
}

fireAsync keeps the HTTP response path clean: the caller gets the answer immediately and the observer runs asynchronously. That makes sense for diagnostics and lightweight counters. It is a bad fit for side effects you cannot afford to lose unless you also have a plan for seeing and recovering from async observer failures.

REST endpoint

src/main/java/dev/forgeassist/ForgeAssistResource.java:

package dev.forgeassist;

import jakarta.inject.Inject;
import jakarta.ws.rs.Consumes;
import jakarta.ws.rs.POST;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.core.MediaType;

@Path("/assist")
public class ForgeAssistResource {

    private final ModelRouter router;

    @Inject
    public ForgeAssistResource(ModelRouter router) {
        this.router = router;
    }

    @POST
    @Consumes(MediaType.TEXT_PLAIN)
    @Produces(MediaType.TEXT_PLAIN)
    public String ask(String question) {
        return router.route(question);
    }
}

Prove it (live Ollama)

With quarkus dev running and Ollama on http://localhost:11434

# Simple prompt — expect fast lane when classification cooperates
curl -s -X POST http://localhost:8080/assist \
  -H "Content-Type: text/plain" \
  -d "What does the --no-cache flag do in forge build?"

# Complex prompt — expect power lane
curl -s -X POST http://localhost:8080/assist \
  -H "Content-Type: text/plain" \
  -d "My ForgeCI pipeline passes locally but fails on cached arm64 runners with an OOM error only when layer cache is warm. What should I investigate first?"

You want a log line like this:

[ROUTING] complexity=SIMPLE model=qwen2.5:0.5b classificationMs=... prompt="What does the --no-cache flag do in forge build?"

The exact classificationMs value moves around, and because the log comes from an async observer it may show up just after the HTTP response. The signal that matters is complexity + model, not exact timings or identical answer text. Small classifiers will mislabel some edge cases. That is normal, and the production section below is where the trade-off starts to matter.

Production risks

Once this works in dev, the pleasant part is over. These are the problems that show up in a real team.

Misclassification is more expensive than over-routing. The dangerous failure mode is a debugging-heavy prompt stamped SIMPLE and sent to the cheap lane, which then answers confidently and badly. When in doubt, route up, not down.

Logging the raw prompt is a demo convenience. Prompt text can contain tokens, stack traces, customer data, or internal hostnames. Production systems often hash, redact, or sample this field.

Routing adds a second model hop. Latency is now classification plus answer. Keep the classifier on a fast local model, but set explicit timeout boundaries on both lanes and decide what the API does when classification times out.

fireAsync() buys latency at the cost of failure visibility. Observer failures are harder to spot than synchronous method failures. If the event becomes business-critical, move that concern to a durable mechanism instead of pretending CDI async delivery is a queue.

Dev Services is a local convenience, not production topology. The app talks to a known Ollama endpoint, models must already exist there, and health checks should reflect that dependency honestly.

Tests

LLM output moves around, so tests that assert answer content age badly. The deterministic part, and the part worth locking down first, is the routing behavior: did the classifier run, and did the router pick the expected lane? The HTTP layer is deterministic too: did POST /assist delegate to the router?

Use @InjectMock with Mockito. ModelRouterTest replaces the classifier and both ChatModel beans so the router never calls Ollama. ForgeAssistResourceTest replaces the router so the HTTP test stays thin and boring, which is exactly what you want from a resource test.

I would not make the first tutorial test about asynchronous CDI delivery. Readers need to trust the lane decision before they care about observer scheduling.

src/test/java/dev/forgeassist/ModelRouterTest.java:

package dev.forgeassist;

import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.mockito.ArgumentMatchers.any;
import static org.mockito.Mockito.clearInvocations;
import static org.mockito.Mockito.verify;
import static org.mockito.Mockito.verifyNoInteractions;
import static org.mockito.Mockito.when;

import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;

import dev.langchain4j.data.message.AiMessage;
import dev.langchain4j.model.chat.ChatModel;
import dev.langchain4j.model.chat.request.ChatRequest;
import dev.langchain4j.model.chat.response.ChatResponse;
import io.quarkiverse.langchain4j.ModelName;
import io.quarkus.test.InjectMock;
import io.quarkus.test.junit.QuarkusTest;
import jakarta.inject.Inject;

@QuarkusTest
class ModelRouterTest {

    @Inject
    ModelRouter router;

    @InjectMock
    PromptClassifier classifier;

    @InjectMock
    @ModelName("fast")
    ChatModel fastModel;

    @InjectMock
    ChatModel powerModel;

    @BeforeEach
    void stubModels() {
        when(fastModel.chat(any(ChatRequest.class))).thenReturn(response("fast-lane"));
        when(powerModel.chat(any(ChatRequest.class))).thenReturn(response("power-lane"));
        clearInvocations(fastModel, powerModel);
    }

    @Test
    void simplePromptUsesFastLane() {
        String prompt = "What does the --no-cache flag do in forge build?";
        when(classifier.classify(prompt)).thenReturn(Complexity.SIMPLE);
        clearInvocations(classifier);

        String answer = router.route(prompt);

        assertEquals("fast-lane", answer);
        verify(classifier).classify(prompt);
        verify(fastModel).chat(any(ChatRequest.class));
        verifyNoInteractions(powerModel);
    }

    @Test
    void complexPromptUsesPowerLane() {
        String prompt = "Why does my pipeline OOM only on cached arm64 builds?";
        when(classifier.classify(prompt)).thenReturn(Complexity.COMPLEX);
        clearInvocations(classifier);

        String answer = router.route(prompt);

        assertEquals("power-lane", answer);
        verify(classifier).classify(prompt);
        verify(powerModel).chat(any(ChatRequest.class));
        verifyNoInteractions(fastModel);
    }

    private static ChatResponse response(String text) {
        return ChatResponse.builder().aiMessage(AiMessage.from(text)).build();
    }
}

src/test/java/dev/forgeassist/ForgeAssistResourceTest.java:

package dev.forgeassist;

import static io.restassured.RestAssured.given;
import static org.hamcrest.Matchers.is;
import static org.mockito.Mockito.when;

import org.junit.jupiter.api.Test;

import io.quarkus.test.InjectMock;
import io.quarkus.test.junit.QuarkusTest;

@QuarkusTest
class ForgeAssistResourceTest {

    @InjectMock
    ModelRouter router;

    @Test
    void assistEndpointDelegatesToRouter() {
        when(router.route("What does --no-cache do?")).thenReturn("fast-lane");

        given()
                .contentType("text/plain")
                .body("What does --no-cache do?")
                .when()
                .post("/assist")
                .then()
                .statusCode(200)
                .body(is("fast-lane"));
    }
}

Run tests (no running Ollama required for assertions):

./mvnw test

Expect BUILD SUCCESS and 3 tests.

Extension exercises

If you still feel adventurous. Some homework ideas:

Three-tier routing — Add MODERATE to the enum, introduce a third Ollama model (for example qwen2.5:3b), and update the system prompt and switch expression. How does the classifier prompt need to change to distinguish MODERATE from both SIMPLE and COMPLEX?

Confidence-aware routing — Return a record ClassificationResult(Complexity complexity, int confidencePercent) instead of a bare enum. Route SIMPLE classifications with confidencePercent < 70 to the power model as a fallback.

Micrometer metrics observer — Add a second CDI observer that increments a Counter per complexity tier and expose the metrics endpoint.

Dev Services contrast — If you have Docker available, try Quarkus Dev Services for Ollama and compare startup experience with the explicit host configuration used here.

Close the loop

ForgeAssist classifies each prompt on a cheap local model, routes SIMPLE questions to qwen2.5:0.5b, routes COMPLEX ones to llama3.2, and logs the decision without blocking the caller. That fixes the opening problem: trivial and heavy questions no longer burn the same expensive default.

Subscribe now

What Should Go in an AGENTS.md File?

Markus — Tue, 02 Jun 2026 06:08:50 +0000

I tend to like the AI post where somebody shares a CLAUDE.md or repo rule file, says “these 21 rules changed everything,” and then the quote tweet count starts to explode.

I like those posts more than most AI productivity advice because they point to something real. A coding agent gets much better once it stops guessing how your project works. The model name, the filename, and the exact rule count are the forgettable parts.

That sounds obvious until you watch one work without any local guidance.

By default, a coding model knows a lot about syntax and just enough about software engineering to be dangerous in the same cheerful way a junior engineer with root access would be dangerous. It can produce code. It can explain code. It can also decide that your tiny bug fix is a great time to “clean up” three unrelated files, assume a requirement you never stated, and speak about its own uncertainty with the confidence of a generated release note.

This breaks for a simpler reason: missing local context. Your agent does not know what “done” means in this repo, which changes are out of bounds, which conventions are non-negotiable, or when it should stop and ask instead of making its own decisions.

That is what the instruction file is for.

Call it AGENTS.md, CLAUDE.md, repo rules, or a small pile of working notes. The name matters a lot less than the job. You are giving the agent an operating manual for this codebase so it can stop guessing its way through every task.

The four rules that pull the most weight

I do not think the magic number is 21. Four rules do most of the real work.

Ask instead of assume.

If requirements are unclear, the agent should surface the ambiguity instead of silently choosing a path. Wrong confidence is more expensive than one extra question.
Start with the smallest working change.

Agents love broad cleanup because it gives them more surface area to look helpful on. That rarely means the task is going well, so I would strongly prefer small, reversible diffs.
Do not touch unrelated code.

Most teams do not mind extra polish in theory. They mind it very much when a review gets slow because the assistant “also improved” files nobody asked about.
Flag uncertainty before acting.

A decent agent should know the difference between “I found the bug” and “I have a plausible theory.” The second state is fine. Hiding it is not.

Those four rules are bigger than any one model. They are the difference between an assistant and an intern who keeps rearranging your desk while answering the wrong question.

What the file is really doing

I think of a good agent instruction file as a boundary-setting document. Its job is to reduce four common failure modes.

Scope drift

The agent starts on a bug fix, notices a naming inconsistency, then notices an outdated helper, then notices a nearby refactor opportunity, and suddenly your one-line change reaches much farther than it should. A rules file tells it what “stay in scope” actually means here.

Bad defaults

Every model comes with habits. Some over-explain. Some rush to code. Some make confident assumptions to keep the turn moving. Some will happily take a destructive action if you did not explicitly say “ask first.” If you do not set the defaults, the model will.

Decision loss

Longer sessions get weird because the model forgets which trade-offs were already settled. You said no refactor. Later it proposes one. You said keep the old API. Later it “improves” it. This is where a tiny memory stack helps more than another clever prompt.

Polite nonsense

This is my least favorite failure mode. The model has partial evidence, but it keeps writing as if it has a proof. A good working agreement makes uncertainty a first-class output, not an embarrassment to hide.

That is why the screenshot-style rule sets often split into three buckets: defaults, behavior, and memory. I think that split is sane, and I would keep it.

What to put in a generalized `AGENTS.md`

If I were writing one file meant to survive changing models, I would keep these sections.

Defaults

This is where you define the repo’s normal operating mode.

Keep changes narrow and task-focused
Prefer the simplest fix that works
Match existing style unless the task is explicitly a redesign
Ask before destructive actions
Explain what changed in plain language
Do not invent requirements, APIs, or test results

Defaults matter because they catch the moments when the prompt is too short to say all of that again.

Behavior

This section tells the agent how to work, not just what to produce.

Restate the task in concrete terms before making major changes
Confirm assumptions when they change behavior or risk
Show diffs or summarize edits clearly
Stop if the new plan expands beyond the original ask
Keep the user in the loop before irreversible steps

This is about visibility, not ceremony. Most people can tolerate an agent being wrong for a turn. They get annoyed when it is wrong and quiet about it.

Memory

This is the part many teams skip, and for me it is where a lot of the quality gain comes from.

Your agent does not just need rules. It needs a place to pin decisions that should survive the next twenty turns.

DECISIONS.md for active trade-offs and chosen direction
KNOWN_ISSUES.md or ERRORS.md for failures already observed
SESSION.md for where work stopped and what should happen next
Permanent facts for “never rename this endpoint” or “this file mirrors an external contract”

You do not need all of these in every repo. You just need enough memory to stop paying for the same rediscovery loop over and over.

Escalation

This is where the agent learns when to slow down.

Ask when two paths have different product consequences
Ask when requirements conflict with existing constraints
Ask before deleting, renaming, or migrating broad surfaces
Say when confidence is low
Prefer a question over a fake conclusion

If you only add one behavioral rule, make it this kind of rule. A coding agent that escalates well is dramatically easier to trust.

A template I would actually use

Here is a generalized version I would be comfortable dropping into a project root today:

# AGENTS.md

## Goal

Help with this repository by making the smallest correct change that solves the
requested task.

## Defaults

- Stay within the requested scope
- Prefer the simplest working fix over broad rewrites
- Match existing code style and project structure
- Do not edit unrelated files just because they could be improved
- Ask before destructive or irreversible actions
- Do not claim tests passed unless you actually ran them
- Do not invent requirements, endpoints, configs, or results

## Working style

- Restate the task briefly before major edits
- Surface assumptions when they affect behavior
- Show what changed and why
- Keep diffs easy to review
- Stop and ask if the task expands into a refactor or redesign

## Uncertainty

- Flag low-confidence conclusions explicitly
- Prefer "I need to verify X" over guessing
- When there are multiple reasonable paths, present the trade-off

## Memory

- Read `DECISIONS.md` before making architectural changes
- Read `KNOWN_ISSUES.md` before debugging recurring failures
- Update `SESSION.md` with current status when work stops mid-task
- Treat pinned project facts as constraints, not suggestions

## Guardrails

- Never hide uncertainty behind polished wording
- Never change public contracts without calling it out
- Never mix requested work with opportunistic cleanup unless asked

That file is boring, which is exactly what you want here. The best rule file in a repo is usually the one that prevents avoidable messes, not the one that sounds smartest on social media.

This is really about interface design

What I like about these rule-file experiments is that they quietly move the conversation away from model hype and back toward engineering.

Better outcomes do not come only from upgrading the model. You also get them by improving the interface between the model and the project. A local instruction file, a short decision log, and a few explicit escalation rules can do more for day-to-day quality than another round of “which coding assistant is winning this week.”

That is also why I would generalize the idea well beyond Claude.

AGENTS.md is a better mental model than CLAUDE.md if you want something durable. Models change. Product names change. The failure modes stay stubbornly the same. Every coding agent needs help with scope, defaults, uncertainty, and memory. If your team solves those once in versioned text, you do not have to solve them again from scratch every time a new assistant shows up with a shinier demo.

The real win

For me, the win is simpler than “21 rules made the model smarter.” The model stopped having to guess what kind of teammate it was supposed to be, which is a much more useful improvement anyway.

If you use coding agents seriously, give them a local operating manual. Keep it short, keep it opinionated, and keep it honest about boundaries. Then add just enough memory that the same wrong turn does not have to be rediscovered every Tuesday.

For me, that is just good interface design for a very fast, very eager collaborator.

Subscribe now

Quarkus Graceful Shutdown That Holds Up During Rolling Deploys

Markus — Mon, 25 May 2026 06:08:54 +0000

Rolling deploys are when I find out a service was never really ready to go away. The pod gets a SIGTERM, the load balancer still has the instance in rotation for another probe interval, and a payment handoff that was fine a second ago comes back as 503 Service Unavailable or just drops the connection. The app looked healthy in unit tests. Production was doing a choreographed shutdown and nobody told the JVM.

Quarkus has had graceful shutdown settings for a while. In Quarkus 3.32 the HTTP stack got a meaningful upgrade (PR #50975): during shutdown it tries to answer requests instead of spraying 503 at everything. That helps. It does not replace the deploy protocol you still need: fail readiness, stop new traffic, let in-flight HTTP finish, then exit.

We build OrderBridge , a tiny payment handoff API, then prove shutdown behavior with a script that keeps a long request in flight while the JVM receives SIGTERM. The sample uses Quarkus 3.35.2.

What we build

OrderBridge is a small service that:

exposes GET /orders/{id} for a quick status check;
exposes POST /orders/handoff that simulates a five-second payment gateway call;
exposes SmallRye Health liveness and readiness on /q/health/live and /q/health/ready;
logs startup, shutdown delay, and shutdown events;
ships two Quarkus profiles: naive (defaults) and graceful (timeout + delay);
includes a bash script that terminates the packaged app mid-handoff so you can see the difference.

What you need

I assume you have shipped Jakarta REST apps and have seen Kubernetes readiness probes in the wild. This is not a hello-world.

JDK 21
Quarkus CLI or Maven
curl and bash for the shutdown script
About 40 minutes

Project setup

Create the project:

quarkus create app com.orderbridge:orderbridge-graceful-shutdown \
  --extension='rest-jackson,smallrye-health' \
  --java=21 \
  --no-code
cd orderbridge-graceful-shutdown

Extensions:

rest-jackson — JSON endpoints and the HTTP stack that participates in graceful shutdown
smallrye-health — readiness and liveness probes

Use package com.orderbridge for application code.

Add the Maven wrapper from the Quarkus getting started guide if your tree does not already include ./mvnw, or clone the finished sample linked at the end.

Order status and payment handoff

Payment handoffs are the interesting case: they run for seconds while deploys happen for seconds. A fast status endpoint gives us something cheap to hit while the slow one is in flight.

DTO records

package com.orderbridge;

public record HandoffRequest(String orderId, long amountCents) {
}


package com.orderbridge;

public record HandoffResult(String orderId, String status, long elapsedMs) {
}


package com.orderbridge;

public record OrderStatus(String orderId, String status) {
}

OrderService

The handoff sleeps to mimic an external gateway. Production code should use timeouts, cancellation, and idempotency keys — not Thread.sleep. For teaching shutdown, sleep is honest about “long request in flight.”

package com.orderbridge;

import java.util.Map;
import java.util.concurrent.ConcurrentHashMap;

import org.eclipse.microprofile.config.inject.ConfigProperty;
import org.jboss.logging.Logger;

import jakarta.enterprise.context.ApplicationScoped;

@ApplicationScoped
public class OrderService {

    private static final Logger LOG = Logger.getLogger(OrderService.class);

    private final Map<String, String> statuses = new ConcurrentHashMap<>();

    @ConfigProperty(name = "orderbridge.handoff.delay-ms", defaultValue = "5000")
    long handoffDelayMs;

    public OrderStatus status(String orderId) {
        String status = statuses.getOrDefault(orderId, "CREATED");
        return new OrderStatus(orderId, status);
    }

    public HandoffResult handoff(HandoffRequest request) {
        long started = System.currentTimeMillis();
        LOG.infof("Starting payment handoff for order %s", request.orderId());
        statuses.put(request.orderId(), "HANDOFF_IN_PROGRESS");

        try {
            Thread.sleep(handoffDelayMs);
        } catch (InterruptedException interrupted) {
            Thread.currentThread().interrupt();
            statuses.put(request.orderId(), "HANDOFF_INTERRUPTED");
            throw new IllegalStateException("Payment handoff interrupted during shutdown", interrupted);
        }

        statuses.put(request.orderId(), "HANDOFF_COMPLETE");
        long elapsedMs = System.currentTimeMillis() - started;
        LOG.infof("Payment handoff complete for order %s in %d ms", request.orderId(), elapsedMs);
        return new HandoffResult(request.orderId(), "HANDOFF_COMPLETE", elapsedMs);
    }
}

OrderResource

package com.orderbridge;

import jakarta.ws.rs.Consumes;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.POST;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.PathParam;
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.core.MediaType;

@Path("/orders")
@Produces(MediaType.APPLICATION_JSON)
@Consumes(MediaType.APPLICATION_JSON)
public class OrderResource {

    private final OrderService orderService;

    public OrderResource(OrderService orderService) {
        this.orderService = orderService;
    }

    @GET
    @Path("/{id}")
    public OrderStatus get(@PathParam("id") String orderId) {
        return orderService.status(orderId);
    }

    @POST
    @Path("/handoff")
    public HandoffResult handoff(HandoffRequest request) {
        return orderService.handoff(request);
    }
}

Base configuration

In src/main/resources/application.properties:

orderbridge.handoff.delay-ms=5000

%script.quarkus.http.port=18080
%script.quarkus.log.console.level=INFO

%graceful.quarkus.shutdown.timeout=15s
%graceful.quarkus.shutdown.delay-enabled=true
%graceful.quarkus.shutdown.delay=5s

%test.orderbridge.handoff.delay-ms=100
%test.quarkus.shutdown.timeout=30s
%test.quarkus.shutdown.delay-enabled=true
%test.quarkus.shutdown.delay=2s

The script profile pins port 18080 so our shutdown script does not fight dev mode on 8080. The graceful profile turns on the shutdown recipe we want in production. Tests use a 100 ms handoff so ./mvnw test stays snappy.

Run dev mode and try the endpoints:

./mvnw quarkus:dev


curl -s http://localhost:8080/orders/ORD-1
curl -s -X POST http://localhost:8080/orders/handoff \
  -H 'Content-Type: application/json' \
  -d '{"orderId":"ORD-1","amountCents":2500}'

The handoff blocks for about five seconds, then returns "status":"HANDOFF_COMPLETE".

Readiness vs liveness during shutdown

Liveness answers: is the process alive? If this fails, Kubernetes restarts the pod.

Readiness answers: should traffic be sent here? If this fails, the pod stays running but is removed from Service endpoints.

During a rolling update, you want readiness to flip DOWN while the instance can still finish work it already accepted. That is exactly what Quarkus shutdown delay is for. The lifecycle guide describes a delay window where HTTP still runs, but readiness reports down so orchestrators and load balancers stop sending new connections.

Check probes manually:

curl -s http://localhost:8080/q/health/live
curl -s http://localhost:8080/q/health/ready

While the app is running, both return "status":"UP".

See naive shutdown hurt the client

With no quarkus.shutdown.timeout and no delay, Quarkus does not wait for your handoff the way you expect. The server log may still show “handoff complete,” while the client sees a dead connection.

The module ships scripts/demonstrate-shutdown.sh. It packages the app, starts the JVM, fires a long POST /orders/handoff, sends SIGTERM, and polls readiness.

Run the naive profile (script port only — no graceful settings):

./scripts/demonstrate-shutdown.sh naive

On my machine the handoff line looked like:

handoff HTTP 000 (total 0.521690s)

HTTP 000 means curl never got a response — connection gone. The log often still shows the handoff finishing a few seconds later, which is the frustrating split-brain: server thought it was fine, client already gave up.

That is the bug we are fixing: shutdown was never part of the contract we tested.

Add `quarkus.shutdown.timeout`

quarkus.shutdown.timeout is a runtime setting. When set, Quarkus waits for active HTTP requests to complete before tearing down, up to the limit. The lifecycle guide documents it; it is off by default.

Add only the timeout first (you can use a throwaway profile or add it to %graceful later):

quarkus.shutdown.timeout=15s

Too short — in-flight handoffs get cut off; clients see resets or errors even though the pod had time to drain.

Too long — deploys stall because Kubernetes will eventually send SIGKILL when terminationGracePeriodSeconds runs out.

Fifteen seconds is generous for our five-second fake gateway, but it leaves headroom for real network jitter.

Enable shutdown delay (readiness first)

Timeout alone does not tell the load balancer to stop new traffic early. For that you need delay:

quarkus.shutdown.delay-enabled=true — build time. You must package the app with this set; flipping it only at runtime is not enough.
quarkus.shutdown.delay — runtime duration of the pre-shutdown phase.

Our %graceful profile sets:

%graceful.quarkus.shutdown.timeout=15s
%graceful.quarkus.shutdown.delay-enabled=true
%graceful.quarkus.shutdown.delay=5s

Package with the graceful profile baked in:

./mvnw package -DskipTests -Dquarkus.profile=graceful,script

What happens on SIGTERM with delay enabled:

Delay phase starts. Readiness goes DOWN (SmallRye reports a Graceful Shutdown check).
Existing connections can still complete work.
After the delay, Quarkus moves toward full shutdown, honoring quarkus.shutdown.timeout for active HTTP.
Process exits.

Run the script in graceful mode:

./scripts/demonstrate-shutdown.sh graceful

Excerpt from a successful run:

-- Readiness before shutdown: UP --
ready HTTP 200
-- Polling readiness during shutdown --
[15:24:23] readiness HTTP 503
[15:24:24] readiness HTTP 503
...
-- Handoff result --
{"orderId":"ORD-SHUTDOWN","status":"HANDOFF_COMPLETE","elapsedMs":5003}
handoff HTTP 200 (total 5.101526s)

Readiness flips to 503 while the handoff still returns 200. That is the protocol you want: orchestrator sees “not ready,” client already in flight gets an answer.

Lifecycle hooks for visibility

Observers make the sequence visible in logs — useful when someone swears “readiness failed too early.”

package com.orderbridge;

import org.jboss.logging.Logger;

import io.quarkus.runtime.ShutdownEvent;
import io.quarkus.runtime.StartupEvent;
import io.quarkus.runtime.ShutdownDelayInitiatedEvent;
import jakarta.enterprise.context.ApplicationScoped;
import jakarta.enterprise.event.Observes;

@ApplicationScoped
public class ShutdownLifecycle {

    private static final Logger LOG = Logger.getLogger(ShutdownLifecycle.class);

    void onStart(@Observes StartupEvent event) {
        LOG.info("OrderBridge is ready to accept traffic");
    }

    void onShutdownDelay(@Observes ShutdownDelayInitiatedEvent event) {
        LOG.info("Shutdown delay started — readiness should fail while HTTP still winds down");
    }

    void onStop(@Observes ShutdownEvent event) {
        LOG.info("OrderBridge shutdown event fired");
    }
}

You can use @ShutdownDelayInitiated on a method instead of the event observer; behavior is the same. Methods marked that way run when delay starts — keep them fast, because they participate in the shutdown path.

In graceful mode you should see Shutdown delay started before OrderBridge shutdown event fired, and SmallRye log lines like Reporting health down status with a Graceful Shutdown check.

Kubernetes timing that actually matches Quarkus

Quarkus only controls what happens inside the pod after SIGTERM. Your platform still needs enough time and sensible probes.

terminationGracePeriodSeconds — must be at least delay + timeout + buffer. With our example (5s delay + 15s timeout), I would not go below 25s; 30s is a comfortable default.

Readiness probe periodSeconds and failureThreshold — control how quickly the Service removes the pod from endpoints. If the probe period is 10s and threshold is 3, it can take ~30s before Kubernetes stops routing even after readiness is DOWN. Align that with how fast your ingress or service mesh drains.

preStop hooks — optional sleep can help legacy load balancers that ignore readiness. Prefer fixing probe and delay alignment first; arbitrary sleep 15 in preStop hides misconfiguration.

Liveness during shutdown — do not point liveness at something that fails during graceful drain unless you want the kubelet to restart a pod that is intentionally winding down.

What graceful shutdown does not cover

The lifecycle guide is explicit: only extensions that opt in participate. Today the documented graceful path is HTTP. Kafka consumers, scheduled jobs, and background queues need their own drain story.

Long business work still needs application-level timeouts. quarkus.shutdown.timeout bounds how long Quarkus waits on HTTP; it does not make an unbounded database migration safe.

Native image and dev mode follow the same configuration ideas, but always re-run your shutdown script on the artifact you actually deploy.

Prove it

Unit and resource tests:

./mvnw test

Integration test against the packaged runner:

./mvnw verify

Shutdown demonstrations:

./scripts/demonstrate-shutdown.sh naive
./scripts/demonstrate-shutdown.sh graceful

Expect naive mode to show readiness dropping only when the process is already gone, and the handoff client to fail often. Expect graceful mode to show readiness 503 for several seconds and the handoff to finish with HTTP 200.

Closing

Graceful shutdown in Quarkus is a small set of properties, but the real work is the deploy protocol: readiness fails first, new traffic stops, in-flight HTTP gets a bounded chance to finish, then the process exits. The 3.32 HTTP improvements reduce surprise 503 responses during that window; they do not remove the need for delay and timeout.

When you wire this into a real service, copy the recipe: enable delay at build time, set delay and timeout for your slowest acceptable request, align Kubernetes termination and probes, and keep a script like ours that proves behavior under SIGTERM, not just in a happy-path integration test.

Source for the full sample lives in the orderbridge-graceful-shutdownrepository.

Subscribe now

Teach a Local Model an Agent Command With LoRA

Markus — Thu, 21 May 2026 06:11:10 +0000

When developers see agents in action, the discussion usually lands on harnesses or raw model capability. If the result is weak, the next suggestion is predictable: use a bigger model, add a smarter planner, bolt on more tools, or find a fancier framework that promises to keep the whole thing under control.

Some of that helps. Some of it is also a distraction. Agent systems do not fail only because the model is too small or the harness is too simple. They also fail because the model is unreliable at the tiny private contracts that make cooperative behavior possible: route labels, planner tags, tool payloads, hand-off markers, or one odd internal command that means “switch into protocol mode now.”

That is the part people tend to miss. Effective agent teams are not just a story about capabilities. They are a story about capabilities plus adapters. Tools give the model reach. Adapters can give it a repeatable behavior inside one narrow lane, which is often the difference between “interesting demo” and “system I can actually wire into code.”

This tutorial uses a deliberately small example to make that visible. We are going to teach a local model one agent-specific trick and then make Quarkus prove whether it learned the trick or not.

Here is the prompt that should make an agent developer slightly nervous:

devcard Dev Services with PostgreSQL

A human can guess what that means. A small local model usually cannot. It may ignore devcard, turn the whole thing into a normal explanation, or produce JSON that looks close enough to fool you right up to the moment your parser throws an exception.

That is a real agent problem. Prompting helps, but small models are not consistently obedient just because we put “return JSON only” in uppercase.

This is where LoRA becomes interesting in a way that is easy to show and honest to explain. We are not going to teach the model all of Quarkus. We are going to teach it one repeatable habit:

when the prompt contains devcard, emit a strict JSON object
when the prompt does not contain devcard, answer like a normal assistant

That sounds small because it is small. That is also why it makes a good tutorial. The adapter effect is visible, the Quarkus app stays understandable, and the agentic point is hard to miss.

By the end, we will have a local Quarkus app that compares the base model with the adapted one side by side, validates the output, and renders a deterministic developer card only when the model follows the contract.

What We Build

The flow is intentionally boring:

[

](https://substackcdn.com/image/fetch/$s_!gpOL!,f_auto,q_auto:good,fl_progressive:steep/https%3A%2F%2Fsubstack-post-media.s3.amazonaws.com%2Fpublic%2Fimages%2Fb862ab46-7142-4c64-bcee-c8799c25c2d1_2213x2310.png)

The contract looks like this:

{
  "command": "devcard",
  "topic": "dev-services",
  "technologies": ["postgresql"],
  "includeExample": true,
  "includeWarning": true
}

The model is only responsible for producing that object. The Quarkus app does the rest. That split matters because it is how real agent systems stay sane: let the model classify or structure the request, then let ordinary code validate, route, and render.

One more detail is worth saying out loud before we start. The MLX LM docs note that if you train against a quantized model, the command uses QLoRA under the covers. We are going to use the default 4-bit MLX model from the README, so the mechanics here are technically QLoRA. I am still using “LoRA” in the article title and the everyday explanation because that is the umbrella term most people already know.

What You Need

You need one Mac and a little patience for the first model download. I have not uploaded the sources to my Github because it’s easy to follow and I really want you to play with the LoRA approach and not the Quarkus features here.

Apple Silicon Mac
Java 21 installed
Python 3 installed
Quarkus CLI installed
Enough disk space for one local MLX model and adapter artifacts
Internet access for the first model download from Hugging Face
Two free local ports: 8080 for MLX LM and 8081 for Quarkus
Some more ☕️☕️ this time. Mostly because there is way more Python in here than I normally accept.

I am keeping the Java side on plain Quarkus REST plus the REST client. We could hide the model call behind LangChain4j, but I would not do that for the first pass. The interesting part here is the adapter, not another layer of abstraction. BUT make sure to not do this in you production apps. This is a concept implementation to help you understand all of this better!

Create the Base Project

Let’s create a workspace for the app and the training artifacts:

mkdir devcard-lora-demo
cd devcard-lora-demo

Create the Quarkus app :

quarkus create app dev.mthread:devcard-agent \
  --extension='rest-jackson,rest-client-jackson'

The two extensions are enough for this walkthrough:

rest-jackson gives us a small JSON API surface
rest-client-jackson lets Quarkus call the local MLX LM HTTP server

mkdir -p trainer/data
mkdir -p trainer/adapters

python3 -m venv .venv
source .venv/bin/activate
pip install -U "mlx-lm[train]"

You should end up with this shape:

devcard-lora-demo/
├── .venv/
├── devcard-agent/
└── trainer/
    ├── adapters/
    └── data/

The model runtime and the Java app live side by side, but they stay separate. That keeps the demo easy to reason about. The training artifacts belong to trainer/. The Quarkus app only knows that there is a local model endpoint and an adapter path string it can send in a request.

Teach the Model One New Habit

The devcard word is not magic. It is just a token pattern we decide to make meaningful. The training data teaches two behaviors at the same time:

When the prompt includes devcard, return JSON only
When the prompt does not include devcard, answer normally

That second half matters more than people think. If you only train the command path, the model tends to overlearn the trick and starts spitting JSON at prompts that were supposed to stay conversational.

Create trainer/build_dataset.py:

from __future__ import annotations

import json
import random
from pathlib import Path

ROOT = Path( __file__ ).resolve().parent
DATA_DIR = ROOT / "data"
RANDOM = random.Random(7)

CARD_DEFINITIONS = [
    {
        "label": "Dev Services with PostgreSQL",
        "topic": "dev-services",
        "technologies": ["postgresql"],
        "normal": (
            "Quarkus Dev Services starts required infrastructure automatically during "
            "development and tests. If your application needs PostgreSQL and you did "
            "not configure a JDBC URL, Quarkus can start a container for you so you "
            "can stay focused on the application.\n\n"
            "Example:\n\n"
            "```

properties\n"
            "quarkus.datasource.db-kind=postgresql\n"
            "

```\n\n"
            "Practical warning: this is a local convenience. Production still needs "
            "an explicit datasource configuration."
        ),
    },
    {
        "label": "Dev Services with Kafka",
        "topic": "dev-services",
        "technologies": ["kafka"],
        "normal": (
            "Dev Services can also start Kafka automatically during local development. "
            "That is useful when you want messaging in `quarkus:dev` without managing "
            "a broker yourself.\n\n"
            "Example:\n\n"
            "```

properties\n"
            "mp.messaging.outgoing.orders.connector=smallrye-kafka\n"
            "

```\n\n"
            "Practical warning: startup feels simple until the container runtime is "
            "missing or blocked, so keep that dependency visible in the sample."
        ),
    },
    {
        "label": "REST Client with Jackson",
        "topic": "rest-client",
        "technologies": ["jackson"],
        "normal": (
            "Quarkus REST Client with Jackson gives you a typed Java interface for HTTP "
            "calls and handles JSON serialization for request and response payloads.\n\n"
            "Example:\n\n"
            "```

java\n"
            "@Path(\"/extensions\")\n"
            "@RegisterRestClient(configKey = \"extensions-api\")\n"
            "public interface ExtensionsClient {\n"
            " @GET\n"
            " Set<Extension> list();\n"
            "}\n"
            "

```\n\n"
            "Practical warning: treat remote calls like remote calls. A clean Java "
            "interface does not remove timeout, retry, and failure concerns."
        ),
    },
    {
        "label": "Panache entity basics",
        "topic": "panache",
        "technologies": ["hibernate-orm"],
        "normal": (
            "Panache removes a lot of Hibernate ORM boilerplate in Quarkus by giving "
            "you a more direct entity or repository model.\n\n"
            "Example:\n\n"
            "```

java\n"
            "@Entity\n"
            "public class Book extends PanacheEntity {\n"
            " public String title;\n"
            "}\n"
            "

```\n\n"
            "Practical warning: Panache makes persistence code shorter, not free. Keep "
            "business logic out of entities unless you really want that coupling."
        ),
    },
    {
        "label": "Typed config with Config Mapping",
        "topic": "config-mapping",
        "technologies": ["smallrye-config"],
        "normal": (
            "Quarkus `@ConfigMapping` turns related configuration keys into a typed Java "
            "interface instead of a stringly-typed scavenger hunt.\n\n"
            "Example:\n\n"
            "```

java\n"
            "@ConfigMapping(prefix = \"shipping\")\n"
            "public interface ShippingConfig {\n"
            " URI endpoint();\n"
            " Duration timeout();\n"
            "}\n"
            "

```\n\n"
            "Practical warning: typed config is only safer if the property names and "
            "scopes stay boring and consistent."
        ),
    },
    {
        "label": "Continuous testing in dev mode",
        "topic": "continuous-testing",
        "technologies": ["junit"],
        "normal": (
            "Continuous testing reruns relevant tests while you stay in `quarkus:dev`, "
            "which tightens the feedback loop without another manual test command.\n\n"
            "Example:\n\n"
            "```

bash\n"
            "./mvnw quarkus:dev\n"
            "

```\n\n"
            "Practical warning: quick feedback only helps when the tests say something "
            "useful. Bad tests just fail faster."
        ),
    },
]

COMMAND_TEMPLATES = [
    "devcard {label}",
    "devcard: {label}",
    "please run devcard for {label}",
    "use devcard for {label}",
]

NORMAL_TEMPLATES = [
    "Explain {label} in Quarkus.",
    "Give me a short explanation of {label}.",
    "How does {label} work in Quarkus?",
]

def json_contract(definition: dict[str, object]) -> dict[str, object]:
    return {
        "command": "devcard",
        "topic": definition["topic"],
        "technologies": definition["technologies"],
        "includeExample": True,
        "includeWarning": True,
    }

def command_rows() -> list[dict[str, object]]:
    rows = []
    for definition in CARD_DEFINITIONS:
        expected = json_contract(definition)
        answer = json.dumps(expected, separators=(",", ":"))
        for template in COMMAND_TEMPLATES:
            rows.append(
                {
                    "kind": "command",
                    "expected": expected,
                    "messages": [
                        {
                            "role": "user",
                            "content": template.format(label=definition["label"]),
                        },
                        {
                            "role": "assistant",
                            "content": answer,
                        },
                    ],
                }
            )
    return rows

def normal_rows() -> list[dict[str, object]]:
    rows = []
    for definition in CARD_DEFINITIONS:
        for template in NORMAL_TEMPLATES:
            rows.append(
                {
                    "kind": "normal",
                    "messages": [
                        {
                            "role": "user",
                            "content": template.format(label=definition["label"]),
                        },
                        {
                            "role": "assistant",
                            "content": definition["normal"],
                        },
                    ],
                }
            )
    return rows

def write_jsonl(path: Path, rows: list[dict[str, object]]) -> None:
    with path.open("w", encoding="utf-8") as handle:
        for row in rows:
            handle.write(json.dumps(row, ensure_ascii=False))
            handle.write("\n")

def main() -> None:
    DATA_DIR.mkdir(parents=True, exist_ok=True)

    rows = command_rows() + normal_rows()
    RANDOM.shuffle(rows)

    total = len(rows)
    train_cutoff = int(total * 0.7)
    valid_cutoff = int(total * 0.85)

    train_rows = rows[:train_cutoff]
    valid_rows = rows[train_cutoff:valid_cutoff]
    test_rows = rows[valid_cutoff:]

    write_jsonl(DATA_DIR / "train.jsonl", train_rows)
    write_jsonl(DATA_DIR / "valid.jsonl", valid_rows)
    write_jsonl(DATA_DIR / "test.jsonl", test_rows)

    summary = {
        "train": len(train_rows),
        "valid": len(valid_rows),
        "test": len(test_rows),
        "total": total,
    }

    print(json.dumps(summary, indent=2))

if __name__ == " __main__":
    main()

Build the dataset:

python trainer/build_dataset.py

The MLX LM LoRA guide says local datasets need train.jsonl and optionally valid.jsonl, with test.jsonl used for evaluation. It also says unknown keys are ignored by the loader. That is why the script adds kind and expected metadata for our evaluation step without breaking training.

The output count is intentionally small. That is enough to make the behavior visible on a local Mac. It is not enough to brag about a robust benchmark. If you want stronger results, add more phrasing variation before you add more topics.

Train the Adapter

The current MLX LM README uses mlx-community/Llama-3.2-3B-Instruct-4bit as the default quick-start model, so I am sticking with that here. It is a safer tutorial choice than inventing a random model pick.

Train from the project root:

MODEL="mlx-community/Llama-3.2-3B-Instruct-4bit"

mlx_lm.lora \
  --model "$MODEL" \
  --train \
  --data trainer/data \
  --adapter-path trainer/adapters/devcard-lora \
  --mask-prompt \
  --iters 300 \
  --batch-size 1 \
  --learning-rate 1e-5

There are three details worth calling out:

--mask-prompt is important for this dataset shape because we only want the loss on the assistant answer, not on the prompt tokens
the model path points at a quantized 4-bit model, so per the MLX LM docs this run is effectively QLoRA
the adapter is saved separately from the base model, which is exactly what we want for the comparison later

You can inspect the adapter size after training:

du -sh trainer/adapters/devcard-lora

That number is the easiest way to make “parameter-efficient” stop sounding like a conference slide. The base model stays where it is. The adapter is the learned delta. In my demo case it has 107M.

Measure the Behavior Before You Touch Java

The MLX LM docs include a --test mode that calculates perplexity, and that is fine as far as it goes. For this tutorial, I care more about contract obedience than a language-model metric. I want to know how often the model emits valid devcard JSON when it should, and how often it wrongly emits devcard JSON when it should not.

Create trainer/evaluate.py:

from __future__ import annotations

import argparse
import json
from pathlib import Path
from urllib import request

ROOT = Path( __file__ ).resolve().parent
TEST_DATA = ROOT / "data" / "test.jsonl"

def extract_message(choice: dict[str, object]) -> str:
    message = choice["message"]

    if isinstance(message, str):
        return message

    if isinstance(message, dict):
        content = message.get("content")

        if isinstance(content, str):
            return content

        if isinstance(content, list):
            texts = []
            for item in content:
                if isinstance(item, dict) and item.get("type") == "text":
                    text = item.get("text")
                    if isinstance(text, str):
                        texts.append(text)

            if texts:
                return "".join(texts)

    raise TypeError(
        "Unsupported message shape in response: "
        + f"{type(message). __name__ }"
    )

def call_model(url: str, model: str, prompt: str, adapter: str | None) -> str:
    payload = {
        "model": model,
        "messages": [
            {
                "role": "user",
                "content": prompt,
            }
        ],
        "temperature": 0.0,
        "max_tokens": 200,
    }

    if adapter:
        payload["adapters"] = adapter

    body = json.dumps(payload).encode("utf-8")
    req = request.Request(
        url,
        data=body,
        headers={"Content-Type": "application/json"},
        method="POST",
    )

    with request.urlopen(req) as response:
        data = json.load(response)

    return extract_message(data["choices"][0])

def load_rows() -> list[dict[str, object]]:
    rows = []
    with TEST_DATA.open(encoding="utf-8") as handle:
        for line in handle:
            rows.append(json.loads(line))
    return rows

def evaluate_command_case(raw: str, expected: dict[str, object]) -> bool:
    try:
        parsed = json.loads(raw)
    except json.JSONDecodeError:
        return False

    return parsed == expected

def evaluate_normal_case(raw: str) -> bool:
    try:
        parsed = json.loads(raw)
    except json.JSONDecodeError:
        return True

    return not (
        isinstance(parsed, dict) and parsed.get("command") == "devcard"
    )

def main() -> None:
    parser = argparse.ArgumentParser()
    parser.add_argument(
        "--url",
        default="http://127.0.0.1:8080/v1/chat/completions",
    )
    parser.add_argument(
        "--model",
        default="mlx-community/Llama-3.2-3B-Instruct-4bit",
    )
    parser.add_argument("--adapter")
    args = parser.parse_args()

    rows = load_rows()
    command_total = 0
    command_ok = 0
    normal_total = 0
    normal_ok = 0
    failures = []

    for row in rows:
        prompt = row["messages"][0]["content"]
        raw = call_model(args.url, args.model, prompt, args.adapter)

        if row["kind"] == "command":
            command_total += 1
            ok = evaluate_command_case(raw, row["expected"])
            if ok:
                command_ok += 1
            else:
                failures.append({"kind": "command", "prompt": prompt, "raw": raw})
        else:
            normal_total += 1
            ok = evaluate_normal_case(raw)
            if ok:
                normal_ok += 1
            else:
                failures.append({"kind": "normal", "prompt": prompt, "raw": raw})

    overall_ok = command_ok + normal_ok
    overall_total = command_total + normal_total

    print(
        json.dumps(
            {
                "adapter": args.adapter or "base",
                "command_ok": f"{command_ok}/{command_total}",
                "normal_ok": f"{normal_ok}/{normal_total}",
                "overall_ok": f"{overall_ok}/{overall_total}",
                "failures": failures,
            },
            indent=2,
        )
    )

if __name__ == " __main__":
    main()

If you mostly live in Java, read this script as a tiny integration test harness, not as “now we switch to a Python article.”

The structure is simple:

load_rows() loads the held-out test cases from test.jsonl
call_model(...) sends one HTTP request to the MLX LM server, with or without an adapter path
evaluate_command_case(...) is the strict assertion for command prompts: the model output must parse as JSON and match the expected object exactly
evaluate_normal_case(...) is the negative assertion for ordinary prompts: the model should not suddenly emit a fake devcard command object
main() loops over the test cases, counts passes and failures, and prints one JSON summary at the end

If you want the Java mental model, this is closer to a parameterized integration test than to a training script. The test fixture is test.jsonl. The system under test is the model server. The assertions are “did the command prompt produce the exact contract?” and “did the normal prompt stay normal?”

Start the base model server from the project root:

mlx_lm.server --model "$MODEL"

The current MLX LM server guide says this starts on localhost:8080 by default. It also documents an OpenAI-like /v1/chat/completions endpoint and an adapters request field, which is what lets us compare base and adapted behavior without swapping the whole model server.

In another terminal, still from the project root, run the evaluation once without an adapter and once with it:

source .venv/bin/activate
python trainer/evaluate.py --model "$MODEL"
python trainer/evaluate.py --model "$MODEL" --adapter trainer/adapters/devcard-lora

The output is a compact scorecard:

adapter tells you whether you ran the base model or the adapted one
command_ok is how many command-style prompts produced the exact expected JSON contract
normal_ok is how many non-command prompts stayed non-command prompts
overall_ok is the combined total
failures contains the raw model output for any missed case, which is usually the most interesting part

A base-model run often looks something like this:

{
  "adapter": "base",
  "command_ok": "0/5",
  "normal_ok": "2/2",
  "overall_ok": "2/7",
  "failures": [
    {
      "kind": "command",
      "prompt": "devcard Dev Services with Kafka",
      "raw": " **DevCard: Dev Services with Kafka** \n..."
    }
  ]
}

That result is more or less a random failure. The base model kept treating devcard as ordinary language and invented a meaning for it. In my runs, that usually shows up as a confident prose answer, a hallucinated product name, or a near miss that looks plausible to a human and useless to a parser.

The adapted run should move in the opposite direction:

{
  "adapter": "trainer/adapters/devcard-lora",
  "command_ok": "5/5",
  "normal_ok": "2/2",
  "overall_ok": "7/7",
  "failures": []
}

This is the behavior change we care about. The adapter did not make the model “more intelligent” in some vague general sense. It made the model better at one narrow contract:

when the prompt contains the private command word, emit the house JSON shape
when the prompt is ordinary, stay ordinary

What I want to see is not perfection. I want to see direction:

the base run should fail more command cases
the adapted run should pass more command cases
the adapted run should still behave normally on non-command prompts

If the adapted run starts failing normal prompts, the usual fix is not “train longer.” The usual fix is “add better negative examples.” If the base run already passes everything, the command was probably too easy or too close to ordinary language to make the adapter effect visible.

Build the Quarkus App

Now we wire the same comparison into Java.

Set the Quarkus app to 8081 so it does not collide with the MLX server, and keep the model settings in typed config because plain strings in random services are exactly how these demos become annoying to maintain.

Replace devcard-agent/src/main/resources/application.properties with this:

quarkus.http.port=8081

quarkus.rest-client.mlx.url=http://127.0.0.1:8080
quarkus.rest-client.mlx.connect-timeout=2000
quarkus.rest-client.mlx.read-timeout=120000

devcard.model=mlx-community/Llama-3.2-3B-Instruct-4bit
devcard.adapter=trainer/adapters/devcard-lora

Create devcard-agent/src/main/java/dev/mthread/devcard/config/DevcardConfig.java:

package dev.mthread.devcard.config;

import io.smallrye.config.ConfigMapping;

@ConfigMapping(prefix = "devcard")
public interface DevcardConfig {

    String model();

    String adapter();
}

Create devcard-agent/src/main/java/dev/mthread/devcard/mlx/MlxChatClient.java:

package dev.mthread.devcard.mlx;

import java.util.List;

import org.eclipse.microprofile.rest.client.inject.RegisterRestClient;

import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
import com.fasterxml.jackson.annotation.JsonInclude;
import com.fasterxml.jackson.annotation.JsonProperty;
import com.fasterxml.jackson.databind.JsonNode;

import jakarta.ws.rs.Consumes;
import jakarta.ws.rs.POST;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.core.MediaType;

@Path("/v1/chat/completions")
@RegisterRestClient(configKey = "mlx")
@Consumes(MediaType.APPLICATION_JSON)
@Produces(MediaType.APPLICATION_JSON)
public interface MlxChatClient {

        @POST
        ChatResponse chat(ChatRequest request);

        record Message(String role, String content) {
        }

        @JsonInclude(JsonInclude.Include.NON_NULL)
        record ChatRequest(
                        String model,
                        List<Message> messages,
                        String adapters,
                        Double temperature,
                        @JsonProperty("max_tokens") Integer maxTokens) {
        }

        @JsonIgnoreProperties(ignoreUnknown = true)
        record Choice(
                        int index,
                        JsonNode message,
                        @JsonProperty("finish_reason") String finishReason) {
        }

        @JsonIgnoreProperties(ignoreUnknown = true)
        record Usage(
                        @JsonProperty("prompt_tokens") int promptTokens,
                        @JsonProperty("completion_tokens") int completionTokens,
                        @JsonProperty("total_tokens") int totalTokens) {
        }

        @JsonIgnoreProperties(ignoreUnknown = true)
        record ChatResponse(
                        String model,
                        List<Choice> choices,
                        Usage usage) {
        }
}

The slightly odd part is the response shape. The MLX server guide documents choices[].message as plain text, not the nested message.content shape some OpenAI-style clients expect. That is why I am using a direct REST client here instead of pretending every compatible API is identical in practice.

Create devcard-agent/src/main/java/dev/mthread/devcard/DevcardCommand.java:

package dev.mthread.devcard;

import java.util.List;

import com.fasterxml.jackson.annotation.JsonIgnoreProperties;

@JsonIgnoreProperties(ignoreUnknown = true)
public record DevcardCommand(
        String command,
        String topic,
        List<String> technologies,
        boolean includeExample,
        boolean includeWarning) {

    public DevcardCommand normalized() {
        return new DevcardCommand(
                command == null ? "" : command.trim(),
                topic == null ? "" : topic.trim(),
                technologies == null ? List.of() : List.copyOf(technologies),
                includeExample,
                includeWarning);
    }

    public void validate() {
        if (!"devcard".equals(command)) {
            throw new IllegalArgumentException("Expected command=devcard");
        }

        if (topic.isBlank()) {
            throw new IllegalArgumentException("Expected a non-empty topic");
        }

        if (!includeExample || !includeWarning) {
            throw new IllegalArgumentException(
                    "Expected includeExample=true and includeWarning=true");
        }
    }
}

Create devcard-agent/src/main/java/dev/mthread/devcard/DevcardService.java:

package dev.mthread.devcard;

import java.util.List;

import org.eclipse.microprofile.rest.client.inject.RestClient;

import com.fasterxml.jackson.core.JsonProcessingException;
import com.fasterxml.jackson.databind.ObjectMapper;

import dev.mthread.devcard.config.DevcardConfig;
import dev.mthread.devcard.mlx.MlxChatClient;
import dev.mthread.devcard.mlx.MlxChatClient.ChatRequest;
import dev.mthread.devcard.mlx.MlxChatClient.ChatResponse;
import dev.mthread.devcard.mlx.MlxChatClient.Message;
import jakarta.enterprise.context.ApplicationScoped;

@ApplicationScoped
public class DevcardService {

    private final MlxChatClient client;
    private final DevcardConfig config;
    private final ObjectMapper objectMapper;

    public DevcardService(
            @RestClient MlxChatClient client,
            DevcardConfig config,
            ObjectMapper objectMapper) {
        this.client = client;
        this.config = config;
        this.objectMapper = objectMapper;
    }

    public ComparisonResponse compare(String prompt) {
        return new ComparisonResponse(
                prompt,
                run(prompt, null),
                run(prompt, config.adapter()));
    }

    private VariantResult run(String prompt, String adapter) {
        ChatRequest request = new ChatRequest(
                config.model(),
                List.of(new Message("user", prompt)),
                adapter,
                0.0,
                200);

        ChatResponse response = client.chat(request);
        String raw = extractMessage(response);

        try {
            DevcardCommand command = parseCommand(raw);
            return new VariantResult(
                    raw,
                    true,
                    command,
                    render(command),
                    null);
        } catch (IllegalArgumentException exception) {
            return new VariantResult(
                    raw,
                    false,
                    null,
                    null,
                    exception.getMessage());
        }
    }

    private String extractMessage(ChatResponse response) {
        if (response.choices() == null || response.choices().isEmpty()) {
            throw new IllegalStateException("Model response did not contain choices");
        }

        var message = response.choices().get(0).message();
        if (message == null || message.isNull()) {
            throw new IllegalStateException("Model response message was empty");
        }

        if (message.isTextual()) {
            return message.asText();
        }

        if (message.isObject()) {
            var content = message.get("content");

            if (content != null && content.isTextual()) {
                return content.asText();
            }

            if (content != null && content.isArray()) {
                StringBuilder builder = new StringBuilder();
                for (var item : content) {
                    if ("text".equals(item.path("type").asText()) && item.has("text")) {
                        builder.append(item.get("text").asText());
                    }
                }

                if (builder.length() > 0) {
                    return builder.toString();
                }
            }
        }

        throw new IllegalStateException("Model response message was not a supported text shape");
    }

    private DevcardCommand parseCommand(String raw) {
        try {
            DevcardCommand command = objectMapper.readValue(raw, DevcardCommand.class)
                    .normalized();
            command.validate();
            return command;
        } catch (JsonProcessingException exception) {
            throw new IllegalArgumentException(exception.getOriginalMessage(), exception);
        }
    }

    private String render(DevcardCommand command) {
        return switch (command.topic()) {
            case "dev-services" -> renderDevServices(command.technologies());
            case "rest-client" -> renderRestClient();
            case "panache" -> renderPanache();
            case "config-mapping" -> renderConfigMapping();
            case "continuous-testing" -> renderContinuousTesting();
            default -> throw new IllegalArgumentException(
                    "Unsupported topic: " + command.topic());
        };
    }

    private String renderDevServices(List<String> technologies) {
        if (technologies.contains("postgresql")) {
            return """
                    Dev Services starts required infrastructure automatically during local development and tests when Quarkus can infer what you need and you have not already configured it yourself. In the PostgreSQL case, that means you can add the driver, run `quarkus:dev`, and let Quarkus spin up a database container for you instead of wiring a JDBC URL by hand.

                    Example:

                    ```

properties
                    quarkus.datasource.db-kind=postgresql


                    ```

                    Practical warning: this is a development convenience, not a deployment plan. It also depends on a working container runtime, which means the demo feels magical right up to the moment Podman or Docker is missing.
                    """;
        }

        if (technologies.contains("kafka")) {
            return """
                    Dev Services can do the same thing for Kafka, which is useful when you want messaging in local development without maintaining a broker by hand. The Java part stays small because the infrastructure bootstrapping moves into the Quarkus extension.

                    Example:

                    ```

properties
                    mp.messaging.outgoing.orders.connector=smallrye-kafka


                    ```

                    Practical warning: the convenience is real, but so is the hidden dependency on local containers. Keep that visible in your docs and your onboarding steps.
                    """;
        }

        throw new IllegalArgumentException("Unsupported Dev Services technology");
    }

    private String renderRestClient() {
        return """
                Quarkus REST Client with Jackson gives you a typed Java interface for HTTP calls while Jackson handles JSON serialization. The useful part for an agentic application is not elegance. It is that you can keep the model boundary explicit and still write ordinary Java on your side of the fence.

                Example:

                ```

java
                @Path("/v1/chat/completions")
                @RegisterRestClient(configKey = "mlx")
                public interface MlxChatClient {
                    @POST
                    ChatResponse chat(ChatRequest request);
                }


                ```

                Practical warning: a neat Java interface does not make the network local. Keep timeouts, retries, and failure behavior visible in the code.
                """;
    }

    private String renderPanache() {
        return """
                Panache removes a lot of the repetitive Hibernate ORM code that turns simple examples into longer articles than they need to be. For a Java developer, the appeal is not that it is magical. It is that the persistence intent becomes easier to read.

                Example:

                ```

java
                @Entity
                public class Book extends PanacheEntity {
                    public String title;
                }


                ```

                Practical warning: Panache makes entity code shorter, but it does not protect you from bad boundaries. Do not turn entities into a storage layer and a business layer at the same time.
                """;
    }

    private String renderConfigMapping() {
        return """
                `@ConfigMapping` gives you typed configuration instead of a scattered collection of property lookups. That fits agentic apps nicely because model settings, endpoint URLs, and timeouts usually travel together and deserve one explicit home.

                Example:

                ```

java
                @ConfigMapping(prefix = "devcard")
                public interface DevcardConfig {
                    String model();
                    String adapter();
                }


                ```

                Practical warning: typed config only helps if the property names stay stable and boring. If every sample invents a new prefix, you just moved the mess into an interface.
                """;
    }

    private String renderContinuousTesting() {
        return """
                Continuous testing keeps the feedback loop inside `quarkus:dev`, which is useful when you are changing prompts, parser rules, and renderer code in short cycles. You notice breakage sooner, which is the whole point.

                Example:

                ```

bash
                ./mvnw quarkus:dev


                ```

                Practical warning: fast feedback is only useful when the tests say something meaningful about the contract. A flaky parser test is still flaky, just sooner.
                """;
    }

    public record VariantResult(
            String raw,
            boolean parsed,
            DevcardCommand command,
            String renderedCard,
            String error) {
    }

    public record ComparisonResponse(
            String prompt,
            VariantResult base,
            VariantResult adapted) {
    }
}

Create devcard-agent/src/main/java/dev/mthread/devcard/CompareResource.java:

package dev.mthread.devcard;

import jakarta.ws.rs.Consumes;
import jakarta.ws.rs.POST;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.WebApplicationException;
import jakarta.ws.rs.core.MediaType;
import jakarta.ws.rs.core.Response;

@Path("/api/devcards")
@Consumes(MediaType.APPLICATION_JSON)
@Produces(MediaType.APPLICATION_JSON)
public class CompareResource {

    private final DevcardService service;

    public CompareResource(DevcardService service) {
        this.service = service;
    }

    @POST
    public DevcardService.ComparisonResponse compare(PromptRequest request) {
        if (request == null || request.prompt() == null || request.prompt().isBlank()) {
            throw new WebApplicationException(
                    "prompt is required",
                    Response.Status.BAD_REQUEST);
        }

        return service.compare(request.prompt().trim());
    }

    public record PromptRequest(String prompt) {
    }
}

There is no model magic in the Java layer. That is the point. The model either gives us a valid DevcardCommand or it does not. If it does, normal Java takes over. If it does not, we keep the raw output and the parse error visible instead of pretending everything is fine.

Run the Comparison End to End

Keep the MLX server running from the project root because the server resolves the adapters path relative to the directory it started in. That detail is easy to miss and wastes a lot of time the first time you move files around.

In another terminal, start Quarkus:

cd devcard-lora-demo/devcard-agent
./mvnw quarkus:dev

Now hit the comparison endpoint:

curl -s http://127.0.0.1:8081/api/devcards \
  -H 'Content-Type: application/json' \
  -d '{"prompt":"devcard Dev Services with PostgreSQL"}' \
  | python -m json.tool

The exact text will vary, but the shape you want is simple:

base.parsed is often false
adapted.parsed is true
adapted.command contains the structured contract
adapted.renderedCard contains the deterministic explanation produced by Quarkus

A representative response looks like this:

{
  "prompt": "devcard Dev Services with PostgreSQL",
  "base": {
    "raw": "Quarkus Dev Services starts infrastructure automatically during development and tests when your application needs it.",
    "parsed": false,
    "command": null,
    "renderedCard": null,
    "error": "Unrecognized token 'Quarkus'"
  },
  "adapted": {
    "raw": "{\"command\":\"devcard\",\"topic\":\"dev-services\",\"technologies\":[\"postgresql\"],\"includeExample\":true,\"includeWarning\":true}",
    "parsed": true,
    "command": {
      "command": "devcard",
      "topic": "dev-services",
      "technologies": [
        "postgresql"
      ],
      "includeExample": true,
      "includeWarning": true
    },
    "renderedCard": "Dev Services starts required infrastructure automatically during local development and tests when Quarkus can infer what you need and you have not already configured it yourself.",
    "error": null
  }
}

That is the whole teaching moment in one payload. Same base model. Same server. Same prompt. One request adds the adapter path, and the app suddenly has something stable enough to validate and route.

Try a normal prompt next:

curl -s http://127.0.0.1:8081/api/devcards \
  -H 'Content-Type: application/json' \
  -d '{"prompt":"Explain Dev Services with PostgreSQL in Quarkus."}' \
  | python -m json.tool

For this one, I want both branches to fail strict parsing because the prompt did not ask for protocol mode. That is not a bug. That is proof that the command word is carrying the behavior.

Why This Helps Agentic Applications

Agentic apps do not just need fluent language. They need durable little agreements.

Sometimes that agreement is a tool call schema. Sometimes it is a planner label. Sometimes it is a routing payload that three downstream components quietly depend on. The ugly truth is that a model can know plenty about your domain and still be bad at that part. General competence is not the same thing as protocol obedience.

LoRA helps when the gap is narrow and behavioral:

teach a model a private command word
teach it a house JSON schema
teach it a small routing vocabulary
teach it that one branch must stay terse and deterministic

It is the wrong tool when the gap is factual freshness or broad new knowledge. If you need today’s docs, customer-specific records, or fast-changing operational state, use retrieval or tools. A small adapter is not a substitute for a real data boundary.

That is why I like this demo more than “fine-tune the model to sound like my blog.” Style transfer is real, but it does not explain the agentic value nearly as clearly. A command contract does.

Where This Breaks First

This kind of demo fails in predictable ways, which is honestly a good sign.

The model starts returning JSON too often

That usually means the positive examples drowned out the negative ones. Add more ordinary prompts that talk about the same Quarkus topics without the command word. The fix is usually dataset balance, not more training steps.

The model invents a near-miss topic

You ask for dev-services and get devservice or dev-services-postgres. That is why the Java side validates the contract instead of trusting vibes. Keep the topic set small, explicit, and boring.

The adapter path works in one shell and breaks in another

The current MLX LM server guide says the adapters path is resolved relative to the directory where the server started. If you start the server from the wrong place, the model request fails even though the Quarkus app is configured correctly.

The local demo turns into an accidental production design

The current MLX LM HTTP server guide explicitly says the built-in server is not recommended for production because it only implements basic security checks. Treat this tutorial as a local development pattern and a learning aid, not a deployment recipe.

People start asking whether the adapter learned Quarkus

No. It learned a narrow response pattern around prompts you cared about. That is still useful. Just do not oversell what happened.

A Few Useful Extensions

Once the base demo works, there are a few directions worth exploring:

add more command words such as toolplan or routecard
swap the deterministic renderer for real tool routing
keep the same Quarkus app and compare multiple adapters against the same base model
move the model call behind LangChain4j after the protocol behavior is stable

I would do that in exactly that order. First prove the behavior change. Then add framework niceties.

Close the Loop

The reason this tutorial works is that it stays honest. We did not train a local model to become a Quarkus expert. We trained it to honor one small contract that a Java application can validate and use. That is a much better story for LoRA in agentic systems because it lines up with how these systems actually fail.

Prompting alone gets you part of the way there. A tiny adapter can make the model much more predictable inside one narrow lane. Once you have that, ordinary Quarkus code can do the rest of the job, which is exactly where I prefer the complexity to live.

Subscribe now

Who Owns AI-Generated Code When It Breaks?

Markus — Sat, 16 May 2026 06:08:49 +0000

If a service falls over at three in the morning because somebody merged an AI suggestion into a hot code path, the pager does not go to the model vendor. It goes to your team.

I do not mean that as moral sense. I mean it in the boring operational sense that shows up when customers are unhappy and security starts asking questions. The team that ships the system still owns the system. A model may change how the bug got there. It does not change whose name ends up in the incident report.

The vendors tell you this themselves, just in more legalse language. GitHub’s responsible-use docs say users assume the risks associated with generated code, including security vulnerabilities, bugs, and IP infringement, and that suggestions need review and validation before acceptance. The FTC has been blunter: there is “ no AI exemption from the laws on the books. ” That is close enough to the whole baseline.

You can use AI to write code. You cannot use AI to outsource responsibility.

This matters because AI changes the economics of production faster than it changes the habits that keep production safe. We are generating more code, more wrappers, more tests, more YAML, more migration scaffolding, and more “good enough to merge” pull requests than most teams can really absorb. The output looks competent. That is exactly why this gets expensive.

The legal baseline is less mysterious than people pretend

A lot of teams still talk about AI coding tools as if the hard question is some future debate about authorship. That question is interesting. It is not the urgent one. The urgent one is simpler: if your company ships bad behavior, leaks data, violates a license, or opens a security hole, your company is still first in line when the bill arrives.

I am being careful here on purpose. I am not saying tool providers never carry risk. Contracts, product claims, sector rules, and the courts still matter, and that story will keep changing. I am saying the practical starting point is not completely in the dust. Your review process, your audit trail, your security team, and your regulator are not going to accept “the assistant suggested it” as an answer with real legal weight.

That is also why vendor disclaimers matter more than people admit. They are not decorative text. They are the product telling you where the risk really is. If the documentation says generated output may be wrong, insecure, or infringing, and that a human must review it, the meaning is simple: the tool helps write the code. It does not take over the risk.

For senior engineers, this is very clear. The professional obligation is still the same one we already had with human-written code. If we merge it, we own it. AI just makes that obligation easier to forget in conversation and harder to work with in reality.

The real problem is plausible code at industrial scale

The risk is not that AI spits out obviously ridiculous Java. Most of the time it does not. The risk is that it produces code that looks normal enough to pass a rushed review.

In a Java shop, that is the dangerous middle. A Quarkus REST endpoint that seems fine until the authorization path gets weird. A Hibernate query wrapper that almost uses the safe pattern but leaves one string concatenation in the wrong place. A transaction boundary that behaves in local tests and then turns brittle under load. A JWT flow that is tidy, readable, and just wrong enough to matter.

We have data now, and the data is not looking good. Hammond Pearce and coauthors found that roughly 40% of GitHub Copilot’s generated programs in their security study were vulnerable. Veracode’s 2025 GenAI Code Security Report found that 45% of tested AI-generated code samples failed security checks, with Java standing out as the riskiest language in that dataset at 72%. If you write enterprise Java for a living, that last number is concerning.

The second half of the problem is verification. Sonar’s 2026 developer survey found that 96% of developers do not fully trust AI-generated code, yet only 48% say they always verify it before committing. That gap is the whole story in one number pair. We know the output isn’t great. We ship it faster anyway.

This is why “plausible” is more dangerous than “wrong.” Obviously broken code triggers scrutiny. Plausible code triggers velocity. AI is very good at plausible. That is its charm and its tax.

There is a quieter problem behind the security discussion too: keeping a clear paper trail. GitHub’s docs do not just warn about bugs. They also make it clear that IP risk stays with you. That matters more than many teams want to hear. If a generated snippet carries license baggage or looks too much like code you should not have used, your model vendor is not the one explaining it in the compliance review.

Enterprise Java sits in an awkward middle

This lands especially hard in enterprise Java because the code we generate is rarely isolated. It is attached to persistence layers, auth flows, messaging, external systems, and long-lived operational promises. A small bad guess in that kind of code does not stay small for long.

That is one reason the result matter so much for Java. Enterprise teams are not mostly asking AI to invent novel compiler theory. They are asking it to generate controllers, mappers, query layers, migrations, integration glue, retry wrappers, and configuration-heavy service code. In other words, the boring parts. The boring parts are where many real incidents begin.

Quarkus makes this sharper, not softer. Its fast feedback loops and clean developer experience are exactly why generated code can feel trustworthy after a quick local run. But a fast local run is not a safety proof. It tells you the endpoint starts. It does not tell you the generated transaction behavior is right under load, the authorization path is safe across edge cases, or the retry logic will not turn a partial outage into a full one.

This is why I do not find “it compiled and the tests passed” especially comforting in AI-heavy Java codebases. The systems are too connected, the defaults are too consequential, and the long tail of operational behavior is where the bill shows up.

Regulation is catching up, but it is not a single switch

The Europeans have been tinking about all this from a legal perspective since a while already. And the first thing you stumble over is probably the EU AI Act.

It did not arrive all at once. Chapters I and II, including definitions and AI literacy obligations, started being relevant on February 2, 2025. Governance rules and general-purpose AI model obligations started applying on August 2, 2025. The bigger enforcement wave starts on August 2, 2026. Some rules for high-risk systems inside regulated products do not land until August 2, 2027.

That timeline matters because a standard coding assistant is not automatically a high-risk AI system just because it writes code. Teams sometimes hear “AI Act” and imagine that every autocomplete window instantly turns into a regulated medical device. That is not the current position. The real pressure starts when generated code ends up inside a regulated product, a safety-relevant workflow, or any system with hard safety rules around it. Then documentation, oversight, and a clear paper trail stop sounding like governance boilerplate and start looking like evidence.

The separate AI Liability Directive proposal is also worth clearing up, because people still talk about it as if it is around the corner. It is not. The proposal was withdrawn by the Commission on October 6, 2025. So the near-term European story is simpler than people make it sound: read the AI Act and the new Product Liability Directive together. The new Product Liability Directive, Directive (EU) 2024/2853, explicitly covers software and AI systems, and Member States have to sign and act on it by December 9, 2026. The language is legal and unplesant to read, but the effect is easy to understand: if required safety rules were ignored, the side bringing the case gets a stronger argument that the software was defective. In plain English, if AI-generated behavior lands inside a regulated product or safety obligation, sloppy process gets a lot harder to defend in court.

I am being careful with “can” on purpose. This is how the rules fit together, not a magic sentence that says “AI equals liability.” Still, it is close enough to shape engineering behavior now. And the point is not that there is a ton of paperwork. The interesting aspect is that it includes the software development process as part of the paper trail. Which means, we will have to adapt the SDLC too and ensure it carries auditing and responsibility documentation too.

What responsible teams do differently

The first change you should make is simple. AI-generated code should get harder reviews, not easier ones.

That sounds backward until you remember the failure mode. Human reviewers are used to reading code for logic mistakes, incomplete edge handling, naming weirdness, and intent drift. AI-generated code deserves all of that plus pattern risk. You are reviewing something that may be locally polished and globally naive, statistically good at common shapes and statistically bad at the exact invariants your system cares about.

The second change is keeping a clear trail. If a significant block of code came from an assistant, say so in the pull request (or git notes) and say who owns it now. I do not mean a simple disclaimer. I mean a useful note. Which tool was used? Which parts were heavily generated? Who reviewed the transaction boundaries, auth assumptions, dependency choices, and data handling? Future you will not remember. Incident review definitely will not guess it correctly from vibes.

The third change is that automation has to stay in the loop after generation. Static analysis, secrets scanning, dependency analysis, and license checks are not anti-AI rituals. They are the minimum viable skepticism for high-volume code generation. If AI is making authorship cheaper, your guardrails need to get cheaper and louder too.

The fourth change is that rules belong close to the tool. Custom instructions, repository rules, banned dependency patterns, template constraints, secure defaults, architectural linting, required checks before merge, and path-specific review policies all matter more now. A handbook that says “please review carefully” is a wish.

A harness that makes bad output harder to suggest and harder to merge is governance.

Most teams do not need a grand AI policy before they can act. They need to start with a small sentence: Every AI-generated code path that reaches production must have a human who can explain what it does, why it is safe enough, and what the failure mode looks like. If nobody on the team can do that, the correct response is not “ship it and monitor.” The correct response is “rewrite it until somebody can.”

Judgment is the scarce thing

I do not think AI makes senior engineers less important. I think it makes unserious ownership much more visible. And I wrote about this before in other words.

For years, authorship and accountability were close enough together that we could treat them as basically the same thing. You wrote the code, so you owned the code. AI breaks that overlap. Now code can be authored by a model, accepted by a developer, reviewed by someone skimming a diff, and deployed by a pipeline that does not care who’s thought that was. The authorship story gets fuzzy fast.

The responsibility story does not. The engineer who signs off, the team that ships, and the company that runs or sells the system still own what it does. That is not old-fashioned. It is the only part of the deal that still works when authorship gets strange.

The developers who build real reputations in this phase will not be the ones who accepted the most suggestions or generated the most files. They will be the ones whose names mean somebody checked the hard parts. In the AI era, that is not a sentimental virtue. It is the job.

Subscribe now

Quarkus JAR Tree Shaking: Trim Dead Weight From JVM Builds

Markus — Wed, 13 May 2026 06:08:55 +0000

./mvnw package finishes, you open target/quarkus-app/lib/main/, and the totals are honest: this is what the JVM will load and what your registry layer will push. A lot of those classes will never run. They are along for the ride because something on the classpath once referenced them, or because a fat dependency carries entire subsystems you never touch.

Native image already does aggressive dead-code elimination; JVM mode did not have the same story at the JAR layer until recently. In Quarkus 3.35 the project shipped an experimental bytecode reachability pass that can remove unreachable dependency classes during packaging. The full behavior, limits, and knobs are documented in the Tree-shaking JAR dependencies guide.

What tree shaking means in this stack

The JavaScript world stole the word “tree shaking” from compilers; in Quarkus it means build-time reachability over dependency bytecode , not wishful thinking about pom.xml. The guide walks the algorithm in detail (roots, BFS, dynamic ClassLoader edge cases, exclusions). The practical contract for this article is smaller:

Config — quarkus.package.jar.tree-shake.mode=classes enables it; none is the default.
Packaging — works for fast-jar, uber-jar, legacy-jar, and aot-jar. It does not apply to mutable-jar (re-augmentation needs complete dependency bytecode).
Scope — only runtime dependency classes are candidates. Your application classes are never removed. Non-class resources mostly stay; a dependency can remain in the layout even if every class file was stripped, because resources might still matter.

If you prefer a picture to a reachability lecture, this is the package-time path we are talking about:

[

](https://substackcdn.com/image/fetch/$s_!7wez!,f_auto,q_auto:good,fl_progressive:steep/https%3A%2F%2Fsubstack-post-media.s3.amazonaws.com%2Fpublic%2Fimages%2Fafe5b85c-2f57-40b6-b115-e465bae1759e_784x181.png)

One easy wrong turn here is to confuse tree shaking with quarkus.index-dependency.*. That property is about Jandex indexing , which is how Quarkus builds its view of third-party JARs for CDI, JAX-RS scanning, and similar build-time work.

Tree shaking is a different step later in packaging. It follows bytecode reachability, plus explicit exclusions such as quarkus.package.jar.tree-shake.excluded-artifacts, so indexing alone will not rescue a class the shaker decided is dead.

If something still blows up at runtime with ClassNotFoundException, the guide’s playbook is: confirm it goes away with mode=none, then exclude the artifact or tighten your dynamic-loading story before you reopen the bug tracker.

What we build

Helios is a fictional fleet platform; we only need a slice that is credible on a résumé and small enough to read in one sitting.

You end up with a Maven aggregator folder and two independent Quarkus services :

helios-analytics — accepts a CSV payload on POST /import using Apache Commons CSV as a CSVParser, count-only JSON response ({"imported": n}).
helios-api — GET /export returns plain text CSV using CSVPrinter only.

Both depend on the same commons-csv coordinate so you can compare how little the library jar itself moves while the overall lib/ still drops when Quarkus peels framework fat. Analysis is per application module at packaging time (Tree-shaking JAR dependencies) — identical classpaths get identical summaries; differing code would diverge.

What you need

This demo is small, but the versions still matter because we are comparing packaging output, not debugging tool drift. If you only want the finished code, grab it from my Github repository.

JDK 21 (matches the demo pom.xml; bump if you standardize elsewhere).
Network for the first Maven download.
Quarkus platform 3.35.1 on the classpath (pinned in both pom.xml files).

Build the aggregator shell

Pick a workspace root — this tutorial uses helios-tree-shaking/ as the directory name.

mkdir -p helios-tree-shaking
cd helios-tree-shaking

Scaffold `helios-analytics`

Still inside helios-tree-shaking/, generate the first application (Maven wrapper included):

mvn -q io.quarkus.platform:quarkus-maven-plugin:create \
  -DprojectGroupId=org.helios \
  -DprojectArtifactId=helios-analytics \
  -Dextensions='rest-jackson' \
  -DclassName="org.helios.analytics.TelemetryImportResource" \
  -Dpath="/import"

Open helios-analytics/pom.xml and check the few things that matter:

packaging is quarkus.
quarkus.platform.version is 3.35.1 (or newer 3.35.x you have validated).
Add commons-csv explicitly (version 1.12.0) alongside quarkus-rest-jackson.

Use this dependency block inside <dependencies> (keep the BOM import dependencyManagement the generator produced; we are only adding what the demo needs):

        <dependency>
            <groupId>org.apache.commons</groupId>
            <artifactId>commons-csv</artifactId>
            <version>1.12.0</version>
        </dependency>

I keep both apps on the same Quarkus extension set on purpose. That way the before/after numbers mostly reflect usage differences inside the shared dependency graph instead of two unrelated application shapes.

Configure HTTP so this service does not fight the sibling module during local runs:

Replace src/main/resources/application.properties with:

quarkus.application.name=helios-analytics

quarkus.http.port=8080

# Baseline measurements use `none`; switch to `classes` when you enable tree shaking.
quarkus.package.jar.tree-shake.mode=none

Create src/test/resources/application.properties:

quarkus.http.test-port=8081

Add the record next to your resource package — src/main/java/org/helios/analytics/TelemetryRecord.java:

package org.helios.analytics;

import java.time.Instant;

public record TelemetryRecord(String deviceId, double lat, double lon, Instant timestamp) {

}

Replace the generated JAX-RS class with src/main/java/org/helios/analytics/TelemetryImportResource.java:

package org.helios.analytics;

import java.io.IOException;
import java.io.StringReader;
import java.time.Instant;
import java.util.List;
import java.util.Map;

import org.apache.commons.csv.CSVFormat;
import org.apache.commons.csv.CSVParser;
import org.apache.commons.csv.CSVRecord;
import org.jboss.logging.Logger;

import jakarta.ws.rs.Consumes;
import jakarta.ws.rs.POST;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.core.MediaType;
import jakarta.ws.rs.core.Response;

@Path("/import")
public class TelemetryImportResource {

    private static final Logger LOG = Logger.getLogger(TelemetryImportResource.class);

    @POST
    @Consumes(MediaType.TEXT_PLAIN)
    @Produces(MediaType.APPLICATION_JSON)
    public Response importCsv(String csvPayload) throws IOException {
        LOG.debug("Importing telemetry CSV payload");

        CSVFormat format = CSVFormat.DEFAULT.builder()
                .setHeader()
                .setSkipHeaderRecord(true)
                .build();

        try (CSVParser parser = format.parse(new StringReader(csvPayload))) {

            List<TelemetryRecord> records = parser.stream()
                    .map(this::toRecord)
                    .toList();

            return Response.ok(Map.of("imported", records.size())).build();
        }
    }

    private TelemetryRecord toRecord(CSVRecord row) {
        return new TelemetryRecord(
                row.get("deviceId"),
                Double.parseDouble(row.get("lat")),
                Double.parseDouble(row.get("lon")),
                Instant.parse(row.get("timestamp")));
    }
}

Change src/test/java/org/helios/analytics/TelemetryImportResourceTest.java:

package org.helios.analytics;

import static org.hamcrest.Matchers.is;

import org.junit.jupiter.api.Test;

import io.quarkus.test.junit.QuarkusTest;
import io.restassured.RestAssured;
import io.restassured.http.ContentType;

@QuarkusTest
class TelemetryImportResourceTest {

    @Test
    void importParsesRows() {
        String csv = ""
                + "deviceId,lat,lon,timestamp\n"
                + "truck-1,53.5511,10.0055,2025-04-02T09:15:30Z\n"
                + "truck-2,48.1351,11.5820,2025-04-02T09:16:01Z\n";

        RestAssured.given()
                .contentType(ContentType.TEXT)
                .body(csv)
                .when()
                .post("/import")
                .then()
                .statusCode(200)
                .body("imported", is(2));
    }
}

Smoke it:

cd helios-analytics
./mvnw test

Scaffold `helios-api`

Return to helios-tree-shaking/:

cd ..

Generate the sibling service:

mvn -q io.quarkus.platform:quarkus-maven-plugin:create \
  -DprojectGroupId=org.helios \
  -DprojectArtifactId=helios-api \
  -Dextensions='rest-jackson' \
  -DclassName="org.helios.api.TelemetryExportResource" \
  -Dpath="/export"

Apply the same BOM + commons-csv + Quarkus dependencies pattern you used for analytics (matching versions). Use a different HTTP port and test port so both apps can coexist on a laptop.

src/main/resources/application.properties

quarkus.application.name=helios-api

quarkus.http.port=8090

quarkus.package.jar.tree-shake.mode=none

src/test/resources/application.properties

quarkus.http.test-port=8091

src/main/java/org/helios/api/TelemetryExportResource.java

package org.helios.api;

import java.io.IOException;
import java.io.StringWriter;

import org.apache.commons.csv.CSVFormat;
import org.apache.commons.csv.CSVPrinter;
import org.jboss.logging.Logger;

import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.core.MediaType;

@Path("/export")
public class TelemetryExportResource {

    private static final Logger LOG = Logger.getLogger(TelemetryExportResource.class);

    @GET
    @Produces(MediaType.TEXT_PLAIN)
    public String exportSampleCsv() throws IOException {
        LOG.debug("Generating sample telemetry CSV");

        CSVFormat format = CSVFormat.DEFAULT.builder()
                .setHeader("deviceId", "lat", "lon", "timestamp")
                .build();

        StringWriter buffer = new StringWriter();
        try (CSVPrinter printer = new CSVPrinter(buffer, format)) {
            printer.printRecord("sample-7", "52.5200", "13.4050", "2025-05-06T08:00:00Z");
        }
        return buffer.toString();
    }
}

src/test/java/org/helios/api/TelemetryExportResourceTest.java

package org.helios.api;

import static org.hamcrest.Matchers.containsString;

import org.junit.jupiter.api.Test;

import io.quarkus.test.junit.QuarkusTest;
import io.restassured.RestAssured;

@QuarkusTest
class TelemetryExportResourceTest {

    @Test
    void exportReturnsCsvBody() {
        RestAssured.given()
                .when()
                .get("/export")
                .then()
                .statusCode(200)
                .body(containsString("deviceId"))
                .body(containsString("sample-7"));
    }
}

cd helios-api
./mvnw test

Give Both Modules a Home

Create pom.xml at the aggregator root (helios-tree-shaking/pom.xml):

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>org.helios</groupId>
    <artifactId>helios-tree-shaking</artifactId>
    <version>1.0.0-SNAPSHOT</version>

    <packaging>pom</packaging>

    <name>Helios fleet demo (aggregator)</name>

    <modules>
        <module>helios-analytics</module>
        <module>helios-api</module>
    </modules>
</project>

You will populate the modules in the next two sections. Maven only needs those <module> lines once matching directories exist.

From the aggregator you can sanity-check both modules:

cd ..
mvn -pl helios-analytics,helios-api test

(Either ./mvnw inside each leaf or your system Maven at the aggregator — the generator gave each leaf its own wrapper, which keeps the demos self-contained.)

Measure before you shake anything

Go into helios-analytics/ first. Produce a fast-jar layout without tree shaking (explicit none keeps the story consistent even after you tweak defaults):

./mvnw package -DskipTests

Total dependency library weight (lib/main is the interesting directory for fast-jar layouts):

du -sh target/quarkus-app/lib/main

Commons CSV footprint inside that directory — filenames follow group-artifact-version.jar:

ls -lh target/quarkus-app/lib/main/org.apache.commons.commons-csv-1.12.0.jar
jar tf target/quarkus-app/lib/main/org.apache.commons.commons-csv-1.12.0.jar | grep '\.class$' | wc -l

On my machine macOS aarch64 with Quarkus 3.35.1, I got ≈ 18 MB under target/quarkus-app/lib/main/ for helios-analytics, and commons-csv still carried 20 .class files inside ≈ 55 KB. Your classpath width will move those digits a bit; the important part is having a baseline you can compare against after the rebuild.

Repeat the du / ls / jar tf … | wc trio for helios-api/ so you trust the aggregator story with your own numbers.

Optional curiosity pass — classify every lib/main JAR quickly (warning: noisy output):

find target/quarkus-app/lib/main -name '*.jar' -exec sh -c \
  'printf "%s: " "$1"; jar tf "$1" | grep -c "\.class$" || true' sh {} \;

Enable tree shaking

Option A — edit `application.properties`

In each module:

quarkus.package.jar.tree-shake.mode=classes

Rebuild with ./mvnw package -DskipTests.

Option B — one-shot Maven invocation

Keeps defaults on disk untouched while you iterate:

./mvnw package -DskipTests -Dquarkus.package.jar.tree-shake.mode=classes

Reading the analyzer output

Tree shaking logs a single INFO line from io.quarkus.deployment.pkg.steps.JarTreeShaker. Example copied from helios-analytics on the reference machine:

[INFO] [io.quarkus.deployment.pkg.steps.JarTreeShaker] Tree-shaking removed 2757 unreachable classes from 90 dependencies, saving 7.2 MB (25.1%)

helios-api logged the same totals here because both apps carry the identical extension set and dependency graph; divergence shows up once your services stop being clones.

Per the guide’s troubleshooting section, you can raise JarTreeShaker to DEBUG for per-dependency detail when something looks wrong:

quarkus.log.category."io.quarkus.deployment.pkg.steps.JarTreeShaker".level=DEBUG

I did not paste multi-screen debug dumps — if you enable it locally, skim for the dependency that violates your intuition before you freeze an exclusion list.

After the shaker runs — rerun the rulers

Rebuild with mode=classes (either property or -D). On the tutorial reference build:

du -sh target/quarkus-app/lib/main
jar tf target/quarkus-app/lib/main/org.apache.commons.commons-csv-1.12.0.jar | grep '\.class$' | wc -l

Dropped to ≈ 14 MB for both modules in du -sh terms (about four megabytes slimmer at the filesystem layer). JarTreeShaker simultaneously reported saving 7.2 MB (25.1%) — that aggregate counts class file payload carved out when Quarkus rewrote dependency JARs, so du and the saving line are related but not the same accountant.

commons-csv itself only shed one .class file in this constrained example ( 20 → 19 ). That is intentional pedagogy: the demo dependency is tiny; the CSVParser ‑heavy versus CSVPrinter ‑only contrast will show up in which commons classes remain far more than in raw jar size. The headline savings came from shaving Netty stacks, ancillary Jackson bits, Vert.x paths, and the rest of Quarkus’s runtime graph that your imports never exercised.

Regression guard:

./mvnw test -Dquarkus.package.jar.tree-shake.mode=classes

If this fails while plain none succeeds, grab the ClassNotFoundException, locate the offending coordinate, and start with quarkus.package.jar.tree-shake.excluded-artifacts as documented upstream. If everything still points to analyzer blind spots, then it is time to open the upstream issue.

Another escape hatch shows up when you are doing the dynamic lookup yourself: @RegisterForReflection for the cases Quarkus cannot infer. If you build type names from strings or wander into service discovery paths the shaker never observed, exclusions still exist. They are blunt, but blunt is often fine when the alternative is a broken build and a heroic explanation.

Native mode already performs its own dead-code story; JVM fast-jar container pulls are where this knob tends to sting.

Optional — feel the packaging tax

Cold builds pay for reachability passes. Rough comparison on the demo machine (helios-analytics):

/usr/bin/time -p ./mvnw package -DskipTests -Dquarkus.package.jar.tree-shake.mode=none
/usr/bin/time -p ./mvnw package -DskipTests -Dquarkus.package.jar.tree-shake.mode=classes

Your wall times will float with caches, Maven -T, and CPU throttle; CI is where budgeting gets serious.

Close the loop

The point of this demo is not that commons-csv suddenly becomes tiny. The point is that a plain JVM Quarkus build can stop shipping a surprising amount of dead dependency bytecode. In this setup, the two apps dropped from about 18 MB to 14 MB , the shaker removed 2757 unreachable classes, and the tests still passed after the rebuild.

That is enough for me to try it on any fast-jar service that is about to become a container image. Measure the baseline, rebuild with classes, rerun the tests, and keep excluded-artifacts nearby for the dynamic corners.

Subscribe now

The Senior Developer's New Job Is Saying No

Markus — Mon, 11 May 2026 06:08:58 +0000

The junior developer on your team shipped three new services last week. With AI. All of them start, answer requests, and have tests. None of them should exist.

That used to be a rarer problem. For a long time, software teams spent most of their energy on the question, “Can we build it?” The answer depended on time, headcount, expertise, patience, and how much pain the codebase could absorb before it started pushing back. Those limits were annoying, but they were also useful. They forced prioritization.

That old question is getting cheaper by the month. In Stop Measuring AI by How Much You Use It, I made the case that AI activity is easy to measure and easy to misunderstand. Token burn, seat activation, prompt volume, and all the rest can make a dashboard look busy without proving that anything improved. Same problem here. AI does not remove the need for judgment. It removes some of the friction that used to hide the need for judgment.

So the senior job changes. Maybe not in title or salary band, but in where the real work sits. We still design, debug, mentor, and clean up the weird edges of production systems. The scarce skill is shifting. The harder question is less often “how do we build this?” and more often “why are we building this at all, and who is going to carry it after the demo?”

When “senior” meant friction

Experience has always been a proxy for judgment. We like to pretend seniority is about knowing more frameworks or having stronger opinions about architecture diagrams, but the useful part was usually much simpler. Senior developers had a better sense for which ideas were worth turning into code.

Older delivery systems had built-in brakes. Sprint capacity, story points, quarterly planning, dependency reviews, architecture boards, “we do not have bandwidth for that this quarter.” Teams complained about those things, often correctly. Plenty of them were theater. But even the theater imposed a cost on new work, and cost changes behavior.

For all the complaining, that friction did two useful things.

First, it made stakeholders explain themselves. If an idea had to survive a planning meeting, somebody usually had to define the actual problem, the affected users, and the trade-off.

Second, it made developers ask whether a proposed change was worth the maintenance bill. You could not casually turn every half-formed suggestion into a service, a background job, a dashboard, or an integration because building any one of those things took enough time to trigger an argument.

AI strips out a lot of that delay. I do not mean only autocomplete. I mean the whole stack of “good enough to merge” generation: code, tests, config, docs, YAML, client wrappers, even the cheerful little README that explains the system nobody asked for. The proposal no longer has to survive scarcity. It only has to survive enthusiasm.

That is why senior developers become filters. Not because we enjoy blocking people, and not because every fast change is reckless. The point is that the old brakes are weaker, and the replacement brake is judgment.

The backlog is now a decision queue

When implementation drops from weeks to an afternoon, every idea starts to look cheap. Stakeholders notice that in about five minutes.

“Could we just have AI spin up a small service for that?”

“Could we wrap this system in a tool so the agent can call it?”

“Could we generate a migration for the old module and clean it up later?”

Of course we could. That is the easy part now.

The harder part is that every one of those “just” decisions creates a maintenance obligation. A tiny service still needs ownership, telemetry, security updates, deployment wiring, on-call understanding, and future changes by somebody who did not generate it. A generated integration is still an integration. A one-off MCP server is still one more thing your team has to remember exists when credentials rotate or a downstream contract changes.

This is where old ideas like YAGNI get interesting again. YAGNI used to be a warning against speculative abstraction inside a codebase. In an AI-heavy workflow, it also needs to become a warning against speculative systems. Martin Fowler makes the small-scale point nicely: lots of tiny YAGNI decisions reduce complexity. The units are bigger now. We are not only overbuilding methods and abstractions. We are overbuilding services, agents, wrappers, and modernization branches.

The enterprise Java world is especially exposed to this. Modernization already creates strong pressure to decompose, migrate, wrap, and replace. Add AI to that, and the volume goes up fast. Konveyor AI shows AI-assisted migration from Java EE to Quarkus. IBM Bob promises validated upgrades in days instead of months. I do not think any of that is fake. The tools are real, and some of them are genuinely useful. The risk is not that the migration output fails to compile. The risk is that teams can now manufacture more architectural surface area than they can sensibly own.

That changes the shape of the backlog. It is no longer just a queue of work. It is a queue of decisions about what not to build.

What “no” is protecting

For me, “no” protects three things.

First, it protects maintenance capacity. McKinsey’s tech debt research already had CIOs estimating debt at 20 to 40 percent of estate value before this generation of AI tooling showed up. AI does not erase that bill. It just makes it easier to put more on the card.

Second, it protects team cognition. More systems do not only mean more code. They mean more names, more data flows, more half-documented assumptions, and more places where a change can surprise you. Every extra service steals a little understanding from the rest of the system. Eventually nobody holds the whole shape in their head, which means every change gets slower even while generation gets faster.

Third, it protects architecture. AI-generated code usually fits locally, which is exactly why it is seductive. The class compiles. The endpoint works. The tests pass. Local fit is cheap. Global fit is the job.

We learned this already with microservices. Teams split monoliths into distributed monoliths because the boundary cost was hidden until production collected the bill. We are volunteering to relearn the same lesson at the agent and tool layer. Wrap every internal system in a tool. Generate an agent for each workflow. Add another broker. Add another memory store. Add another approval loop. Soon the topology diagram looks modern and the operating model looks tired.

Conway’s Law still wins here. If your organization is confused, the generated architecture will mirror that confusion. AI does not clean up the org chart. It renders it faster.

This is also where the current vibe coding discourse gets interesting. I do not even dislike the term. It is at least honest. For small experiments, internal tools, and personal prototypes, vibes are fine. Production systems still need adults in the room. Somebody eventually has to understand the failure modes, and “the model wrote it” is not an operational plan.

Four tests before you say yes

If senior developers are now filters, the obvious next question is what the filter looks like. I do not think this needs a giant framework, laminated card, or maturity model. It needs a few blunt questions asked early enough to matter.

The Carry Test

Would we still want this if the AI that generated it disappeared tomorrow and we had to own it by hand?

That question clears out a surprising amount of nonsense. If the answer is no, we are not approving a system. We are approving a temporary hallucination with hosting.

The Problem Clarity Test

Can someone state the problem this solves in one sentence without mentioning the technology?

If the explanation starts with the agent, the model, the framework, the microservice, or the protocol, we probably do not have a problem statement yet. We have a build impulse wearing technical clothes.

The Duplication Test

Does this already exist somewhere in the estate, and is our version meaningfully different?

AI makes duplicate effort feel cheap because the local cost is low. The estate-level cost is still real. A second service with 85% overlap is not faster delivery. It is a forked maintenance burden with a nicer origin story.

The Consequence Test

What is the blast radius if this is wrong?

Wrong does not only mean “throws an exception.” It also means bad routing, bad approvals, wrong data, false confidence, and a migration that preserves behavior nobody wanted to preserve. In enterprise systems, wrong software often works beautifully right up until it reaches the business rule that mattered.

Those four tests do not replace judgment. They force it into the room earlier, which is where it belongs.

Metrics still miss the real question

This is also why I am wary of using AI-era throughput as a proxy for value.

I still like the classic DORA four keys because they say something real about delivery performance: deployment frequency, lead time, change failure rate, and time to restore service. Keep them. They are still better than vanity metrics.

But notice what they do not measure. None of them asks whether the thing should have been built. They measure how quickly and safely software moves, which is useful. It is still not the same as product judgment.

Once raw output becomes the celebrated number, Goodhart’s Law walks in right on schedule. If teams get rewarded for how much AI-assisted work they can push through the pipe, they will produce more work for the pipe. Some of it will be useful. Some of it will be architecture confetti. The dashboard will not know the difference, and the repo definitely will.

That gap between “can ship” and “should exist” is where senior judgment earns its keep.

No is design

I do not think saying no is a failure of imagination. For me, it is one of the last places real design still shows its teeth.

The best systems are defined as much by what they exclude as by what they contain. Good architecture is not a pile of clever yeses. It is a sequence of selective refusals: no, this does not need its own service; no, this workflow does not need an agent; no, we are not wrapping a stable internal API in three new layers because the demo looked smooth; no, we are not modernizing this part yet because we still do not know whether it should survive the business process around it.

AI will always offer to help you say yes. That is part of its charm. Give it a prompt and it will produce momentum. The human job is to decide whether that momentum deserves a future or just a branch nobody should merge.

The developers who matter most over the next five years will not be the fastest builders. They will be the best deciders. They will know when speed helps, when reuse is fake, when modernization is actually expansion, and when a clean-looking diff is still a bad system.

No is a skill. Senior developers should practice it on purpose. Even more so now.

Subscribe now

Stop Measuring AI by How Much You Use It

Markus — Tue, 05 May 2026 06:08:19 +0000

A colleague dropped a line in Slack that has been stuck in my head:

Some people are trying to burn as many coins as possible because it is measurable, and they think that counts as productivity.

Coins, credits, tokens, messages, seats, prompts. Pick your unit. Every enterprise AI platform eventually produces a dashboard that looks reassuringly precise. Someone can show that usage went up. Someone else can show that more teams activated their accounts. A third person can point to token consumption and say, with the straight face corporate dashboards seem to require, that adoption is accelerating.

The measurement is real. The interpretation is where things get slippery.

I understand why management wants adoption numbers. AI budgets are large, executive pressure is real, and nobody wants to explain that the company spent a year “exploring” while competitors shipped. IBM’s 2025 CEO study puts the pressure plainly: only 25% of surveyed AI initiatives delivered expected ROI, only 16% scaled enterprise-wide, and 64% of CEOs said fear of falling behind drives investment in some technologies before value is clear.

That is a perfect environment for adoption theater.

The danger is not that people use AI too much. I want developers, architects, platform engineers, support teams, and product people to experiment. I want agents inside the software delivery lifecycle. I want boring work to get automated and hard questions to get better support.

The danger is that we confuse measurable AI activity with productive change.

The Dashboard Is Not The Work

Usage metrics are useful. They tell you whether people have access, whether a rollout reached the intended audience, whether capacity planning is sane, whether cost is drifting, whether some teams need help, and whether governance controls are being bypassed.

They are bad productivity metrics.

Seat activation means someone can use the tool. Prompt count means someone did use the tool. Token spend means the system processed text. Reasoning-token consumption may mean people are asking the model to do harder work. It may also mean the agent got stuck in a loop, the prompt was sloppy, or the team turned a vague task into a very expensive conversation.

This is the old metrics problem with a new billable unit. Goodhart’s law is usually summarized as: when a measure becomes a target, it stops being a good measure. If prompt volume becomes a visible success metric, people will create prompt volume. If token consumption becomes evidence of transformation, people will burn tokens. Efficiently, even. We are very good at optimizing for the thing on the dashboard.

Developer productivity research has been warning about this for years. The SPACE framework exists partly because productivity is too complex to collapse into one number. It includes satisfaction and well-being, performance, activity, communication and collaboration, and efficiency and flow. The whole point is that activity is only one dimension. It is the easiest to count and one of the easiest to misread.

AI does not repeal that lesson. It makes the trap shinier.

Adoption Is High. Value Is Uneven.

The broad adoption story is real. McKinsey’s 2025 State of AI survey says 88% of respondents report regular AI use in at least one business function. It also says nearly two-thirds of organizations have not begun scaling AI across the enterprise, and only 39% report EBIT impact at the enterprise level.

That is the gap.

The tools are inside the building. The value is not automatically inside the operating model.

OpenAI’s own enterprise AI report shows how fast usage can scale: weekly ChatGPT Enterprise messages grew about 8x year over year, and average API reasoning-token consumption per organization grew about 320x. The report also argues that deeper workflow integration is where value appears. I agree with that framing. The important word is workflow. The value is not in the message count. The value is in the work that changed because of it.

Gartner’s supply-chain research makes the same point from another angle. In a 2025 survey, desk-based workers saved 4.11 hours per week with GenAI, and that time saved correlated with better individual output and quality. At team level, the time savings dropped to 1.5 hours per team member per week, with no correlation to improved output or higher quality.

That is not an anti-AI result. It is an anti-magic result.

Individual acceleration does not automatically become organizational throughput. A developer may finish a local task faster while the team spends more time reviewing a larger diff. A support engineer may draft a better answer faster while the knowledge base remains stale. A product manager may summarize customer feedback faster while prioritization still happens through politics, habit, and whoever had the louder slide.

AI can improve all of this. But the improvement has to land in the system, not just in an individual’s session history.

The Inner Loop Got Cheaper

For software delivery, the obvious AI story lives in the developer inner loop.

A developer states an intent. An agent reads context, edits files, runs tests, explains failures, adjusts the patch, drafts a pull request, and maybe writes the release notes. This is real. It is useful. It changes the economics of implementation.

Code, tests, docs, configuration, summaries, and analysis are now cheaper to produce. That is a big deal.

It also moves the bottleneck.

When implementation gets cheaper, specification and verification get more important. The hard part becomes deciding what should be true, constraining the work enough that the agent does not wander, proving that the result behaves correctly, and leaving enough evidence that another human can review the change without reconstructing the whole conversation from the diff.

This is where zero-spec agent work gets expensive. A vague prompt may produce a plausible patch quickly. That patch still has to be reviewed, tested, integrated, secured, deployed, operated, and explained. If the agent solved the wrong problem, the cost did not disappear. It moved downstream into the team.

I keep coming back to this sentence:

The unit of work is not the prompt. The unit of work is the change packet.

A useful change packet includes the intent, assumptions, non-goals, plan, diff, test results, validation results, open questions, rollback notes, and operational watchpoints. A pull request can carry that packet. A release artifact can carry it. The exact format matters less than the evidence.

Counting prompts ignores the packet. Counting tokens ignores the packet. Counting activated users ignores the packet.

The packet is where AI work becomes reviewable engineering work.

The Outer Loop Is Where Enterprise Value Appears

The narrow story says AI transforms the developer inner loop. True, but too small.

The serious enterprise story is the outer loop.

The inner loop turns intent into one change. The outer loop decides whether the stream of changes is sustainable. It includes portfolio choices, product priority, architecture ownership, risk classification, CI/CD, release controls, operations, compliance evidence, incident response, and learning from production.

Agents can help here too, but the work looks different. They can summarize incidents, draft runbook updates, compare release evidence, explain telemetry, prepare compliance notes, find repeated review comments, propose tests for recurring defects, and turn operational pain into better repository guidance.

That is where agentic development becomes an operating-model change.

If the outer loop does not change, faster implementation can make the organization worse. Bigger diffs arrive faster. Review queues grow. Test suites become trust bottlenecks. Security teams see more generated code with less visible intent. Platform teams answer the same questions again because the agent did not know local conventions. Operations inherits changes that looked technically valid but did not match ownership, deployment policy, or production reality.

The work looked cheap at the prompt boundary. The cost arrived in everyone else’s calendar.

This is why I like thinking in terms of an agentic SDLC rather than a coding assistant rollout. The goal is not just more AI in editors. The goal is a delivery system where agents can participate safely across the lifecycle:

Shared intent before execution
Small validated specs instead of vague prompts
Repo-local guidance such as AGENTS.md
Reusable skills with ownership and review
Behavior tests that act as executable oracles
Validation gates for security, policy, provenance, and release readiness
Risk-based autonomy instead of one permission model for every task
A controlled production boundary
Evidence that survives the chat session
Operational feedback that improves the next round of agent work

That list is not a plea for more process. Please, no. Enterprises have enough process sediment to form attractive geological layers.

The point is to move judgment into durable places. If a reviewer leaves the same comment on five agent-generated pull requests, that comment should probably become repo guidance, a skill, a test, or a validation gate. If an incident reveals that the agent did not understand an operational constraint, that learning should feed the readiness layer. If a team keeps burning tokens rediscovering the same build command, the problem is not enthusiasm. The problem is missing context.

Measure Flow, Not Heat

Token burn is heat. It tells you energy was consumed.

Flow tells you whether the system got better at turning intent into safe production change.

For software teams, we already have a better starting point than AI usage dashboards. DORA’s software delivery metrics measure change lead time, deployment frequency, failed deployment recovery time, change fail rate, and deployment rework rate. DORA groups these into throughput and instability, which is exactly the kind of balance AI programs need. Speed alone is not a win if the speed mostly creates rework.

DORA’s 2025 AI-assisted software development report also uses a phrase I like: AI is an amplifier. It magnifies an organization’s existing strengths and weaknesses. That feels right. A team with strong tests, clear ownership, small batches, good CI, and healthy review habits gets more leverage. A team with weak specs, flaky tests, unclear architecture, and overloaded reviewers gets faster confusion.

So measure the system.

At the inner-loop level, useful questions look like this:

Did change lead time improve for comparable work?
Did agent-assisted changes stay small enough to review?
Did the team add or improve behavior tests with the change?
How often did reviewers have to reconstruct intent from the diff?
How often were agent-generated changes accepted, substantially rewritten, or abandoned?
Which task categories produced reliable gains, and which produced rework?

At the outer-loop level, the questions get more interesting:

Did deployment rework go down?
Did change fail rate stay stable or improve?
Did recovery get faster because rollback notes and operational watchpoints improved?
Did repeated review comments turn into guidance, tests, or skills?
Did incidents feed back into AGENTS.md, runbooks, validation gates, or architecture rules?
Did security and compliance get better evidence earlier in the lifecycle?
Did platform teams see fewer repeated questions because context became reusable?

That is a different adoption story.

“We consumed 40 million tokens this quarter” is a cost sentence pretending to be a transformation sentence.

“We reduced review rework for dependency upgrades because the agent now follows a maintained skill, opens smaller pull requests, attaches test evidence, and updates rollback notes” is a transformation sentence.

Less shiny. Much better.

Exploration Still Counts

There is one caveat worth saying clearly: exploration is real work.

Early AI adoption needs space for experiments that do not immediately produce ROI. People need to learn the tools. Teams need to find where agents help and where they are mostly expensive autocomplete with confidence issues. Some use cases will die, and they should. Killing a bad AI use case is not resistance. It is governance with a pulse.

The problem starts when exploration metrics get promoted into productivity metrics.

During exploration, usage can be a healthy signal. You want to know whether people are trying the tools, where they get stuck, which workflows attract attention, and where cost spikes. But an exploration phase should produce learning artifacts:

A list of useful and rejected use cases
Prompt and workflow patterns that survived contact with real work
Team guidance for when to use agents and when not to
New or improved behavior tests
Updated AGENTS.md files
Reusable skills
Safer tool permissions
Better validation gates
Evidence templates for pull requests and releases

If exploration produces only consumption, it was consumption.

If exploration improves the outer loop, it was investment.

What I Would Ask Before Celebrating Adoption

The next time someone shows an AI adoption dashboard, I would not start by arguing with the chart. The chart probably tells a useful operational story. I would ask what story it cannot tell.

Five questions usually get there:

Which workflow changed?
What got better for the customer, developer, operator, or business?
What human work disappeared, and what new human work appeared?
What risk did we introduce or reduce?
Which durable artifact improved the next run: test, skill, guidance, validation gate, runbook, evidence trail, or architecture rule?

Those questions are harder than “how many people used AI last month?” That is why they are useful.

They also protect teams from the worst version of adoption pressure. If leadership asks only for usage, rational teams will produce usage. If leadership asks for workflow outcomes and evidence, teams have permission to do the slower, more valuable work of changing the system.

The Better Adoption Story

I am not interested in an enterprise where everyone gets a chatbot and a quarterly dashboard declares victory.

I am interested in an enterprise where agentic development changes how software moves from intent to production. The developer inner loop gets faster, yes. But the outer loop gets smarter too. Specifications become smaller and more testable. Pull requests carry better evidence. Review friction becomes reusable guidance. Incidents update future agent context. Production boundaries stay controlled. Low-risk work gets lighter paths. High-risk work gets better analysis without handing production keys to an enthusiastic model.

That is adoption worth measuring.

Burning coins may be necessary while teams learn. It is also a terrible definition of progress. Ashes are measurable. So is heat. Neither tells you whether the organization learned how to deliver safer, better software.

The useful AI question is:

What changed in the system because we used it?

If the answer is only “the usage graph went up,” we did not transform the SDLC. We decorated the burn rate.

Subscribe now

Build a Real-Time ISS Tracker with Quarkus, SSE, and Qute

Markus — Mon, 30 Mar 2026 06:08:44 +0000

Most developers look at a small real-time app like this and think it is mainly a frontend exercise. Poll an API, move an icon on a map, done. That works for a demo, but it breaks down fast when you turn it into an actual service. Browsers start polling too often, upstream calls pile up, your server does duplicate work for every tab, and one slow public API drags the whole thing down.

The better mental model is this: the browser is not the source of truth. Your Quarkus service is. It owns the upstream HTTP call, it decides how often data gets refreshed, it caches the latest good result, and it pushes updates to every connected client. That gives you one polling loop, one failure boundary, and one place to harden behavior when the upstream service is slow or unavailable.

This matters even in a small tutorial. Public APIs fail. Network calls stall. Frontends reconnect. SSE clients disappear without warning. If you do not put the right boundaries in place, a harmless little tracker turns into a noisy service that wastes threads, floods logs, and shows stale or broken data when you most need predictable behavior.

In this tutorial, we build the safer version. We use a typed REST client for the Open Notify ISS endpoint, a scheduler that polls every 10 seconds, an application-scoped cache that stores the latest fix, an SSE endpoint that broadcasts updates, and a Qute frontend that renders the marker on a world map.

The ISS has always had a special pull on us at home. The kids and I have been fascinated by NASA, rockets, astronauts, and all the space stuff for as long as I can remember, and the ISS makes that fascination feel real because it is not science fiction or a distant concept, it is up there right now, moving above our heads. It is also a nice reminder that space software lives under hard, real-world constraints where reliability, testability, and long-term maintainability matter more than hype. That is one reason the stable JVM ecosystem keeps showing up in serious environments: NASA’s own history includes Java-based work such as Java Pathfinder at Ames, and even Java Champion James Weaver has been featured in a NASA Goddard colloquium context.

Prerequisites

You need a recent Java and Maven setup, and you should already be comfortable with CDI, REST endpoints, and basic Quarkus project structure. This is not a beginner Java tutorial. It is aimed at Java developers who want a clean end-to-end example that they can understand, run, and extend.

Java 21 installed
Maven 3.9+
Quarkus CLI installed, or comfort with the Maven plugin
Basic understanding of CDI, JAX-RS, and JSON
A working internet connection because the service calls the Open Notify ISS endpoint

Project Setup

Create the project or start from my Github repository:

quarkus create app com.themainthread:iss-tracker \
  --extension='rest-jackson,rest-client-jackson,qute,rest-qute,scheduler,smallrye-health' \
  --no-code
cd iss-tracker

Each extension has a job:

rest-jackson - REST endpoints with Jackson JSON serialization
rest-client-jackson - typed REST client support for the upstream ISS API
qute - server-side templates
rest-qute - smooth integration between Qute and REST resources
scheduler - periodic polling of the ISS position
smallrye-health - /q/health endpoints and readiness checks

Add two extra test dependency are needed. For @InjectMock support in Quarkus tests and RestAssured:

<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-junit-mockito</artifactId>
    <scope>test</scope>
</dependency>
        <dependency>
            <groupId>io.rest-assured</groupId>
            <artifactId>rest-assured</artifactId>
            <scope>test</scope>
        </dependency>

Create the souce folder structure:

mkdir -p src/main/java/com/themainthread/iss/{client,health,resource,service,util}
mkdir -p src/main/resources/templates/IndexResource
mkdir -p src/test/java/com/themainthread/iss/{resource,service,util}

Implementation

Model the upstream API

The Open Notify ISS endpoint returns a very small JSON payload with latitude and longitude as strings, not doubles. Model that shape exactly first. Do not “improve” the upstream contract in your record. Parse when you need numbers. The API docs show that shape explicitly.

Create src/main/java/com/themainthread/iss/client/IssPosition.java:

package com.themainthread.iss.client;

import com.fasterxml.jackson.annotation.JsonProperty;

public record IssPosition(
        @JsonProperty("latitude") String latitude,
        @JsonProperty("longitude") String longitude) {
    public double latDouble() {
        return Double.parseDouble(latitude);
    }

    public double lonDouble() {
        return Double.parseDouble(longitude);
    }
}

Create src/main/java/com/themainthread/iss/client/IssNowResponse.java:

package com.themainthread.iss.client;

import com.fasterxml.jackson.annotation.JsonProperty;

public record IssNowResponse(
        String message,
        long timestamp,
        @JsonProperty("iss_position") IssPosition issPosition) {
}

Java records are the right fit here. The data is read-only, small, and short-lived. You get immutability and clean logging without boilerplate. The limit is obvious too: records do not replace domain logic. They are just a good boundary for a small external JSON contract.

Create the typed REST client

Now we create the client that talks to Open Notify. Quarkus supports this pattern directly with MicroProfile REST Client, and the Quarkus REST client guide still recommends rest-client-jackson when you want Jackson-based JSON mapping.

Create src/main/java/com/themainthread/iss/client/IssApiClient.java:

package com.themainthread.iss.client;

import org.eclipse.microprofile.rest.client.inject.RegisterRestClient;

import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.core.MediaType;

@RegisterRestClient(configKey = "iss-api")
@Path("/iss-now.json")
public interface IssApiClient {

    @GET
    @Produces(MediaType.APPLICATION_JSON)
    IssNowResponse fetchPosition();
}

This client gives you one clear interface for the upstream dependency. That matters later when you test the poller. You can swap in a mock and drive the scheduler logic without touching the network.

The limit is that this interface does not solve resilience on its own. If the upstream hangs, this call hangs until your configured timeout hits. That is why we set tight timeouts in configuration and use SKIP on the scheduler. The interface is clean. The failure behavior still depends on the rest of the system.

Convert latitude and longitude to map pixels

We need server-side projection math so every client gets the same coordinates. That avoids duplicated math in every browser and keeps the frontend simple.

Create src/main/java/com/themainthread/iss/util/MercatorProjection.java:

package com.themainthread.iss.util;

public final class MercatorProjection {

    public static final int MAP_WIDTH = 1280;
    public static final int MAP_HEIGHT = 640;

    private static final double MAX_WEB_MERCATOR_LAT = 85.05112878;

    private MercatorProjection() {
    }

    public static int[] toPixel(double latDeg, double lonDeg) {
        double clampedLat = Math.max(-MAX_WEB_MERCATOR_LAT, Math.min(MAX_WEB_MERCATOR_LAT, latDeg));

        double x = (lonDeg + 180.0) / 360.0 * MAP_WIDTH;

        double latRad = Math.toRadians(clampedLat);
        double mercatorY = Math.log(Math.tan(Math.PI / 4.0 + latRad / 2.0));
        double y = (MAP_HEIGHT / 2.0) - (MAP_WIDTH / (2.0 * Math.PI)) * mercatorY;

        int pixelX = (int) Math.round(Math.max(0, Math.min(MAP_WIDTH - 1, x)));
        int pixelY = (int) Math.round(Math.max(0, Math.min(MAP_HEIGHT - 1, y)));

        return new int[] { pixelX, pixelY };
    }
}

This utility gives you one guarantee: the same (lat, lon) always maps to the same (x, y) on your chosen canvas. That consistency matters because the backend and frontend now agree on a fixed coordinate system.

What it does not guarantee is cartographic correctness for every map projection you might use later. This is tuned for a Mercator-style image and a fixed canvas size. Change the map projection or aspect ratio and you must revisit the math. That is normal. Projection code is always coupled to how you draw the world.

Build the application-scoped cache and stream source

The cache is the center of the service. The scheduler writes to it. The JSON endpoint reads from it. The SSE endpoint streams from it. This is where we stop the browser from becoming the source of truth.

Create src/main/java/com/themainthread/iss/service/IssPositionCache.java:

package com.themainthread.iss.service;

import java.time.Instant;
import java.util.concurrent.atomic.AtomicReference;

import com.themainthread.iss.client.IssNowResponse;
import com.themainthread.iss.util.MercatorProjection;

import io.smallrye.mutiny.Multi;
import io.smallrye.mutiny.operators.multi.processors.BroadcastProcessor;
import jakarta.enterprise.context.ApplicationScoped;

@ApplicationScoped
public class IssPositionCache {

    public record PositionFix(
            double latitude,
            double longitude,
            int pixelX,
            int pixelY,
            long timestamp,
            Instant updatedAt) {
    }

    private final AtomicReference<PositionFix> latest = new AtomicReference<>(null);
    private final BroadcastProcessor<PositionFix> processor = BroadcastProcessor.create();

    public PositionFix update(IssNowResponse response) {
        double lat = response.issPosition().latDouble();
        double lon = response.issPosition().lonDouble();
        int[] pixels = MercatorProjection.toPixel(lat, lon);

        PositionFix fix = new PositionFix(
                lat,
                lon,
                pixels[0],
                pixels[1],
                response.timestamp(),
                Instant.now());

        latest.set(fix);
        return fix;
    }

    public PositionFix latest() {
        return latest.get();
    }

    public boolean hasData() {
        return latest.get() != null;
    }

    public void broadcast(PositionFix fix) {
        processor.onNext(fix);
    }

    public Multi<PositionFix> stream() {
        return processor;
    }
}

AtomicReference is enough here because each update replaces the whole snapshot. Readers never see half-written state. They either see the old fix, the new fix, or null before the first successful poll. That is exactly what you want.

The BroadcastProcessor gives you hot-stream behavior. Connected clients get new events. Clients that connect later do not get a backlog. That is the right behavior for a live tracker. The limit is that this is not a durable event log. If you want history, you need storage. A processor is for fan-out, not persistence.

Add the scheduler that polls Open Notify

Now we connect the REST client to the cache.

Create src/main/java/com/themainthread/iss/service/IssPoller.java:

package com.themainthread.iss.service;

import org.eclipse.microprofile.rest.client.inject.RestClient;
import org.jboss.logging.Logger;

import com.themainthread.iss.client.IssApiClient;
import com.themainthread.iss.service.IssPositionCache.PositionFix;

import io.quarkus.scheduler.Scheduled;
import jakarta.enterprise.context.ApplicationScoped;
import jakarta.inject.Inject;

@ApplicationScoped
public class IssPoller {

    private static final Logger LOG = Logger.getLogger(IssPoller.class);

    @Inject
    @RestClient
    IssApiClient client;

    @Inject
    IssPositionCache cache;

    @Scheduled(every = "10s", concurrentExecution = Scheduled.ConcurrentExecution.SKIP)
    void poll() {
        try {
            var response = client.fetchPosition();

            if (!"success".equalsIgnoreCase(response.message())) {
                LOG.warnf("Unexpected upstream response message: %s", response.message());
                return;
            }

            PositionFix fix = cache.update(response);
            cache.broadcast(fix);

            LOG.debugf("ISS fix updated - lat=%.4f lon=%.4f x=%d y=%d",
                    fix.latitude(), fix.longitude(), fix.pixelX(), fix.pixelY());

        } catch (Exception e) {
            LOG.errorf("Failed to fetch ISS position: %s", e.getMessage());
        }
    }
}

This method does one thing well. It fetches one fresh upstream value, updates one shared snapshot, and broadcasts one event. That simplicity matters in production. Scheduled code becomes fragile fast when it tries to do too much.

The critical setting here is concurrentExecution = SKIP. Without it, a slow upstream call can overlap with the next scheduled run. That is how tiny polling jobs slowly turn into thread waste. With SKIP, you lose one tick when the upstream is slow. That is fine for a public ISS feed updating every 10 seconds. Missing one poll is cheaper than building a queue of blocked work.

Expose the JSON and SSE endpoints

Quarkus REST supports SSE with @Produces(MediaType.SERVER_SENT_EVENTS) and @RestStreamElementType(MediaType.APPLICATION_JSON).

Create src/main/java/com/themainthread/iss/resource/IssResource.java:

package com.themainthread.iss.resource;

import org.jboss.resteasy.reactive.RestStreamElementType;

import com.themainthread.iss.service.IssPositionCache;
import com.themainthread.iss.service.IssPositionCache.PositionFix;

import io.smallrye.mutiny.Multi;
import jakarta.inject.Inject;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.core.MediaType;

@Path("/api/iss")
public class IssResource {

    @Inject
    IssPositionCache cache;

    @GET
    @Path("/position")
    @Produces(MediaType.APPLICATION_JSON)
    public PositionFix position() {
        return cache.latest();
    }

    @GET
    @Path("/stream")
    @Produces(MediaType.SERVER_SENT_EVENTS)
    @RestStreamElementType(MediaType.APPLICATION_JSON)
    public Multi<PositionFix> stream() {
        return cache.stream();
    }
}

The JSON endpoint is useful for the initial page load. The SSE endpoint is useful after that. This split keeps the frontend responsive even if it opens before the first live event arrives.

One small but important point: returning null from position() maps cleanly to 204 No Content. That means you do not have to invent a fake placeholder payload before the first successful poll. The client can handle “no data yet” honestly.

Serve the Qute frontend

Qute’s @CheckedTemplate support gives you build-time verification that your template exists. That is exactly the kind of failure you want at build time, not after deployment. The Qute guide still documents this pattern. (quarkus.io)

Create src/main/java/com/themainthread/iss/resource/IndexResource.java:

package com.themainthread.iss.resource;

import io.quarkus.qute.CheckedTemplate;
import io.quarkus.qute.TemplateInstance;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.core.MediaType;

@Path("/")
public class IndexResource {

    @CheckedTemplate
    public static class Templates {
        public static native TemplateInstance index();
    }

    @GET
    @Produces(MediaType.TEXT_HTML)
    public TemplateInstance index() {
        return Templates.index();
    }
}

Create src/main/resources/templates/IndexResource/index.html:

(I’ve omitted the styles here, go check out the Github repository!)

<!DOCTYPE html>
<html lang="en">

<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>ISS Tracker</title>
    <style>

    </style>
</head>

<body>

    <h1>ISS Real-Time Tracker</h1>
    <div id="status">Connecting to live feed...</div>

    <div id="map-container">
        <img id="world-map"
            src="https://upload.wikimedia.org/wikipedia/commons/thumb/8/80/World_map_-_low_resolution.svg/1280px-World_map_-_low_resolution.svg.png"
            alt="World map">
        <div id="iss-marker"></div>
    </div>

    <div id="coords">
        Lat: <span id="lat">-</span>

        Lon: <span id="lon">-</span>

        Updated: <span id="updated">-</span>
    </div>

    <footer>
        Data from <a href="https://open-notify.org/" target="_blank">Open Notify</a>
    </footer>

    <script>
        const MAP_WIDTH = 1280;
        const MAP_HEIGHT = 640;

        const marker = document.getElementById("iss-marker");
        const status = document.getElementById("status");
        const latEl = document.getElementById("lat");
        const lonEl = document.getElementById("lon");
        const updatedEl = document.getElementById("updated");

        function placeMarker(pixelX, pixelY) {
            const leftPercent = (pixelX / MAP_WIDTH) * 100;
            const topPercent = (pixelY / MAP_HEIGHT) * 100;
            marker.style.left = leftPercent + "%";
            marker.style.top = topPercent + "%";
        }

        function renderFix(fix) {
            placeMarker(fix.pixelX, fix.pixelY);
            latEl.textContent = fix.latitude.toFixed(4) + "°";
            lonEl.textContent = fix.longitude.toFixed(4) + "°";
            updatedEl.textContent = new Date(fix.updatedAt).toLocaleTimeString();
        }

        fetch("/api/iss/position")
            .then(response => response.status === 204 ? null : response.json())
            .then(fix => {
                if (fix) {
                    renderFix(fix);
                }
            });

        const source = new EventSource("/api/iss/stream");

        source.onopen = () => {
            status.textContent = "Live - updates every 10 seconds";
            status.style.color = "#3fd6a5";
        };

        source.onmessage = (event) => {
            const fix = JSON.parse(event.data);
            renderFix(fix);
        };

        source.onerror = () => {
            status.textContent = "Connection lost - reconnecting...";
            status.style.color = "#ffb366";
        };
    </script>

</body>

</html>

This frontend stays small because the server already did the hard work. The browser only places a marker and updates a few text fields. That is the right split for a live app like this.

It also handles reconnects cleanly because EventSource reconnects automatically. That does not make SSE free. A large number of open clients still means a large number of open HTTP connections. For a small tracker that is fine. For public-scale fan-out, you would think harder about limits, proxies, and backpressure.

Add a readiness check

Health endpoints are only useful if they reflect real readiness. For this service, “ready” means we have fetched at least one good ISS position.

Create src/main/java/com/themainthread/iss/health/IssDataReadinessCheck.java:

package com.themainthread.iss.health;

import org.eclipse.microprofile.health.HealthCheck;
import org.eclipse.microprofile.health.HealthCheckResponse;
import org.eclipse.microprofile.health.Readiness;

import com.themainthread.iss.service.IssPositionCache;
import com.themainthread.iss.service.IssPositionCache.PositionFix;

import jakarta.enterprise.context.ApplicationScoped;
import jakarta.inject.Inject;

@Readiness
@ApplicationScoped
public class IssDataReadinessCheck implements HealthCheck {

    @Inject
    IssPositionCache cache;

    @Override
    public HealthCheckResponse call() {
        if (!cache.hasData()) {
            return HealthCheckResponse.named("iss-data")
                    .down()
                    .withData("reason", "No successful poll yet")
                    .build();
        }

        PositionFix fix = cache.latest();

        return HealthCheckResponse.named("iss-data")
                .up()
                .withData("latitude", String.valueOf(fix.latitude()))
                .withData("longitude", String.valueOf(fix.longitude()))
                .withData("updatedAt", fix.updatedAt().toString())
                .build();
    }
}

This check gives you an honest signal for deployment platforms. A process that has started but never fetched data is alive, but it is not ready. That distinction matters once you put this behind a load balancer.

Configuration

Configure the application in src/main/resources/application.properties:

quarkus.application.name=iss-tracker
quarkus.http.port=8080

quarkus.rest-client.iss-api.url=http://api.open-notify.org
quarkus.rest-client.iss-api.connect-timeout=3000
quarkus.rest-client.iss-api.read-timeout=5000

quarkus.log.level=INFO
quarkus.log.category."com.themainthread.iss".level=DEBUG

%dev.quarkus.scheduler.start-mode=forced
%dev.quarkus.log.category."com.themainthread.iss".level=DEBUG

quarkus.rest-client.iss-api.url points the typed REST client at the public ISS endpoint documented by Open Notify. (open-notify.org)

connect-timeout=3000 prevents a dead TCP connection attempt from hanging too long. When the upstream is down, three seconds is enough to fail fast and keep your scheduler thread moving.

read-timeout=5000 prevents the actual response read from blocking forever. This is the difference between a recoverable slow upstream and a scheduler job that quietly stalls.

%dev.quarkus.scheduler.start-mode=forced makes development behavior obvious when you are iterating locally. You do not want to wonder whether the scheduler started after a hot reload.

Production Hardening

What happens when the upstream API is slow

The upstream service is free and public. Treat it like a dependency you do not control. That means timeouts are mandatory, and overlapping polls are a bug, not a feature.

With the current setup, one slow call blocks only one scheduled execution. The next tick gets skipped because of Scheduled.ConcurrentExecution.SKIP. That is intentional. You keep the last good fix, you avoid overlapping network calls, and your service stays stable.

Without SKIP, slow upstream calls stack up. That is how small scheduled jobs turn into thread leaks under bad network conditions. The tracker does not need every possible update. It needs predictable behavior.

SSE fan-out is cheap until it is not

SSE is simpler than WebSockets for one-way live updates. That is why it fits this tutorial well. The browser API is tiny, the server code is small, and reconnection behavior is built in.

But every client still holds a long-lived HTTP connection. A few browsers are nothing. Thousands of browsers change the operational picture. Reverse proxy timeouts, max connections, and memory overhead start to matter. For a public internet app, you would put this behind a proxy configured for long-lived streams and think about per-IP connection limits.

Stale data is better than broken data

When a poll fails, we keep the last successful position in memory. This is the correct failure mode for a tracker. Users keep seeing the last known good fix, not a blank map or a server error.

This does not mean the data is fresh. It means the service is honest about its last successful state. If freshness matters more than availability, expose an age field and let the frontend show “stale” after a threshold. For this tutorial, readiness tells you whether data exists at all, and the timestamps tell you how current it is.

No auth does not mean no abuse surface

This service has no login and no database. That does not make it safe by default. The abuse surface is the number of open SSE connections and the number of HTTP requests you let through.

If you publish this beyond your laptop, add rate limiting. Also think about response caching on /api/iss/position, and consider authentication if the stream is not meant to be public. Real-time endpoints are attractive to scrapers because they are cheap to consume and easy to reconnect.

Verification

Run the application

Start dev mode:

quarkus dev

Open the app http://localhost:8080

[

](https://substackcdn.com/image/fetch/$s_!YdS3!,f_auto,q_auto:good,fl_progressive:steep/https%3A%2F%2Fsubstack-post-media.s3.amazonaws.com%2Fpublic%2Fimages%2F36651a16-d805-4702-b7d5-6c21d0f8374d_3024x1724.png)

You should see a world map, an ISS marker, and coordinates that update every 10 seconds. I have also added a small tracking feature to the Github repository. So make sure to check that out!

Verify the JSON endpoint

Call the snapshot endpoint:

curl -i http://localhost:8080/api/iss/position

Expected behavior after the first successful poll:

HTTP/1.1 200 OK
Content-Type: application/json

Expected payload shape:

{
  "latitude": 12.3456,
  "longitude": -78.9012,
  "pixelX": 360,
  "pixelY": 280,
  "timestamp": 1716835200,
  "updatedAt": "2026-03-14T10:15:30.123Z"
}

Before the first successful poll, you should get:

HTTP/1.1 204 No Content

That verifies the cache boundary is working correctly.

Verify the readiness endpoint

Call readiness:

curl http://localhost:8080/q/health/ready

Expected output after a successful poll:

{
    "status": "UP",
    "checks": [
        {
            "name": "iss-data",
            "status": "UP",
            "data": {
                "latitude": "-24.2744",
                "longitude": "-86.3863",
                "updatedAt": "2026-03-14T10:56:08.176814Z"
            }
        }
    ]
}

This proves the app is not just running. It has real upstream data.

Test the projection math

Create src/test/java/com/themainthread/iss/util/MercatorProjectionTest.java:

package com.themainthread.iss.util;

import static org.junit.jupiter.api.Assertions.assertTrue;

import org.junit.jupiter.api.Test;

class MercatorProjectionTest {

    @Test
    void nullIslandMapsNearCenter() {
        int[] pixels = MercatorProjection.toPixel(0.0, 0.0);

        assertTrue(Math.abs(pixels[0] - 640) <= 2);
        assertTrue(Math.abs(pixels[1] - 320) <= 2);
    }

    @Test
    void easternDatelineMapsNearRightEdge() {
        int[] pixels = MercatorProjection.toPixel(0.0, 179.9);
        assertTrue(pixels[0] > 1260);
    }

    @Test
    void westernDatelineMapsNearLeftEdge() {
        int[] pixels = MercatorProjection.toPixel(0.0, -179.9);
        assertTrue(pixels[0] < 20);
    }
}

This test proves the one piece of pure math in the service. If the projection is wrong, the frontend marker is wrong even when every other part works.

Test the REST resource

Create src/test/java/com/themainthread/iss/resource/IssResourceTest.java:

package com.themainthread.iss.resource;

import static io.restassured.RestAssured.given;
import static org.hamcrest.Matchers.is;
import static org.mockito.Mockito.when;

import java.time.Instant;

import org.junit.jupiter.api.Test;

import com.themainthread.iss.service.IssPositionCache;
import com.themainthread.iss.service.IssPositionCache.PositionFix;

import io.quarkus.test.InjectMock;
import io.quarkus.test.junit.QuarkusTest;

@QuarkusTest
class IssResourceTest {

    @InjectMock
    IssPositionCache cache;

    @Test
    void returnsCurrentFix() {
        PositionFix fix = new PositionFix(
                51.5074,
                -0.1278,
                640,
                250,
                1716835200L,
                Instant.parse("2026-03-14T10:15:30Z"));

        when(cache.latest()).thenReturn(fix);

        given()
                .when().get("/api/iss/position")
                .then()
                .statusCode(200)
                .body("latitude", is(51.5074f))
                .body("longitude", is(-0.1278f))
                .body("pixelX", is(640))
                .body("pixelY", is(250));
    }

    @Test
    void returns204WhenNoFixExists() {
        when(cache.latest()).thenReturn(null);

        given()
                .when().get("/api/iss/position")
                .then()
                .statusCode(204);
    }
}

This test proves the HTTP contract. It does not care about the scheduler or the external API. That is good. Resource tests should stay focused.

Test the scheduler

Create src/test/java/com/themainthread/iss/service/IssPollerTest.java:

package com.themainthread.iss.service;

import static org.junit.jupiter.api.Assertions.assertDoesNotThrow;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertTrue;
import static org.mockito.Mockito.when;

import org.eclipse.microprofile.rest.client.inject.RestClient;
import org.junit.jupiter.api.Test;

import com.themainthread.iss.client.IssApiClient;
import com.themainthread.iss.client.IssNowResponse;
import com.themainthread.iss.client.IssPosition;

import io.quarkus.test.InjectMock;
import io.quarkus.test.junit.QuarkusTest;
import jakarta.inject.Inject;

@QuarkusTest
class IssPollerTest {

    @InjectMock
    @RestClient
    IssApiClient apiClient;

    @Inject
    IssPoller poller;

    @Inject
    IssPositionCache cache;

    @Test
    void pollPopulatesCacheOnSuccess() {
        IssNowResponse response = new IssNowResponse(
                "success",
                1716835200L,
                new IssPosition("51.5074", "-0.1278"));

        when(apiClient.fetchPosition()).thenReturn(response);

        poller.poll();

        assertTrue(cache.hasData());

        var fix = cache.latest();
        assertEquals(51.5074, fix.latitude());
        assertEquals(-0.1278, fix.longitude());
    }

    @Test
    void pollSwallowsNetworkErrors() {
        when(apiClient.fetchPosition()).thenThrow(new RuntimeException("timeout"));

        assertDoesNotThrow(() -> poller.poll());
    }
}

This test proves the behavior that matters most in production: one bad network call does not crash the polling loop.

Conclusion

We built a Quarkus service that treats real-time tracking as a backend responsibility, not a browser trick. The REST client isolates the upstream dependency, the scheduler controls polling, the application-scoped cache holds the last good state, the SSE endpoint fans out updates efficiently, and the Qute frontend stays simple because the server already did the hard work. More importantly, the service fails in the right way: it skips overlapping polls, keeps stale-but-valid data when the upstream breaks, and reports readiness only after it has something real to serve.

This is a small app, but the architecture is the same one you use when a toy demo has to survive the real world.

Subscribe now

DEV Community: Markus

AI Coding Governance for Real Software Teams

Prompting is not the hard part

Big tasks still fail for familiar reasons

The useful tooling exposes systems, not just text

The bill comes back during review

Java is in a stronger position than the hype suggests

What I would actually tell a team

Quarkus AWS Lambda HTTP: Live-Code Serverless on Localhost

What we build

What you need

Create the project

Add the quote model

Add the pricing service

Add the Lambda-aware REST resource

Run it in dev mode

Prove the live-coding part

Push a raw API Gateway V2 event into /_lambda_

Test the same flow in Quarkus

Package it for Lambda

Run the packaged Lambda with SAM CLI

A few honest boundaries

Close the loop

Quarkus JFR: Find Performance Bugs Before Users Do

What we build

What you need

Create the project

Build the sample

Add typed config

Keep the response types boring

Add the blocking and fixed paths

Add the allocation-heavy path

Add one ugly startup path

Expose the endpoints

Configure the sample

Prove it with tests

Record the app in dev mode

Read the recording without guessing

Fix one issue and compare before and after

Run the same workflow in a Podman container

Close the loop

Model Routing in Quarkus LangChain4j with Ollama

What you will be able to do

What we build

What you need

Project setup

Configure two Ollama models

The complexity enum

The classifier AiService

Routing decision record

The routing event observer

The model router

Shell and injections

Classification and timing

Dispatch and event

REST endpoint

Prove it (live Ollama)

Production risks

Tests

Extension exercises

Close the loop

What Should Go in an AGENTS.md File?

The four rules that pull the most weight

What the file is really doing

What to put in a generalized AGENTS.md

Defaults

Behavior

Memory

Escalation

A template I would actually use

This is really about interface design

The real win

Quarkus Graceful Shutdown That Holds Up During Rolling Deploys

What we build

What you need

Project setup

Order status and payment handoff

DTO records

OrderService

OrderResource

Push a raw API Gateway V2 event into `/_lambda_`

What to put in a generalized `AGENTS.md`

Add `quarkus.shutdown.timeout`

Scaffold `helios-analytics`

Scaffold `helios-api`

Option A — edit `application.properties`