DEV Community: Ayush Soni

Choose a database by access pattern, not by hype

Ayush Soni — Mon, 02 Nov 2026 09:25:05 +0000

Across ten years of backend work I've shipped production systems on MySQL, PostgreSQL, DynamoDB, MongoDB, Elasticsearch, Neo4j, Redis, Redshift and BigQuery. The rule I keep coming back to: write down the queries before you pick the database.

"We need something that scales" isn't a requirement. "Fetch an order by ID in under 10 ms at 5,000 requests per second", "find products similar to this one by shared attributes", "sum revenue by region for the last two years" — those are requirements, and each one points at a different kind of store.

Start with an access-pattern list

Before choosing, list for each entity:

Question	Example answer
How is it looked up?	By `orderId`; by `customerId` + date range
What filters and sorts?	Status, created date, newest first
Read/write ratio and peak rate	20:1, 3,000 reads/s at peak
Consistency needs	Read-your-own-writes for the owner
Relationships	Order → items → products
Analytics	Daily revenue by category, two years of history

Ten minutes on this table saves months of fighting the wrong store.

The main families, by the query they're good at

Relational (PostgreSQL, MySQL) — the default. Joins, transactions, constraints, flexible queries you didn't predict. Most systems should start here and leave only when a specific access pattern demands it.

SELECT o.id, o.total, c.email
FROM   orders o JOIN customers c ON c.id = o.customer_id
WHERE  o.status = 'PAID' AND o.created_at > now() - interval '7 days';

Key-value / wide-column (DynamoDB, Cassandra) — known patterns at huge scale. Predictable single-digit-millisecond lookups by key, practically unlimited throughput, and you must design keys around your queries up front. Ad-hoc queries are expensive or impossible.

GetItem   PK = "TENANT#acme"   SK = "PROFILE"
Query     PK = "TENANT#acme"   SK begins_with "EVENT#2026-10"

Document (MongoDB) — aggregates read and written whole. Good when an entity is naturally a nested document (a product with variable attributes, a form submission) and you mostly load it by ID.

Search (Elasticsearch, OpenSearch) — text, filters, ranking. Full-text relevance, faceted filters, fuzzy matching, aggregations for filter counts. Treat it as a derived index, fed from your source of truth, not as the source of truth itself.

{ "query": { "bool": {
    "must":   { "match": { "name": "oak dining table" } },
    "filter": [ { "term": { "in_stock": true } }, { "range": { "price": { "lte": 40000 } } } ]
}}}

Graph (Neo4j) — relationships several hops deep. "Which products share categories and attributes with this one?", "what depends on this feature?". In SQL these become recursive joins; in a graph database they're a short pattern. I've used it for product recommendations and for ML metadata lineage.

MATCH (p:Product {id: $id})-[:HAS_ATTRIBUTE|IN_CATEGORY]->(x)<-[:HAS_ATTRIBUTE|IN_CATEGORY]-(other:Product)
WHERE other <> p
RETURN other.id, count(x) AS shared
ORDER BY shared DESC LIMIT 10;

Cache (Redis) — hot reads, counters, short-lived state. Sessions, rate limits, leaderboards, cached responses. Plan for it being empty after a restart.

Warehouse (BigQuery, Redshift, Snowflake) — scans over history. Columnar storage that makes "sum revenue by month and category over two years" cheap. Not for serving user requests.

SELECT DATE_TRUNC(order_date, MONTH) AS month, category, SUM(total) AS revenue
FROM   analytics.orders
WHERE  order_date >= DATE_SUB(CURRENT_DATE(), INTERVAL 2 YEAR)
GROUP  BY month, category;

When you need two (or three)

Real systems often combine stores: Postgres for orders, Elasticsearch for product search, a warehouse for reporting. That's fine — if you decide three things explicitly:

Which store is the source of truth for each piece of data. Everything else is derived and can be rebuilt.
How derived stores are fed: events, change data capture, or batch loads — and how stale they may be. Search results a few seconds behind are usually fine; a balance a few seconds behind usually isn't.
How you rebuild a derived store from scratch. If you can't re-index search from the source of truth, it has quietly become a second source of truth.

The anti-pattern is the one in the picture at the end of this post: each new feature adds a store because it's fashionable, with no answer to those three questions.

A quick decision guide

If your dominant query is…	Start with
Transactions, joins, flexible filters	PostgreSQL / MySQL
Lookups by key at very high, predictable scale	DynamoDB / Cassandra
Whole nested documents by ID	MongoDB (or JSONB in Postgres)
Full-text search, facets, ranking	Elasticsearch / OpenSearch, fed from the source of truth
Multi-hop relationships	Neo4j
Aggregations over large history	BigQuery / Redshift / Snowflake
Hot reads, counters, ephemeral state	Redis

Takeaways

Write the access-pattern list before choosing a database.
Start relational; move a workload out when a specific query demands it.
Search indexes and caches are derived — feed them from the source of truth and be able to rebuild them.
When you use several stores, name the source of truth for every piece of data.

Originally published at ayushwing.com.

Durable workflows vs. a queue and a cron job

Ayush Soni — Sun, 01 Nov 2026 07:25:02 +0000

Some work doesn't fit in a request. Moving a customer's data to new infrastructure. Onboarding a merchant across five systems. Generating, approving and sending a large batch of documents. These jobs have many steps, take minutes to days, call systems that fail, and must survive deploys and crashes.

Most teams start the same way: a queue, a cron job and a status column.

What queue + cron becomes

Version one is clean: a job row with status = PENDING, a worker that picks it up, does the work, sets DONE. Then reality adds requirements, one at a time:

A step fails transiently → add a retries column and a RETRYING status.
A worker dies mid-job → add locked_by and locked_at, and a cron that releases stale locks.
Step 4 must not run twice → add per-step status columns.
A step needs to wait for a human approval or a 24-hour cool-down → add resume_after and another cron.
Step 6 fails permanently after steps 1–5 succeeded → write undo logic, scattered across the codebase.
Nobody can tell where a job is → build an admin page that reads all these columns.

Each addition is reasonable. Together they're a workflow engine — one with no tests for its failure paths, state spread across columns, and behaviour that only one engineer fully understands. (The picture at the end of this post is only slightly exaggerated.)

What a durable workflow engine gives you

A durable workflow engine — Temporal is the one I've used; Cadence, AWS Step Functions and others share the idea — lets you write the process as ordinary code while the engine persists every step's progress:

@WorkflowInterface
public interface DataMoveWorkflow {
    @WorkflowMethod
    void move(String accountId);
}

public class DataMoveWorkflowImpl implements DataMoveWorkflow {

    private final MoveActivities act = Workflow.newActivityStub(MoveActivities.class,
            ActivityOptions.newBuilder()
                    .setStartToCloseTimeout(Duration.ofMinutes(30))
                    .setRetryOptions(RetryOptions.newBuilder()
                            .setInitialInterval(Duration.ofSeconds(5))
                            .setBackoffCoefficient(2.0)
                            .setMaximumAttempts(5)
                            .build())
                    .build());

    @Override
    public void move(String accountId) {
        Saga saga = new Saga(new Saga.Options.Builder().build());
        try {
            act.preflightChecks(accountId);

            String target = act.provisionTarget(accountId);
            saga.addCompensation(act::releaseTarget, target);

            act.copySnapshot(accountId, target);
            act.syncChanges(accountId, target);       // catch up writes made during the copy
            act.verifyChecksums(accountId, target);

            act.switchTraffic(accountId, target);
            saga.addCompensation(act::switchTrafficBack, accountId);

            Workflow.sleep(Duration.ofHours(24));     // soak period; costs nothing while waiting
            act.decommissionSource(accountId);
        } catch (ActivityFailure e) {
            saga.compensate();                        // undo completed steps in reverse order
            throw e;
        }
    }
}

What the engine handles for you:

Durability. Each completed activity is recorded. If the worker crashes after copySnapshot, a new worker replays the history and continues at syncChanges — it doesn't copy again.
Retries and timeouts per step, as configuration rather than columns.
Long waits. Workflow.sleep(Duration.ofHours(24)) holds no thread and no lock; the engine wakes the workflow when the timer fires. The same goes for waiting on a signal, such as a human approval.
Compensation. The Saga helper records how to undo each step and runs the compensations in reverse if a later step fails.
Visibility. Every workflow's current step, history and inputs are queryable — the admin page you'd otherwise build.

Steps run forward; compensations run backward. Explore the interactive diagram

The price: determinism

Workflow code is replayed to rebuild state after a crash, so it must make the same decisions every time it runs with the same history. In practice:

No Thread.sleep, System.currentTimeMillis(), UUID.randomUUID() or Random in workflow code — use Workflow.sleep, Workflow.currentTimeMillis(), Workflow.randomUUID().
No I/O in workflow code. Database calls, HTTP calls and file access go in activities.
Changing a running workflow's logic needs versioning (Workflow.getVersion), because in-flight workflows replay against the old history.

Activities, on the other hand, are normal code — and because they're retried, they must be idempotent (see Idempotency keys).

These rules take a week to internalise. They also force a clean separation between "what happens in what order" (workflow) and "how each step talks to the world" (activities), which tends to make the code easier to read.

When it's worth it — and when it isn't

Situation	Queue + worker	Durable workflow
One step, idempotent, seconds long	✅ Simple and enough	Overkill
2–3 steps, no waits, rare failures	✅ Usually fine	Optional
Many steps, external systems, partial failure needs undo	Grows into a hand-built engine	✅
Waits of hours or days, human approvals	Crons and `resume_after` columns	✅ Timers and signals
You must answer "where exactly is job X?"	Build an admin page	✅ Built in

The real cost is operational: you run (or pay for) the engine's cluster and learn its model. For one small job, that cost dominates. For a platform that runs long, multi-step processes every day — migrations, onboarding, provisioning — it pays for itself quickly, because every new process gets retries, timers, visibility and compensation for free.

Takeaways

A queue + cron + status table grows into a workflow engine; decide early whether to build one or adopt one.
Durable workflows give resumability, per-step retries, cheap long waits, compensation and visibility.
The price is determinism in workflow code and idempotency in activities.
Use it for long, multi-step, failure-prone processes; keep simple jobs simple.

Originally published at ayushwing.com.

Idempotency keys: making retries safe for money

Ayush Soni — Sat, 31 Oct 2026 16:31:17 +0000

A request that times out may still have succeeded. That single fact is why wallet and refund systems — I've built both — have to be designed around retries from day one.

Here is the sequence. A client calls POST /refunds. The server debits the merchant, credits the customer, commits — and then the response is lost: a load balancer timeout, a pod restart, a mobile network drop. The client sees an error and does the reasonable thing: it retries. The server, seeing what looks like a new request, refunds again.

Retries are not the bug. Retries are essential; networks fail all the time. The bug is an API that can't tell a retry from a new request.

The pattern

An idempotency key is a unique value the client generates once per operation — not per HTTP attempt — and sends with every attempt:

POST /refunds
Idempotency-Key: 6f1c2a9e-7d3b-4f0a-9a51-2c8e0b7d4e11
Content-Type: application/json

{"orderId": "A-1042", "amount": 1499}

The server promises: for a given key, the operation happens at most once, and every attempt gets the same response. Stripe popularised this design for its public API, and it applies to any endpoint that moves money, sends a message or creates something a user would notice twice.

Reserve first, work second, replay on retry. Explore the interactive diagram

The table

CREATE TABLE idempotency_keys (
    key            TEXT        NOT NULL,
    client_id      TEXT        NOT NULL,
    request_hash   TEXT        NOT NULL,          -- SHA-256 of method + path + body
    status         TEXT        NOT NULL,          -- IN_PROGRESS | COMPLETED
    response_code  INT,
    response_body  JSONB,
    created_at     TIMESTAMPTZ NOT NULL DEFAULT now(),
    PRIMARY KEY (client_id, key)
);

Scope keys per client: two different clients may well generate the same string, and that must not leak one client's response to the other.

The flow, with the edge cases

@PostMapping("/refunds")
public ResponseEntity<RefundResponse> refund(@RequestHeader("Idempotency-Key") String key,
                                             @RequestBody RefundRequest req,
                                             Principal client) {
    String hash = sha256(req);

    // 1. Reserve the key BEFORE doing any work. The primary key makes this atomic.
    int inserted = jdbc.update("""
        INSERT INTO idempotency_keys (key, client_id, request_hash, status)
        VALUES (?, ?, ?, 'IN_PROGRESS')
        ON CONFLICT (client_id, key) DO NOTHING
        """, key, client.getName(), hash);

    if (inserted == 0) {
        StoredKey existing = keys.find(client.getName(), key);
        if (!existing.requestHash().equals(hash)) {
            return ResponseEntity.unprocessableEntity().build();   // same key, different body
        }
        if (existing.status() == Status.IN_PROGRESS) {
            return ResponseEntity.status(409).build();              // concurrent retry: try again later
        }
        return existing.toResponse();                               // replay the stored result
    }

    // 2. Do the work and record the result in ONE transaction.
    return tx.execute(status -> {
        RefundResponse result = refunds.issue(req);
        keys.complete(client.getName(), key, 201, result);
        return ResponseEntity.status(201).body(result);
    });
}

Each branch exists because of a real failure mode:

Reserve before you work. If you check for the key, do the refund, and only then insert the key, two retries arriving 5 ms apart both pass the check. The INSERT ... ON CONFLICT DO NOTHING against the primary key is the lock: exactly one attempt wins the reservation.

Same key, different body. A client bug that reuses a key for a different refund must not get the first refund's response — that would silently hide the second operation. Hash the request and reject mismatches with a 422.

In progress. A retry that arrives while the first attempt is still running gets a 409. The client backs off and retries; by then the first attempt has finished and the retry gets the stored response.

Work and result commit together. If the refund commits but storing the response doesn't, the next retry finds an IN_PROGRESS row forever. Keep the business write and the key update in the same database transaction.

When the work isn't in your database

The single-transaction trick only works when the side effect lives in the same database as the key table. When step 2 calls an external payment provider, you can't roll that back. Two things help:

Pass the key downstream. Most payment providers accept their own idempotency key. Derive it from yours (for example refund:{clientId}:{key}), so a retry after a crash asks the provider for the same operation instead of a new one.
Recover stuck rows. A process can die between the provider call and the commit. A sweeper that finds rows stuck IN_PROGRESS for longer than your longest timeout can query the provider by the derived key and complete or release the row.

How long to keep keys

Keep keys at least as long as any client will retry, plus a margin. Stripe keeps them for 24 hours; for internal services where queues can redeliver messages days later, I'd lean longer. Delete old rows with a scheduled job — not inside the request path.

Where else this applies

The same idea shows up whenever "at least once" delivery meets "exactly once" side effects:

Queue consumers. Kafka and SQS redeliver. Use the message ID (or a business ID) as the key and record it in the same transaction as the effect.
Webhooks. Providers retry webhooks; store the event ID before acting on it.
Scheduled jobs. A job that runs twice after a deploy should find its own key and stop.

Takeaways

Retries are necessary; duplicate side effects are optional.
The key belongs to the operation, generated by the client once and reused on every attempt.
Reserve the key atomically before the work, store the response with the work, and replay it on retry.
Reject a reused key with a different body, and pass keys to every downstream system that moves money.

Originally published at ayushwing.com.

Same AI, two developers: why the experienced one spends fewer tokens

Ayush Soni — Fri, 30 Oct 2026 03:36:05 +0000

Everyone is building apps with AI now. My cousin built one. Your manager built one. Somebody built one during a meeting about whether we should build one.

That's genuinely great. But it raises a fair question: if a first-time builder and an engineer with ten years of experience use the same model with the same prompt, what's actually different?

Let's run the experiment in our heads. Two developers, same AI, same request:

"Build me a task-tracker app with user login."

Meet Nia, the native AI builder: smart, fast, has never shipped software before. And Sam, the seasoned engineer, who has broken production enough times to be careful.

Day 1: no difference at all

Both get a working demo in an afternoon. Login page, task list, a nice dark theme, a little confetti when you finish a task. Both post a screenshot. Both get 40 likes.

If you only look at day 1, experience doesn't matter. This is the part of the story everyone's excited about, and they're right to be. The AI did in an afternoon what used to take a week.

The difference shows up later, the way it always does in software: in the second month, when you change things.

Where the tokens go

Here's Nia's day 3. A user reports that tasks sometimes disappear.

Nia:  tasks disappear sometimes, fix it
AI:   (rewrites the storage layer)
Nia:  now login is broken
AI:   (rewrites the auth flow)
Nia:  login works but tasks still disappear
AI:   (adds a retry, a cache, and a second database "for reliability")
Nia:  it's slower now and still broken. FIX IT PROPERLY
AI:   (apologises, rewrites the storage layer again)

Every one of those messages drags the whole conversation and a growing chunk of the codebase into context again. Every fix touches more files than the bug lives in. After a week the app works most of the time, nobody knows why, and the token bill looks like a phone number.

Sam's day 3, same bug:

Sam:  Read CLAUDE.md. Tasks occasionally disappear after editing.
      Don't change code yet: find where tasks are written and list
      the ways two writes could race.
AI:   Two tabs saving the same task: last write wins, no version check.
Sam:  Write a failing test that reproduces it with two concurrent saves.
AI:   (test fails, as expected)
Sam:  Fix it with a version column and a conditional update. Keep the diff small.
AI:   (12-line change, test passes)
Sam:  (reads the diff, commits)

Four messages. One small diff. A test that will catch the bug if it ever comes back. Sam spent fewer tokens than Nia, not more. Experience didn't make Sam write better prompts in some magic way. It made Sam ask for smaller, checkable steps.

(If that bug looks familiar, it's the same race I wrote about in Model business workflows as state machines. AI doesn't remove these problems. It just reaches them faster.)

Same model, two loops. Only one of them ends. Explore the interactive diagram

The side-by-side

	Nia (first-time builder)	Sam (experienced engineer)
First prompt	"Build the whole app"	"Plan the app; don't write code yet"
Size of each request	A feature, or "fix everything"	One change you can review in two minutes
Context	Re-explains the project every session	A project instructions file the AI reads every time
Definition of done	"It looks like it works"	A test passes, and the diff makes sense
When it breaks	"Fix it" (again)	"Explain why before changing anything"
Tools	Pastes logs and docs into the chat	Gives the AI tools: skills, plugins, MCP servers
Dependencies	Whatever the AI suggested	Asks why each one is needed
Secrets	API key in the code, "temporarily"	Environment variables from the start
Git	One giant commit called "final"	A commit after every green step
Day 30	Afraid to touch it	Adds features on a Friday

None of Sam's column is about AI. It's just engineering: small steps, tests, version control, knowing what "done" means. AI is a multiplier, and it multiplies whatever habits you bring.

What makes AI-written code sustainable

"Sustainable" is a fancy word for one question: can someone change this code next month without breaking it? "Someone" includes you, and it includes the AI.

Four things decide the answer:

Tests that describe behaviour. A test suite is the only spec the AI can't misread. With tests, "refactor this" is safe. Without them, every change is a gamble the AI makes with confidence.
Small, readable diffs. If you can't explain a change in a sentence, you can't review it, and unreviewed code is how plausible-but-wrong bugs ship. My favourite: a refund endpoint that retries on timeout and pays twice. It looks perfectly correct in a diff (here's how to prevent it).
Written-down decisions. A project instructions file (CLAUDE.md, AGENTS.md, .cursorrules, whatever your tool reads) that says: how to run the tests, what the architecture is, what not to touch. The AI stops rediscovering your codebase every session, and that's most of the token savings right there.
Boring choices. One database, not five. A library everyone knows, not the one the AI half-remembers. AI is very good at writing glue for popular tools and very bad at debugging an obscure one.

Skills, plugins and tools: stop pasting, start equipping

The biggest token sink I see is pasting: the same error log, the same docs page, the same "here's how our project works" paragraph, over and over.

Experienced developers give the AI tools instead:

Skills and plugins package a repeatable way of doing something, such as a review checklist, a deploy process or an audit, so you don't explain it every time.
MCP servers let the AI read your tickets, query a staging database or check a deploy itself, instead of you copying the output in. (I built one for Java services for exactly this reason.)
Your own scripts: a test command, a screenshot script, a linter. The AI can run them and check its own work.

A real example: this site. While building it with an AI assistant:

Archify drew the diagrams, with its own validation checks, instead of the AI hand-placing boxes.
An SEO audit skill (claude-seo) ran its checklist against the built site and found a real bug: robots.txt pointed at a sitemap that no longer existed.
Every visual change was screenshotted in a headless browser before it shipped, which caught a meme overflowing on phones and a diagram that rendered as a broken image.
And the homepage stack section went through two designs I didn't like. Before the third attempt, I was asked to pick a concept from four sketches. That one stuck.

That last one isn't a tool at all. It's the oldest engineering habit there is: agree on what you're building before you build it. It turns out it works on AI too.

Signs you're vibe coding

Score yourself honestly. One point each:

[ ] Your most-used prompt is "fix it".
[ ] You've said "PLEASE" to a compiler in capital letters.
[ ] Your app has 3 state-management libraries and you know the name of one.
[ ] There is a file called utils2_final_REAL.ts.
[ ] Your git history is one commit: "init".
[ ] You don't know what happens if two users click Save at the same time.
[ ] The AI added a cache "for performance" and you were too scared to ask why.
[ ] Your API key is in the frontend, but "only for now".

0–2: you're Sam. 3–5: you're on the way. 6–8: you're Nia, and that's fine. Every Sam started as a Nia. The good news is that every habit in Sam's column can be learned, and the AI will happily help you learn it if you ask it to explain instead of just fix.

The playbook

If you want to work like Sam starting tomorrow, here's the whole thing:

Plan before code. Ask for a plan and push back on it before any code exists.
Write a project instructions file on day 1: how to run, how to test, the rules.
One change per request, small enough to review in two minutes.
Test first for anything that matters: write the failing test, then the fix.
Read every diff. If you don't understand it, ask "why" before you accept it.
Commit after every green step, so you can always go back.
Equip, don't paste: skills, plugins, MCP servers and scripts the AI can run.
When stuck, ask for a diagnosis, not a fix. "Explain why this fails" costs less than five rewrites.

Takeaways

On day 1, AI makes everyone equal. By day 30, habits make the difference.
Experienced developers often spend fewer tokens, because small steps, tests and saved context beat "fix it" loops.
Sustainable AI-written code has tests, small diffs, written decisions and boring choices.
Give the AI tools, not copy-paste.
Experience isn't about typing faster anymore. It's about knowing what to ask for, and knowing when the answer is wrong.

Originally published at ayushwing.com.

Ten years of building: the patterns that keep repeating

Ayush Soni — Thu, 29 Oct 2026 14:14:11 +0000

I started my career in 2015 building REST APIs for an SMB commerce platform: orders, inventory, billing, purchase orders. Since then I've worked on checkout, wallet and refund services at an e-commerce marketplace, an email platform sending around 20 million personalized emails a day at a travel company, a feature-store platform at an AI startup, and large-scale cloud infrastructure.

Different domains, different stacks. The same lessons kept coming back. This post collects them, and links to everything I've written about each.

Change running systems one reversible step at a time

Splitting monoliths, moving data between systems, upgrading platforms underneath live traffic: the approach that works is a series of small, reversible steps. Doing it in one go is where these projects get into trouble.

Assume the network will lie to you

Distributed systems fail partially: a request times out after it succeeded, a message arrives twice, a dependency slows down instead of failing. Designing for that up front is far cheaper than discovering it in production.

The non-code half of senior engineering

The further I've gone, the more of my impact has come from things other than code: how incidents are handled, how decisions get made and recorded, which debt gets paid, and whether my team is a queue or a platform.

Built in the open

Most production work lives behind NDAs, so I try ideas out in public projects too:

What I'd tell my 2015 self

Read the old code before you judge it. Most "weird" code encodes a lesson someone learned the hard way. Find out which one before deleting it.
Learn the database properly. Indexes, transactions, isolation levels, locking. A surprising number of scaling problems turn out to be data problems.
Make failure boring. Timeouts, retries, idempotency, rollbacks. The systems that are calm during incidents are the ones designed around failure from the start.
Measure before and after. "It's faster now" convinces nobody; "p99 went from 1.2 s to 300 ms" convinces everyone.
Automate what you repeat — and then hand the automation to others. The biggest jumps in team capacity I've seen came from turning expert-only tasks into safe self-serve tools.
Write it down. Design docs, decision records, runbooks, and now this blog. Writing is how one engineer's judgment scales to a team.

If you're working on similar problems — distributed systems, platform engineering, AI infrastructure — I'd like to hear from you: email me or find me on LinkedIn.

Originally published at ayushwing.com.

GraphQL Federation with Java subgraphs, without the N+1

Ayush Soni — Wed, 28 Oct 2026 06:29:12 +0000

When I worked on GraphQL APIs that sat in front of several backend services, the hard part was never the query language. It was the joins: one screen needs a product from one service, its reviews from another and each reviewer's name from a third. Do that in a single GraphQL server and you get a "god schema" that every team must change. Do it naively across services and you get a storm of small requests.

Apollo Federation is one answer: each team owns a subgraph for its own types, and a router composes them into one supergraph. I built graphql-federation-playground to understand the patterns you hit in production, with Java subgraphs instead of the usual Node examples.

The setup

Service	Port	Owns	Extends
`user-subgraph`	8081	`User`	—
`product-subgraph`	8082	`Product`	`User` with `products`
`review-subgraph`	8083	`Review`	`Product` with `reviews`, `averageRating`, `reviewCount`; `User` with `reviews`
Apollo Router	4000	the supergraph	—

Each subgraph is a Spring Boot 3 app using the Netflix DGS framework. A single docker compose up boots all three, the router and Jaeger.

The router plans the query; each subgraph resolves only the fields it owns. Explore the interactive diagram

Entities: a type with a key

The idea that makes federation work is the entity: a type that several subgraphs can contribute fields to, identified by a key. The review subgraph doesn't own Product, but it can add fields to it:

type Product @key(fields: "id") @extends {
    id: ID! @external
    reviews: [Review!]!
    averageRating: Float
    reviewCount: Int!
}

When a client asks for a product's name and its reviews, the router first fetches the product from the product subgraph, then sends the review subgraph an _entities query containing just { __typename: "Product", id: "p1" }. The review subgraph turns that key into an object and resolves the fields it owns:

@DgsEntityFetcher(name = "Product")
public Product fetchProductEntity(Map<String, Object> values) {
    return new Product((String) values.get("id"));
}

The reverse direction is equally small. A Review stores only an authorId, so the review subgraph returns a reference and lets the router fetch the rest from the user subgraph:

@DgsData(parentType = "Review", field = "author")
public Map<String, Object> author(DataFetchingEnvironment env) {
    Review review = env.getSource();
    return Map.of("__typename", "User", "id", review.getAuthorId());
}

No service calls another service directly. Ownership stays clean: the user team can change how users are stored without the review team noticing.

The N+1 problem, multiplied

Here's the catch. Ask for 50 products with their reviews and the router sends one _entities request with 50 product keys. If Product.reviews runs a repository query per product, that's 50 queries for one request — and in federation the pattern repeats at every hop.

The fix is a DataLoader: resolvers ask for a key, the loader collects every key requested in the same execution tick, and fetches them in one batch.

@DgsDataLoader(name = "reviewsByProduct")
public class ReviewsByProductDataLoader implements BatchLoader<String, List<Review>> {

    @Override
    public CompletionStage<List<List<Review>>> load(List<String> productIds) {
        return CompletableFuture.supplyAsync(() -> {
            Map<String, List<Review>> byProduct =
                    reviewRepository.findByProductIds(Set.copyOf(productIds));
            // results must come back in the same order as the keys
            return productIds.stream()
                    .map(id -> byProduct.getOrDefault(id, List.of()))
                    .toList();
        }, executor);
    }
}

The resolver then becomes a one-liner returning a future:

@DgsData(parentType = "Product", field = "reviews")
public CompletableFuture<List<Review>> productReviews(DataFetchingEnvironment env) {
    Product product = env.getSource();
    return env.<String, List<Review>>getDataLoader("reviewsByProduct").load(product.id());
}

Two details worth calling out: the batch function must return results in key order (a missing product gets an empty list, not a gap), and keys are de-duplicated before they hit the repository.

Measure every resolver

I added a ResolverTimingInstrumentation to each subgraph. It extends graphql-java's SimplePerformantInstrumentation, times every field fetch, records a Micrometer timer graphql.resolver.duration tagged with parent type, field and status, and logs anything slower than a threshold (observability.graphql.slow-threshold-ms, default 50 ms) at WARN.

That is how I found the N+1 that's still in the code — and I've left it there as the example for this post.

The N+1 I didn't fix (yet)

Look at averageRating and reviewCount:

@DgsData(parentType = "Product", field = "averageRating")
public Double averageRating(DataFetchingEnvironment env) {
    Product product = env.getSource();
    List<Review> reviews = reviewRepository.findByProductId(product.id());
    ...
}

Both call the repository per product. Request reviews, averageRating and reviewCount for 50 products and you get one batched query plus 100 individual ones. The timing logs show it immediately: the batched field takes one slow-ish call, the other two fields take many fast ones that add up.

The fix is to derive both from the same DataLoader — load the reviews once per product and compute the average and count from the cached list. DataLoaders cache per request, so the second and third field reuse the first fetch for free.

What I'd do differently in production

Bound the DataLoader thread pool. The playground uses Executors.newCachedThreadPool(), which grows without limit under load. Use a fixed pool sized to your database connection pool.
Add query cost limits at the router. Federation makes deep queries cheap to write and expensive to run. Depth and cost limits belong at the edge.
Treat the supergraph schema as a contract. Run schema composition checks in CI for every subgraph change, so a breaking change fails a build instead of the router.

Takeaways

Federation is about ownership: each team owns its types and contributes fields to shared entities by key.
Every field that crosses an entity boundary needs a DataLoader, or your API slows down as lists grow.
Per-resolver timing turns "the API feels slow" into a specific field name.

The full playground — three subgraphs, router config, subscriptions and tests — is on GitHub.

Originally published at ayushwing.com.

Building an annotation-driven MCP server in Java

Ayush Soni — Tue, 27 Oct 2026 11:45:16 +0000

Exposing a Java method to an AI agent should take one annotation. When I started using MCP servers daily with Claude Code and Cursor, I noticed that almost every example was written in Python or TypeScript — while most of the systems I'd want an agent to call are Spring Boot services.

So I wrote java-mcp-server: a small toolkit where this is the whole integration:

@Component
public class MyTools {

    @McpTool(name = "greet", description = "Say hello to someone")
    public String greet(@McpParam(value = "name", description = "Person's name") String name) {
        return "Hello, " + name + "!";
    }

    @McpResource(uri = "config://app/{key}", description = "Read a config value")
    public String config(@McpParam("key") String key) {
        return System.getProperty(key, "(not set)");
    }
}

Start the app, and any MCP client can list and call greet and read config://app/java.version. This post covers how it works, the decisions behind it, and the parts I'd change.

MCP in one paragraph

The Model Context Protocol is a JSON-RPC 2.0 protocol between an AI client (Claude Desktop, Claude Code, Cursor) and a server that offers tools (functions the model may call), resources (read-only data addressed by URI) and prompts. A session starts with initialize, the client asks tools/list, and when the model decides to use a tool the client sends tools/call with a name and JSON arguments. That's the core loop — and it maps almost one-to-one onto "find a method, describe it, invoke it".

The shape of the toolkit

I split the project into four Maven modules, and the split turned out to be the most useful decision in the project:

Module	What it holds	Depends on Spring?
`mcp-core`	Annotations (`@McpTool`, `@McpResource`, `@McpParam`) and the JSON-RPC / tool models	No
`mcp-server-spring-boot`	Auto-configuration, bean scanning, the `/mcp` HTTP endpoint	Yes
`mcp-server-stdio`	Newline-delimited JSON-RPC over stdin/stdout, for Claude Desktop	No
`mcp-server-sample`	A runnable app with system-info and math tools	Yes

Keeping mcp-core free of Spring meant the stdio transport — which Claude Desktop uses when it launches a server as a child process — was a small module on top of the same models, not a second implementation.

One endpoint, two registries, plain Spring beans underneath. Explore the interactive diagram

Step 1: turn methods into tool definitions

At startup, McpToolRegistry walks every bean in the ApplicationContext, looks for methods carrying @McpTool, and builds a ToolDefinition for each one. The interesting part is the input schema, because that's what the model reads to decide how to call your method:

for (Parameter param : method.getParameters()) {
    McpParam mp = param.getAnnotation(McpParam.class);
    String paramName = mp != null ? mp.value() : param.getName();
    String paramDesc = mp != null ? mp.description() : "";
    boolean isRequired = mp == null || mp.required();

    properties.put(paramName, new ParameterSchema(jsonType(param.getType()), paramDesc));
    if (isRequired) required.add(paramName);
}

Java types map to JSON Schema types (int/long → integer, double → number, boolean → boolean, everything else → string). It's deliberately simple. I found that descriptions matter more than types: a model given name: string guesses; a model given "Person's name, as it should appear in the greeting" gets it right.

Step 2: one endpoint, a switch on the method

Every request arrives at a single POST /mcp (configurable via mcp.endpoint). The controller is a switch over the JSON-RPC method:

return switch (method) {
    case "initialize"     -> handleInitialize(id);
    case "tools/list"     -> handleToolsList(id);
    case "tools/call"     -> handleToolsCall(id, request.getParams());
    case "resources/list" -> handleResourcesList(id);
    case "resources/read" -> handleResourcesRead(id, request.getParams());
    case "notifications/initialized",
         "notifications/cancelled" -> JsonRpcResponse.success(id, null);
    default -> JsonRpcResponse.error(id, ERR_METHOD_NOT_FOUND, "Unknown method: " + method);
};

Errors use the JSON-RPC codes clients expect: -32601 for an unknown method, -32602 for bad params (a missing tool name, an unknown tool, a URI that matches no resource), -32603 for anything that blew up inside.

Step 3: invoke, and never throw at the model

McpToolInvoker maps each JSON argument onto the Java parameter type with Jackson's treeToValue, calls the method reflectively, and wraps the return value: strings pass through, anything else is serialised to JSON.

The rule I settled on: a failing tool returns a tool error, not a protocol error. If your method throws, the client receives a ToolResult flagged as an error with the cause's message. The model can read that and recover ("the divisor can't be zero, let me ask the user"), which it can't do with a transport-level failure.

Resources: a tiny URI-template matcher

@McpResource(uri = "config://app/{key}") registers a template. When a client reads config://app/java.version, the registry splits both on /, matches literal segments, and captures {variables} into a map that's passed to the method. It's twenty lines and handles the common cases; it doesn't do wildcards or query strings, and I haven't needed them yet.

Two transports, one handler

HTTP is the natural fit for a service already running in your infrastructure. Claude Desktop, though, launches MCP servers as child processes and speaks newline-delimited JSON-RPC over stdin/stdout. McpStdioRunner is a read-line loop around the same request handler, with two details that bit me:

Logs must go to stderr. Anything written to stdout that isn't a JSON-RPC message corrupts the stream.
Notifications get no response. A message without an id must not produce a reply, or strict clients drop the connection.

What I'd do differently

This is a v0.1, and three things are already on my list:

Proxied beans hide annotations. The registry reads bean.getClass().getMethods(). If the bean is wrapped in a CGLIB proxy — say because it has @Transactional — the proxy's overriding methods don't carry @McpTool, and the tool silently disappears. The fix is to resolve the target class with AopUtils.getTargetClass() and use AnnotationUtils.findAnnotation.
Missing arguments become null. That's fine for String, but a missing value for an int parameter fails at invoke time. Validate against the required list before calling and return a clear -32602.
Parameter names need -parameters. Without @McpParam, names come from reflection, which yields arg0 unless the code is compiled with the -parameters flag. Either fail fast at startup or require @McpParam.

Takeaways

Keep the protocol core independent of your framework; transports become cheap.
Spend your effort on descriptions and schemas — that's the interface the model actually reads.
Return tool failures as data the model can reason about.

The code, tests and sample app are on GitHub. If you're putting internal Java services in front of agents, I'd like to hear how you're handling auth — that's the next big piece.

Originally published at ayushwing.com.