If the page is cached, everything works smoothly. Problems begin when the cache is empty, expired, or being refreshed. Then, the first group of users all miss the cache together, and every request asks the app to generate the same response. (This same thing would also happen with a trending news story, a search crawler, frontend prefetching, or after a cache reset.)

This situation is known as the “thundering herd” problem. Every user request is valid, but the work gets repeated. Your app uses CPU, database, and network resources to calculate the same result over and over, just when response times are already strained.

Rather than sending all traffic straight to your app, wouldn’t it be great if you could place a gateway in front that spots duplicate in-flight reads and combines them before they hit Node.js?

Platformatic Gateway now does exactly this. With request deduplication, it merges concurrent requests for the same data. Only one goes upstream, while the others wait and then get the same response.

This is not a replacement for caching. Instead, it acts as a short-term coordination layer for requests in progress. The cache handles future requests, while deduplication shields your app while the first response is still being generated.

This is especially important for self-hosted Next.js apps. A popular route can cause heavy server rendering, React Server Component processing, image metadata checks, or backend API calls. When many users hit that route at once, or during cache refreshes, deduplication stops the gateway from sending the same work to Next.js over and over.

A Local Benchmark

To see how much this helps, we ran a simple local test with a purposely slow route behind a proxy. The upstream route waited 100 ms before responding, simulating a page or API call that needs backend work. The test used the same leader/waiter pattern as gateway deduplication and sent 100 requests at once to the same URL.

These are the median numbers from three runs:

The key result isn’t the slight change in average latency, but the number of upstream requests. With deduplication, the proxy still answers every client, but the upstream app only processes one response per wave of requests. In a test with 10,000 requests, that meant just 100 upstream responses instead of 10,000. In real situations, this can mean the difference between a burst that overwhelms your app and one that the gateway handles smoothly.

How It Works

Gateway deduplication uses a leader/waiter model that is easy to reason about in production.

The first matching request becomes the leader. It acquires a lock, goes to the upstream application, buffers the response, stores it for a short time, and notifies any waiters. Concurrent requests with the same key become waiters. They do not call the upstream service immediately; instead, they wait for the leader response and replay it when it becomes available.

In a production gateway, deduplication often sits next to caching. You can use separate Valkey instances or separate key prefixes in the same Valkey deployment, but the two stores serve different purposes: cache storage keeps reusable responses, while deduplication storage keeps short-lived locks and response buffers for in-flight requests.

To prevent deadlocks, every coordination point has an expiration. The leader lock uses a lockTtl, waiters have a timeout, and retries are limited. If the leader fails, the lock expires, a waiter times out, or retries run out, the request switches back to normal proxying. This fallback is intentional—deduplication is meant to lower load, not cause requests to get stuck during traffic spikes.

For a single request, the decision path looks like this:

The Simplest Configuration

Enable deduplication globally under gateway.deduplication:

{
  "gateway": {
    "deduplication": {
      "enabled": true
    },
    "applications": [
      {
        "id": "frontend",
        "proxy": {
          "prefix": "/"
        }
      }
    ]
  }
}

By default, deduplication works for GET and HEAD requests and uses memory for storage.

This default is intentionally cautious. GET and HEAD are the safest types of requests to deduplicate. Write requests often need custom rules before they can be safely coordinated.

Per-Application Overrides

You can also configure deduplication per proxied application with gateway.applications[].proxy.deduplication. Application-level options override the global options.

{
 "gateway": {
   "deduplication": {
     "enabled": true,
     "methods": ["GET"]
   },
   "applications": [
     {
       "id": "frontend",
       "proxy": {
         "prefix": "/",
         "deduplication": {
           "enabled": true,
           "routes": [{ "method": "GET", "path": "/blog/*" }]
         }
       }
     }
   ]
 }
}

This approach lets you begin where the benefits are clear. You can deduplicate public catalogue pages, blog posts, product details, or framework prefetch routes, while keeping endpoints with strict per-user behaviour unchanged.

Choosing The Deduplication Key

The default key is computed from:

• the configured application origin

• the HTTP method

• the rewritten proxy URL, including the query string

• selected request headers

The default headers are:

["authorization", "cookie", "accept", "accept-language"]

Including headers matters because many read responses are not only a function of the URL. A localized page can depend on accept-language. A user-specific page can depend on cookie or authorization. If those headers were ignored, unrelated callers could incorrectly share a response.

You can adjust the headers included in the key for a deduplication configuration:

{
 "gateway": {
   "deduplication": {
     "enabled": true,
     "headers": ["authorization", "cookie", "x-tenant-id"]
   }
 }
}

Currently, you can’t set headers per route. If you need different header behaviour for different routes, use separate deduplication settings for each application or create a custom key function.

For full control, provide a synchronous key function:

{
 "gateway": {
   "deduplication": {
     "enabled": true,
     "key": "./deduplication-key.js"
   }
 }
}

export function computeDeduplicationKey(request, context) {
 return `${context.origin}:${context.method}:${context.url}`
}

The function receives the request and a context object containing the origin, method, rewritten URL, parsed query, selected headers, and application configuration. It must return the key synchronously.

Route Whitelisting

For tighter control, configure a route whitelist. Routes use find-my-way syntax.

{
 "gateway": {
   "deduplication": {
     "enabled": true,
     "routes": [
       { "method": "GET", "path": "/blog/*" },
       { "methods": ["GET", "HEAD"], "path": "/products/:id" }
     ]
   }
 }
}

When routes are configured, route matching decides whether deduplication applies. When routes are not configured, the methods list decides.

Storage: Memory Or Valkey

TBy default, memory is used for storage. It handles duplicate requests within a single gateway instance and doesn’t need any external service. This setup is great for local development, single-instance deployments, and easy rollouts.

{
 "gateway": {
   "deduplication": {
     "enabled": true,
     "storage": {
       "adapter": "memory"
     }
   }
 }
}

For deployments that scale horizontally, use the valkey adapter. It stores locks, response pointers, and buffered responses in a Redis-compatible Valkey server, allowing multiple gateway workers, instances, or pods to coordinate. This way, you get the same deduplication benefits even when traffic is spread across several replicas.

{
 "gateway": {
   "deduplication": {
     "enabled": true,
     "storage": {
       "adapter": "valkey",
       "url": "redis://127.0.0.1:6379",
       "prefix": "my-application"
     }
   }
 }
}

Use a prefix if several applications share the same Valkey instance and need separate key spaces.

Operational Behavior

Deduplication is a best-effort feature, not a guarantee of exactly-once processing.

Duplicate upstream requests can still occur if the in-flight lock expires before the upstream response is ready, if a gateway instance fails while handling the leader request, if a waiter times out, or if retries run out. In these cases, the gateway just switches back to normal proxying.

The main timing options are:

• timeout: how long a duplicate request waits for the leader response before retrying lock acquisition

• retries: how many additional deduplication attempts are made before falling back to normal proxying

• ttl: how long stored responses remain available for waiting requests

• lockTtl: how long an in-flight lock can live before it expires

Defaults are:

{
 "timeout": 1000,
 "retries": 3,
 "ttl": 10000,
 "lockTtl": 500
}

Responses are fully buffered before being replayed. This works well for short bursts of duplicate reads, but large responses can use more gateway memory and, with Valkey, add some storage overhead. It’s best to start with routes where responses are small and where repeated upstream work is already costing you in money, speed, or capacity.

Custom Gateway Handlers

Deduplication comprises custom gateway handlers. When both a custom handler and deduplication are configured, deduplication runs first, and the leader request is delegated to the handler.

Handlers that use reply.from() do not need special handling. Platformatic Gateway uses reply.from() from @fastify/reply-from to proxy upstream requests.

export function handler(request, reply, dest, options) {
 return reply.from(dest, options)
}

If a handler overrides onResponse or onError, it can call the helper functions provided in options, so waiting requests still receive the correct signal:

export function handler(request, reply, dest, options) {
 return reply.from(dest, {
   ...options,
   async onResponse(request, reply, res) {
     reply.header('x-custom-handler', 'true')
     return options.deduplicateResponse(request, reply, res)
   },
   async onError(reply, error) {
     return options.deduplicateError(reply, error)
   }
 })
}

Handlers that send responses directly without reply.from() cannot be replayed by gateway deduplication.

Metrics

The feature also adds Gateway metrics so you can prove whether deduplication is helping in production:

• gateway_deduplication_leader_count

• gateway_deduplication_waiter_count

• gateway_deduplication_replay_count

• gateway_deduplication_fallback_count

• gateway_deduplication_error_count

These counters help answer real-world questions: how many requests became leaders, how many waited, how many were replayed, and how often the gateway had to switch back to normal proxying.

Conclusion

Gateway deduplication works best when lots of clients request the same resource at once, and the upstream response can be safely reused for matching keys. This is just like the product launch or hot-news example from earlier: many users show up at once, the cache is cold or refreshing, and your app is about to generate the same page over and over.

The best places to start are public, read-heavy routes, framework prefetch endpoints, cache refresh paths, and expensive upstream reads with limited response sizes. Turn it on for a small set of routes first. Keep an eye on the leader, waiter, replay, and fallback metrics. Then, expand to other routes where you see duplicate work causing the most trouble.

You’ll see results right away: the gateway handles traffic spikes, your services do less repeated work, and users get more consistent response times during busy periods.

This kind of optimization adds up over time. You protect your upstream resources without changing your app code. You cut down on unnecessary backend load before it hits your databases, APIs, or rendering services. You also get metrics to see if the feature is delivering value. And if deduplication can’t help in a certain case, the request just goes through as usual.

For teams using Platformatic Gateway in front of modern web apps, especially self-hosted Next.js apps, request deduplication is a practical way to make read-heavy traffic more manageable. It gives you a safety net for traffic bursts, an easier way to scale with Valkey, and a rollout approach that doesn’t require changing your backend services.

Running Medusa in production is more than just starting a single process. The real challenge is keeping the entire commerce stack fast, organized, and easy to update, especially when you have a backend, storefront, admin UI, image optimization, internal networking, and Kubernetes involved.

This is where using a Watt monorepo really helps.

Watt is Platformatic’s tool for combining multiple Node.js apps into one deployable unit by running them as worker threads under a single process.

Medusa can be deployed in a Kubernetes environment. To manage, monitor, and optimize your application in this setting, you can use the Intelligent Command Center (ICC). ICC is a sophisticated cloud control plane that provides intelligent management, monitoring, and optimization of cloud-native applications deployed in Kubernetes environments. ICC offers enterprise-grade features for application lifecycle management, intelligent autoscaling, compliance monitoring, and comprehensive observability.

For basic deployment, simply running Watt on Kubernetes is sufficient.

Rather than spreading complexity across multiple repos, custom Dockerfiles, and manual service connections, you can keep everything in one workspace and let Watt manage it as a single platform. This gives you one dependency graph, one build process, one deployment artifact, and a single place to manage the rules that keep your system running smoothly.

In this post, we will look at a working Medusa setup deployed on ICC with:

• web/backend: Medusa backend via @platformatic/node

• web/frontend: Medusa Next.js starter via @platformatic/next

• web/gateway: public routing via @platformatic/gateway

• image-server: a dedicated @platformatic/next image optimizer application that reuses the same codebase as web/frontend

This set-up can be both far easier to manage and more performant. Let’s explore.

Why a monorepo is a good fit for Medusa

Medusa already pushes you toward a multi-application architecture. Even in a relatively standard deployment, you are dealing with:

• a backend API

• an admin UI

• a storefront

• image optimization

• environment variables shared across services

• public and internal URLs that must stay aligned

You can spread these parts across different repositories and deployment pipelines, but as soon as you do, even simple changes become complicated.

For example, changing a base path means updating several repos. Keeping React versions consistent gets harder. Coordinating Docker changes turns into a big release task. Even figuring out if the storefront is calling the right backend can take more effort than it should.

With Watt, the monorepo becomes the control plane for the whole stack.

• Each application stays isolated as a worker thread with Watt.

• The whole platform is configured in one place.

• Internal service discovery comes for free.

• Deployment stays a single build and a single runtime entry point.

This approach gives you the best of both worlds: separation where it matters, and simplicity where you want it.

The workspace layout

The sample project is structured like this:

.
|-- package.json
|-- pnpm-workspace.yaml
|-- watt.json
`-- web
    |-- backend
    |   |-- medusa-config.ts
    |   |-- package.json
    |   |-- url-handler.js
    |   `-- watt.json
    |-- frontend
    |   |-- next.config.js
    |   |-- package.json
    |   |-- watt.image-optimizer.json
    |   |-- watt.json
    |   `-- src
    `-- gateway
        |-- package.json
        `-- watt.json

At the root, watt.json autoloads the web/* applications, sets gateway as the public entrypoint, and adds an extra application called image-server that reuses the frontend codebase with a different config.

This is where the monorepo model really shines. You can easily reuse the same codebase for different runtime roles. There’s no need to create a second Next.js project just to separate /_next/image. Instead, you keep one frontend codebase and let Watt run it in two different ways.

pnpm workspace setup: one dependency graph, fewer surprises

If you use pnpm, make the workspace explicit with pnpm-workspace.yaml:

packages:
 - web/*

Then pin the React family at the root in package.json:

{
 "pnpm": {
   "overrides": {
     "react": "19.0.4",
     "react-dom": "19.0.4",
     "@types/react": "19.0.4",
     "@types/react-dom": "19.0.4"
   }
 }
}

This is a clear reason why using a monorepo matters. The Medusa storefront, Next.js, and related tools all rely on React. In a multi-repo setup, versions can easily get out of sync. With a Watt monorepo, you set the version once at the root, and every app benefits right away.

This makes building more predictable and keeps maintenance costs much lower.

One .env, clear public and internal boundaries

The root .env needs a few shared values:

• REDIS_HOST

• MEDUSA_PUBLIC_BACKEND_URL

• MEDUSA_BACKEND_URL

The key distinction is this:

• MEDUSA_PUBLIC_BACKEND_URL is for the externally visible backend URL

• MEDUSA_BACKEND_URL is for server-side calls from the frontend

On ICC, this is the ideal setup:

MEDUSA_PUBLIC_BACKEND_URL=https://medusa.plt/backend
MEDUSA_BACKEND_URL=http://backend.plt.local

Why it matters:

• browsers and the admin UI use the public backend URL

• The frontend server uses http://backend.plt.local and stays on the Platformatic mesh.

It’s worth emphasizing that second point, since it provides both great DevEx and a substantial performance boost. Thanks to Watt and inter-thread communication, server-side requests skip the public gateway and stay within the process’s internal network.

Once again, the monorepo helps here. The internal service name and public URL strategy are side-by-side in the same workspace, making them much harder to misconfigure.

Backend: run Medusa as a Watt application

In web/backend/package.json, add @platformatic/node:

{
 "dependencies": {
   "@platformatic/node": "^3.44.0"
 }
}

Then configure web/backend/watt.json:

{
 "$schema": "https://schemas.platformatic.dev/@platformatic/node/3.44.0.json",
 "application": {
   "basePath": "/backend",
   "commands": {
     "development": "npm run dev",
     "build": "npm run build",
     "production": "npm run start"
   },
   "changeDirectoryBeforeExecution": false,
   "entrypointPort": 3000
 },
 "node": {
   "disableBuildInDevelopment": true,
   "dispatchViaHttp": true,
   "absoluteUrl": true
 },
 "watch": false
}

This setup gives Medusa a clear application boundary within the workspace, while still allowing the gateway to publish it under /backend.

The companion change in web/backend/medusa-config.ts is just as important:

import { defineConfig, loadEnv } from '@medusajs/framework/utils'

loadEnv(process.env.NODE_ENV || 'development', process.cwd())

module.exports = defineConfig({
 projectConfig: {
   databaseUrl: process.env.DATABASE_URL,
   http: {
     storeCors: process.env.STORE_CORS!,
     adminCors: process.env.ADMIN_CORS!,
     authCors: process.env.AUTH_CORS!,
     jwtSecret: process.env.JWT_SECRET || 'supersecret',
     cookieSecret: process.env.COOKIE_SECRET || 'supersecret'
   },
   cookieOptions: {
     sameSite: 'lax',
     secure: false
   }
 },
 admin: {
   path: (new URL(process.env.MEDUSA_PUBLIC_BACKEND_URL!).pathname + '/app') as `/string`,
   backendUrl: process.env.MEDUSA_PUBLIC_BACKEND_URL,
   vite: config => {
     config.server.allowedHosts ??= []
     config.server.allowedHosts.push('.plt.local')
   }
 }
})

The admin path comes from the public backend URL. So, if ICC publishes the backend at /backend, the admin will automatically be available at /backend/app.

You should also keep web/backend/url-handler.js in place. Medusa’s API and admin UI do not behave identically when you put them behind a prefixed public path, so Watt’s gateway uses this file to rewrite requests correctly.

The implementation used in the sample project looks like this:

const basePath = process.env.PLT_BASE_PATH ?? ''
const adminPath = new URL(process.env.MEDUSA_PUBLIC_BACKEND_URL).pathname.replace(/\/$/, '')
const adminUiPath = adminPath + '/app'
const adminMatcher = new RegExp(`^${adminPath}`)

export default {
 preRewrite(url) {
   if (basePath && !url.startsWith(basePath)) {
     url = `${basePath}${url}`
   }

   url = url.startsWith(adminUiPath) ? url : url.replace(adminMatcher, '')
   return url
 }
}

This file may be small, but it does important work. It keeps the admin UI path intact while removing the backend prefix for API routes that Medusa expects to serve from the root.

Frontend: one codebase, two runtime roles

In web/frontend/package.json, add @platformatic/next:

{
 "dependencies": {
   "@platformatic/next": "^3.44.0"
 }
}

The standard frontend config in web/frontend/watt.json is simple:

{
 "$schema": "https://schemas.platformatic.dev/@platformatic/next/3.44.0.json",
 "application": {
   "basePath": "{PLT_BASE_PATH}",
   "changeDirectoryBeforeExecution": true
 },
 "next": {
   "trailingSlash": true
 }
}

And in web/frontend/next.config.js, set:

const nextConfig = {
 reactStrictMode: true,
 logging: {
   fetches: {
     fullUrl: true
   }
 },
 eslint: {
   ignoreDuringBuilds: true
 },
 typescript: {
   ignoreBuildErrors: true
 }
}

Here’s where it gets interesting: the monorepo lets you reuse the same frontend codebase as a dedicated image optimization service, with almost no extra work.

Split image optimization without splitting the repo

We recently covered why this architecture matters in our post on scaling Next.js image optimization with a dedicated Platformatic application: image optimization is CPU-heavy and can become a noisy neighbour for SSR traffic.

That is exactly why this Medusa setup runs /_next/image separately.

Create web/frontend/watt.image-optimizer.json:

{
 "$schema": "https://schemas.platformatic.dev/@platformatic/next/3.44.0.json",
 "logger": {
   "level": "trace"
 },
 "application": {
   "basePath": "/",
   "changeDirectoryBeforeExecution": true
 },
 "next": {
   "trailingSlash": true,
   "imageOptimizer": {
     "enabled": true,
     "fallback": "frontend",
     "timeout": 30000,
     "ttl": 3600000,
     "maxAttempts": 3,
     "storage": {
       "type": "valkey",
       "url": "{REDIS_HOST}"
     }
   }
 }
}

This is a great example of why Watt monorepos work so well.

• You reuse the same frontend app.

• You keep one source tree.

• You give it a second runtime role.

• You isolate a CPU-heavy path without creating a second frontend project.

This setup improves both maintainability and performance, which is exactly what you want from your platform architecture.

The fallback: "frontend" setting is especially nice here: relative image URLs are resolved through the main storefront service over the runtime network, so the optimizer stays tightly integrated without being coupled to the frontend worker pool.

Next.js build-time pragmatism: force dynamic where it helps

Because the Medusa backend is not available during the wattpm build, the storefront cannot pre-generate some pages safely.

For these files:

• web/frontend/src/app/[countryCode]/(main)/products/[handle]/page.tsx

• web/frontend/src/app/[countryCode]/(main)/categories/[...category]/page.tsx

• web/frontend/src/app/[countryCode]/(main)/collections/[handle]/page.tsx

comment out generateStaticParams and add:

export const dynamic = 'force-dynamic'

This uses Next.js Route Segment Config to force runtime rendering instead of static generation.

In a typical Next.js app, this might seem like a compromise. But in this setup, it’s the right choice. The storefront relies on live Medusa data, and Watt provides that backend at runtime.

This is another area where the monorepo helps. The build behaviour is clear because the backend and frontend are in the same workspace, and their dependencies are easy to see.

Gateway: one public surface for the whole stack

Add @platformatic/gateway in web/gateway/package.json:

{
 "dependencies": {
   "@platformatic/gateway": "^3.44.0"
 }
}

Then define web/gateway/watt.json like this:

{
 "$schema": "https://schemas.platformatic.dev/@platformatic/gateway/3.44.0.json",
 "gateway": {
   "applications": [
     {
       "id": "backend",
       "proxy": {
         "prefix": "/backend",
         "custom": {
           "path": "../backend/url-handler.js"
         }
       }
     },
     {
       "id": "frontend",
       "proxy": {
         "prefix": "/"
       }
     },
     {
       "id": "image-server",
       "proxy": {
         "prefix": "/",
         "routes": ["/_next/image", "/_next/image/*"],
         "methods": ["GET"]
       }
     }
   ]
 }
}

This is where the monorepo approach really starts to feel smooth and efficient.

• /backend goes to Medusa

• / goes to the storefront

• GET /_next/image goes to the image optimizer

Thanks to @platformatic/gateway, you get one public entry point, but the traffic still lands on the right internal application.

This setup is easier to understand, change, and scale than trying to connect separate services outside the repo.

A small middleware detail that improves the experience

There is another subtle optimization in the storefront middleware (web/frontend/src/middleware.ts).

When the request already contains a country code in the URL but does not yet have the medusacache_id cookie, the middleware sets that cookie and returns NextResponse.next() instead of forcing another redirect.

It’s a small detail, but it’s the kind of optimization that’s easier to maintain in a monorepo. Storefront routing, Medusa region lookups, and platform-level caching thanks to Watt HTTP caching handling are all managed together.

In practice, this helps the storefront set up its region-aware state smoothly, without extra steps.

The change is small enough to think of as a focused patch:

 if (urlHasCountryCode && !cacheIdCookie) {
+    const response = NextResponse.next()

   response.cookies.set('_medusa_cache_id', cacheId, {
     maxAge: 60 * 60 * 24
   })

   return response
 }

This is the kind of practical improvement that’s easier to maintain when routing logic, storefront behaviour, and platform deployment are all in the same repo.

ICC environment values

In .env.icc, the main settings to align are:

MEDUSA_PUBLIC_BACKEND_URL=https://medusa.plt/backend
STORE_CORS=https://docs.medusajs.com,https://medusa.plt
ADMIN_CORS=https://docs.medusajs.com,https://medusa.plt
AUTH_CORS=https://docs.medusajs.com,https://medusa.plt
NEXT_PUBLIC_BASE_URL=https://medusa.plt

They all reflect the same core rule: the whole application is published under /medusa, so both Medusa and Next.js need to agree on that public shape.

Since these settings are in one workspace and one deployment artifact, keeping them in sync is much easier than with a split-repo setup.

The Docker build is simple because the repo is simple

The container image is straightforward:

FROM node:22-alpine

# Environment setup
ENV APP_HOME=/home/app/node/
ENV PLT_BASE_PATH="/medusa"
ENV PLT_ICC_URL="http://icc.platformatic.svc.cluster.local"
WORKDIR $APP_HOME

# Install dependencies
RUN npm install -g pnpm wattpm-utils "@platformatic/watt-extra@latest"
COPY package.json pnpm-lock.yaml pnpm-workspace.yaml $APP_HOME
RUN pnpm install --frozen-lockfile --node-linker=hoisted

# Copy application
COPY web $APP_HOME/web
COPY .env.icc watt.json $APP_HOME
RUN mv .env.icc .env
RUN pnpm run build

# Final setup
EXPOSE 3042
EXPOSE 9090
CMD ["watt-extra", "start"]

There are two details worth mentioning.

First, using --node-linker=hoisted with pnpm installs dependencies in a flatter layout, instead of the usual symlink-heavy structure. In a workspace with Medusa, Next.js, shared React versions, and several Watt apps, this makes module resolution more predictable and helps avoid compatibility issues during container builds.

Second, @platformatic/watt-extra is a helper CLI that starts Watt smoothly in container environments like ICC. It adds the operational support you need at runtime, so your container entrypoint remains simple.

This is another area where the monorepo pays off right away: you have one install step, one build step, and one runtime command.

Why does this feel better to maintain

The main advantage of this Medusa setup isn’t any single config file. It’s the overall structure:

• One repo for backend, frontend, gateway, and optimizer

• One dependency strategy

• One place to define public and internal URLs

• One deployment artifact for Kubernetes and ICC

• One runtime that still preserves application boundaries

Since Watt sees the platform as a group of coordinated apps, you can make performance improvements without making the system harder to manage.

You can send image optimization to a dedicated service, keep frontend-to-backend calls on the mesh network, mount everything under a base path, and update all these rules in one place.

That’s the real value of running Medusa in a Watt monorepo on ICC: convenience and performance work together, instead of getting in each other’s way. Because ICC provides a Kubernetes (K8S)-native environment, your monorepo and its services benefit from K8s's inherent scalability, resilience, and orchestration capabilities. This integration ensures that deploying and managing Medusa within the Watt monorepo is seamless, leveraging the enterprise-grade infrastructure of ICC (which is built on K8S) for optimal operational efficiency.

If you’re building commerce systems with lots of moving parts, this is the kind of platform setup you want.

Regina lets you go from single-agent demos to real systems you can run and scale confidently. You define agents in Markdown, start instances over HTTP, and get built-in lifecycle management, persistence, and recovery, all by running and managing agents in Watt as isolated worker threads.

Why Regina, why now

Most AI projects hit the same wall after the first demo:

• Prompts are not versioned in a clean, operational way.

• Sessions disappear on restart.

• Scaling introduces routing and state headaches.

• Tool-heavy workflows are hard to observe and control.

Regina solves these problems directly, so your team can focus on building your product and not re-inventing the wheel when it comes to complex orchestration and state management.

What you get on day one

Regina comes as three packages:

• @platformatic/regina: per-pod agent manager

• @platformatic/regina-agent: per-agent runtime

• @platformatic/regina-storage: pluggable backup adapters (fs, s3, redis)

With this stack, you’ll have:

• stateful agent instances with per-instance SQLite VFS (“Virtual File System”)

• suspend/resume lifecycle management with idle timeout control

• NDJSON streaming events for full run visibility

• steerable agentic loops via POST /instances/:id/steer

• storage-backed restore for resilient multi-pod operation

Markdown-native agent definitions

Regina uses Markdown with YAML frontmatter as the main source for each agent.

---
name: support-agent
description: Customer support assistant
model: anthropic/claude-sonnet-4-5
provider: vercel-gateway
tools:
 - ./tools/search-docs.ts
temperature: 0.3
maxSteps: 10
---
You are a helpful support agent.

This setup keeps prompt and runtime configuration together, so it’s easy to review in pull requests and update across teams.

Built for real runtime behaviour

Regina keeps management and execution separate:

• @platformatic/regina discovers definitions, spawns instances, and proxies instance APIs

• @platformatic/regina-agent runs each instance in isolation

• message history is persisted at /.session/messages.jsonl in each instance VFS

This design gives you reliable performance, even under heavy load:

• Idle suspension to free resources automatically

• Auto-resume on next request

• State continuity across restarts

• Rich streaming (text-delta, tool-call, tool-result, step-finish)

In practice, running your agents with Regina and Watt gives you agents that act like durable workflows backed by persistent state instead of ephemeral, one-off chat sessions.

Start simple and scale smoothly

Regina works great in single-pod mode with no Redis, no external storage, and minimal setup.

As your traffic grows, you can add Redis or Valkey for member and instance mapping, and add shared storage for state restore if needed. The API stays the same, so clients don’t need to change as your setup evolves.

Getting started

The Regina demo app is small on purpose, but it shows the full production pattern in a single repo:

• watt.json at the root defines a single entrypoint service for Regina

• services/regina/watt.json enables @platformatic/regina and points to the shared agents/ directory

• Each file in agents/ is a full agent definition (prompt + model + provider + tools)

• Custom tools sit alongside agents in agents/tools/*

Here’s how the demo app is set up.

Root watt.json:

{
 "$schema": "https://schemas.platformatic.dev/wattpm/3.50.0.json",
 "server": {
   "port": 3042
 },
 "management": true,
 "entrypoint": "regina",
 "services": [
   {
     "id": "regina",
     "path": "./services/regina",
     "management": {
       "operations": ["addApplications", "removeApplications", "getApplications", "getApplicationDetails", "inject"]
     }
   }
 ]
}

Service services/regina/watt.json:

{
 "$schema": "https://schemas.platformatic.dev/@platformatic/regina/0.1.0.json",
 "regina": {
   "agentsDir": "../../agents"
 }
}

Example agent definition (agents/assistant.md):

---
name: assistant
description: A general-purpose assistant with file and shell access
model: anthropic/claude-sonnet-4-5
provider: vercel-gateway
greeting: "Hi! I'm a general-purpose assistant. I can read and write files, run commands, and help with any task."
temperature: 0.3
maxSteps: 15
---
You are a helpful assistant. You can read, write, and edit files, run bash commands, and help with any task.

Here’s a typical flow in the demo:

1. Start Watt (wattpm start).

2. Create an instance from an agent definition (POST /agents/:defId/instances).

3. Chat with that instance (POST /instances/:instanceId/chat or /chat/stream).

4. Resume the same instance later with history already available.

This is important because it shows Regina’s core value from start to finish: agents are defined as code, run as managed instances, and keep their state across requests without extra orchestration work.

Storage options for state backup

For multi-pod setups, configure regina.storage so you can restore on another pod.

Filesystem (fs)

{
 "module": "@platformatic/regina",
 "regina": {
   "storage": {
     "type": "fs",
     "basePath": "/mnt/shared/regina-state"
   }
 }
}

Object storage (s3)

{
 "module": "@platformatic/regina",
 "regina": {
   "storage": {
     "type": "s3",
     "bucket": "regina-state",
     "prefix": "backups/",
     "endpoint": "https://s3.amazonaws.com"
   }
 }
}

Redis (redis)

{
 "module": "@platformatic/regina",
 "regina": {
   "redis": "redis://valkey:6379",
   "storage": {
     "type": "redis"
   }
 }
}

All adapters use the same interface (put, get, delete, list, close), so you can switch backends without changing how your clients work.

Get started

• Regina repository

• Regina package docs

• Agent runtime docs

• Storage adapters docs

Regina is built for teams shipping serious AI systems on Node.js. If you need agents that are reliable, observable, and stateful in production, Regina is ready for you.

Before now, using @platformatic/kafka with Confluent Schema Registry meant writing extra code to connect the pieces. With @platformatic/kafka v1.27.0, that’s no longer needed.

@platformatic/kafka now has built-in support for Confluent Schema Registry, including:

• AVRO

• Protocol Buffers

• JSON Schema

• Basic and Bearer authentication

• Automatic schema fetch and caching

• Integrated Producer and Consumer hooks

You get schema-aware messaging, and the project still focuses on being fast and predictable for Node.js Kafka clients.

Why This Matters

Most schema registry integrations add complexity where you don’t want it: in the message serialization and deserialization paths. Fetching remote schemas is asynchronous, but encoding and decoding should stay synchronous for speed and consistency.

Put simply, network I/O and cache coordination should happen before the main data processing, not during it. Keeping these steps separate helps maintain stable throughput and latency as traffic increases.

This release introduces a two-layer architecture to keep that separation clear:

1. Low-level hooks for async pre-processing:

   • beforeSerialization

   • beforeDeserialization

2. High-level registry API via ConfluentSchemaRegistry

In practice, this means schemas are fetched and cached before encode/decode happens, so your serializers and deserializers stay synchronous when messages are processed.

This gives application teams a simpler way to think about things: do the asynchronous prep first, then keep codec behavior predictable during main processing.

At a high level, the flow is:

• Extract schema ID from message metadata (producer) or wire payload (consumer).

• Resolve schema from local cache when available.

• On cache miss, fetch asynchronously via beforeSerialization/beforeDeserialization hooks and cache the schema.

• Run synchronous serialization/deserialization with the resolved schema.

In multi-instance deployments, that cache layer can be backed by Redis or Valkey, so workers share schema state across nodes while keeping encode/decode synchronous in the hot path.

What You Can Do Now

You can connect a registry directly to both the Producer and Consumer, letting @platformatic/kafka handle schema-aware serialization from start to finish.

This is especially helpful when several services publish and consume the same topics on different deployment cycles, since consistent schema handling is a must.

import { Consumer, Producer } from '@platformatic/kafka'
import { ConfluentSchemaRegistry } from '@platformatic/kafka/registries'

const registry = new ConfluentSchemaRegistry({
  url: 'http://localhost:8081'
})

const producer = new Producer({
  clientId: 'orders-producer',
  bootstrapBrokers: ['localhost:9092'],
  registry
})

const consumer = new Consumer({
  groupId: 'orders-consumers',
  clientId: 'orders-consumer',
  bootstrapBrokers: ['localhost:9092'],
  registry
})

When producing, pass schema IDs in message metadata:

await producer.send({
  messages: [
    {
      topic: 'orders',
      key: { orderId: 101 },
      value: { customerId: 'cust-44', total: 129.99 },
      metadata: {
        schemas: {
          key: 10,
          value: 11
        }
      }
    }
  ]
})

When consuming, payloads are automatically decoded with the cached schema. If a schema isn’t found, the registry fetches it before deserialization continues.

This makes it easy to move from custom codec code to a single registry integration in your client setup.

Authentication and Enterprise Scenarios

Schema Registry deployments are often protected. The new integration includes:

• Basic auth (username + password)

• Bearer token auth (token)

• Dynamic credentials via providers

This makes it easier to connect to managed or secured registry instances without writing custom transport code. It also makes credential rotation simpler when you use providers.

If your setup uses short-lived credentials, provider functions let you refresh tokens and secrets without having to rebuild your producer or consumer logic.

Performance and Reliability Considerations

One main design goal was to avoid unnecessary overhead to message processing.

The implementation focuses on cache locality and step-by-step pre-processing:

• Schema IDs are extracted from the wire format (or message metadata).

• Unknown schemas are fetched once and cached.

• Repeated schema IDs in a batch are resolved from the cache.

• Encode/decode continues in synchronous paths.

This setup cuts down on unnecessary async work while still supporting remote schema registries safely. It also helps keep throughput and performance steady, as you’d expect from a Node.js client.

Operationally, this also makes failures easier to understand. Schema resolution errors happen during fetch or preparation, while codec errors are still linked to payload and schema compatibility.

Also Included in This Release

The v1.27.0 release also shipped quality improvements around consumer behaviour and protocol handling, with broad test coverage and new playground clients for:

• AVRO

• Protobuf

• JSON Schema

• Authenticated Schema Registry setups

The end result is a production-ready integration you can try out quickly, starting in local development and moving to secure production registries.

Experimental API Notice

ConfluentSchemaRegistry and its related hooks are currently experimental. They may change in minor or patch releases as we keep improving them based on real-world use and feedback.

If you plan to use this in production, make sure to pin your versions and check the release notes. We’ll keep refining the API based on feedback from real deployments.

If your team is rolling this out, here’s a practical way to start:

1. Start with one topic and one schema format (typically AVRO or JSON Schema)

2. Validate serialization/deserialization behaviour in staging with real payloads.

3. Expand topic coverage and introduce auth/credential providers as needed.

Getting Started

Install the package:

npm install @platformatic/kafka

For Protobuf support, also install:

npm install protobufjs

Next, follow the full integration guide in the documentation:

• Confluent Schema Registry docs

• v1.27.0 release notes

If you give it a try, we’d love to hear your feedback at hello@platformatic.dev. Real-world schema workflows will help shape the next version of this API and guide our priorities for future improvements.

Thanks for building with us! 🚀