Integration & API Platform

MCP Server & LangGraph Agent

The platform's fourth contract, this one written for language models. An MCP server publishes the system as six tools, three resources and two prompts; a LangGraph agent on Azure OpenAI consumes it — and so can Claude Code, over the same stdio transport.

• Why it matters: the first three contracts were read by programs someone wrote and tested. This one is read at runtime by something that improvises — it retries, invents plausible arguments, and will call the write endpoint twice.
• The finding: every guard already built for human-written clients held it without modification — the XSD's closed enumerations, the facade's Idempotency-Key, and the gateway's key-auth and rate limiting.
• Writes are gated: the graph pauses inside the tool call, checkpoints, and waits for a human. Only the write — interrupting before every read would make the agent unusable.
• Beyond tools: inventory://contract/openapi serves the Phase 2 spec itself as an MCP resource — the same document governing the REST consumer and the LLM consumer.
• Runs with no credentials: with no API key a scripted offline model still drives the real tools against the real gateway.

Verified against the live stack: 34 offline tests plus eight checks against the running platform — the agent's correlation ID survives the gateway unchanged, and two identical record_movement calls in one session produced one database row (quantity 28 → 29, the second returning replayed: true) through an idempotency key derived from the arguments rather than the attempt.

GraphQL Facade

The phase that audits the rest of the project by breaking it. Moving query composition from the server to the client invalidates three mechanisms the earlier phases depend on — and each one needs a different replacement.

• Measured, not claimed: a backend-call counter is reset before each query and read after it, so the numbers below are outputs.
• Cost analysis done properly: the stock complexity calculator scores a 600-row list the same as one row — the exact query that hurts, rated as cheap. A list-aware calculator multiplies by the expected page size, and the estimate is honestly an estimate: you are choosing how wrong to be, and which way.
• What batching actually fixes: duplication and parallelism — not cost. With no bulk operation upstream, six distinct SKUs still cost six calls.

Verified against the live stack: 13 assertions plus 9 unit tests. lowStock { sku } costs 1 backend call; adding one nested field costs 7; a deeper selection is refused having spent 0. All three are one HTTP POST to one URL, and the gateway counted each as a single request against the same quota.

Try it: a read-only build of this same facade — one container, no database, scale-to-zero. Same resolvers, same validation, same cost analysis; only the data source is swapped, for a snapshot of the real database. GraphiQL opens on its own boilerplate, so paste one of these:

{ lowStock { sku warehouseCode quantity deficit } }

{ lowStock { sku quantity product { name reorderQuantity } } }

{ lowStock { sku product { name stockLevels { warehouseCode quantity } } } }

Distributed Tracing

OpenTelemetry across every phase, into Jaeger. Phase 3's correlation ID told you which request you were looking at. A trace tells you what it did — the order, the nesting, and where the time went.

• The same bug, twice: the trace died at the SOAP hop, exactly as the correlation ID once did — WebServiceTemplate is not auto-instrumented, so nothing sends traceparent unless you write it. Two healthy services, two unrelated traces, no error anywhere.
• Free instrumentation: the Redis get/set spans and the Lua rate limiter's evalsha were never written by hand. That is the case for a standard over a bespoke logging convention.
• Sampling, honestly: 1.0 on a laptop; the README says plainly why that cannot ship, and what tail-based sampling is actually for.

What the trace caught that a counter could not: Phase 6 measured its N+1 as “7 backend calls” and was right — but the waterfall showed those calls running strictly sequentially, while the batch loader used .parallel() and both the code comment and the README claimed concurrency. The .parallel() was deleted rather than the sentence quietly softened. A counter can only confirm what you thought to count.

Durable Orchestration

A stock-transfer saga on Temporal, and the deliberate counterpart to Phase 4. Choreography answered how do parts of this system react to each other. This answers who is responsible for finishing.

• The state no event represents: query a transfer mid-flight and the goods have left WH-WEST and not reached WH-EAST — they are in neither. Phase 4 could not have an event for that, because in transit is the gap between two events.
• Failure is the interesting half: a rejection, a timed-out approval and an unavailable carrier all unwind the same way, because each compensation is registered immediately after the step it undoes.
• Retries meet idempotency from the other side: Temporal does not make retries safe, it makes them certain — so every activity carries the same Idempotency-Key the facade has accepted since Phase 2.
• The honest cost: the workflow knows every step, which is exactly what Phase 4 spent effort decoupling. Worth paying only when something must complete.

Verified against the live stack: 11 assertions covering all three unwind paths — after a rejection and after a carrier failure, the stock is back in WH-WEST to the unit, and the result still names the movement it made and reversed rather than hiding it.