DEV Community: Praveen Yadav

Building a Multi-Agent Hiring Workflow with LangChain4j and LangGraph4j on Spring Boot

Praveen Yadav — Wed, 05 Aug 2026 06:57:32 +0000

I wanted to actually learn LangChain4j and LangGraph4j beyond the "hello world" chat example, so I built something with enough moving parts to force real decisions: a hiring workflow where several AI agents independently score a candidate, a graph aggregates their opinions into a routing decision, and a human gets pulled in whenever the signals aren't clean. It's langchain4j-sample on Spring Boot, with LangGraph4j's Postgres checkpointer for state.

This post is two things: first, how the framework pieces fit together and what I learned exploring them; second — because I didn't stop at "works against a mock LLM" — what happened when I pointed the same graph at a real, local, CPU-only Ollama model, and what that taught me about running agentic workflows outside a demo.

Why LangGraph4j instead of just chaining LangChain4j calls

The workflow needed three things a plain sequence of LLM calls doesn't give you for free: independent agents that run at the same time, a pause point that waits for a human and resumes later (possibly minutes or days later, possibly after a restart), and a durable record of exactly what happened at each step. That's what pushed me toward LangGraph4j's StateGraph rather than just wiring LangChain4j calls together by hand.

The graph itself reads close to how I'd describe the process out loud:

parseResume
     │
     ├─ unreadable? ──────────────► humanReview
     │
     ▼ (fan out, 4 concurrent agents)
skills · experience · cultureFit · redFlags
     │
     ▼
aggregateScores ──► automated? ──► finalDecision ──► notification
     │
     └─ not automated ──► humanReview ──(approve/reject/re-analyze)──► finalDecision

ParseResumeNode extracts structured data from raw resume text. If it comes back unreadable, there's no point running four scoring agents against nothing, so the graph short-circuits straight to human review. Otherwise it fans out to four independent agents — skills, experience, culture fit, red flags — each reasoning about a different dimension of fit. AggregateScoresNode combines their verdicts with a weighted formula, and anything that isn't a clean auto-advance or auto-reject drops into a humanReview interrupt. A human can approve, reject, or ask for a targeted re-analysis, which loops back into review until someone makes a final call.

What AiServices made pleasant

Each agent is a plain Java interface — no client boilerplate, no manual JSON parsing:

public interface SkillsAgent {

    @UserMessage("""
            Candidate ID: {{candidateId}}
            Job Requisition ID: {{requisitionId}}

            Use the available tools to fetch the job requisition and the candidate. Assess how
            well the candidate's skills (from their resume text) match the requisition's required
            skills. Score 0-100. Flag any required skill that's missing (e.g.
            "MISSING_REQUIRED_SKILL:Kubernetes"). Recommend ADVANCE, CAP, or REJECT.
            """)
    AgentScoreResult analyzeSkills(@V("candidateId") long candidateId, @V("requisitionId") long requisitionId);
}

AgentScoreResult is a plain record — score, flags, recommendation — and LangChain4j handles getting the model to fill it in and parsing the result back into that shape. Wiring in tools was just as low-friction: AiServices.builder(SkillsAgent.class).chatModel(...).tools(jobRequisitionTool, candidateTool).build(), and the model decides for itself when to call fetchJobRequisition or fetchCandidate mid-conversation. No manual function-calling loop to write.

The part I liked most: swapping LLM backends is pure config, not code. One ChatModel bean is conditional on llm.provider=mock and returns fixture data (great for tests and for exploring the graph's routing logic without burning tokens); another is conditional on llm.provider=ollama and builds a real OllamaChatModel. Every agent is wired against whichever bean is active — the agent interfaces and the graph don't know or care which one it is.

What LangGraph4j made pleasant — and one thing that wasn't obvious

The four scoring agents run through a ParallelNode — you point several edges out of the same source node and LangGraph4j fans them out concurrently. What wasn't obvious from the docs: registering an executor once at graph-compile time isn't enough. Every single invocation needs the executor attached to its own RunnableConfig, or the "parallel" branches just run one after another:

private RunnableConfig runnableConfig(String threadId) {
    return RunnableConfig.builder()
            .threadId(threadId)
            .addParallelNodeExecutor(HiringWorkflowGraph.ANALYSIS_FAN_OUT, analysisFanOutExecutor)
            .build();
}

The other genuinely nice piece is interruptBefore(HUMAN_REVIEW) paired with a PostgresSaver checkpointer. The graph pauses inside an in-progress execution, persists its exact state, and returns control to the HTTP request — then, whenever a human decision comes in (hours or days later, possibly against a different app instance after a restart), compiledGraph.invoke(GraphInput.resume(...), sameThreadId) picks the graph back up exactly where it left off. I didn't have to build any of that resumability myself.

One thing that cost me some trial and error: checkpointing serializes state to plain JSON with no type tagging, so a value read back after a reload comes back as a generic Map/String, not the original record. Every accessor on my WorkflowState normalizes through ObjectMapper.convertValue so callers get a consistently-typed result whether the value just came from the same in-memory node-to-node handoff or from a checkpoint reload:

private <T> Optional<T> convert(String key, Class<T> type) {
    return this.<Object>value(key)
            .map(raw -> type.isInstance(raw) ? type.cast(raw) : OBJECT_MAPPER.convertValue(raw, type));
}

With that in place, and the mock provider driving deterministic fixture data, the whole graph — fan-out, aggregation, human-review interrupt, resume, final decision — worked exactly as designed. That's usually where a learning project like this stops. I kept going, because "works against canned fixtures" and "works against a real model" turned out to be very different claims.

Then I pointed it at a real, local, CPU-only model

I didn't want a cloud API key for a side project, so I ran Ollama locally on an old CPU-only laptop. This is where the framework knowledge from above collided with the actual, physical limits of local inference — and where I learned the most.

Lesson 1: a synchronous call and a busy backend interact in a non-obvious way

My smoke-test script submits eight candidate/requisition pairs with a 900-second timeout per case — generous, I assumed, for a 3B model. Case 1 blew straight through it with no response.

The instinct is to suspect the model is stuck. The real interaction was between two things I'd built independently and never thought to consider together: WorkflowController.submit runs the entire graph invocation synchronously on the request thread (compiledGraph.invoke(...), no timeout of its own), and ollama serve runs with a single execution slot by default (-np 1) — so the four "concurrent" fan-out agents don't run concurrently against it at all, they queue and execute one at a time. When curl gave up at 900 seconds, nothing told the server thread to stop; it kept running, kept holding its place in Ollama's queue, for a client that had already left. Every subsequent request just queued up behind it, since nothing had cancelled it.

The fix taught me something reusable well beyond this project: run the invocation on its own executor with a bounded Future.get(timeout), and call future.cancel(true) on timeout. For a thread blocked inside a JDK HttpClient.send(), that interrupt actually propagates and releases the connection — it's not just a client-side illusion of giving up.

private Optional<WorkflowState> invokeWithTimeout(String threadId, GraphInvocation invocation) throws Exception {
    Future<Optional<WorkflowState>> future = workflowInvocationExecutor.submit(invocation::invoke);
    try {
        return future.get(runTimeoutSeconds, TimeUnit.SECONDS);
    } catch (TimeoutException e) {
        future.cancel(true);
        throw new ResponseStatusException(HttpStatus.GATEWAY_TIMEOUT, ...);
    }
}

The generalizable lesson: "parallel" describes your code's intent, not a guarantee about the backend underneath it. Fan four calls out against something with one execution slot, and you've built a queue with extra latency dressed up as concurrency — and if nothing can cancel a request once its caller stops waiting, that queue only grows.

Lesson 2: a "thinking" model taxes you even when you didn't ask it to think

I benchmarked the model I'd configured — qwen3.5:4b — with the simplest possible prompt: "Reply with exactly: OK." It took 35.2 seconds. The response carried a 158-token internal reasoning trace ahead of the two-word answer — this is a reasoning model, and it pays that cost on every call, regardless of how trivial the task is. Switching to qwen2.5:3b, a similarly-sized non-reasoning model I already had pulled, the identical prompt came back in 7.4 seconds with no reasoning overhead at all.

For a real resume-scoring prompt the gap held: qwen2.5:3b answered in 14.9 seconds with 56 tokens of correctly-shaped JSON. Out of curiosity I tried phi3:mini too — 22.9 seconds, 149 tokens, and the JSON was invalid: wrapped in markdown fences despite being told not to, with fields that weren't even in the schema I'd asked for.

What I took from this: for a task with a strict output contract, a model's willingness to reason out loud isn't a bonus, it's overhead you're paying for on every single call whether you wanted it or not. Model choice mattered more here than any amount of prompt tuning afterward.

Lesson 3: an agent that can call tools can also just... not

Once the faster model was in, I re-ran the smoke test and got something odder: every one of eight very different candidates came back with an identical, critical, human-review-forcing flag — POLICY_VIOLATION. Including candidates whose resumes had nothing resembling a policy issue.

I turned on LangChain4j's request/response logging and timestamp-correlated every call in one run to see exactly what each agent actually did. Three of the four scoring agents called their tools (fetchCandidate, fetchJobRequisition, fetchCompanyPolicies) before answering. The red-flags agent's very first response — before any tool call — was already its final answer:

{"score": 75, "redFlags": [{"code": "POLICY_VIOLATION", "severity": "CRITICAL", "forcesHumanReview": true}]}

It never looked at any data. Comparing prompts explained why this agent specifically: its example code, "POLICY_VIOLATION", is a complete, plausible-sounding answer with nothing candidate-specific to fill in. The skills agent's example, "MISSING_REQUIRED_SKILL:Kubernetes", isn't copyable the same way — the model has to supply a real, specific skill name for it to make sense. A model that's uncertain about tool use can lazily echo the first kind of example wholesale; it can't do that with the second.

The fix was making the tool-use requirement explicit and making the example un-copyable:

- Use the available tools to fetch the job requisition, the candidate, and the
- company policies applicable to the requisition's department. ... give a short code
- (e.g. "EMPLOYMENT_GAP", "POLICY_VIOLATION")
+ You must call fetchJobRequisition, fetchCandidate, and fetchCompanyPolicies before
+ forming any opinion — never answer from the candidate ID and requisition ID alone.
+ ... give a short code naming the specific policy or issue (e.g. "EMPLOYMENT_GAP",
+ "POLICY_VIOLATION:NON_COMPETE"). If the fetched data shows no actual gap or policy
+ conflict, return an empty redFlags array — never report a flag you can't tie to
+ something the tools actually returned.

The fabricated critical violations disappeared. Being honest about the rest of the story: re-tracing calls afterward, the model still occasionally skipped tool-calling on its first turn — it just now defaults to a safe {"score": 0, "redFlags": []} instead of a dangerous fabricated one. The prompt change narrowed the blast radius of the underlying behavior; it didn't eliminate it. That's a genuinely useful thing to learn about steering a small model through instructions alone: it has a ceiling.

Lesson 4: knowing where that ceiling actually is

The obvious next step past "ask nicely" is "force it." LangChain4j has exactly the primitive for that:

OllamaChatModel.builder()
    .defaultRequestParameters(
        ChatRequestParameters.builder().toolChoice(ToolChoice.REQUIRED).build())
    .build();

This didn't get silently ignored — it failed fast, at startup, before ever reaching Ollama:

UnsupportedFeatureException: ToolChoice.REQUIRED is not supported yet by this model provider

LangChain4j's own client-side validation refuses to construct the model. As of the version I'm on (1.18.0), forced tool choice just isn't wired up for the Ollama integration yet. Useful to know precisely, rather than spending an afternoon guessing why a "fix" wasn't taking effect: if I want that guarantee today, the actual answer is architectural, not a config flag — fetch the data in Java myself and hand it to the model directly, rather than asking the model to decide whether to fetch it.

Shipping it without asking anyone to install Ollama by hand

None of the above is worth much if trying the project means manually pulling a model before anything works. The Compose setup ended up as three long-running services plus one one-shot:

ollama:
  image: ollama/ollama
  healthcheck:
    test: ["CMD", "ollama", "list"]
    interval: 5s
    timeout: 5s
    retries: 10

# One-shot: pulls the model into ollama's own volume, cached across restarts,
# so the app never races a still-downloading model on first startup.
ollama-pull:
  image: ollama/ollama
  environment:
    OLLAMA_HOST: ollama:11434
  entrypoint: ["ollama", "pull", "qwen2.5:3b"]
  depends_on:
    ollama:
      condition: service_healthy

app:
  build: .
  environment:
    LLM_PROVIDER: ollama
    OLLAMA_MODEL_NAME: qwen2.5:3b
  depends_on:
    ollama-pull:
      condition: service_completed_successfully

ollama-pull is a throwaway container whose only job is telling the already-running ollama service to pull a model over the network. The model lands in ollama's own volume, not the puller's, so it's cached across every future docker compose up — confirmed by watching a re-run finish in under a second instead of re-downloading. app waits for that pull to fully complete, not just for Ollama to answer a healthcheck, so there's no race against a half-downloaded model on first boot.

What I'd want to remember from this

LangChain4j's AiServices + tool-calling genuinely removes boilerplate — the agent interfaces stayed clean even once real tool use and structured output were involved.
LangGraph4j's interrupt/resume + Postgres checkpointing is the feature I'd reach for again immediately; building durable human-in-the-loop pauses by hand would've been a project on its own.
A synchronous call with no timeout is a promise you can't keep once a caller stops waiting — and if nothing can cancel the underlying work, "the caller gave up" and "the work is still running" quietly become two different facts.
Concurrency is a property of your code's intent; whether it's real depends entirely on what's on the other end of the call.
For strict-output tasks, a reasoning model's internal monologue is a cost you pay on every call, not a quality feature.
A few-shot example that's copyable as a complete, plausible answer is a hallucination surface, especially for a model that's unsure what else to do.
Prompt engineering has a ceiling with small models — it's worth knowing exactly where the framework's own capabilities stop, rather than assuming a wording tweak will eventually close the gap.

The repo — graph, agents, the timeout/fallback fixes, and the Compose setup — is at github.com/ykpraveen/langchain4j-sample.

What a fake production stack taught me about CI/CD

Praveen Yadav — Tue, 28 Jul 2026 14:13:31 +0000

I recently built jenkins-ansible-sample, a self-contained sandbox that simulates a real deployment pipeline: Jenkins builds and tests an app, Ansible rolls it out across a fake dev/staging/prod fleet over SSH, and a health-check-driven rollback gets exercised by a deliberately broken deploy. Everything runs as Docker containers on a single machine — no cloud account, no real servers.

The point of the project wasn't the app (a two-endpoint Flask service). It was to force myself through the parts of CI/CD that tutorials usually skip: real host topology, secrets that have to flow through three different execution contexts, and a rollback path that has to actually fire, not just exist in a diagram. This post is less "here's how to configure Jenkins" and more "here's what I'd tell someone before they start" — the general principles, with the code that fell out of them.

Simulate the real topology, not a shortcut

It's tempting, when building a demo, to have your "deploy" step just be a docker exec into a sibling container. It's fast and it works. It also teaches you nothing about the failure modes of a real deploy, because docker exec doesn't have host keys, network partitions, or a login shell.

So the fleet here is plain containers running sshd as PID 1, reachable only over real SSH:

fleet-dev:
  build: docker/ssh-fleet
  hostname: dev
  privileged: true
  networks:
    fleet_net:
      aliases: [dev]
  ports:
    - "2201:22"

Ansible talks to dev exactly the way it would talk to a real VM — inventory groups, an SSH key, become: true for privilege escalation. The theoretical point: the fidelity of your test environment should match the fidelity of the failure modes you actually want to catch. A shortcut that skips SSH also skips every SSH-shaped problem (host key changes, key permissions, connection timeouts) you'll eventually hit for real.

The same idea shows up in docker_engine, a role that installs an actual Docker daemon onto each of these simulated hosts (privileged: true, its own nested dockerd) rather than assuming Docker is already there. It's more setup, but it means the role is exercised the same way it would run against a freshly provisioned VM, not against an environment that already has half the prerequisites baked in.

Docker-outside-of-Docker: a tradeoff, not a hack

Any CI step that needs to build or run containers has to reach a Docker daemon somehow. There are two common answers: run a nested dind (Docker-in-Docker) daemon inside the CI container, or mount the host's docker.sock into it (Docker-outside-of-Docker, DooD). This project uses DooD everywhere — the Jenkins agent, the ansible-control container, Molecule's test runner:

ansible-control:
  build: docker/ansible-control
  volumes:
    - /var/run/docker.sock:/var/run/docker.sock

DooD is simpler and has none of dind's storage-driver quirks, but the tradeoff is real and worth stating plainly: a container with the host's docker.sock mounted has root-equivalent access to that host. Any process inside it can launch a privileged container and walk straight out of its own sandbox. That's an acceptable tradeoff for a single-tenant CI box you control; it would not be an acceptable default for, say, a shared multi-tenant build service running arbitrary user code.

The lesson generalizes: infrastructure shortcuts aren't inherently bad, but they need to be a named decision with a stated blast radius, not an implementation detail nobody thought about. If you can't articulate what a shortcut costs you, you haven't finished evaluating it.

One consequence of DooD worth knowing about: when a container spawned via docker.sock is a sibling of the container that launched it, not something nested inside it, cleanup can't rely on the parent's lifecycle to take the child down with it. Molecule's test container in this project is launched exactly that way, which is why the CI stage runs it with --destroy=always — without that, a failed step earlier in the test sequence would skip teardown, and the test container would happily outlive the short-lived agent that spawned it.

Rollback is a state machine, not an `if` statement

The centerpiece of the project is the deploy role's rollback logic, and it's worth describing as what it actually is: a small state machine with three states (deploying, healthy, rolling back), not a single try/catch.

- name: Wait for the new container to pass its post-deploy health check
  ansible.builtin.uri:
    url: "http://localhost:{{ app_port }}/health"
    status_code: 200
  register: health_result
  until: health_result.status | default(0) == 200
  retries: "{{ health_check_retries }}"
  delay: "{{ health_check_delay }}"
  failed_when: false

- name: Roll back to the last-known-good image if the health check failed
  when: health_result.status | default(0) != 200
  block:
    - name: Start the last-known-good image in its place
      ansible.builtin.command: "docker run -d --name {{ app_name }} ... {{ rollback_image }}"
      when: rollback_image | length > 0
    - name: Wait for the rolled-back container to pass its health check
      ansible.builtin.uri:
        url: "http://localhost:{{ app_port }}/health"
        status_code: 200
      ...

- name: Fail the play if the post-deploy health check never passed
  ansible.builtin.fail:
    msg: "..."
  when: health_result.status | default(0) != 200

A few decisions here are more important than the YAML makes them look:

The "last known good" reference is captured before touching anything, not reconstructed after a failure. By the time you know a deploy is bad, it's too late to reliably ask "what was running a minute ago" — you have to have written it down while it was still true.
A rolled-back deploy still fails the pipeline. The host ends up healthy, but the build is still reported red. Silently "fixing itself" and reporting green would hide a real regression behind a rollback that happened to work — the whole point of the signal is to make someone look at it.
Rollback failure is a distinct, more serious outcome than deploy failure, and the code actually distinguishes it (a rollback that itself fails its health check gets a different message than a clean rollback). Collapsing both into "deploy failed" throws away the information an on-call engineer needs most: is this a bad release, or is the host actually down?
any_errors_fatal: true plus per-environment plays means a bad dev deploy never even attempts staging or prod. Promotion gates only work if a failure upstream actually stops the pipeline instead of merely being logged.

One secret, one indirection, three consumers

Secrets management often turns into a different bespoke mechanism per environment: a .env file locally, a different secret store in CI, yet another one in the deployment tool. This project instead puts a single layer of indirection in front of one password and lets every consumer go through it.

ansible.cfg points at a script instead of a static file:

[defaults]
vault_password_file = vault_pass.sh

#!/bin/sh
set -eu
: "${ANSIBLE_VAULT_PASSWORD:?ANSIBLE_VAULT_PASSWORD must be set}"
echo "$ANSIBLE_VAULT_PASSWORD"

Locally, that's an exported shell variable. In GitHub Actions, it's a repository secret injected as an env var on the steps that need it. In Jenkins, it's a credential bound via withCredentials in the pipeline. All three paths terminate at the exact same script reading the exact same variable name — nothing about how Ansible reads its vault password changes depending on who's driving it. The theoretical payoff: the number of places that need to know "how do I get the secret" should be one, regardless of how many places need the secret.

That same discipline shows up in how the Jenkinsfile passes the SSH key through to a shell command:

sh "ansible-playbook deploy.yml --limit dev -e app_deploy_app_image_tag=${IMAGE_TAG} " +
   "-e fleet_ssh_private_key_file=" + '$FLEET_SSH_KEY'

$FLEET_SSH_KEY is deliberately left single-quoted so the shell expands it at runtime, not Groovy's string interpolation at pipeline-compile time. Interpolating a credential straight into the script text via a Groovy GString bypasses Jenkins' log-masking, because masking works by pattern-matching the credential's value in the process's own output, not by tracking where a variable came from — if the value never appears as a literal in the generated shell command, masking has nothing to catch. It's a small, easy-to-miss distinction with a real consequence: get it backwards and your vault password shows up in plaintext in a build log.

If it's not codified, it doesn't count as tested

Every config surface in this project is provisioned by code, not clicked into place: Jenkins' users, credentials, and seed job are all defined in jenkins.yaml (JCasC); Grafana's datasource and dashboard are provisioned from files, not built by hand in the UI; even which services start at all is driven by Compose profiles (--profile tools, --profile observability) rather than commenting lines in and out.

jenkins:
  systemMessage: "jenkins-ansible-sample — configured via JCasC, do not click around by hand"
  numExecutors: 0   # forces every build onto a Docker Cloud agent, never the controller itself

The reason this matters more than it sounds: a manually clicked configuration is a fact about one running instance, not a fact about the system. It can't be code-reviewed, it can't be diffed between two setups that disagree, and it silently stops being true the moment someone reinstalls. Config-as-code turns "how is this configured" from a question you answer by inspecting a live system into one you answer by reading a file.

Different artifacts fail differently — lint each one on its own terms

It's tempting to reach for one linter and call it done. This project runs four completely different checks, because a Dockerfile, a YAML playbook, a Python app, and an Ansible role's actual runtime behavior fail in four different ways:

hadolint for Dockerfiles (image-layer hygiene, not application logic)
yamllint + ansible-lint for the Ansible layer (syntax and Ansible-specific anti-patterns)
pytest, run as a build stage the final image can't skip:

  FROM base AS test
  RUN uv sync --frozen --group test --no-install-project
  COPY app.py .
  COPY tests/ tests/
  RUN python -m pytest -q

  FROM base AS final
  COPY --from=test /app/app.py .   # only reachable if the test stage above succeeded

molecule for the common role, which spins up a real container, applies the role, and asserts on the actual resulting state of the machine — not the playbook's syntax, but what it did:

  - name: /etc/timezone should be UTC
    ansible.builtin.command: cat /etc/timezone
    register: tz
    changed_when: false
    failed_when: tz.stdout != "UTC"

A linter can tell you a playbook is well-formed; only actually converging it against a host and asserting on the result tells you it does what you think it does. Static analysis and behavioral testing catch disjoint sets of bugs — treating a passing lint as proof of correctness is a mistake regardless of language or tool.

Make the failure mode visible, not just handled

Deploy success/failure is worth almost nothing as a signal if nobody sees it in context. Rather than invent a new metric for "a deploy happened," this project posts deploy attempts as annotations onto a dashboard that already exists:

- name: Record this deploy as a Grafana annotation
  ansible.builtin.uri:
    url: "{{ grafana_url }}/api/annotations"
    method: POST
    body: {text: "{{ deploy_event_text }}", tags: [deploy, "{{ environment_name }}", "{{ deploy_event_tag }}"]}
  when: app_deploy_grafana_annotate | default(true)
  failed_when: false   # an unreachable dashboard must never fail a deploy over it

Two design choices here matter beyond the specific tool: annotating an existing CPU/memory dashboard means a rollback shows up as a visible marker on the same graph where its effects would be seen, instead of living in a separate "deploys" panel nobody checks. And failed_when: false encodes an explicit priority order — observability is a consumer of the deploy, not a dependency of it. A monitoring outage should never be able to fail a deploy.

CI failures aren't always about your code

Not every red build is a bug in the thing being tested — sometimes it's drift between two steps in the pipeline that only look the same. While working on this project, one CI job's lint step failed consistently, and the cause turned out to be nothing about the YAML being linted: ansible-lint shells out to ansible-playbook --syntax-check internally, which needs the vault password just to parse a group_vars file — even though nothing in a syntax check touches the vaulted values. The pipeline step running the linter simply hadn't been given that credential, while every later step that actually deployed had.

The general takeaway: when a CI step fails in a way that doesn't match the tool's stated job, check what else that tool does under the hood before assuming the input is wrong. And when you're debugging a step that runs inside a container with pinned tool versions, reproducing it with the exact same versions locally turns a guessing game into a repeatable test — version drift between "works on my machine" and CI is its own separate failure mode, easy to rule out early if you pin first and debug second.

What's deliberately not here

Kubernetes, multi-cloud provisioning, and blue-green deploys are all out of scope on purpose. The goal was depth on one deploy pattern (rolling deploy + health-check-gated rollback, over SSH, onto host-like targets) rather than breadth across every pattern that exists. That's its own lesson: a project that tries to demonstrate everything ends up demonstrating nothing well — better to pick one path all the way through, including its failure modes, than to sketch three and finish none.

The full project, architecture diagram, and README are at github.com/ykpraveen/jenkins-ansible-sample.

I Ran From EJB2 to Spring. Then I Went Back. Here's What I Found.

Praveen Yadav — Tue, 21 Jul 2026 14:47:39 +0000

The Ghost of Deployment Descriptors Past

A few weeks ago I sat down to build a small clinic-appointment backend on WildFly, just to scratch an itch and relearn Jakarta EE properly. Nothing dramatic — a REST API, a booking flow, some business rules, and a small Vue 3 frontend on top so I'd have something to click through while I tested it. The kind of thing I'd normally reach for Spring Boot to knock out in an afternoon.

Except I didn't reach for Spring Boot. I reached for EJB.

And the second I typed @Stateless into an empty Java file, a very specific kind of dread crawled up my spine. Because the last time I wrote a line of EJB code with any seriousness, it was EJB 2.1, and it was not a good time.

If you never lived through that era, let me set the scene. To write what should have been a five-line "create a customer" method, you needed:

A home interface, so the container could tell you how to create or find your bean.
A remote (or local) interface, so callers could actually talk to it.
A bean implementation class that had to implement lifecycle callbacks it almost never used (ejbCreate, ejbActivate, ejbPassivate, ejbRemove — hello darkness, my old friend).
An XML deployment descriptor (ejb-jar.xml) wiring the interfaces to the implementation, declaring transaction attributes, and generally repeating everything you'd already written in Java, but in angle brackets.
If you were unlucky enough to use CMP entity beans for persistence, a second vendor-specific XML file mapping fields to columns, because the spec left enough gaps that every app server (WebLogic, WebSphere, JBoss) filled them in its own special way.

A trivial CRUD operation could sprawl across five files. Container-Managed Persistence entity beans were so notoriously painful that "just use Hibernate directly and skip CMP entirely" was common, accepted advice — inside a spec whose entire job was persistence. People didn't leave Java EE because they hated Java. They left because EJB 2.x had turned "write a business object" into a small bureaucracy.

So I did what a lot of people did: I left. Spring Framework showed up promising Plain Old Java Objects, dependency injection without a home interface in sight, and @Transactional on a method instead of an XML block. I spent most of the following decade there — Spring, then Spring Boot, autoconfiguration, embedded Tomcat, application.properties doing in one line what used to take a deployment descriptor. Somewhere in the last couple of years I also poked at Quarkus, drawn in by the "supersonic subatomic" pitch — sub-second live reload, GraalVM native images, the sense that the JVM startup tax was finally being paid down.

So — genuine question, going into this clinic project — was I about to relive 2007? Or had EJB actually caught up while I wasn't looking?

First Fork in the Road: EJB 3 or EJB 4?

Before writing a single bean, I had to answer a boring-sounding but surprisingly consequential question: which EJB version?

Here's the short version of EJB's history, as I pieced it back together:

EJB 1.x / 2.x (1998–2003ish): the bureaucracy described above. Home/remote interfaces, CMP entity beans, javax.ejb.*.
EJB 3.0 (2006): the reset button. Annotations replaced deployment descriptors for the common case. @Stateless, @Stateful, @MessageDriven beans became plain classes with an annotation on top. JPA was introduced as a completely new, much saner persistence model, explicitly designed to replace CMP.
EJB 3.1 (2009): the "you don't even need an interface" release — the no-interface view, plus @Singleton beans and an embeddable container for testing.
EJB 3.2 (2013): mostly pruning and cleanup — some of the crustier optional pieces (like the entity bean component contract, if you can believe it survived that long as "optional") were marked for removal, async session bean invocation got polished.
The Jakarta rename (2017–2019): Oracle handed Java EE to the Eclipse Foundation. Trademark reasons meant the javax.* namespace couldn't keep being evolved under the old name, so the specs were rebranded Jakarta EE, and eventually (Jakarta EE 9, 2020) every javax.* package was mechanically renamed to jakarta.*.
Jakarta EJB 4.0 (2022, part of Jakarta EE 10): the namespace flip finally lands inside EJB itself (jakarta.ejb.*), plus a genuine pruning pass — CMP/BMP entity beans and a few other legacy corners are gone for good. This is also the version this article — and the WildFly 35 sample project it's built on — actually uses.

Here's the twist that surprised me: EJB 4.0 isn't a big conceptual leap from 3.2. It's not "EJB 3 was good, EJB 4 reinvents it again." It's much closer to "EJB 3.2, tidied up, renamed, with the truly dead weight finally thrown out." If you already know @Stateless, @Stateful, and @MessageDriven, you already know EJB 4.0. The import changes from javax.ejb to jakarta.ejb, a couple of legacy APIs vanish, and that's essentially the delta.

Which made the actual decision easy: for anything new, there is no reason to target EJB 3.x today. Modern app servers — WildFly, Payara, Open Liberty, TomEE — are all building against the jakarta.* namespace now. Picking EJB 3.x for a new project in 2024+ would be deliberately choosing the legacy on-ramp. The only reason to stay on 3.x is that you're stuck maintaining something old that hasn't been ported yet — and that's a migration problem, not a new project decision.

So: EJB 4.0, on WildFly 35, targeting Jakarta EE 10. Onward.

Okay, But Is It Actually Nicer to Write Now?

Enormously, yes. A @Stateless service bean in 2024 looks like this:

@Stateless
public class CustomerManagementService {
    @PersistenceContext(unitName = "customerMgmtPU")
    private EntityManager em;

    @Transactional
    public Customer createCustomer(Long clinicId, String fullName, String username, String email, String phone) {
        // ...validate, persist, return
    }
}

No home interface. No remote interface (unless you deliberately want a remote one, for actual distributed calls across JVMs — most people never do). No deployment descriptor for this. It's a plain class with two annotations, injected wherever it's needed via @Inject or @EJB, and the container hands you connection pooling, thread-safety (it manages a pool of instances so you never worry about concurrent calls to the same object), and transaction demarcation for free.

If you've been living in Spring Boot, this will feel extremely familiar, just with different spelling:

Spring	Jakarta EE / EJB
`@Service` / `@Component`	`@Stateless` (or a CDI `@ApplicationScoped` bean)
`@Autowired`	`@Inject` (CDI) or `@EJB` (EJB-specific lookup)
`@Transactional`	`@Transactional` (yes, actually the same annotation package in modern Jakarta EE — `jakarta.transaction.Transactional`)
`@RestController` + `@GetMapping`	JAX-RS `@Path` + `@GET` resource class
Spring Data repository	`@PersistenceContext EntityManager` + JPQL (more manual, but the same underlying JPA)

The mental model transfers almost one-to-one. Which, honestly, was the biggest surprise of this whole exercise — I expected to be relearning a foreign paradigm, and instead I was mostly relearning vocabulary.

Where it stops feeling like Spring Boot is packaging and deployment. This project ships as an EAR (Enterprise Archive) — a WAR for the REST layer plus several EJB JARs, one per business domain, all bundled together and deployed to a running WildFly instance. There's no embedded server, no single fat executable jar you java -jar and go. You build, you drop the EAR into WildFly's deployments/ folder (or let a deployment scanner pick it up), and the server hosts it. Compared to Spring Boot's "it's just a jar" simplicity, or Quarkus's aggressive dev-mode hot reload, this is a heavier loop — more ceremony in the Maven multi-module setup, a real datasource to configure on the app server itself (WildFly's CLI, not a one-line application.properties), and a slower edit-deploy-test cycle. That tradeoff is real, and it's the main thing that still feels dated. But it buys you something Spring Boot and Quarkus don't hand you automatically: a shared, centrally-managed runtime where multiple applications can be deployed side by side under one operations team's control — which is exactly the world a lot of regulated enterprises still live in, and exactly the use case EJB and application servers were built for.

Message-Driven Beans: Async Without the Config Headache

The part I'd genuinely half-forgotten existed: Message-Driven Beans. An MDB is a bean that doesn't get invoked by a caller at all — it gets invoked by the container whenever a message shows up on a queue or topic. No REST call, no method call, just: message arrives, container spins up (or reuses) a pooled instance, and calls onMessage.

In the clinic project, every time an appointment is booked, cancelled, or rescheduled, the business-logic bean publishes a small JSON event onto a JMS queue. A separate MDB picks it up asynchronously and turns it into a durable audit-log entry:

@JMSDestinationDefinition(
        name = "java:jboss/exported/jms/queue/AppointmentEvents",
        interfaceName = "jakarta.jms.Queue"
)
@MessageDriven(activationConfig = {
        @ActivationConfigProperty(propertyName = "destinationType", propertyValue = "jakarta.jms.Queue"),
        @ActivationConfigProperty(propertyName = "destination", propertyValue = "java:jboss/exported/jms/queue/AppointmentEvents")
})
public class AppointmentEventMDB implements MessageListener {
    @Override
    public void onMessage(Message message) {
        // decode the event, persist an audit entry
        // failures here don't block the original booking transaction
    }
}

What struck me is how little of this I had to configure by hand. The queue itself is declared right there in an annotation (@JMSDestinationDefinition) — no separate resource-adapter XML, no manual JNDI binding step. The container manages the listener's thread pool, its transaction (each message delivery gets its own container-managed transaction by default), and its lifecycle. I didn't write a single line of "here's how many concurrent consumers to run" boilerplate.

The closest things I've used since are Spring's @JmsListener (functionally similar, a bit more configuration around the connection factory and listener container) and Quarkus's SmallRye Reactive Messaging (@Incoming/@Outgoing, which leans further into a reactive-streams style and is genuinely lovely for Kafka-shaped problems). MDBs are older, less flashy, and tied specifically to JMS rather than being transport-agnostic — but for "decouple this side-effect from the main transaction, and let the container deal with concurrency," it's still a remarkably small amount of code for what it does. The audit trail in this project can fail to write without ever rolling back the appointment booking that triggered it, purely because the two run in separate transactions, on separate threads, and neither one has to know the other exists.

Stateful Session Beans: Conversation, Held By the Server

The other bean type this project leans on, and the one I think is genuinely underrated: Stateful Session Beans.

A @Stateless bean is anonymous — any pooled instance can handle any call, because it holds no per-client state between invocations. A @Stateful bean is the opposite: the container hands you your own dedicated instance, and it remembers instance fields across multiple method calls, for as long as your conversation with it lasts.

The clinic project uses this for a multi-step booking wizard. A REST client starts a session, then makes a sequence of calls — pick a doctor, pick a schedule, pick a time, add notes, confirm — without ever having to resend everything it already told the server:

@Stateful
@ConcurrencyManagement(ConcurrencyManagementType.CONTAINER)
public class BookingSessionBean {
    private Long clinicId;
    private Long doctorId;
    private Long scheduleId;
    private LocalTime selectedTime;
    // ...

    @Lock(LockType.WRITE)
    public void selectDoctor(Long doctorId) {
        this.doctorId = doctorId;
        // reset anything that depended on the previous doctor
    }

    @Lock(LockType.WRITE)
    @Remove
    public Appointment confirmBooking(String createdBy) {
        // uses everything accumulated across prior calls
        // @Remove: the container destroys this bean instance afterward
    }
}

Each REST call in the wizard resolves to the same bean instance (tracked via a session id, held in a small in-memory registry in this sample — in a real deployment, an app server can passivate an idle stateful bean to disk and reactivate it later, entirely transparently to the client). @Lock(LockType.WRITE) tells the container "serialize concurrent calls to this instance," which matters because a stateful bean is, definitionally, shared mutable state scoped to one conversation. And @Remove marks the method that ends the conversation — after confirmBooking runs, the container discards the instance; there's nothing left to passivate.

I don't think I'd reach for this every day — plenty of "multi-step form" problems are perfectly well solved by just... storing a draft row in the database and updating it, which is honestly the more portable, horizontally-scalable choice (this sample's in-memory registry, worth saying plainly, means an in-progress booking is lost if the server restarts — a real tradeoff, not a hidden one). But for a short-lived, single-server, "walk me through these five steps" conversation, having the container hold your state for you — with real concurrency control and a defined end-of-life hook — is a genuinely different tool than anything Spring or Quarkus hand you out of the box. Both of those ecosystems would push you toward an explicit session store (Redis, a database row, a signed client-side token) for the same problem; EJB just... has a bean type for it.

So, EJB 2 Survivor's Verdict

Coming back to this after a decade-plus of Spring and a Quarkus flirtation, here's where I landed:

EJB today is not EJB 2. The bureaucracy is gone. Annotations replaced almost all of the XML. JPA replaced CMP with something people actually choose to use voluntarily. A @Stateless service bean reads like a Spring @Service with a different import line. If you know modern Spring or Quarkus, you already know 90% of the concepts here — dependency injection, declarative transactions, annotation-driven REST endpoints — you're just relearning the spelling.

EJB 4.0 over EJB 3.x, no contest, for anything new. The gap between them is a namespace flip and some cleanup, not a redesign — so there's no "wait and see" argument for staying on 3.x the way there might be for a genuinely risky major version bump. If your target server supports Jakarta EE 10 (WildFly 27+, recent Payara, recent Open Liberty), there's no reason to write against the older, javax-based spec today.

What still costs you, relative to Spring Boot or Quarkus, is the operational loop, not the programming model — a real app server to configure, an EAR to build and deploy, a slower inner development cycle than Quarkus's live reload or Spring Boot's java -jar. That's the genuine, non-nostalgic tradeoff, and it's worth knowing about before you pick this stack for a new project versus a mature one already living on an app server.

And the two bean types I'd half-forgotten — MDBs and Stateful Session Beans — turned out to be the most interesting part of revisiting this. Not because they're better than a Kafka consumer or a Redis-backed session store, but because they solve the same problems with less code than I expected, when the container itself is a good enough fit for what you're building.

If you want to poke at the actual code behind any of this — the full clinic-appointment backend, the MDB, the stateful booking wizard, the multi-module Maven setup, and the Vue 3 frontend that talks to it — it's on GitHub: ykpraveen/ejb-wildfly-sample.

I came in expecting to relive 2007. I left with a renovated opinion of a technology I'd written off. Turns out it wasn't EJB that aged badly — it was EJB 2.

From Spring Boot to Quarkus

Praveen Yadav — Mon, 13 Jul 2026 12:24:00 +0000

What I Learned Building a Microservices System

I have architected and developed many enterprise solutions using Spring Boot microservices for many years. Spring MVC, WebFlux, Integration, Batch, Data JPA, Security — that whole world is muscle memory. When I decided to try Quarkus, I expected it to be "Spring Boot on a diet." In some ways it is. In other ways, it is a genuinely different philosophy about what a Java framework should be.

I built a small microservices system: an identity service, a catalog service, an order service, and an API gateway — all backed by a single PostgreSQL instance with schema-level isolation, containerized with Docker Compose, and secured with JWT. The project lives at quarkus-panache-sample. Everything I describe below is drawn from that codebase.

This is not a Quarkus tutorial. It is a literature of discovery — the things that surprised me, the things that frustrated me, and the things that made me reconsider where I reach for which framework.

The First Surprise: Dev Mode Is Actually Fast

Spring Boot DevTools reloads the application context. It works, but when your project crosses a certain size, you wait. Quarkus takes a different path: build-time processing. Annotations are processed at compile time, not runtime. Reflection is minimized. CDI beans are wired ahead of time.

The result is a development loop that genuinely feels iterative. ./mvnw quarkus:dev starts in under a second after the first build. Hot reload of Java classes, resources, and configurations happens without restarting the JVM. Spring Boot DevTools works, but I never felt the feedback loop was fast enough to keep flow state. Quarkus gets close.

# Catalog service config — Quarkus reads this at build time
quarkus.http.port=${QUARKUS_HTTP_PORT:8082}
quarkus.datasource.jdbc.url=${DB_URL:jdbc:postgresql://localhost:5432/platform}

The ${VAR:default} interpolation works the same as Spring's, but the processing model is fundamentally different. Quarkus resolves what it can at compile time. Spring Boot evaluates at startup, which gives you more dynamism but costs you startup time.

Panache vs Spring Data JPA: Same Destination, Different Vehicle

This was the most interesting comparison for me. Spring Data JPA uses the repository pattern: you define an interface, Spring generates the implementation. Quarkus offers two approaches through Panache: the active-record pattern (entity extends PanacheEntityBase) and the repository pattern (class implements PanacheRepository).

I chose active record for this project. Here is a product entity:

@Entity
@Table(name = "products", schema = "catalog")
public class ProductEntity extends PanacheEntityBase {

    @Id
    @GeneratedValue(strategy = GenerationType.SEQUENCE, generator = "catalog_products_seq_gen")
    @SequenceGenerator(name = "catalog_products_seq_gen", schema = "catalog",
                       sequenceName = "products_seq", allocationSize = 1)
    private Long id;

    @Column(nullable = false, length = 160)
    private String name;

    @Column(nullable = false, precision = 12, scale = 2)
    private BigDecimal price;

    // ... more fields

    public static List<ProductEntity> findActive(int page, int size) {
        return find("SELECT p FROM ProductEntity p LEFT JOIN FETCH p.category WHERE p.deletedAt IS NULL")
                .page(page, size).list();
    }
}

And here is the service that uses it:

@ApplicationScoped
public class CatalogService {

    @Bulkhead(10)
    public ProductResponse getProduct(Long productId) {
        ProductEntity product = ProductEntity.findById(productId);
        if (product == null || product.getDeletedAt() != null) {
            throw new ApiException(Response.Status.NOT_FOUND, "Product not found");
        }
        return toResponse(product);
    }

    @Bulkhead(5)
    @RateLimit(value = 20, window = 1, windowUnit = ChronoUnit.SECONDS)
    @Transactional
    public ProductResponse createProduct(CreateProductRequest request) {
        // ...
        product.persist();
        return toResponse(product);
    }
}

ProductEntity.findById(productId) is a static method. product.persist() is an instance method. No @Autowired JpaRepository<ProductEntity, Long> repository. The entity is the data access object. In Spring Data JPA, the repository interface sits between the service and the entity. In Panache's active-record mode, that layer disappears entirely.

I had mixed feelings about this. For simple CRUD, active record is concise and readable. For complex queries, it still supports the same HQL/JPQL you already know. But if you are used to the repository abstraction for testability and separation of concerns, Panache's repository mode is there too:

@ApplicationScoped
public class ProductRepository implements PanacheRepository<ProductEntity> {
    public List<ProductEntity> findActive(int page, int size) {
        return find("deletedAt IS NULL").page(page, size).list();
    }
}

I could have used this pattern instead. I chose active record because I wanted the full Quarkus experience. Both are well documented at Panache.

REST Resources: JAX-RS Feels Like Coming Home

Spring Boot uses @RestController, @RequestMapping, @GetMapping. Quarkus uses JAX-RS: @Path, @GET, @POST. If you have ever worked with JAX-RS before Spring Boot took over the world, this is familiar ground.

@Path("/api/v1/catalog")
@Consumes(MediaType.APPLICATION_JSON)
@Produces(MediaType.APPLICATION_JSON)
public class CatalogResource {

    @Inject
    CatalogService catalogService;

    @POST
    @Path("/products")
    @RolesAllowed("ADMIN")
    public Response createProduct(@Valid CreateProductRequest request) {
        ProductResponse product = catalogService.createProduct(request);
        return Response.status(Response.Status.CREATED).entity(product).build();
    }

    @GET
    @Path("/products/{productId}")
    @RolesAllowed({"USER", "ADMIN"})
    public ProductResponse getProduct(@PathParam("productId") Long productId) {
        return catalogService.getProduct(productId);
    }
}

@Inject instead of @Autowired. jakarta.ws.rs.core.Response instead of ResponseEntity. @PathParam instead of @PathVariable. The mapping is nearly one-to-one. Spring Boot drew from the same well — Spring MVC was inspired by JAX-RS, and over time the industry converged on Jakarta EE standards. Quarkus bet on the standard directly.

The @RolesAllowed annotation is the Jakarta EE security standard. In Spring Boot, you would write @PreAuthorize("hasRole('ADMIN')"). It accomplishes the same thing. The difference is that @RolesAllowed works with any Jakarta-compatible security implementation, not just Spring Security.

Exception Mapping Instead of Controller Advice

Spring Boot uses @ControllerAdvice with @ExceptionHandler for centralized error handling. Quarkus uses JAX-RS ExceptionMapper:

@Provider
public class ApiExceptionMapper implements ExceptionMapper<ApiException> {
    @Override
    public Response toResponse(ApiException exception) {
        return Response.status(exception.status())
                .type(MediaType.APPLICATION_JSON)
                .entity(new ApiError(
                    exception.status().getStatusCode(),
                    exception.getMessage()
                ))
                .build();
    }
}

The @Provider annotation registers the mapper automatically. No explicit configuration needed. I found this cleaner than Spring's approach, where you typically need to remember to add @ControllerAdvice to a class and annotate individual methods. The tradeoff is that ExceptionMapper operates at the JAX-RS layer, not the HTTP layer, which means it catches exceptions from JAX-RS resource methods but not filters. For most services, that is sufficient. The Quarkus documentation on error handling covers the full picture.

The API Gateway: Vert.x Routes Instead of Spring Cloud Gateway

This was the most alien part. Spring Cloud Gateway uses a builder DSL or YAML configuration for routes. Quarkus offers Vert.x Web routes as a first-class feature:

@ApplicationScoped
public class ReactiveGatewayRoutes {

    @Route(path = "/api/v1/identity/*", methods = Route.HttpMethod.GET)
    @Route(path = "/api/v1/identity/*", methods = Route.HttpMethod.POST)
    void identity(RoutingContext ctx) {
        proxy(ctx, identityBaseUrl);
    }

    @Route(path = "/api/v1/catalog/*", methods = Route.HttpMethod.GET)
    void catalogGet(RoutingContext ctx) {
        if (requireRoles(ctx, "USER", "ADMIN")) return;
        proxy(ctx, catalogBaseUrl);
    }

    @Route(path = "/api/v1/orders", methods = Route.HttpMethod.POST)
    void ordersReadWrite(RoutingContext ctx) {
        if (requireRoles(ctx, "USER", "ADMIN")) return;
        proxy(ctx, orderBaseUrl);
    }
}

@Route is processed at build time into Vert.x route handlers. The RoutingContext gives you access to the request, response, headers, and body — all reactive. Proxying is done via WebClient:

private void proxy(RoutingContext ctx, String baseUrl) {
    var req = client.requestAbs(method, baseUrl + targetPath);
    String auth = ctx.request().getHeader("Authorization");
    if (auth != null) req.putHeader("Authorization", auth);
    String correlationId = ctx.get("correlationId");
    if (correlationId != null) req.putHeader("X-Correlation-Id", correlationId);

    req.send()
        .onSuccess(resp -> sendResponse(ctx, resp))
        .onFailure(err -> sendError(ctx, err));
}

I could have used Spring Cloud Gateway instead, but that would have meant running a separate Spring Boot application alongside the Quarkus services. Vert.x routes let me keep everything in one Quarkus binary. The tradeoff is that I had to write the proxying logic myself — Spring Cloud Gateway gives you uri: http://identity-service in YAML.

REST Clients and Fault Tolerance: MicroProfile Over Feign

For inter-service communication, Spring Boot developers reach for @FeignClient (from Spring Cloud OpenFeign) or WebClient. Quarkus uses MicroProfile REST Client:

@Path("/api/v1/catalog/products")
@RegisterRestClient(configKey = "catalog-api")
public interface CatalogProductClient {

    @GET
    @Path("/{id}")
    @Bulkhead(5)
    @CircuitBreaker(requestVolumeThreshold = 10, failureRatio = 0.5,
                    delay = 5000, delayUnit = ChronoUnit.MILLIS)
    CatalogProductResponse getProduct(@PathParam("id") Long id);
}

The @RegisterRestClient annotation tells Quarkus to generate the implementation. The @Bulkhead and @CircuitBreaker annotations come from MicroProfile Fault Tolerance, not Resilience4j. They work the same way — configure limits, thresholds, delays — but they are specified by a Jakarta EE standard rather than a Spring-specific library.

I could have used Resilience4j directly (it has no Spring dependency), but the MicroProfile annotations integrate natively with Quarkus's metadata scanning and build-time processing. The MicroProfile Fault Tolerance specification documents the full annotation set.

Tests: @QuarkusTest vs @SpringBootTest

Tests in Quarkus use @QuarkusTest. The equivalent of @WithMockUser is @TestSecurity:

@QuarkusTest
class CatalogResourceTest {

    @Test
    @TestSecurity(user = "admin", roles = {"ADMIN"})
    void fullCrud() {
        // REST Assured calls against the running Quarkus instance
        given()
                .contentType(ContentType.JSON)
                .body("{\"name\":\"Electronics\"}")
                .when().post("/api/v1/catalog/categories")
                .then().statusCode(201);
    }

    @Test
    void listProductsUnauthenticated() {
        given()
                .when().get("/api/v1/catalog/products")
                .then().statusCode(401);
    }
}

REST Assured is the default HTTP test client (Spring Boot also supports it, but TestRestTemplate is the traditional choice). Mocking CDI beans uses @InjectMock (Quarkus-specific), which is equivalent to Spring's @MockBean. The test framework boots Quarkus once per test class, not per method, which keeps test runs fast.

I did not use Quarkus Mockito configuration, but the project includes quarkus-junit5-mockito for that purpose. The order service tests use @InjectMock to simulate the catalog REST client.

The Memory Problem That Started This All

Building native images with GraalVM is memory-intensive. Each Quarkus service consumes 4–16 GB of RAM during compilation. Starting all four at once with docker compose -f docker-compose.yml -f docker-compose.native.yml up --build can overwhelm a development machine.

The solution is incremental builds — one service at a time:

docker compose -f docker-compose.yml -f docker-compose.native.yml build identity-service
docker compose -f docker-compose.yml -f docker-compose.native.yml build catalog-service
docker compose -f docker-compose.yml -f docker-compose.native.yml build order-service
docker compose -f docker-compose.yml -f docker-compose.native.yml build api-gateway

Or skip compose and build the Docker image directly:

docker build -f identity-service/Dockerfile.native -t identity-service .

The native Dockerfiles in this project use the quay.io/quarkus/ubi9-quarkus-mandrel-builder-image with Mandrel (the GraalVM distribution maintained by the Quarkus team). The multi-stage build pattern mirrors what you would do for any compiled language — build in a heavy image, run in a minimal one:

FROM quay.io/quarkus/ubi9-quarkus-mandrel-builder-image:jdk-21 AS build
# ... copy sources, compile with -Dquarkus.native.enabled=true

FROM quay.io/quarkus/ubi9-quarkus-micro-image:2.0
WORKDIR /work/
COPY --from=build /code/api-gateway/target/*-runner /work/application
CMD ["./application", "-Dquarkus.http.host=0.0.0.0"]

The resulting image is around 130 MB — comparable to a Go binary container. Startup time is under 100 milliseconds. If you have ever watched a Spring Boot application struggle through classpath scanning on a cold start in Kubernetes, you understand why this matters.

Where I Still Reach for Spring Boot

I built this system to learn Quarkus. I chose Quarkus for this project deliberately. But I am not abandoning Spring Boot. Here is where I still reach for Spring Boot:

Large teams with established conventions. Spring Boot has been the dominant enterprise Java framework for over a decade. If you are onboarding developers who know Spring Boot but not JAX-RS or CDI, the learning curve for Quarkus — subtle as it is — still exists. Spring Boot's documentation ecosystem is unmatched. The Stack Overflow corpus for Spring Boot is vast. Quarkus is catching up, but it is not there yet.

Existing Spring ecosystem investments. If you already use Spring Cloud Config, Spring Cloud Gateway, Spring Security OAuth2, Spring Batch, or Spring Cloud Data Flow, replacing individual components with Quarkus equivalents requires rewriting infrastructure code. The return on investment diminishes unless you also need the startup time or memory improvements.

Projects that need maximum library compatibility. Quarkus works by processing bytecode at build time. Most libraries work, but some use reflection, dynamic class loading, or runtime bytecode generation in ways that break the Quarkus build model. Spring Boot imposes no such restrictions — if a library runs on the JVM, it runs in Spring Boot. The Quarkus extension ecosystem is growing, but it is not comprehensive.

Monoliths that are not in containers. Quarkus's killer features — sub-second startup, low memory footprint, native compilation — matter most in containerized environments where you pay for idle. If you are deploying a monolith to a traditional server, Spring Boot's startup time is a one-time cost, and memory is cheaper than migration effort.

Where I Choose Quarkus Going Forward

Serverless and function-as-a-service workloads. Cold start is the enemy of serverless Java. Quarkus native images start in milliseconds. I have seen Spring Boot functions take 5–10 seconds to initialize on AWS Lambda cold starts. That is a non-starter for latency-sensitive APIs. Quarkus eliminates the problem entirely. The Quarkus AWS Lambda guide documents the integration.

Microservices where density matters. If you are running twenty microservices on a Kubernetes node with 8 GB of RAM, each one needs to be small. A Quarkus native binary uses 20–50 MB of RSS. A Spring Boot JAR on a JVM with the same service typically uses 200–400 MB. That is the difference between fitting on one node and needing three.

High-iteration development loops. I found the Quarkus dev mode genuinely faster — not incrementally faster, but categorically faster — than Spring Boot DevTools. If your team is doing rapid prototyping or frequent refactoring, the reduced cycle time adds up. Hot reload in Quarkus is sub-second for most changes.

Projects where build-time validation catches errors. Quarkus validates configuration and injection points at compile time, not at startup. A misconfigured @ConfigProperty or a missing bean dependency fails the build, not a production deployment. This is a cultural shift — you catch errors earlier in the pipeline — but it changes how you think about configuration.

Greenfield projects with a preference for standards over frameworks. JAX-RS, CDI, MicroProfile JWT, MicroProfile Fault Tolerance, and MicroProfile REST Client are Jakarta EE and MicroProfile standards. They are not tied to a single vendor or framework. If you value portability across runtimes, the standard-oriented approach is appealing. Spring Boot has been moving toward standards as well (Spring Data JPA is JPA, Spring Security supports OAuth2 standards), but Quarkus starts from the standard and builds out.

The Decision Matrix

Criteria	Spring Boot	Quarkus
Startup time	Seconds to minutes	Milliseconds (JVM) / microseconds (native)
Memory (idle)	200–400 MB per service	20–50 MB per service (native)
Dev iteration speed	Fast (DevTools)	Faster (build-time processing + hot reload)
Library ecosystem	Comprehensive	Growing (extensions model)
Standards alignment	Spring conventions	Jakarta EE + MicroProfile specifications
Learning curve for Spring devs	None	Low (mapping is nearly one-to-one)
Serverless / FaaS	Struggles with cold start	First-class
Kubernetes density	Needs more resources	Efficient
Documentation corpus	Massive	Good and improving
Build-time validation	Limited	Extensive
Multi-module Maven/Gradle	Well supported	Well supported

What I Used and What I Could Have Used

The project uses:

Quarkus 3.15.2 with RESTEasy Reactive for the REST layer
Hibernate ORM with Panache for persistence, active-record mode (Panache documentation)
Flyway for schema migrations (Quarkus Flyway guide)
SmallRye JWT for token issuance and validation (SmallRye JWT documentation)
MicroProfile REST Client for inter-service HTTP calls (REST Client guide)
MicroProfile Fault Tolerance (@Bulkhead, @RateLimit, @CircuitBreaker) for resilience (Fault Tolerance guide)
Vert.x Web routes for the API gateway (Reactive Routes guide)
Micrometer + Prometheus for metrics (Micrometer guide)
SmallRye OpenAPI / Swagger UI for API documentation (OpenAPI guide)
Hibernate Validator for bean validation (Validation guide)
Quarkus Test with REST Assured and @TestSecurity for integration tests (Testing guide)
Docker Compose with multi-stage native-image Dockerfiles (Building Native Images guide)

I could have used instead:

PanacheRepository instead of active-record mode if I wanted the repository abstraction
Spring Cloud Gateway instead of Vert.x routes if I preferred YAML-based routing configuration
Resilience4j instead of MicroProfile Fault Tolerance if I wanted to stay closer to the Spring ecosystem
Gradle instead of Maven (the Quarkus plugin supports both equally)
Testcontainers via @QuarkusTestResource for integration tests against real databases (Testcontainers guide)
Keycloak as an external identity provider instead of issuing JWTs internally (the README documents this as a planned migration path)

Final Thoughts

Quarkus does not replace Spring Boot. It complements it. Each framework has a strength profile, and the profiles overlap in the middle. If you are building a monolith with a well-known architecture, deploy to traditional servers, and have a team that knows Spring Boot — stay with Spring Boot. If you are building microservices for Kubernetes, caring about startup time, memory budget, and iteration speed — Quarkus is worth the investment.

The migration from Spring Boot to Quarkus is not a rewrite. It is a translation. The concepts map one-to-one. The annotations change names. The configuration keys change prefixes. But the patterns — dependency injection, REST endpoints, JPA persistence, JWT security, Flyway migrations — are the same patterns you already use.

I built this project to learn, and I learned that Java frameworks are converging on common patterns faster than the community rhetoric suggests. The gap between Spring Boot and Quarkus is smaller than the gap between either framework and the previous generation of Java enterprise frameworks. We are all moving in the same direction.

The full source code is available at github.com/ykpraveen/quarkus-panache-sample.

Redis 8 in Practice: Building a Full-Stack Movie Library with Search, JSON, Time Series, and Real API Workloads

Praveen Yadav — Wed, 01 Jul 2026 09:53:21 +0000

I have used Redis in production for years. In a previous role, our stack used Redis 6 on Azure Cache for Redis with a Spring Boot backend and Jedis. It worked, but advanced capabilities often came with extra decisions around cost, packaging, and service tier selection.

Looking back, that tradeoff may also help explain some of the platform direction we are seeing now, including the move toward Azure Managed Redis and a clearer separation in positioning and capabilities.

If we wanted richer search behavior, that typically pushed us toward higher service tiers and additional operational planning. For side projects and experiments, that friction was enough to keep many ideas in the "maybe later" bucket.

That context is why this project exists.

Redis is often introduced as "just a cache," but that framing misses how far the platform has evolved. In this project, I treated Redis 8 as the primary operational data engine for a full-stack movie application: document storage, full-text search, aggregations, and time-series telemetry.

The result is a practical reference implementation, not a toy script. The app supports:

JSON-backed movie records
Full-text and faceted search
Numeric filtering and sorting
Aggregation dashboards
Time-series event tracking
CRUD workflows in a React UI

This article is deliberately verbose and implementation-heavy, but with a practical story arc: what was painful before, what changed in Redis 8, and what that change looks like in a real app.

If you want the full project, the sample repo is here: GitHub repository.

TL;DR

I used to treat Redis primarily as a fast key-value/cache layer in Redis 6 era workloads.
Redis 8 made it easier to approach Redis as a multi-model operational data backend.
I built a Movie Library app to test this directly with RediSearch, RedisJSON, and RedisTimeSeries.
The result: one Redis service powers CRUD, full-text search, analytics, and time-series event tracking.

Why This Was a Big Shift for Me

Coming from Redis 6 + managed cloud usage, I was used to a split between "simple Redis usage" and "advanced Redis usage." The second path usually meant more planning around feature availability, pricing, and platform choices.

For teams with budget and clear production requirements, that can be reasonable. For learning, prototyping, and internal tools, it can be a blocker.

With this project, I wanted to test whether Redis 8 reduced that friction enough to change day-to-day developer behavior.

In practice, the setup is intentionally simple: one Redis 8 container, one Node.js API container, and one React frontend container. If you want to inspect the exact Compose and Docker configuration, it is easier to browse it directly in the GitHub repository than to repeat it inline here.

No custom module loading is required in this setup. The backend starts, connects, creates a search index, and serves traffic. Operationally, that dramatically improves first-run experience for learning projects and demos, especially compared with the "figure out modules first, build app second" workflow many of us had before.

The Build: A Full-Stack Movie Library

This is a three-container architecture:

redis (port 6379)
backend Node.js + Express API (port 3001)
frontend React + Vite app (port 5173)

Backend stack details:

express for API routes
redis official node-redis client (^4.7.0)
zod for request/query validation
express-rate-limit for traffic throttling
morgan for request logging

Frontend stack details:

React 19
React Router 7
Redux Toolkit
Recharts for charts
Tailwind CSS + shadcn/ui components

RedisJSON, CRUD, and Search UX

I started with the baseline product loop every app needs: create, read, update, delete, then make discovery pleasant with search and filters.

One early lesson: my first search experience felt "technically correct" but practically flat. Results came back, but relevance was not great for title-heavy queries. Giving title a higher search weight immediately improved that, and it reminded me that search quality is mostly about thoughtful schema and scoring choices, not just endpoint wiring.

Data Model: RedisJSON as the Source of Truth

Each movie is stored as a JSON document at key pattern movie:{id} using RedisJSON. A typical record includes core metadata such as title, plot, genres, year, rating, votes, cast, director, runtime, language, poster, and tags. The exact seed data and JSON shape are available in the GitHub repository.

The backend seed process loads real movie records from movies.json, then generates synthetic titles, plots, cast lists, and metadata until the dataset reaches 500 movies. That larger cardinality makes filtering, sorting, and aggregation behavior more visible than a tiny static set, which is important if you want search and dashboard behavior to feel believable.

Search Design: How It Actually Works

On startup, the API creates RediSearch index idx:movies over JSON documents with prefix movie:.

Field mapping used by the app:

$.title -> TEXT (WEIGHT 2)
$.plot -> TEXT
$.director -> TEXT
$.cast[*] -> TEXT
$.genres[*] -> TAG
$.tags[*] -> TAG
$.language -> TAG
$.year -> NUMERIC SORTABLE
$.rating -> NUMERIC SORTABLE
$.votes -> NUMERIC SORTABLE

Two practical implications:

Weighting title higher than plot improves relevance for title-driven queries.
Marking numeric fields sortable enables efficient server-side ordering for UX controls like "top rated" or "newest first".

I also found that getting sortable numeric fields right up front saved rework later. In earlier projects, I had deferred sorting strategy and paid for it with awkward API changes once product requirements became concrete.

API Surface and Behavior

Health and operational endpoints

GET /health pings Redis and returns service state.
Every non-health request increments ts:activity using RedisTimeSeries for global API throughput telemetry.

CRUD endpoints

POST /movies creates a record with generated tt... style ID.
GET /movies/:id fetches one movie.
PUT /movies/:id updates an existing movie (404 if absent).
DELETE /movies/:id deletes a movie (204 on success).

Validation is done with Zod. Example constraints include:

year must be integer between 1888 and 2030
rating must be between 0 and 10
votes must be non-negative integer
poster must be URL (or empty string)

Search endpoint

GET /movies/search supports combined full-text + structured filtering + pagination + sorting.

Supported query params:

q
genre
tag
language
yearFrom, yearTo
minRating, maxRating
sortBy (rating | year | votes)
sortOrder (ASC | DESC)
limit (1-100)
offset (>= 0)

A representative request would be a search for shawshank, filtered to the Drama genre, constrained to movies with rating >= 8, and sorted by rating descending.

The backend dynamically composes RediSearch syntax such as:

@genres:{Drama} for tag filtering
@rating:[8 +inf] for numeric thresholds
Combined query form (shawshank) @genres:{Drama} @rating:[8 +inf]

Input hardening detail: tag-like fields are escaped before interpolation to reduce query parser edge cases from punctuation.

Every successful search also increments ts:searches, which later powers trend charts.

The practical effect is that product behavior feeds analytics behavior automatically: users search, and you immediately gain a signal you can graph and monitor.

That "single action, dual value" pattern was one of my favorite outcomes in this build. In previous systems, I often had to bolt analytics on after core features shipped. Here, product events and telemetry evolved together.

Analytics with FT.AGGREGATE

The analytics endpoints push computation to Redis instead of pulling records into Node and reducing in application code.

This was the moment the architecture clicked for me. In older Redis usage patterns, I would usually pull records into the service and aggregate there. It works, but it adds code paths, memory overhead, and maintenance burden. Using server-side aggregation simplified both the implementation and the mental model.

Implemented operations include movie counts by genre, average rating by genre, and decade-based grouping derived from the release year. The exact query shapes are in the GitHub repository, but the important point here is that the aggregation work stays inside Redis instead of moving into application-side loops.

Exposed API routes:

GET /analytics/genres
GET /analytics/ratings
GET /analytics/decades
GET /analytics/top-rated

/analytics/top-rated uses FT.SEARCH with SORTBY rating DESC and LIMIT 0 10 to return top titles.

I kept this endpoint intentionally simple because "top rated" is one of those deceptively expensive features if you do it repeatedly in the application layer under load.

Time-Series Telemetry with RedisTimeSeries

The project tracks three classes of events:

Search volume (ts:searches)
API activity (ts:activity)
Per-movie views (ts:movie:views:{id})

Write examples in this app:

POST /movies/:id/view -> TS.ADD ts:movie:views:{id} * 1
Search requests -> TS.ADD ts:searches * 1
Non-health API requests -> TS.ADD ts:activity * 1

Read and downsample examples:

GET /movies/:id/views?bucket=3600000
GET /timeseries/searches?bucket=3600000
GET /timeseries/activity?bucket=86400000

All of these rely on TS.RANGE with AGGREGATION SUM and a configurable bucket size (default 3,600,000 ms, i.e. 1 hour).

If a series key does not yet exist, the API returns [] rather than a hard error, which simplifies frontend state handling.

This small API decision turned out to matter a lot in UI polish. Returning empty arrays lets charts render gracefully on first use and avoids noisy error states for a perfectly valid condition: "no data yet."

Reliability and Runtime Safeguards

This sample includes several practical safeguards that are easy to forget in demos:

Redis connection retry loop (15 retries, 2s delay)
Backend waits on Redis service health in Compose
Backend healthcheck probes GET /health
Rate limiting: 100 requests/minute per IP
CORS scoped to frontend origin

These are not enterprise-hardening substitutes, but they are meaningful defaults for local and staging environments.

I added the Redis retry loop after seeing the classic local race: API container starts milliseconds before Redis is ready, then fails fast. With retries in place, startup became boring in the best way.

Frontend Workflow and UX Model

The React app implements pages for:

Search and filter
Add movie
Edit movie
Movie detail
Analytics dashboard
Time-series dashboard

The search experience combines:

Text query
Faceted filtering (genre, tag, language)
Numeric ranges (year, rating)
Server-side sorting and pagination

State is managed with Redux Toolkit slices and async APIs per feature (movies, filters, analytics, timeseries).

In practice, this keeps query-building deterministic and enables consistent "URL-ish" state transitions between views.

Seed Strategy: Why the Data Looks Realistic Enough

The seed script does more than static insertion:

Starts from curated real movie examples
Expands to 500 documents with synthetic generation
Adds 30 days of search/activity signals
Adds per-movie view entries with probabilistic sparsity

This matters because aggregation and charting workflows are often misleading when driven by tiny uniform datasets.

Running the Project

You can run the project fully in Docker or split it into local frontend/backend development against Redis in Docker. Rather than duplicate the setup commands throughout the article, I would point readers to the GitHub repository for the latest start-up steps, project structure, and environment notes.

Default endpoints:

API: http://localhost:3001
Frontend: http://localhost:5173

What This Project Demonstrates Clearly

Redis can act as a multi-model operational backend in a single service boundary.
FT.SEARCH + FT.AGGREGATE cover a surprisingly wide analytics/search spectrum without a second database.
RedisTimeSeries reduces bespoke metrics plumbing for product-level event trends.
A Node.js + React team can adopt this incrementally: start with JSON storage, then add search, then aggregations, then telemetry.

Gaps and Next Steps

The sample is intentionally practical, but not production-complete. Major follow-ups would be:

Authentication/authorization
Integration and load tests
Cursor-based pagination for high offsets
Background jobs for denormalized materializations
Observability beyond logs (traces, structured metrics)
Optional vector similarity for recommendation UX

Final Takeaway

Redis 8 becomes most compelling when you evaluate it as a system-building platform rather than a key-value primitive. In this movie app, a single Redis deployment handles:

document persistence
search relevance and faceting
aggregation queries
time-series telemetry

with straightforward operational wiring in Docker and a conventional Node/React stack.

If you want a concrete way to learn Redis beyond cache tutorials, this architecture is a solid, extensible starting point.

If your own Redis history looks like mine (fast cache first, advanced features later), Redis 8 is worth a fresh look with a project that exercises multiple features end-to-end.

Personally, this project changed how I scope Redis in new designs. I still use it as a cache when that is the right fit, but I now consider it much earlier as an operational data layer when search, aggregations, and event trends are part of the product surface.

Repository

The full sample project is available here: https://github.com/ykpraveen/rediseach-sample.

If you publish updates, that repository is also the best place to keep the article in sync with the latest code, commands, and configuration.

Questions, issues, or ideas for extending the sample are welcome.

If you publish your own Redis 8 build, share it. I would love to compare approaches, especially around vector search, ranking strategies, and production hardening patterns.

Building Distributed Data Processing with Spring Batch 6 + Spring Boot 4

Praveen Yadav — Thu, 25 Jun 2026 11:37:27 +0000

When people first use Spring Batch, they usually start with a simple single-threaded job. That works for small datasets, but once data volume grows, throughput becomes the bottleneck.

In this sample project, I implemented a partitioned, multi-threaded Spring Batch pipeline to process sales records in parallel using a master/worker step model.

👉 Code repo: github.com/ykpraveen/spring-batch-sample

Spring Batch

At its core, Spring Batch is built around a few key abstractions:

Job: a complete batch workflow
Step: one phase of a job
ItemReader / ItemProcessor / ItemWriter: read-transform-write pipeline
Chunk processing: process N items in one transaction (chunkSize) ### Why chunking matters

In chunk-oriented steps, Spring Batch reads and processes items until the chunk size is reached, then writes and commits in one transaction.

So with chunk(500):

500 items are read/processed/written
one commit happens per chunk
failures can be retried at chunk boundaries

This gives a good balance between:

too-small chunks (high transaction overhead)
too-large chunks (long transactions, higher rollback cost)

How Spring Batch scales

Spring Batch offers multiple scaling patterns:

Multi-threaded Step: one step, concurrent chunk processing
Partitioning: split input domain into partitions, each handled by a worker step
Remote Chunking / Remote Partitioning: distribute work across processes/nodes

This project uses partitioning + thread pool execution (local distributed-style parallelism).

How this project applies those concepts

Repository: spring-batch-sample

The architecture is:

A master step creates partitions (data ranges)
A worker step executes each partition
A ThreadPoolTaskExecutor runs workers concurrently

Key classes (see src/main/java in repo):

BatchConfiguration → job/step orchestration
SalesDataPartitioner → partition boundary logic
SalesDataProcessor → business transformation logic

Code area: src/main/java

Performance tuning used here

The sample uses:

gridSize: 8 (number of partitions)
Thread pool: corePoolSize=4, maxPoolSize=8
chunk size: 500
Sample input: 5000 records

Interpretation

gridSize controls parallel work units.
Thread pool size controls actual concurrent execution.
Effective throughput depends on DB I/O, CPU, and item processing complexity.
Increasing partitions beyond available threads can still help load balancing, but with diminishing returns.

Database + metadata angle

Spring Batch is not just a processing framework; it is also a stateful execution framework.

It tracks job/step execution state in metadata, enabling:

restartability
execution history
failure diagnostics

In this sample, PostgreSQL stores both:

domain tables (sales_data, processed_data, processing_statistics)
batch execution context/metadata managed by Spring Batch

That combination is what makes batch jobs operationally reliable in real systems.

Run locally

1) Start PostgreSQL

docker compose up -d

2) Build and run the app

mvn clean install
mvn spring-boot:run

3) Trigger the batch job

curl -X POST http://localhost:8080/api/batch/start

4) Stop PostgreSQL

docker compose down

Why this pattern is useful in real projects

This design is a strong baseline for:

ETL and data migration
order/payment reconciliation
large-volume reporting prep
scheduled backend data shaping

You get:

clear separation of orchestration vs business logic
predictable transactional boundaries
scalable parallel execution
operational observability through batch metadata

Next extensions

If you want to evolve this sample toward production-grade scale:

Add retry/skip policies for fault tolerance.
Export job metrics (Micrometer + Prometheus/Grafana).
Make partition strategy adaptive to dataset size.
Move to remote partitioning for multi-node execution.

If you’re learning Spring Batch or designing high-throughput processing pipelines, this pattern is a solid starting point: simple enough to understand, realistic enough to extend.

Building an AI Chat Agent with MCP, Spring AI

Praveen Yadav — Wed, 24 Jun 2026 09:41:20 +0000

Model Context Protocol (MCP) is an open standard for connecting AI apps to tools and data sources. A useful way to think about it is as a USB-C port for AI: one standard interface that lets different models plug into different capabilities without custom glue code for every integration.

In this project, we combine MCP, Spring AI, and Google Gemini to build a chat app that can answer weather questions using real tools instead of hallucinating. The system has three parts:

MCP tool server - a Spring Boot service that exposes weather and geocoding tools
AI chat agent - a Spring Boot service that uses Spring AI + Gemini and calls MCP tools when needed
React chat UI - a lightweight frontend for sending messages and rendering replies

The result is a small but realistic architecture you can extend into a production assistant.

Architecture

User (Browser:3000)
    | POST /api/chat
    v
AI Agent (Spring:7171) -- MCP / Streamable HTTP --> MCP Server (Spring:7170)
    |                                               |
    | Google Gemini                                 | Bright Sky API (weather)
    |                                               | OpenStreetMap Nominatim (geocoding)
    v                                               v
Chat response                                    Tool execution

The full source code is available on GitHub.

1. The MCP Tool Server

The tool server is a Spring Boot application that exposes MCP tools through Spring AI's annotation scanner. It runs on port 7170 and uses Streamable HTTP for transport.

Dependencies

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-mcp-server-webmvc</artifactId>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>

Defining tools

With Spring AI, a tool is just a Spring bean method annotated with @McpTool:

@Component
public class WeatherTool {

    private final WeatherToolService weatherToolService;

    public WeatherTool(WeatherToolService weatherToolService) {
        this.weatherToolService = weatherToolService;
    }

    @McpTool(name = "get_current_weather",
             description = "Get current weather by dwd_station_id or by lat/lon")
    public Map<String, Object> getCurrentWeather(
            @McpToolParam(description = "DWD station ID", required = false)
            String dwd_station_id,
            @McpToolParam(description = "Latitude", required = false) Double lat,
            @McpToolParam(description = "Longitude", required = false) Double lon
    ) {
        return weatherToolService.getWeather(dwd_station_id, lat, lon);
    }
}

Spring turns that method into an MCP tool definition and publishes the parameter metadata as part of the schema. That means the model can discover the tool, understand its inputs, and decide when to call it.

The project also includes a geocoding tool that resolves city names to coordinates:

@McpTool(name = "geocode_city",
         description = "Convert a city name to latitude and longitude using OpenStreetMap Nominatim")
public Map<String, Object> geocodeCity(
        @McpToolParam(description = "City name (e.g., 'Berlin', 'New York')", required = true)
        String cityName
) { ... }

The service layer

The tools delegate the real work to services that handle validation, caching, and external API calls:

@Service
public class WeatherToolService {

    public Map<String, Object> getWeather(String dwdStationId, Double lat, Double lon) {
        // Validate the request
        // Check the cache
        // Call Bright Sky if needed
        // Return a structured response
    }
}

The key design choices are straightforward:

Separate TTL caches for station-id and coordinate lookups
Structured responses with success, error_code, and error_message
Cache metadata in each response so you can see whether the result came from cache or upstream

Server configuration

server:
  port: 7170

spring:
  ai:
    mcp:
      server:
        name: spring-sample-mcp-server
        version: 1.0.0
        protocol: STREAMABLE
        type: SYNC
        annotation-scanner:
          enabled: true

mcp:
  security:
    api-key: ${MCP_API_KEY:}

The STREAMABLE protocol gives the agent a lightweight MCP transport, and the shared API key keeps the demo simple without adding full auth infrastructure.

2. Security for the Demo

The MCP server and agent share an MCP_API_KEY. The agent adds it automatically as an X-API-Key header, and the server validates it on inbound MCP requests.

That is enough for local development and a sample project. For anything public-facing, move to Spring Security, OAuth2 or JWT, rate limiting, and a gateway in front of the MCP endpoint.

3. The AI Chat Agent

The agent is responsible for deciding when to use tools, calling Gemini, and keeping the conversation stateful.

Dependencies

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-model-google-genai</artifactId>
</dependency>
<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-mcp-client</artifactId>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>

MCP client configuration

The agent injects the shared API key through a custom HTTP request customizer:

@Configuration
public class AgentConfiguration {

    @Bean
    McpClientCustomizer<HttpClientStreamableHttpTransport.Builder>
    streamableHttpTransportCustomizer(AgentProperties properties) {
        McpSyncHttpClientRequestCustomizer requestCustomizer =
                (builder, method, uri, body, context) -> {
                    if (StringUtils.hasText(properties.getMcpApiKey())) {
                        builder.header("X-API-Key", properties.getMcpApiKey());
                    }
                };
        return (name, builder) -> builder.httpRequestCustomizer(requestCustomizer);
    }
}

Core chat flow

The agent keeps a small in-memory conversation history, checks whether the user message looks like a tool request, and then routes the prompt through either a plain Gemini client or a tool-enabled client.

public String reply(String sessionId, String userMessage) {
    List<ConversationTurn> history = memoryStore.history(sessionId);
    String prompt = buildPrompt(history, userMessage);
    boolean toolRequest = shouldUseTools(userMessage);
    ChatClient client = toolRequest ? toolEnabledClient() : plainChatClient;
    String answer = invokeModel(client, prompt);
    memoryStore.appendTurn(sessionId, userMessage, answer);
    return answer;
}

The lazy initialization is deliberate: the agent can start even if the MCP server is down, and it only initializes MCP clients when a tool request actually arrives.

The tool trigger is intentionally simple:

private static boolean shouldUseTools(String userMessage) {
    String normalized = userMessage.toLowerCase(Locale.ROOT);
    for (String keyword : TOOL_KEYWORDS) {
        if (normalized.contains(keyword)) {
            return true;
        }
    }
    return false;
}

That heuristic is enough for a demo and easy to explain. In a larger system, you could replace it with a router model or intent classifier.

Virtual threads and timeout handling

The model call runs on a virtual thread with a configurable timeout so the request does not hang forever if Gemini is slow or unreachable:

private String invokeModel(ChatClient client, String prompt) {
    var executor = Executors.newVirtualThreadPerTaskExecutor();
    try {
        var future = executor.submit(() ->
                client.prompt().user(prompt).call().content());
        return future.get(timeoutSeconds, TimeUnit.SECONDS);
    } catch (TimeoutException ex) {
        throw new ResponseStatusException(HttpStatus.GATEWAY_TIMEOUT, ...);
    } finally {
        executor.shutdownNow();
    }
}

Session memory

Conversation history lives in an in-memory LRU store with a small per-session turn window. That keeps follow-up questions like "What about tomorrow?" grounded in the earlier exchange without introducing a database too early.

The agent configuration sets the model to gemini-3.5-flash, the memory limit to 20 turns per session, and the session cap to 500.

4. The React Chat UI

The frontend is a Vite app with a simple chat window, minimal state, and no component library.

const [messages, setMessages] = useState([]);
const [loading, setLoading] = useState(false);

const sendMessage = async (text) => {
    setMessages(prev => [...prev, { role: 'user', content: text }]);
    setLoading(true);
    const response = await fetch('/api/chat', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ sessionId, message: text })
    });
    const data = await response.json();
    setMessages(prev => [...prev, {
        role: 'assistant',
        content: data.reply || 'No response'
    }]);
    setLoading(false);
};

The Vite dev server proxies /api/* to the agent:

proxy: {
  '/api': {
    target: 'http://localhost:7171',
    changeOrigin: true,
    rewrite: (path) => path.replace(/^\/api/, '')
  }
}

The UI is intentionally plain: a purple gradient, responsive layout, and a smooth message list are enough to make the app feel complete without distracting from the architecture.

5. Putting It All Together

Running the application

Set the environment variables:

export GEMINI_API_KEY=your_gemini_api_key
export MCP_API_KEY=a_shared_secret

Start the MCP server:

cd mcp-server-spring
mvn spring-boot:run

Start the agent:

cd mcp-spring-agent
mvn spring-boot:run

Start the UI:

cd mcp-ui
npm install
npm run dev

What happens when you ask a question

If the user asks, "What's the weather in Berlin?" the flow looks like this:

The agent sees the word "weather" and switches to tool-enabled mode
Gemini calls geocode_city("Berlin") to get coordinates
The agent calls get_current_weather(lat=52.52, lon=13.41)
Gemini turns the raw data into a readable response
The UI renders the answer

6. Why This Architecture Works

MCP separates the model from the tools. The agent knows what tools exist and how to call them, but not how those tools are implemented. That makes the system easier to evolve.

The same server can serve different models. Gemini is just the model in this demo. The MCP server itself can work with any compatible client.

Lazy initialization keeps the app resilient. The agent can boot even if the MCP server is temporarily unavailable, and tool support only activates when it is actually needed.

7. What's Next

This sample is a solid starting point. Natural next steps include:

Docker Compose - run all services together
PostgreSQL persistence - durable chat history and richer memory
OAuth2 - authenticated multi-user access
WebSocket streaming - token-by-token responses
Kubernetes - scale the agent and tool server independently

Resources

Have you built anything with MCP and Spring AI? I'd love to hear how you approached it.

Building an Order Processing Pipeline with Spring Integration (HTTP + File Polling)

Praveen Yadav — Wed, 24 Jun 2026 07:57:53 +0000

If you’ve used Spring Boot REST APIs but haven’t explored Spring Integration yet, this project is a practical way to see what message-driven flow design looks like in real code.

I built a sample app that processes orders from two different entry points:

HTTP API (POST /api/orders)
File polling (drop CSV files into input/)

Both inputs share the same core processing logic.

👉 Source code: https://github.com/ykpraveen/spring-integration-sample

What this project does

Each order goes through this pipeline:

Transform input payload into Order
Validate (id, customer, total)
Route by amount:
- total <= 100 → EXPRESS
- total > 100 → REVIEW
Persist order (JPA)
Fan out to:
- archive output file
- summary aggregation

Runtime persistence uses PostgreSQL, and tests use H2.

Tech stack

Java 21
Spring Boot 4.1
Spring Integration 7 (Java DSL)
Spring Data JPA
PostgreSQL (runtime)
H2 (test)
Maven

Architecture at a glance

1) HTTP flow

POST /api/orders sends raw JSON to a messaging gateway, then:

JsonToOrderTransformer
OrderValidationService
content-based router (EXPRESS / REVIEW)
OrderStore.put(...)
publish-subscribe to archive + summary + HTTP response message

2) File flow

The poller watches input/*.csv, then:

FileToStringTransformer
CsvToOrderTransformer
validation + routing + persistence
publish-subscribe to archive + summary

3) Error handling

HTTP errors return JSON via dedicated HTTP error handling.
File processing errors generate failure logs in output/failed/ and move bad source files to input/failed/.

Why Spring Integration here?

Using Spring Integration made these parts clean and explicit:

Routing rules are declarative.
Fan-out behavior is easy with publish-subscribe channels.
Retry advice can be attached per handler in the file pipeline.
The integration graph (/api/integration/graph) helps visualize the runtime flow.

Example requests

Submit an EXPRESS order

curl -X POST http://localhost:8080/api/orders \
  -H "Content-Type: application/json" \
  -d '{"id":"ORD-001","customer":"Alice","description":"Book","total":25.00}'

Submit a REVIEW order

curl -X POST http://localhost:8080/api/orders \
  -H "Content-Type: application/json" \
  -d '{"id":"ORD-002","customer":"Bob","description":"Laptop","total":1500.00}'

Get one order

curl http://localhost:8080/api/orders/ORD-001

List all orders

curl http://localhost:8080/api/orders

Running locally

Clone the repo first:

git clone https://github.com/ykpraveen/spring-integration-sample.git
cd spring-integration-sample

Then run:

docker compose up -d
mvn clean package
mvn spring-boot:run

Then test HTTP endpoints or drop a CSV file into input/.

Testing

The project currently has 38 tests (unit + integration), covering:

transformation and validation
HTTP happy paths and failure paths
duplicate order handling (409 Conflict)
file poller processing and retries
summary aggregation behavior via Spring Integration aggregator + writer service
integration graph endpoint

You can run these directly from the repo: https://github.com/ykpraveen/spring-integration-sample

Key implementation details I found useful

Use correlation IDs in headers and push them into MDC for traceable logs across flow steps.
Keep config split by concern (HttpIntegrationConfig, FileIntegrationConfig, shared config) instead of one huge integration config class.
Treat summary aggregation as stateful logic: clear release rules (batch size vs timeout), stable keys, and append-safe file writing.
Prefer explicit web path-variable lookup for GET /api/orders/{id} over indirect URL parsing.

Repo

You can clone the project and run it as a demo starter for:

Spring Integration basics
event/message-driven service design in Spring
hybrid ingestion patterns (HTTP + file)

If you’re learning Spring Integration, this pattern is a good stepping stone before Kafka/Rabbit-based distributed flows.

GitHub: https://github.com/ykpraveen/spring-integration-sample