Coder Legion - Recent posts tagged quarkus

quarkus-chat-ui (2): The Actor Design Behind LLM-to-LLM Conversation

Sun, 05 Apr 2026 10:01:50 +0000

Originally published on ScivicsLab Blog

In a previous post I introduced POJO-actor — a lightweight actor-model library for Java that needs no framework, no annotation processor, and no external runtime. Just plain Java 21.

This post is about how I actually use it in quarkus-chat-ui, a Quarkus-based LLM chat UI that connects to Claude Code CLI, vLLM, and other backends. The application manages stateful LLM sessions, streams responses via SSE, handles concurrent MCP requests, and supports a /btw command for side questions — all without a single synchronized block.

The three actors that make this work are ChatActor, BtwActor, and QueueActor. This post focuses on the first two and the design principle behind them.

Quick POJO-actor recap

A POJO-actor actor wraps any plain Java object. Messages are lambdas dispatched through a LinkedBlockingQueue. The actor runs its message loop on a single virtual thread, processing one message at a time.

ActorSystem system = new ActorSystem("chat-ui");
ActorRef<Counter> counter = system.actorOf("counter", new Counter());

// tell() — enqueue, return immediately
counter.tell(c -> c.increment());

// ask() — enqueue, return CompletableFuture with result
int value = counter.ask(c -> c.getValue()).join(); // = 1

// tellNow() — bypass queue, execute on a NEW virtual thread immediately
counter.tellNow(c -> c.emergencyStop());

The key properties:

tell() and ask(): FIFO, safe by default — only one message runs at a time on the actor's virtual thread.
tellNow() and askNow(): bypass the queue, run concurrently on a fresh virtual thread. The caller takes responsibility for thread safety.

This is the whole API. The class itself is a plain Java object — no annotations, no base class to extend, no interface to implement. Any POJO becomes an actor simply by passing it to ActorSystem.actorOf(). The object does not know it is running inside an actor.

The problem: blocking I/O kills the message loop

An LLM API call can take 30–60 seconds. If ChatActor calls the LLM directly inside a message handler, the actor's message loop is blocked for the entire duration:

tell(startPrompt) → message.run() → provider.sendPrompt() ← blocks for 30s
                                                               |
tell(cancel)  ← enqueued, but not processed until sendPrompt() returns

The cancel button press arrives as a tell(cancel), but the actor won't see it until the blocking call returns. That's useless.

The fix: delegate the blocking I/O to a separate virtual thread and return immediately.

ChatActor: the state guardian

ChatActor holds all session state — API key, model, history, busy flag. It protects that state by being the single thread that reads and writes it.

public class ChatActor {

    private final LlmProvider provider;
    private volatile Thread activeThread;  // written by actor thread, read by cancel()

    private boolean busy;
    private String apiKey;
    private String sessionId;
    // ... other session state

    public void startPrompt(String text, String model, Consumer<ChatEvent> emitter,
                            ActorRef<ChatActor> self, Runnable done) {
        busy = true;
        emitter.accept(ChatEvent.status(sessionId, true));

        // Delegate the blocking I/O to a virtual thread and return immediately.
        // The actor's message loop is now free to process the next message.
        activeThread = Thread.startVirtualThread(() -> {
            try {
                ProviderContext ctx = new ProviderContext(apiKey, history, false, () -> {});
                provider.sendPrompt(text, model, emitter, ctx);
            } catch (Exception e) {
                emitter.accept(ChatEvent.error(e.getMessage()));
            } finally {
                // Report completion back through the actor's queue (thread-safe)
                self.tell(a -> a.onPromptComplete(emitter));
            }
        });
        // ← returns here immediately. The actor is ready for the next message.
    }

    public void cancel() {
        provider.cancel();
        Thread t = activeThread;       // read volatile field
        if (t != null) t.interrupt(); // interrupt the I/O virtual thread
    }

    private void onPromptComplete(Consumer<ChatEvent> emitter) {
        busy = false;
        activeThread = null;
        emitter.accept(ChatEvent.status(sessionId, false));
    }
}

The message flow after startPrompt() is called:

tell(startPrompt) → starts I/O thread → returns immediately
                    actor loop is now idle, waiting for next message

tell(cancel)      → no queue wait → cancel() runs → I/O thread interrupted
                    I/O thread catches exception → finally → self.tell(onPromptComplete)

This is the core pattern. The actor is the state guardian; the virtual thread is the I/O worker. The actor never blocks. Every cancel, every MCP request, every queue tick finds the actor ready to respond.

Why `volatile Thread activeThread`?

activeThread is written by the actor's virtual thread (in startPrompt) and read by cancel(). Normally both are on the same actor thread, so volatile is redundant — but cancel() is also called via tellNow(), which runs on a different virtual thread. volatile ensures the write to activeThread is visible across that thread boundary. It's a defensive declaration that costs nothing and prevents a subtle bug.

Why `tellNow()` for cancel?

The REST endpoint that handles the cancel button:

@POST
@Path("/cancel")
public ChatEvent cancel() {
    actorSystem.getChatActor().tellNow(ChatActor::cancel);
    return ChatEvent.info("Cancelled");
}

Why tellNow() and not tell()?

With tell(), cancel() would be enqueued behind whatever is currently in the queue. But startPrompt() delegates its I/O immediately and returns — so in practice, the actor's queue is already empty and tell(cancel) would be processed right away. The behavior is correct either way.

The reason to use tellNow() is semantic clarity: "cancel NOW" — not "cancel when it's your turn". It also makes the intent obvious to readers of the code. cancel() touches only volatile activeThread and provider.cancel(), both of which are designed for concurrent access, so bypassing the queue is safe here.

BtwActor: a second independent actor

Claude Code CLI has a /btw command: while the LLM is processing a long task, you can type /btw what does this mean? and get an immediate answer from a parallel LLM call, without interrupting the main task.

quarkus-chat-ui implements the same UX. The Web UI detects the /btw prefix and sends the question to POST /api/btw. The response appears in a floating overlay in the bottom-right corner; the main chat continues uninterrupted.

The key insight: this is just a second independent actor that follows the same pattern as ChatActor.

public class BtwActor {

    private final LlmProvider provider;
    private volatile Thread activeThread;

    public void startBtw(String question, String model, String apiKey,
                         Consumer<ChatEvent> emitter, ActorRef<BtwActor> self) {
        activeThread = Thread.startVirtualThread(() -> {
            try {
                ProviderContext ctx = new ProviderContext(apiKey, List.of(), false, () -> {});
                provider.sendPrompt(question, model, event -> {
                    // Map provider events to btw-specific SSE event types
                    if ("delta".equals(event.type()))  emitter.accept(ChatEvent.btwDelta(event.content()));
                    if ("result".equals(event.type())) emitter.accept(ChatEvent.btwResult());
                }, ctx);
            } catch (Exception e) {
                emitter.accept(ChatEvent.error("BTW error: " + e.getMessage()));
            } finally {
                self.tell(a -> a.activeThread = null);
            }
        });
    }

    public void cancel() {
        Thread t = activeThread;
        if (t != null) { provider.cancel(); t.interrupt(); }
    }

    public boolean isBusy() { return activeThread != null; }
}

BtwActor is registered alongside ChatActor in LlmConsoleActorSystem:

chatActorRef = actorSystem.actorOf("chat", new ChatActor(provider, configApiKey));
btwActorRef  = actorSystem.actorOf("btw",  new BtwActor(provider));

The REST endpoint is three lines:

@POST
@Path("/btw")
public ChatEvent btw(BtwRequest request) {
    String apiKey = actorSystem.getChatActor().ask(ChatActor::getApiKey).join();
    String model  = request.model != null ? request.model : provider.getCurrentModel();
    var btwRef    = actorSystem.getBtwActor();
    btwRef.tell(a -> a.startBtw(request.question, model, apiKey, this::emitSse, btwRef));
    return ChatEvent.info("BTW processing");
}

The frontend receives btw_delta and btw_result SSE events (distinct from the main chat's delta/result), streams the response into the overlay, and closes it on ESC or the × button.

Thread safety with a shared provider

ChatActor and BtwActor share the same LlmProvider instance. For HTTP-based providers (Anthropic API, vLLM), each sendPrompt() call is an independent HTTP request — parallel calls are safe by construction.

BtwActor intentionally does not call provider.setModel() before sendPrompt(). Calling setModel() would mutate shared provider state, potentially corrupting ChatActor's current model mid-stream. Instead, the model is passed directly as a parameter to sendPrompt(). The actors are isolated at the state level even though they share the provider.

The actor system structure

ActorSystem "chat-ui"
  ├── ChatActor    — session state, model selection, history
  ├── BtwActor     — /btw side questions (independent)
  ├── QueueActor   — message queuing for MCP/concurrent requests
  └── WatchdogActor — stall detection (CLI providers only)

All four follow the same pattern: the actor is the state guardian, virtual threads handle I/O. tell() for normal messages, tellNow() for urgent bypasses that are provably safe.

What I like about this approach

No framework tax. Each actor is a POJO. The actor model adds one concept (tell vs tellNow) on top of plain Java. Reading ChatActor requires no knowledge of Akka, Quarkus, or any actor framework — just Java.

The virtual thread + actor split is explicit. The code visually shows the boundary: Thread.startVirtualThread(...) inside startPrompt() is the handoff from "actor's domain" to "I/O worker's domain". When something goes wrong, it's immediately clear which side owns the problem.

Adding actors is cheap. BtwActor is 30 lines. Adding /btw cancel in the future is one tellNow() call. The pattern scales to new actors (WatchdogActor, QueueActor) without changing the existing ones.

State bugs are localized. ChatActor is the only place that can modify session state. If the session ID is wrong, the bug is in ChatActor. There is no "it could be any thread" scenario.

quarkus-chat-ui: A Web Front-End for LLMs, and a Real-World Case for POJO-actor

Sun, 05 Apr 2026 08:04:37 +0000

Note: This article was originally published on
SciVicsLab.

quarkus-chat-ui: A Web Front-End for LLMs, and a Real-World Case for POJO-actor

quarkus-chat-ui is a web UI for LLMs where multiple instances can talk to each other — built as a real-world use case for POJO-actor.

Each quarkus-chat-ui instance exposes an HTTP MCP server at /mcp, so Instance A can call tools on Instance B, and Instance B can reply by calling tools back on A. The LLM backend — Claude Code CLI, Codex, or a local model via claw-code-local — acts as an MCP client that can reach these endpoints. The question was how to wire that up over HTTP, and how to handle the fact that LLM responses take tens of seconds and arrive as a stream.

quarkus-chat-ui is the bridge that makes this work. Each instance wraps one LLM backend and exposes it as an HTTP MCP server at /mcp. For multi-agent communication, use a backend with MCP client capability: Claude Code CLI, Codex, or claw-code-local (which brings MCP support to Ollama, vLLM, and other local models). The openai-compat provider works for single-agent use but cannot call other MCP servers. Agents call each other by name. Humans can watch both sides of the conversation in their browsers.

Once the async communication layer was in place, a capable web UI and a prompt queue came along naturally. The browser gives you a stable place to type — your input won't vanish when the AI responds, and paste and multi-line just work. If you need an LLM front-end and happen to be a Java developer, those turn out to be useful in their own right.

This post is about quarkus-chat-ui as a tool you can use. Companion posts cover:

The internal design — how POJO-actor keeps the concurrency clean → quarkus-chat-ui (2): The Actor Design Behind LLM-to-LLM Communication
Scaling beyond two agents — why quarkus-mcp-gateway becomes necessary → quarkus-chat-ui (3): Scaling Multi-Agent Communication with MCP Gateway

What it does

1. LLM instances talking to each other via MCP

Each quarkus-chat-ui instance exposes an HTTP MCP server at /mcp. The tools are submitPrompt, getPromptStatus, getPromptResult, cancelRequest, and a few others.

submitPrompt accepts a _caller parameter. When Instance B receives a prompt with _caller pointing back to A, it enriches the prompt with position awareness and reply instructions before forwarding it to its LLM:

[Context]
You are running on: http://localhost:28020
Received via MCP from: localhost:28010

[Message]
What should we work on today?

[How to Reply]
Use callMcpServer tool:
- serverUrl: http://localhost:28010
- toolName: submitPrompt
- arguments: {"prompt": "your reply", "_caller": "http://localhost:28020"}

The LLM reads this, formulates a reply, and calls submitPrompt on Instance A. The conversation continues autonomously.

Browser A (port 28010)             Browser B (port 28020)
──────────────────────             ──────────────────────
[MCP from localhost:28020]         [MCP from localhost:28010]
What should we work on today? ←→   Let's start with the API layer.
                                   [MCP from localhost:28010]
[MCP from localhost:28020]         ...
Good idea. Let's define...

You can also put a quarkus-mcp-gateway in front of many instances, routing by name instead of port. Service discovery scans a port range and registers all running agents automatically.

2. Written in Quarkus — streaming made simple

LLM tooling tends to be Python. If you want to customise how prompts are enriched, add a new backend, or change the queue policy, quarkus-chat-ui is a straightforward Quarkus Maven project.

Adding a new LLM backend means implementing one interface:

public interface LlmProvider {
    String id();
    void sendPrompt(String prompt, String model,
                    Consumer<ChatEvent> emitter, ProviderContext ctx);
    void cancel();
    // ...
}

SSE streaming, queue management, MCP server, and conversation history are already there.

Quarkus made the streaming part almost trivial. Exposing an SSE endpoint is a matter of returning Multi<T> from a JAX-RS method:

@GET @Path("/events/{sessionId}")
@Produces(MediaType.SERVER_SENT_EVENTS)
@RestStreamElementType(MediaType.APPLICATION_JSON)
public Multi<ChatEvent> events(@PathParam("sessionId") String sessionId) {
    return chatService.getEventStream(sessionId);
}

That is all. The framework handles chunked encoding, keep-alive, and client reconnection. Backpressure flows naturally through Mutiny's reactive streams. There is no manual buffer management, no explicit flush calls, no thread-pool tuning. You return a Multi, Quarkus streams it.

3. A prompt queue that does the obvious thing

When the LLM is busy and you want to queue your next question, you can. When the current response finishes, the queued prompt runs automatically.

[LLM is processing "Explain this code"]

You type: "Now write the tests"    →  added to queue
You type: "And the documentation"  →  added to queue

[Response arrives]
→ "Now write the tests" runs automatically
[Response arrives]
→ "And the documentation" runs automatically

The queue is visible in the UI, persistent across page reloads, and editable — reorder or delete items before they run.

Cancel works correctly in the multi-agent case too. Pressing Cancel stops the current generation and removes MCP-sourced messages from the backend queue. Messages you typed yourself stay in the queue and run after the cancel.

Why the concurrency is manageable

Multi-agent HTTP conversation sounds like a concurrency nightmare: SSE streams arriving from multiple agents, a queue draining as responses land, cancel signals that need to reach the right places. In practice it is not, because the design is explicit about who owns what state.

Each concern — chat session, side questions, queue management, stall detection — runs in its own actor backed by POJO-actor. Blocking I/O runs on virtual threads that report back to the actor when done. The actors communicate through tell() and ask() calls. There are no synchronized blocks in the application code.

The companion post goes into detail: quarkus-chat-ui (2): The Actor Design Behind LLM-to-LLM Communication.

Quick start

Three providers are supported:

`chat-ui.provider`	What it wraps	Requires
`claude`	Claude Code CLI	`ANTHROPIC_API_KEY`
`codex`	OpenAI Codex CLI	`OPENAI_API_KEY`
`openai-compat`	Any OpenAI-compatible HTTP server (vLLM, Ollama, …)	running local server

Preparing a local LLM (openai-compat)

If you want to run a local model instead of a cloud API, Ollama is the easiest way to get started:

# Install Ollama, then pull a model
ollama pull qwen2.5-coder:7b

# Ollama listens on http://localhost:11434 by default
# Use -Dchat-ui.servers=http://localhost:11434/v1 when starting quarkus-chat-ui

For GPU-accelerated inference, vLLM serves any HuggingFace-compatible model on the same OpenAI-compatible API:

vllm serve Qwen/Qwen2.5-Coder-7B-Instruct --port 8000
# Use -Dchat-ui.servers=http://localhost:8000

Option 1: Native executable (no JDK required)

Java traditionally requires a JVM to run. You install a JDK, compile your code to bytecode, and the JVM interprets or JIT-compiles it at runtime. This is why "installing Java" has always been a prerequisite for running Java applications.

GraalVM native image changes this. It compiles Java bytecode ahead-of-time into a native executable for your OS and CPU architecture. The result is a standalone binary — just like a C or Go program. No JVM, no JDK, no JAVA_HOME. Download, run, done.

This is where Quarkus shines again. Traditional Java frameworks rely heavily on runtime reflection, making native image compilation painful — you end up maintaining long lists of reflection configuration by hand. Quarkus was designed from the start with native compilation in mind. It moves reflection and configuration processing to build time, and its extensions generate the necessary GraalVM hints automatically. You just run mvn package -Dnative and it works.

Pre-built native executables are available on the Releases page.

Platform	Binary
Linux x86_64	`quarkus-chat-ui-linux-amd64`
Linux ARM64	`quarkus-chat-ui-linux-arm64`
macOS Intel	`quarkus-chat-ui-macos-amd64`
macOS Apple Silicon (M1/M2/M3)	`quarkus-chat-ui-macos-arm64`
Windows x64	`quarkus-chat-ui-windows-amd64.exe`

# Linux x86_64
./quarkus-chat-ui-linux-amd64 -Dchat-ui.provider=claude -Dquarkus.http.port=28010

# Linux ARM64
./quarkus-chat-ui-linux-arm64 -Dchat-ui.provider=claude -Dquarkus.http.port=28010

# macOS Intel
./quarkus-chat-ui-macos-amd64 -Dchat-ui.provider=claude -Dquarkus.http.port=28010

# macOS Apple Silicon (M1/M2/M3)
./quarkus-chat-ui-macos-arm64 -Dchat-ui.provider=claude -Dquarkus.http.port=28010

# Windows PowerShell
.\quarkus-chat-ui-windows-amd64.exe -Dchat-ui.provider=claude -Dquarkus.http.port=28010

Option 2: Build from source

Prerequisites: JDK 21+ and Maven 3.x

git clone https://github.com/scivicslab/quarkus-chat-ui
cd quarkus-chat-ui
mvn install -DskipTests

Run with Claude Code CLI:

java -Dchat-ui.provider=claude \
     -Dquarkus.http.port=28010 \
     -jar app/target/quarkus-app/quarkus-run.jar

Run with vLLM or Ollama (OpenAI-compatible API):

java -Dchat-ui.provider=openai-compat \
     -Dchat-ui.openai-compat.base-url=http://localhost:11434/v1 \
     -Dquarkus.http.port=28010 \
     -jar app/target/quarkus-app/quarkus-run.jar

Open http://localhost:28010 in a browser.

For all providers (claude, codex, openai-compat) and configuration options, see the README.

Setting up two agents to talk (Claude Code CLI)

Two quarkus-chat-ui instances talking to each other via MCP.

Overview:

You will set up two instances (Alice and Bob) that can send messages to each other via MCP:

Alice runs on port 28010
Bob runs on port 28020
Each instance has its own browser window
Claude Code CLI acts as the MCP client for both instances

Prerequisites:

quarkus-chat-ui repository cloned and built (see "Option 2: Build from source" above)
Working directory: quarkus-chat-ui/ (repository root)
3 terminal windows (or tabs)
2 browser windows (or tabs)

1. Install Claude Code CLI

Where: Any directory

npm install -g @anthropic-ai/claude-code

Verify:

claude --version

2. Set API Key

Where: Any terminal (environment variable applies to all subsequent commands in that terminal)

export ANTHROPIC_API_KEY=sk-ant-api03-...

3. Start Alice (port 28010)

Terminal 1, working directory: quarkus-chat-ui/ (repository root)

java -Dchat-ui.provider=claude \
     -Dquarkus.http.port=28010 \
     -jar app/target/quarkus-app/quarkus-run.jar

Open http://localhost:28010 in your browser

4. Start Bob (port 28020)

Terminal 2, working directory: quarkus-chat-ui/ (repository root)

First, set the API key in this terminal too:

export ANTHROPIC_API_KEY=sk-ant-api03-...

Then start Bob:

java -Dchat-ui.provider=claude \
     -Dquarkus.http.port=28020 \
     -jar app/target/quarkus-app/quarkus-run.jar

Open http://localhost:28020 in another browser tab

5. Register MCP Endpoints

Terminal 3, working directory: Any directory (MCP registrations are stored in ~/.claude/)

# So Alice can call Bob
claude mcp add bob --transport http http://localhost:28020/mcp

# So Bob can call Alice
claude mcp add alice --transport http http://localhost:28010/mcp

Verify the registrations:

claude mcp list

Expected output:

alice: http (http://localhost:28010/mcp)
bob: http (http://localhost:28020/mcp)

6. Restart Both Instances

Claude Code CLI reads MCP registrations at startup. Stop and restart both.

Terminal 1 (Ctrl+C to stop, then restart Alice):

java -Dchat-ui.provider=claude \
     -Dquarkus.http.port=28010 \
     -jar app/target/quarkus-app/quarkus-run.jar

Terminal 2 (Ctrl+C to stop, then restart Bob):

java -Dchat-ui.provider=claude \
     -Dquarkus.http.port=28020 \
     -jar app/target/quarkus-app/quarkus-run.jar

7. Test: Alice Sends to Bob

Where: Alice's browser (http://localhost:28010)

In the prompt input field, type:

Use mcp__bob__submitPrompt to send "Hello Bob!" to Bob.
Set _caller to http://localhost:28010

Then click Send. Claude will use the MCP tool to send the message to Bob.

8. Verify: Bob Receives

Where: Bob's browser (http://localhost:28020)

You should see the message appear in Bob's chat area:

[MCP from localhost:28010] Hello Bob!

Testing the reply: In Bob's browser, type:

Use mcp__alice__submitPrompt to reply "Hi Alice!" to Alice.
Set _caller to http://localhost:28020

Then check Alice's browser — the reply should appear there.

Cleanup

Where: Any terminal

When you're done testing, remove the MCP registrations:

claude mcp remove alice
claude mcp remove bob

Verify they're removed:

claude mcp list

Troubleshooting

Problem	Solution
`mcp__bob__submitPrompt` not found	Run `claude mcp add bob --transport http http://localhost:28020/mcp` and restart Alice (Terminal 1)
Connection refused	Check that the target instance is running on the expected port (use `lsof -i :28010` or `lsof -i :28020`)
Bob can't reply to Alice	Run `claude mcp add alice --transport http http://localhost:28010/mcp` and restart Bob (Terminal 2)
`ANTHROPIC_API_KEY` not found	Set the environment variable in each terminal: `export ANTHROPIC_API_KEY=sk-ant-api03-...`
`app/target/quarkus-app/quarkus-run.jar` not found	Run `mvn install -DskipTests` from the `quarkus-chat-ui/` repository root

Beyond two agents

For three or more agents, use quarkus-mcp-gateway. See quarkus-chat-ui (3): Scaling Multi-Agent Communication with MCP Gateway.

Quarkus: Revolutionizing Java Development for the Cloud-Native Era

Fri, 26 Sep 2025 19:10:18 +0000

In the rapidly evolving landscape of cloud-native development, Java has faced criticism for being slow to start and memory-hungry compared to newer technologies. Enter Quarkus, a framework that promises to make Java “supersonic and subatomic” while maintaining the rich ecosystem and developer experience Java developers love.

If you’re coming from Spring Boot or other traditional Java frameworks, this comprehensive guide will help you understand what Quarkus brings to the table and whether it’s the right choice for your next project.

Sample project link with a readme: https://github.com/rajkundalia/url-shortener-quarkus

1. Introduction to Quarkus

Quarkus is a Kubernetes-native Java stack tailored for OpenJDK HotSpot and GraalVM, crafted from the best-of-breed Java libraries and adhering to Jakarta EE and MicroProfile standards. Developed by Red Hat, it’s designed to make Java a leading platform in Kubernetes and serverless environments by dramatically reducing startup times and memory consumption.

The “Supersonic Subatomic Java” tagline isn’t just marketing — it reflects Quarkus’s core promise:

Supersonic: Lightning-fast startup times (under 100ms for many applications)
Subatomic: Minimal memory footprint (as low as 12MB for simple applications)

Key Benefits

Performance: Applications start in milliseconds rather than seconds, with memory usage reduced significantly compared to traditional frameworks. This translates to significant cost savings in cloud environments.
Developer Productivity: Live coding capabilities, dev UI, and tooling make development faster and more enjoyable.
Cloud-Native First: Built with containers, Kubernetes, and serverless in mind. Quarkus generates Kubernetes manifests, Docker files, and provides native compilation support out of the box.

Target Use Cases

Quarkus excels in:

Microservices architectures
Serverless applications that need instant startup
Cloud-native applications requiring efficiency
High-throughput, low-latency systems leveraging reactive programming

What sets Quarkus apart is its compile-time optimization approach. Unlike traditional frameworks (e.g., Spring Boot) that rely on runtime classpath scanning and reflection, Quarkus shifts this work to build time, eliminating overhead at runtime.

2. Core Architecture & Development Experience

Dependency Injection

Quarkus uses CDI (Contexts and Dependency Injection) 2.0, specifically the ArC implementation. All DI metadata is processed at build time:

@ApplicationScoped
public class GreetingService {
    public String greeting(String name) {
        return "Hello " + name;
    }
}

@Path("/hello")
public class GreetingResource {
    @Inject
    GreetingService service;

    @GET
    @Produces(MediaType.TEXT_PLAIN)
    public String hello() {
        return service.greeting("World");
    }
}

Extension Ecosystem

Extensions augment application bytecode at build time, moving runtime operations to compile time. Popular extensions include:

quarkus-resteasy-reactive — REST endpoints
quarkus-hibernate-orm-panache — database operations
quarkus-smallrye-openapi — API documentation
quarkus-micrometer — metrics

Configuration Management

Configuration with application.properties is simple:

# Database configuration
quarkus.datasource.db-kind=postgresql
quarkus.datasource.jdbc.url=jdbc:postgresql://localhost/mydatabase

# Profiles
%dev.quarkus.log.level=DEBUG
%test.quarkus.datasource.jdbc.url=jdbc:h2:mem:test
%prod.quarkus.log.level=WARN

Hot Reloading & Live Coding

Run mvn quarkus:dev for instant updates:

Code recompiles automatically
Config updates apply instantly
Continuous testing runs automatically

DevUI

At http://localhost:8080/q/dev/, you’ll find:

Extension management
Database console
OpenAPI browser
Config editor
Health checks & metrics

Testing

Testing is seamless with @QuarkusTest:

@QuarkusTest
public class GreetingResourceTest {
    @Test
    public void testHelloEndpoint() {
        given()
            .when().get("/hello")
            .then()
            .statusCode(200)
            .body(is("Hello World"));
    }
}

3. Performance & Technology Stack

JVM vs Native Mode

JVM Mode: Faster than Spring Boot (0.8–1.5s startup, 50–100MB memory), build time \~45s
Native Mode: GraalVM compilation gives <100ms startup, \~12–20MB memory, tiny container images, build time \~2–5 minutes [Not tried, obtained from Internet]</li>

Trade-off: Native builds take longer (2–5 minutes).

Performance Comparison

Aspect	Quarkus (JVM)	Spring Boot
Startup Time	0.8–1.5s	2.5–4s
Memory Usage	50–100MB	250–500MB
Build Time	\~45s	\~30s

Note: Please note, these are approximate numbers.

Technology Stack

Eclipse Vert.x → Reactive, event-driven foundation
Eclipse MicroProfile → Enterprise features (config, health, metrics, security, tracing)
GraalVM Integration → AOT compilation, dead code elimination, pre-initialized structures

4. Cloud-Native & Production Features

Container-First

Quarkus auto-generates optimized Dockerfiles:

FROM registry.access.redhat.com/ubi8/openjdk-11:1.3
COPY target/quarkus-app/ /deployments/

Native images shrink containers to under 100MB.

Kubernetes Integration

Auto-generated manifests
ConfigMaps & Secrets support
Health/readiness probes
Operator integration

Observability

Health endpoints
Metrics via Micrometer/Prometheus
Tracing with Jaeger/OpenTracing
Structured logging

Security

OIDC, OAuth2, JWT
RBAC via annotations
Keycloak integration

5. Framework Comparisons

Aspect	Quarkus	Spring Boot
Startup Time	0.8–1.5s (JVM), <0.1s (Native) </td>	2.5–4s
Memory Usage	50–100MB (JVM), 10–30MB (Native)	250–500MB
Architecture	Build-time optimized	Runtime reflection/scanning
Ecosystem	Growing, EE/MicroProfile aligned	Mature, massive
Native Compilation	Core feature	Experimental (Spring Native)
Reactive	Built-in (Vert.x)	Optional

Please note, numbers can vary.

Choose Quarkus when you need performance, microservices, serverless, or reactive programming.

Quarkus vs Micronaut

Quarkus: Build-time optimization, enterprise-ready (MicroProfile), Red Hat backing
Micronaut: Compile-time DI, small footprint, broader language support (Kotlin, Groovy)

Essential Extensions

quarkus-resteasy-reactive-jackson — REST + JSON
quarkus-hibernate-orm-panache — ORM
quarkus-jdbc-postgresql — Database
quarkus-smallrye-health — Health checks
quarkus-micrometer-registry-prometheus — Metrics
quarkus-container-image-docker — Container builds

Learning Resources

Official Guides
GitHub
Community: Zulip, Stack Overflow, GitHub Discussions
Red Hat training for enterprises
https://code.quarkus.io/?e=rest
https://www.logicmonitor.com/blog/quarkus-vs-spring — a good read
https://medium.com/sysco-labs/quarkus-a-supersonic-subatomic-java-e7c3ba510d79
https://maddevs.io/blog/spring-boot-vs-quarkus/

Conclusion

Quarkus represents a significant evolution in Java development — addressing performance bottlenecks while preserving Java’s strengths.

With sub-second startups, tiny memory usage, and enterprise-ready features, it’s tailor-made for microservices, serverless, and cloud-native apps. Backed by Red Hat and a growing community, Quarkus is positioned for long-term success.

Whether starting fresh or migrating from Spring Boot, Quarkus deserves serious consideration for your next Java application.

Quarkus Neo4j: How to build a Quarkus app with Neo4j

Fri, 30 May 2025 20:23:12 +0000

I've recently been working on expanding my horizons in different Java frameworks, and Quarkus was on my list to try.

Quarkus is a Kubernetes-native Java framework designed to reduce an application's footprint, ideal for addressing challenges in deploying, running, and maintaining applications in cloud-based environments.

It has become a major player in list of frameworks, so naturally, I wanted to try it out! I started by following the first few steps in this blog post, as it outlines how to get a project up and running and the dependency needed for Neo4j. I felt the Quarkus Neo4j documentation was a bit overly complicated and verbose for a starter app.

All of the code for this blog post is available in the quarkus-coffee-shop Github repository.

Note: I also have a sister project using Spring Data Neo4j, for comparison. :)

Creating a project

Similar to the Spring Initializr that offers a web interface for defining a project and its dependencies, Quarkus has code.quarkus.io. Quarkus also offers a CLI, which would be especially helpful for creating multiple projects quickly.

On code.quarkus.io, I filled out the project name, and then added three dependencies for the Neo4j client, RESTEasy Classic, and RESTEasy Classic JSON-B. Once that is complete, click the Generate your application blue button to download the .zip file.

Next, unzip the folder and open it in your preferred IDE. The project template includes a GreetingResource class with a default /hello endpoint, so we can run the application and call the endpoint to see a message.

./mvnw quarkus:dev

http ":8080/hello"

Hello RESTEasy

Setup

However, to build out our application, there are a couple of adjustments needed to the pom.xml. To utilize object graph mapping capabilities, we need to include the neo4j-ogm-quarkus library, which currently (v3.14.0) is only compatible with Quarkus 3.22.1.

Note: There is an open Github pull request for 3.23, which may be released soon.

So, we need to downgrade Quarkus's platform version in order to use OGM (for now). Open the pom.xml, then navigate to the <properties> section and change the quarkus.platform.version property to version 3.22.1, as shown below.

<properties>
    <quarkus.platform.version>3.22.1</quarkus.platform.version>
</properties>

Next, add the following library to the <dependencies> section.

<dependency>
    <groupId>org.neo4j</groupId>
    <artifactId>neo4j-ogm-quarkus</artifactId>
    <version>3.14.0</version>
</dependency>

Next, we need a Neo4j database and to connect to the instance from our application.

Creating and connecting to an instance of Neo4j

If you don't have one already, spin up a free cloud instance of Neo4j Aura.

Once the instance is running, load the data by clicking on the Query tool along the left console menu, then copy the contents of the coffee shop import script and paste into the input box at the top of the window. Click the play button on the right of the input box and wait for all steps to complete.

Back in the Quarkus application, open the src/main/resources/application.properties file to add configuration for connecting to Neo4j.

# Neo4j config
quarkus.neo4j.uri=<NEO4J_URI>
quarkus.neo4j.authentication.username=<NEO4J_USERNAME>
quarkus.neo4j.authentication.password=<NEO4J_PASSWORD>

# OGM config
org.neo4j.ogm.use-native-types=true

The first three properties should match the URI, username, and password for the Neo4j instance. The final property is so that OGM will map temporal data types (dates and times) correctly.

The next step is to create the domain classes for Order, Receipt, Staff, and Customer entities.

Domain classes

The domain model for this application contains 4 main entities and the relationships between them.

We will map the Order entity first. Create a new file named Order.java and define the class as follows.

import java.time.LocalDate;
import java.time.LocalTime;

import org.neo4j.ogm.annotation.Id;
import org.neo4j.ogm.annotation.NodeEntity;
import org.neo4j.ogm.annotation.Relationship;

@NodeEntity
public class Order {
    @Id
    private String transactionId;
    private String orderId;
    private LocalDate orderDate;
    private LocalTime orderTime;
    private String inStore;

    //make OGM happy
    public Order() {
    }

    public Order(String transactionId) {
        this.transactionId = transactionId;
    }

    //getters and setters
}

The @NodeEntity annotation is for OGM to map this class to an Order node in Neo4j, and the @Id annotation pinpoints the id field for the class. After the class variables for orderId, etc, we have to create an empty constructor, as well as a required parameter constructor for OGM. Then, the getters and setters follow.

Next, let's define the Staff.java and Customer.java classes.

Staff.java:

@NodeEntity
public class Staff {
    @Id
    String staffId;
    String firstName;
    String lastName;
    LocalDate startDate;

    public Staff() {
    }

    public Staff(String staffId, String firstName, String lastName, LocalDate startDate) {
        this.staffId = staffId;
        this.firstName = firstName;
        this.lastName = lastName;
        this.startDate = startDate;
    }

    //getters and setters
}

Customer.java:

@NodeEntity
public class Customer {
    @Id
    private String customerId;
    private String customerName;
    private String loyaltyId;

    public Customer() {
    }

    public Customer(String customerId, String customerName, String loyaltyId) {
        this.customerId = customerId;
        this.customerName = customerName;
        this.loyaltyId = loyaltyId;
    }

    //getters and setters
}

These classes are similar to Order, so the code shouldn't contain any surprises.

Relationships

The next step is to define relationships. While we can directly define the relationship by adding a new variable to point to the other entity, this domain also contains relationship properties between Order and Customer that hold information on how many items the customer ordered and the total amount for the order.

To map these properties, we need another class that holds the receipt information.

import org.neo4j.ogm.annotation.EndNode;
import org.neo4j.ogm.annotation.GeneratedValue;
import org.neo4j.ogm.annotation.Id;
import org.neo4j.ogm.annotation.RelationshipEntity;
import org.neo4j.ogm.annotation.StartNode;

@RelationshipEntity("BOUGHT")
public class Receipt {
    @Id @GeneratedValue
    private Long id;

    private Integer itemsInOrder;
    private Double orderTotal;

    @StartNode
    private Customer customer;

    @EndNode
    private Order order;

    //getters and setters
}

The @RelationshipEntity maps this class to the BOUGHT relationship in Neo4j. @Id and @GeneratedValue define the id and note that it's an internally-generated id. Two class variables hold the number of items and order total. Then, the @StartNode and @EndNode point to the starting and ending entities for the relationship.

Finally, we can connect these pieces together by mapping the relationships from the Order.java class.

@NodeEntity
public class Order {
    //previous class variables

    @Relationship(value = "BOUGHT", direction = Relationship.Direction.INCOMING)
    private Receipt receiptAndCustomer;
    @Relationship(value = "SOLD", direction = Relationship.Direction.INCOMING)
    private Staff staff;

    //constructors

    //getters and setters
}

There are two definitions - one for each relationship. The @Relationship annotation defines the relationship type (BOUGHT or SOLD) and the direction (both incoming to the Order node). Those are mapped to class variables that return the entity type (Receipt and Staff).

These definitions map connections from the Order class to related entities. Now we need to define a repository and resource to retrieve entities from the database and create endpoints for us to access it.

Repository class

Create an OrderRepository.java and populate it with the following code:

import java.util.Map;
import org.neo4j.ogm.session.SessionFactory;
import jakarta.enterprise.context.ApplicationScoped;

@ApplicationScoped
public class OrderRepository {
    private final SessionFactory sessionFactory;

    OrderRepository(SessionFactory sessionFactory) {
        this.sessionFactory = sessionFactory;
    }
    
    Iterable<Order> findTenOrders() {
        return sessionFactory.openSession().query(Order.class, 
            "MATCH (order:Order)<-[rel:BOUGHT]-(c:Customer), " +
                "(order)<-[rel2:SOLD]-(s:Staff) " + 
                "RETURN order, collect(rel), collect(c), collect(rel2), collect(s) LIMIT 10;", 
            Map.of());
    }
}

The @ApplicationScoped annotation will share this repository bean across the application. Inside the class, we inject the OGM SessionFactory into the class to handle connections to Neo4j.

Next, we define a method to find 10 orders. The query retrieves customers who bought orders, and staff who sold those orders. By returning the order nodes and collecting related entities, unique patterns (orders) are returned. OGM will map returned nodes and relationships accordingly.

Finally, we need an endpoint to access this information.

Resource (i.e. Controller) class

Quarkus uses the term Resource rather than Controller, so the OrderResource.java will handle the user interface by creating a REST api.

import jakarta.enterprise.context.RequestScoped;
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;

@RequestScoped
@Path("/orders")
public class OrderResource {
    private final OrderRepository orderRepository;

    @Inject
    public OrderResource(OrderRepository orderRepository) {
        this.orderRepository = orderRepository;
    }

    @GET
    @Produces(MediaType.APPLICATION_JSON)
    public Iterable<Order> getOrders() {
        return orderRepository.findTenOrders();
    }
}

First, the @RequestScoped narrows this bean to each request, and the @Path defines the root url of /orders. Within the class, there is a variable for the repository and it's injected into the class constructor, so that we can call the query method we wrote earlier.

Next, we define the getOrders() method as a HTTP GET method that will return multiple orders (Iterable<Order>) in JSON output @Produces(MediaType.APPLICATION_JSON). The method will call the repository's findTenOrders() method.

Now we can test the application!

Run and test the application

Run the application in dev mode with the following command:

./mvnw quarkus:dev

We can test the default /hello endpoint (GreetingResource), as well as the /orders endpoint (OrderResource), which retrieves 10 order entities (and their related entities) from Neo4j:

http ":8080/hello"

http ":8080/orders"

Wrapping up!

In this blog post, we walked through the following:

How to create a Quarkus application using the Quarkus project online tool.
How to connect to Neo4j.
How to map domain entities to Neo4j with OGM.
How to run queries in Neo4j and access the data via a REST endpoint.

This project is a jumping point into so many other facets, and I'll be sure to bring you along for the ride.

Happy coding!

Resources

Github repository: Accompanying code for this blog post
Documentation: What is Quarkus?
Data set: Coffee shop graph data
Documentation: Quarkus Neo4j
Github repository: Neo4j Quarkus OGM library

Coder Legion - Recent posts tagged quarkus

quarkus-chat-ui (2): The Actor Design Behind LLM-to-LLM Conversation

Quick POJO-actor recap

The problem: blocking I/O kills the message loop

ChatActor: the state guardian

Why volatile Thread activeThread?

Why tellNow() for cancel?

BtwActor: a second independent actor

Thread safety with a shared provider

The actor system structure

What I like about this approach

Links

quarkus-chat-ui: A Web Front-End for LLMs, and a Real-World Case for POJO-actor

quarkus-chat-ui: A Web Front-End for LLMs, and a Real-World Case for POJO-actor

What it does

1. LLM instances talking to each other via MCP

2. Written in Quarkus — streaming made simple

3. A prompt queue that does the obvious thing

Why the concurrency is manageable

Quick start

Preparing a local LLM (openai-compat)

Option 1: Native executable (no JDK required)

Option 2: Build from source

Setting up two agents to talk (Claude Code CLI)

1. Install Claude Code CLI

2. Set API Key

3. Start Alice (port 28010)

4. Start Bob (port 28020)

5. Register MCP Endpoints

6. Restart Both Instances

7. Test: Alice Sends to Bob

8. Verify: Bob Receives

Cleanup

Troubleshooting

Beyond two agents

Links

Quarkus: Revolutionizing Java Development for the Cloud-Native Era

1. Introduction to Quarkus

Key Benefits

Target Use Cases

2. Core Architecture & Development Experience

Dependency Injection

Extension Ecosystem

Configuration Management

Hot Reloading & Live Coding

DevUI

Testing

3. Performance & Technology Stack

JVM vs Native Mode

Performance Comparison

Technology Stack

4. Cloud-Native & Production Features

Container-First

Kubernetes Integration

Observability

Security

5. Framework Comparisons

Quarkus vs Micronaut

Essential Extensions

Learning Resources

Conclusion

Quarkus Neo4j: How to build a Quarkus app with Neo4j

Creating a project

Setup

Creating and connecting to an instance of Neo4j

Domain classes

Relationships

Repository class

Resource (i.e. Controller) class

Run and test the application

Wrapping up!

Resources

Why `volatile Thread activeThread`?

Why `tellNow()` for cancel?