The usual way to keep teams apart is to put a network between them, with separate services, separate deployables and contracts checked at run time. This time I moved the boundaries into the build instead. Each area is a package. The compiler and a small lint script decide what each package may touch. Effect wires the pieces together on the server, and React Router 8 renders the pages.

This post walks through how that works. To keep it concrete, I’ll follow one request the whole way: a signed-in citizen opens /en/jobs to see job postings that match their experience.

One trade-off up front, so it doesn’t feel hidden later: every team ships on the same release train. If a team truly needs to deploy on its own schedule, the modules don’t give them that. Near the end I’ll show the one narrow exception I made, and what it costs. In exchange you get no version skew between pages, no composition layer to run, one developer experience, and contracts the compiler checks.

The shape: one app, many packages

The repository has two kinds of workspace: applications and packages. One application is the product. The other is the exception I just mentioned, and I’ll come back to it near the end.

apps/web/                  the application: one build, one process, one image
  server.ts                process entry
  server/runtime.ts        composition root: every module's Effect layer
  server/http/             the Effect HTTP server
  app/routes.ts            React Router's route config, built from the modules
  app/register.ts          types the kernel with the real app (more on this later)
  app/routes/layouts/      three layouts; the language page and the 404
apps/cra-tax-slips/        the one exception: a frontend built and deployed on its own (near the end)
packages/
  kernel/                  shared kernel: the Effect ↔ React Router bridge, request scope, module contract, fragment slot
  ui/                      the design system
  identity/                sign-in, sign-out, the session, page guards
  profile/                 the citizen's record, contact details, consent
  benefits/                the program catalogue and the benefits finder
  jobs/                    job postings matched to the citizen, and their shortlist
  dashboard/               the account's home page
  mfe-host/                mounts the exception inside the account
  mfe-contract/            the mount contract both sides share
  …                        payments, employment records, and a few more

The application is the composition root. It owns almost nothing: the process entry, the HTTP server, three layouts, the 404 page, and the wiring that pulls every module in. There’s no business logic in it at all.

Each package under packages/ is one bounded context, owned by one team. The kernel is the shared kernel in the DDD sense: a small, slow-moving set of types and helpers every module agrees on. It depends on no other workspace package. ui is the design system, and it depends only on the kernel.

One detail surprised people at first: modules can’t be built on their own. A module has a package.json for its dependencies, its exports and its tests. It has no build, no server and no separate typecheck. The application typechecks every module’s source and tests as one program. So a module is always checked against the real route table, the real set of services and the real translations, and never against a stub that drifted.

A package is only a boundary if something stops other packages from reaching inside it. That’s where the module’s own layout comes in.

Inside a bounded context

Here is the jobs module, trimmed a little:

packages/jobs/
├── package.json            exports (what the app may use) and "published" (what other modules may use)
└── src/
    ├── index.ts            module definition: translations, navigation entries
    ├── routes.ts           the route table (plain data)
    ├── routes/             React Router route modules: thin loaders/actions and page components
    ├── components/         React components (DTOs in, markup out)
    ├── features/           *.server.ts: the HTTP side; each one runs a use case
    ├── domain/             entities, value objects, domain services: plain values and functions
    ├── application/
    │   ├── ports/          outbound ports (Effect services)
    │   └── use-cases/      Effect programs
    ├── infrastructure/     adapters for the ports
    ├── api.ts              the published API: a service and its DTOs
    └── layer.server.ts     the module's Effect layer

The folders follow the usual DDD layering, and the rules are checked, not just suggested:

• domain/ is pure. It doesn’t import React, UI code or Effect services. domain/match.ts, for example, is a plain, explainable scoring function: skills count most, then job title, then years of experience.
• application/ orchestrates the domain through ports. It never touches React or HTTP.
• Route modules and components never import infrastructure/. A loader calls a function in features/, and that function runs a use case.
• Components get plain DTOs. No domain type ever reaches the browser.

The published API

Each module decides what the rest of the world may see, in two places in its package.json:

{
  "name": "@app/jobs",
  "exports": {
    ".": "./src/index.ts",
    "./api": "./src/api.ts",
    "./layer.server": "./src/layer.server.ts",
    "./routes": "./src/routes.ts",
    "./routes/*": "./src/routes/*"
  },
  "app": {
    "kind": "module",
    "published": ["./api"]
  }
}

exports lists what the application may import: the route table, the route modules, the Effect layer. published is narrower. It lists what other modules may import, and for jobs that’s just ./api. Node, Vite and TypeScript all refuse to resolve a file a package doesn’t export. A lint rule refuses any import from another module that isn’t in its published list.

api.ts is the module’s open host service: an Effect service plus the DTOs it speaks in.

export class JobMatches extends Context.Service<
  JobMatches,
  {
    /** How many jobs near the citizen match their experience strongly (or better). */
    readonly strongMatchesFor: (citizen: AuthUser) => Effect.Effect<number>;
  }
>()('@app/jobs/JobMatches') {}

Two ways to depend on another context

Modules call each other in two different ways, on purpose:

• Customer/supplier. The dashboard owns no data. It asks profile who the citizen is, asks benefits which programs might help, and asks jobs how many postings match. It uses each supplier’s language as-is, because all it does is display the answers.
• Anti-corruption layer. Jobs needs to know about the citizen too, but it thinks in terms of a candidate with skills and years of experience, not a citizen record. So jobs defines its own port in its own language, and exactly one adapter translates profile’s API into it. We’ll see that adapter shortly.

Either way, a call between modules is a plain function call inside one process. There’s no network hop, no serialization and no API version to keep compatible at run time. The contract is still real, though. It’s just enforced at build time and in code review instead of on the wire.

Who enforces all this

A single script, check-boundaries.ts, runs as part of lint. It checks things a reviewer shouldn’t have to spot by eye:

• Direction. Nothing depends on the application. The kernel depends on nothing, and ui depends only on the kernel. The module graph has no cycles.
• Published APIs only. A module may import another module only through an entry listed in published.
• Declared dependencies. If a module imports another workspace package at run time, that package must be in its dependencies, so package.json always shows the real module graph.
• No reaching out. A relative import never leaves its package.
• Layering inside each module, as described above.
• Owned infrastructure. Only the identity module may use the OIDC client or Redis, and only identity may make outbound network calls. Every other module reaches the outside world through a port.
• No dynamic code. An import() of anything but a string literal is allowed in exactly one file, and you’ll meet it near the end.
• Other applications may depend on shared packages only, never on a module.

CODEOWNERS covers the social side. Each module, and each application, belongs to one team. The contract files (api.ts and package.json) belong to an architecture group, so adding an edge to the module graph is a reviewed decision. The boundaries script even checks that CODEOWNERS keeps up: every workspace has an owner, and every contract file is owned by the architecture group alone.

What the script can’t see is GitHub’s side of that file. If a team named in CODEOWNERS doesn’t exist, or can’t write to the repository, GitHub quietly ignores it. The files it was meant to guard then have no code owner at all, and anyone with write access can approve them. So the teams are code too. A small Terraform module, applied with Terragrunt, manages every team CODEOWNERS names, who is in each one, and each team’s access to the repository.

The list of teams lives in one file, .github/code-owner-teams.json. The boundaries script checks CODEOWNERS against it, and the Terragrunt stack reads the same file and passes it to the module, which refuses to plan unless the two match. Here’s that check, simplified a little:

validation {
  condition     = toset(keys(var.teams)) == toset(var.required_team_slugs)
  error_message = "The managed teams must be exactly required_team_slugs (the CODEOWNERS team registry)."
}

So adding a team is one pull request that touches three files: the registry, CODEOWNERS and the stack. Lint checks that the first two agree, and the plan checks the third. The stack is applied before the pull request merges, so CODEOWNERS never names a team that doesn’t exist yet.

A few details make the teams as hard to drift as the code:

• Membership is authoritative. The stack lists who is in each team. Anyone added through GitHub’s settings page is removed on the next apply. Joining a team is a pull request against infra/, which the platform team owns, so it gets reviewed like any other change.
• Every team gets write access. CODEOWNERS ignores an owner that can’t push, so the stack grants it explicitly.
• An empty team fails to plan. An authoritative, empty member list would empty the team on GitHub, and quietly leave its files without an owner.
• Every name has a project prefix, like msca-jobs or msca-architecture, so a team can’t be mistaken for another project’s team in a shared organization.

Two limits, stated plainly. The state is a local file for now, outside the worktree, with no locking between machines. One person applies, and anyone else rebuilds the state by importing what’s already on GitHub. A shared backend comes before production. And the stack doesn’t cover branch protection, the setting that turns a code owner’s review into a requirement.

That covers the layout. Inside each module, though, the interesting part is how the layers connect: the domain is plain code, and everything else reaches the world through ports. That’s where Effect comes in.

Ports and adapters, wired by Effect

If you haven’t used Effect, you need one idea for the rest of this post. An Effect<A, E, R> is a description of a program that succeeds with an A, can fail with a typed error E, and needs the services R before it can run. That third parameter, R, is the one that matters here.

A port is a service

A port is a Context.Service: a typed key plus the interface behind it.

/** Outbound port: the jobs on offer. */
export class JobBoard extends Context.Service<
  JobBoard,
  {
    readonly postings: Effect.Effect<readonly JobPosting[]>;
    readonly find: (jobId: string) => Effect.Effect<Option.Option<JobPosting>>;
  }
>()('@app/jobs/JobBoard') {}

There’s no decorator, no reflection and no container to configure. It’s a class you can yield* from inside an Effect program.

A use case declares its ports in its type

Here is the use case behind /en/jobs:

export const SearchJobs = (request: SearchRequest) =>
  Effect.gen(function* () {
    const user = yield* CurrentUser;
    const candidate = yield* candidateWithSkills(user);
    const shortlist = yield* (yield* Shortlists).find(user.subject);
    const postings = yield* (yield* JobBoard).postings;
    const location = request.location ?? `${candidate.city}, ${candidate.province}`;

    // Pure domain code: filter, score, sort.
    const ranked = rank(postings, candidate, shortlist, { ...request, location });

    return { candidate, location, results: paginate(ranked, request.page ?? 1) /* … */ };
  }).pipe(Effect.withSpan('SearchJobs'));

You don’t write its type by hand. TypeScript infers it:

Effect<SearchResult, never, CurrentUser | CandidateProfiles | SkillProfiles | Shortlists | JobBoard>

That last parameter is the list of ports this use case needs, and the compiler tracks it for you. If you come from Spring, it’s a lot like constructor injection, except the wiring is checked at compile time and not when the context starts. If you add a yield* SomeNewPort and nothing ever provides SomeNewPort, the build fails.

Adapters are layers

An adapter implements a port and is packaged as a Layer. The in-memory job board is about as simple as one gets:

export const layer = Layer.effect(
  JobBoard,
  Effect.gen(function* () {
    const now = yield* Clock.currentTimeMillis;
    const postings = SAMPLES.map(/* date each sample relative to now */);
    return JobBoard.of({
      postings: Effect.succeed(postings),
      find: (jobId) => Effect.succeed(Option.fromNullishOr(postings.find((p) => p.id === jobId))),
    });
  }),
);

The anti-corruption layer is also just an adapter. Jobs has its own port, CandidateProfiles, and this adapter implements it on top of profile’s published CitizenDirectory:

/**
 * Profile's language (a citizen) becomes ours (a candidate with skills and
 * experience) here, and only here: if profile's API changes, this file
 * changes; the jobs domain doesn't.
 */
export const layer = Layer.effect(
  CandidateProfiles,
  Effect.gen(function* () {
    const directory = yield* CitizenDirectory; // profile's published API
    const work = yield* WorkExperience;        // another of jobs' own ports
    return CandidateProfiles.of({
      candidateFor: (citizen) =>
        Effect.gen(function* () {
          const summary = yield* directory.summaryOf(citizen);
          const experience = yield* work.experienceOf(citizen).pipe(
            Effect.catchTag('ExperienceUnavailable', () =>
              Effect.logWarning('employment records unavailable; matching without experience').pipe(
                Effect.as('unavailable' as const),
              ),
            ),
          );
          return toCandidate(summary, experience);
        }),
    });
  }),
);

In the whole jobs module, this is the only file that knows profile’s API exists. It also makes a domain decision at the seam: if employment records are down, jobs still answers, with a candidate flagged as having unknown experience.

Put together, the module looks like a textbook hexagon:

Tests swap a port in one line

Because a port is just a key in R, a test provides whatever it likes for it. Here’s the anti-corruption layer tested against a stand-in for profile and a failing employment-records port:

it.effect('degrades to a candidate flagged as having unreadable experience', () =>
  Effect.gen(function* () {
    const candidate = yield* (yield* CandidateProfiles).candidateFor(USER);
    assert.strictEqual(candidate.experienceUnavailable, true);
    assert.deepStrictEqual(candidate.skills, []);
  }).pipe(
    Effect.provide(
      ProfileCandidates.layer.pipe(
        Layer.provide(
          Layer.mergeAll(
            Layer.succeed(CitizenDirectory, CitizenDirectory.of({
              summaryOf: () => Effect.succeed({ givenName: 'Sam', city: 'Ottawa', province: 'ON' }),
            })),
            Layer.succeed(WorkExperience, WorkExperience.of({
              experienceOf: () => Effect.fail(new ExperienceUnavailable()),
            })),
          ),
        ),
      ),
    ),
  ),
);

There are no mocking libraries and no monkey-patching. The test builds a smaller graph of layers than production does.

So each module ends up handing back one Layer. Something has to put all of those together.

The composition root

A module’s layer.server.ts merges its adapters with the services it publishes:

const Adapters = Layer.mergeAll(
  InMemoryJobBoard.layer,
  InMemoryShortlists.layer,
  InMemoryApplyStores.layer,
  ProfileCandidates.layer.pipe(Layer.provide(EmploymentExperience.layer)),
);

/** Requires profile's CitizenDirectory and employment-records' EmploymentRecords (the application provides them). */
export const layer = Layer.merge(JobMatchesService.layer, JobMatchesService.activityLayer).pipe(
  Layer.provideMerge(Adapters),
);

The published service has one small trick worth showing. JobMatches is built on top of jobs’ own use cases, which need jobs’ private ports. I don’t want those ports showing up in the dashboard’s R just because the dashboard calls JobMatches. So the service captures its dependencies when the layer is built, and provides them itself:

export const layer = Layer.effect(
  JobMatches,
  Effect.gen(function* () {
    const services = yield* Effect.context<CandidateProfiles | JobBoard | Shortlists | SkillProfiles>();
    return JobMatches.of({
      strongMatchesFor: (citizen) => countMatches(citizen, 'strong').pipe(Effect.provideContext(services)),
    });
  }),
);

From the outside, strongMatchesFor returns an Effect<number> that needs nothing. Jobs’ internals stay internal, even at the type level.

Five tiers

The application’s server/runtime.ts stacks every module’s layer in tiers that mirror the module graph:

/** Modules whose layers need no other module's services. */
const Independent = Layer.mergeAll(Identity.layer, Benefits.layer, EmploymentRecords.layer, Payments.layer);

/** Profile reads employment records. The island host reads identity, and manifests through the app's HTTP adapter. */
const Profiled = Layer.mergeAll(Profile.layer, MfeHost.layer.pipe(Layer.provide(HttpManifestSource.layer))).pipe(
  Layer.provideMerge(Independent),
);

/** Jobs reads profile and employment records; employment insurance reads employment records. */
const Services = Layer.mergeAll(Jobs.layer, EmploymentInsurance.layer).pipe(Layer.provideMerge(Profiled));

/** Life events derive from what every service above publishes. */
const Events = LifeEvents.layer.pipe(Layer.provideMerge(Services));

/** The dashboard is the sink: it composes the layers above, and nothing depends on it. */
const Modules = Dashboard.layer.pipe(Layer.provideMerge(Events));

export const AppLayer = Demo.pipe(Layer.provideMerge(Modules));

Two properties fall out of this for free.

A missing service is a compile error. The server only accepts a Layer whose remaining requirements are never. If jobs starts needing a service that no tier provides, AppLayer won’t typecheck.

Bad configuration stops the process at boot. Layers are built once, eagerly, when the process starts. Settings are read with Effect’s Config. A missing setting, a session secret that’s too short, or an identity provider that doesn’t answer means the layer fails to build, and the process exits before it accepts a single request.

Choosing an adapter from configuration is also just a layer:

const stores = { memory: InMemorySessionStore.layer, redis: RedisSessionStore.layer } as const;

export const layer = Layer.unwrap(
  Effect.gen(function* () {
    return Layer.merge(stores[yield* StoreKind], Session.secretLayer); // SESSION_STORE=memory|redis
  }),
);

At this point AppLayer describes the whole application. Next, something has to serve it.

The server is a Layer too

The process entry is one line:

runServer({ layer: AppLayer, wrap: (handler) => withSession(handler) });

and runServer is hardly longer:

export const runServer = <A, E>(options: ServerOptions<A, E>): void => {
  NodeRuntime.runMain(Layer.launch(makeServerLayer(options)), { teardown });
};

The HTTP server itself is a Layer, built with Effect’s platform HTTP modules. NodeRuntime.runMain owns the process: it handles SIGTERM and SIGINT, interrupts the program, and runs every finalizer in reverse order. The custom teardown makes a graceful stop exit with code 0. By default an interrupt exits with 130, which an orchestrator reads as a crash.

Every request passes through a small middleware stack, outermost first:

const middleware = HttpMiddleware.make((app) =>
  Tracing.middleware(RequestId.middleware(HttpMiddleware.logger(app))),
);

• Tracing opens the HTTP server span and continues an incoming traceparent, using OpenTelemetry under the hood.
• RequestId takes a well-formed x-request-id header or generates one. It adds the ID to every log line and to the span, and provides it as a CurrentRequest service. It echoes the header from a pre-response handler, so the header is set even on error responses.
• The logger writes the access log.

A few more details from the server layer:

• It only listens once it can answer. The server loads the SSR bundle (or starts Vite) before it opens the port. If it accepted a connection while it was still loading, that request would hang, and so would a readiness probe.
• In production, hashed assets under /assets/ are served with a one-year immutable cache. Anything that isn’t a file falls through to React Router.
• In development, Vite runs in middleware mode as a scoped resource (Effect.acquireRelease), so it closes when the program’s scope closes. Vite registers its own signal handlers that call process.exit(). The server removes them so that runMain stays the only thing in charge of shutdown.
• There’s no server build step. server.ts runs directly under Node’s built-in TypeScript type stripping.

The session is an Effect wrapper

withSession wraps the React Router handler. It reads a signed __Host- cookie, loads the session from the store, and keeps the request’s session state in a Ref. It provides a CurrentSession service to everything inside. It also registers a pre-response handler that saves the session and sets or clears the cookie, so even an error response gets the cookie right. A session that’s never written is never stored. Tokens from the identity provider never reach the browser. (The island near the end gets a narrower, short-lived token of its own.)

By the time a request reaches the end of this chain, it carries a full Effect context: the application’s services, the server span, the log annotations, CurrentRequest and CurrentSession. Next it goes to React Router, which knows nothing about Effect.

React Router 8 owns the page

React Router runs in framework mode with server rendering on. Its job is everything a page needs: matching URLs, layouts, loaders and actions, rendering, and client-side navigation.

Route config built from packages

Each module declares its pages as plain data:

export const routes = defineModuleRoutes({
  module: 'jobs',
  idPrefix: 'JOB',
  routes: {
    account: [
      { id: 'JOB-0001', file: '@app/jobs/routes/search.tsx', paths: { en: '/en/jobs', fr: '/fr/emplois' } },
      { id: 'JOB-0002', file: '@app/jobs/routes/job.tsx', paths: { en: '/en/jobs/:jobId', fr: '/fr/emplois/:jobId' } },
      // …
    ],
  },
});

A few things to notice:

• file is a package specifier, not a path. While React Router loads its route config, the application resolves each one with require.resolve, through the module’s package exports. So a module decides which of its files are route modules, and a page can’t point into another module’s internals.
• Every page has an English and a French path. The route table comes from our i18n routing library. It fails at startup if an ID is duplicated or a translation is missing. The URL is the only source of the language. We never look at a cookie or the Accept-Language header, and a lint rule bans the helper that would.
• Pages are grouped by area: public, onboarding or account. The area decides which layout wraps the page.

The application’s routes.ts puts everything together:

export default [
  index('routes/language-selection.tsx'),
  ...untranslatedRoutes(routeTables).map(({ id, path, file }) => route(path, toAppFile(file), { id })),
  ...toRouteConfigEntries(resolveRouteFiles(i18nRoutes)),
  route('*', 'routes/not-found.tsx'),
] satisfies RouteConfig;

Layouts and middleware guards

/en/jobs is an account page, so it renders inside the account layout. That layout uses React Router’s middleware to guard every page under it:

export const middleware: Route.MiddlewareFunction[] = [requireSignedIn, requireConsent];

export const loader = ({ context }: Route.LoaderArgs) => ({ user: signedInUser(context) });

requireSignedIn comes from the identity module, and requireConsent comes from profile. The layout doesn’t know how either one works. A signed-out request gets a document redirect to sign in, because signing in leaves the application for the identity provider, and a client-side navigation can’t follow it there. A signed-in request gets the user recorded in the router context. The layout also renders the side navigation, which every module contributes entries to through its defineModule definition.

Thin route modules

The jobs page’s route module barely does anything:

export const loader = ({ context, request }: LoaderFunctionArgs) => loadJobs(context, request);
export const action = ({ context, request }: ActionFunctionArgs) => changeShortlist(context, request);

export default function JobSearchPage() {
  const { results, total, query /* … */ } = useLoaderData<typeof loader>();
  // …render
}

useLoaderData<typeof loader>() gives the component the exact DTO type the loader returns. The search itself is a plain GET form, so its state lives in the URL. It works without JavaScript, and you can bookmark a search. Moving between modules (from jobs to benefits, say) is a client-side navigation inside one React tree and one router. Our end-to-end tests check that crossing every module in the navigation never reloads the document.

That leaves two unanswered questions in that loader. What exactly is context? And how does loadJobs reach SearchJobs, which needs five services that React Router has never heard of?

The bridge

The answer is a small piece of the kernel that joins the two runtimes. Here’s the whole trip for our request:

From Effect to React Router

At the end of the middleware chain, the Effect server hands the request to React Router’s request handler. Before it does, it captures the request’s entire Effect context:

const makeReactRouterHandler = (loadBundle: () => Promise<SsrBundle>) => {
  const handleRequest = createRequestHandler(async () => (await loadBundle()).build, mode);

  return Effect.gen(function* () {
    // This request's services, server span, log annotations, CurrentRequest, CurrentSession…
    const context = yield* Effect.context();

    return yield* HttpEffect.fromWebHandler(async (request) => {
      const bundle = await loadBundle();
      return handleRequest(request, bundle.createAppLoadContext({ context, signal: request.signal }));
    });
  });
};

createAppLoadContext stores that context, together with the request’s abort signal, in React Router’s RouterContextProvider under a typed key:

const requestScopeKey = createContext<RequestScope>();

export const createAppLoadContext = (scope: RequestScope): RouterContextProvider => {
  const context = new RouterContextProvider();
  context.set(requestScopeKey, scope);
  return context;
};

One gotcha here cost me an afternoon. React Router context keys are compared by identity. The key that sets the scope and the key that loaders read it with must be the same object. That only holds if both come from the same module graph. So createAppLoadContext is re-exported from the SSR bundle’s entry, next to React Router’s server build, and the server always takes both from the bundle.

From React Router back to Effect: run()

Loaders, actions and middleware all call one function to get back into Effect. Here it is, simplified a little:

export async function run<A, E extends Tagged, H extends ErrorHandlers<E>>(
  context: Readonly<Pick<RouterContextProvider, 'get'>>,
  effect: Effect.Effect<A, E, BridgeServices>,
  options: { readonly span: string; readonly onError: H },
): Promise<A | ReturnType<H[keyof H]>> {
  const scope = requestScope(context);
  const user = getAuthUser(context);
  const services = user === undefined ? scope.context : Context.add(scope.context, CurrentUser, user);

  const exit = await Effect.runPromiseExitWith(services)(
    effect.pipe(Effect.tapCause((cause) => logOutcome(options.span, cause)), Effect.withSpan(options.span)),
    { signal: scope.signal },
  );

  if (Exit.isSuccess(exit)) return exit.value;          // a plain DTO (or a redirect)
  const failure = Cause.findError(exit.cause);
  if (failure._tag === 'Failure') throw Cause.squash(exit.cause); // defect or interruption: a 500
  return options.onError[failure.success._tag](failure.success);  // a typed failure: its handler
}

It does a few jobs in a small space:

• It runs the effect inside the request’s own context. The use case can yield* any application service, and its spans become children of the HTTP server span. Its log lines carry the request ID.
• It adds CurrentUser. The account layout’s guard recorded the signed-in user in the router context, and run() turns that into a CurrentUser service. That’s why SearchJobs can simply yield* CurrentUser. A module never sees the session, the tokens or the identity provider, only a plain AuthUser.
• It follows the request’s lifetime. If the browser goes away, the abort signal interrupts the running effect. That gets logged at info level, not as an error.
• It keeps three kinds of failure apart. Expected failures are logged at debug level and mapped to a response. Defects are logged as errors and become a 500 through the route’s error boundary. Interruptions are just logged.

So here’s loadJobs, the function the jobs loader calls:

export const loadJobs = (context: Context, request: Request) => {
  const params = new URL(request.url).searchParams;
  const query = (params.get('q') ?? '').slice(0, 100);
  // …parse the rest of the search from the URL

  return run(
    context,
    Effect.gen(function* () {
      const found = yield* SearchJobs({ query, location, savedOnly, province, sort, page });
      return {
        query,
        total: found.results.total,
        results: found.results.items.map(({ posting, score, rating, saved, top }) => ({
          id: posting.id,
          title: posting.title,
          employer: posting.employer,
          score,
          rating,
          // …a plain DTO, nothing from the domain
        })),
      };
    }),
    { span: 'jobs.search', onError: {} },
  );
};

onError: {} is not a shortcut. It’s a statement that SearchJobs can’t fail in an expected way, and the compiler holds us to it. ErrorHandlers is a mapped type with one required handler per error tag:

type ErrorHandlers<E extends { readonly _tag: string }> = {
  readonly [K in E['_tag']]: (error: Extract<E, { readonly _tag: K }>) => ReturnType<typeof data> | Response;
};

If a use case gains a new failure, every call site that doesn’t handle it stops compiling.

A second request: when things can fail

/en/jobs never fails in an interesting way, so let’s look at a different request for a moment. A citizen edits their phone number on their profile, and the form posts back. The ChangeDetail use case can fail in two ways. The domain can reject the value (DetailRejected), or someone may have changed the profile in another tab since this form was opened (RevisionConflict, an optimistic-concurrency check).

return run(context, ChangeDetail(field, value, version).pipe(Effect.map(() => redirect(pageWithout(request, 'edit')))), {
  span: 'profile.details.change',
  onError: {
    DetailRejected: ({ problem }) =>
      data({ fieldError: { field, problem, value }, conflict: false }, { status: 400 }),
    // Someone (another tab, another device) changed the profile since this form was opened.
    RevisionConflict: () => data({ fieldError: null, conflict: true }, { status: 409 }),
  },
});

The use case knows nothing about HTTP status codes. The route module knows nothing about how a phone number is validated. The bridge is the one place where a typed domain failure becomes a 400 or a 409, and the compiler won’t let anyone forget a case.

How the kernel learns about the app

That leaves one puzzle. run() lives in the kernel, and the kernel depends on nothing. Yet run() rejects an effect that needs a service no module provides. How does the kernel know which services exist?

It doesn’t. The application tells it, through TypeScript’s declaration merging:

The kernel declares an empty interface and derives its types from whatever ends up in it:

export interface Register {}

export type BridgeServices = Register extends { readonly services: infer S }
  ? S | CurrentRequest | CurrentUser
  : any;

The application fills it in from app/register.ts:

declare module '@app/kernel/bridge.server' {
  interface Register {
    // Every module's services, plus the per-request session.
    readonly services: Layer.Success<typeof Runtime.AppLayer> | SessionServices;
  }
}

declare module '@app/kernel/routing' {
  interface Register {
    readonly routing: typeof I18nRoutes.i18nRouting;
  }
}

declare module 'i18next' {
  interface CustomTypeOptions {
    readonly defaultNS: 'ui';
    readonly resources: (typeof I18n.resources)['en'];
  }
}

It’s dependency inversion at the type level. Imports only point toward the kernel, but because every module is typechecked inside the application’s program, every module sees the real types:

• run() accepts only effects whose services AppLayer actually provides.
• A link to a page that doesn’t exist, in any module, is a type error, because route keys are those package specifiers.
• A translation key that doesn’t exist is a type error.

One session, kept apart

The bridge gives every use case the request’s whole context, and that context includes the session. Identity needs it, because that’s where it keeps the citizen’s authentication. For every other module, though, a shared session is a risk. There’s one per browser, shared by every module and by every tab the citizen has open. Left alone, it turns into the place where modules quietly pass data to each other, and where two tabs overwrite each other’s work.

So each module gets its own slice of the session, and each tab gets its own slice of that.

A slice per bounded context

Modules still keep the citizen’s real data in their own repositories, keyed by the citizen. The session is only for short-lived state: what someone is doing during this visit. When a module needs that, it asks identity for its own view of the session:

export interface ContextSession {
  readonly context: string;
  readonly get: Effect.Effect<ContextData>;
  /** Replaces this context's slice with `f(current)`. */
  readonly update: (f: (current: ContextData) => ContextData) => Effect.Effect<void>;
  readonly clear: Effect.Effect<void>;
  /** Reads another context's slice; denied unless `owner` is in this context's grants. */
  readonly readFrom: (owner: string) => Effect.Effect<ContextData, SessionAccessDenied>;
}

export const contextSession = (options: {
  readonly context: string;
  /** Other contexts whose slices this one may read. Empty by default. */
  readonly mayReadFrom?: readonly string[];
}): Effect.Effect<ContextSession, never, CurrentSession> => /* … */;

contextSession is in identity’s published list, as ./session.server. The raw CurrentSession service isn’t. The application imports it to type the bridge, but no module can import it, so no module can yield* it. The boundaries script guards it the same way it guards every other module’s internals.

A module reads and writes its own slice, and that’s all it can write. It can read another context’s slice only if it names that context in mayReadFrom. Otherwise readFrom fails with a typed SessionAccessDenied, and the exhaustive onError you saw in the bridge makes the caller decide what that means. Identity’s authentication isn’t a slice, so no grant reaches it. Even the names are checked: a context can’t call its slice __proto__.

A grant is a line of code next to the call, so letting one context look at another’s state shows up in a diff. It can’t happen by accident.

There’s one more constraint, and it comes from running several replicas. During a rolling deployment, a replica may read a session written by an older or a newer version of itself. So the stored shape of the session can only grow. The slices went in as one new optional field, validated on the way in like everything else in the store.

A slice per tab

A slice per context still isn’t enough, because the session belongs to the browser, not to the tab. We already saw this with the profile form, where someone may have changed the profile “in another tab”. The benefits finder ran into it next.

The finder now remembers the citizen’s last search, so coming back to /en/benefits picks up where they left off. Store that search once per session, though, and two tabs fight over it. Search for dental care in one tab and pensions in another, return to the first, and it shows you pensions.

The fix is our tab ID hook. In the page, useTabId() gives each tab a short ID of its own, kept in that tab’s sessionStorage and added to the URL as tid. In the loader, getTabId(request) reads it back. The finder then keeps one selection per tab inside benefits’ slice:

const slice = contextSession({ context: 'benefits' });

export const rememberSelection = (tabId: string, selection: FinderSelection) =>
  Effect.gen(function* () {
    const { update } = yield* slice;
    yield* update((data) => {
      const { [tabId]: _replaced, ...others } = tabsOf(data);
      // Re-inserting last makes the oldest tabs the first to be dropped.
      const kept = Object.entries(others).slice(-(MAX_TABS - 1));
      return { ...data, tabs: { ...Object.fromEntries(kept), [tabId]: selection } };
    });
  });

The loader’s rule is simple. If the URL asks for something (a query, a situation or a view), that’s the tab’s new selection, and it’s stored under the tab’s ID. If the URL asks for nothing, the tab gets its own last selection back. The finder’s own links always name a view, so an otherwise empty URL is never mistaken for “give me my last search”.

A few small details keep this honest:

• A tid that doesn’t look like one the hook generates is ignored. It never becomes a key in the session.
• At most ten tabs are remembered. The oldest is dropped first, so a long day of browsing can’t grow the session without limit.
• Session data is untyped JSON. So each field is parsed again on the way out, like any other input the module didn’t just create.
• The URL still wins. Without JavaScript there’s no tab ID, so the finder just reads the search from the URL, as it always did. A search is still a plain GET form that you can bookmark.

An end-to-end test opens two tabs on one session, searches for something different in each, and checks that each tab gets its own search back.

Resilience and observability at the seams

A modular monolith can still have partial failures. The modules are in-process, but many of their adapters stand in for real back-end systems that will be slow or down some of the time. The dashboard feels this most, because it composes six or seven modules on one page.

The kernel has a tiny helper for that:

export type Part<A> = { readonly state: 'ready'; readonly value: A } | { readonly state: 'unavailable' };

export const settle = <A, E, R>(name: string, effect: Effect.Effect<A, E, R>, timeout = PART_TIMEOUT) =>
  effect.pipe(
    Effect.timeout(timeout),
    Effect.map((value): Part<A> => ({ state: 'ready', value })),
    Effect.catchCause((cause) =>
      Effect.logWarning(`${name} unavailable; showing the page without it`, cause).pipe(
        Effect.as<Part<A>>({ state: 'unavailable' }),
      ),
    ),
  );

The home page’s use case runs each part through it, all at once:

const claim = settle('home: claim', (yield* ClaimStatus).of(user));
const applications = settle('home: job applications', (yield* JobApplicationsGlance).of(user));
const payments = settle('home: payments', (yield* PaymentsGlance).recent(user, 3));
// …

const [claimed, applied, paid, life, matches, news] = yield* Effect.all(
  [claim, applications, payments, lifeEvent, jobMatches, whatsNew],
  { concurrency: 'unbounded' },
);

A typed failure, a defect or a timeout all end up as the same thing: a value the page knows how to render. A slow payments system costs the citizen one card, not the whole page.

Observability comes almost for free from the bridge. Because run() executes inside the request’s context, the trace for our request nests naturally:

GET /en/jobs                       HTTP server span (Tracing middleware)
└── jobs.search                    run() in the loader
    └── SearchJobs                 the use case

Every log line along the way carries the same requestId. Spans can go to the console or to any OTLP endpoint.

Testing failure is part of the design too. In test mode (off by default; when it’s off, these endpoints answer 404), the application exposes two endpoints, both protected by a shared secret. One resets every module to its seed data. The other switches a simulated back-end outage on or off. The composition root implements both on top of each module’s unpublished demo entry. The end-to-end suite uses them to prove that, for example, the dashboard still renders with the payments system down.

One exception: an area that ships on its own

At the start I said every team rides the same release train. That’s true for every module. But one area of this account isn’t really ours. Tax slips belong to the Canada Revenue Agency (CRA): a different organization, with its own team and its own release schedule. The citizen shouldn’t notice any of that. They should see the same header, the same side navigation, the same session and the same language toggle.

So I made one explicit, limited exception: an island. It’s a separate frontend, built and deployed on its own, and mounted inside the account’s chrome under /en/canada-revenue-agency/* and /fr/agence-du-revenu-du-canada/*. It is not the first step toward turning modules into micro-frontends. That isn’t on the table. It’s what we do for the rare area that can’t share our build.

To keep this concrete, here’s a third request: the same citizen opens /en/canada-revenue-agency/slips/T4-2025-0003-1 to look at last year’s T4. Almost everything up to the loader is what you’ve already seen: the account layout, the requireSignedIn and requireConsent middleware, and run(). Only the body of the page is different.

The host is just another module

The host side of the island is an ordinary bounded context, @app/mfe-host, built the same way as every other module. Its domain knows what a remote manifest and a mount path are. Its ports are a RemoteRegistry, a ManifestSource and DelegatedAccess. It reaches identity through an anti-corruption layer, publishes nothing, and sits in the second tier of the composition root, next to profile.

Its route table owns one splat page per remote:

account: [
  {
    id: 'MFE-0001',
    file: '@app/mfe-host/routes/cra-tax-slips.tsx',
    paths: { en: '/en/canada-revenue-agency/*', fr: '/fr/agence-du-revenu-du-canada/*' },
  },
],

Because it’s an account page, it gets the account layout and its guards for free. Everything under the prefix belongs to the island.

The island itself is a second application, apps/cra-tax-slips/, with its own build, its own container image, its own deployment and its own team in CODEOWNERS. The boundaries script has a rule for it: an application other than the main one may depend on shared packages only. It can’t import a module, published API or not.

The contract is a package with no dependencies

The only thing the host and the island share is a small package, @app/mfe-contract. It has no dependencies at all. The kernel can’t hold it, because the kernel imports React and the island doesn’t use React.

export const MOUNT_CONTRACT = 'app-mfe/1';

export interface MountContext {
  /** The host path the remote owns: `/en/canada-revenue-agency`. */
  readonly basename: string;
  /** A change of language is a new document, so a new mount. */
  readonly language: 'en' | 'fr';
  /** The host owns history. A target outside `basename` is refused. */
  navigate(to: string, options?: { readonly replace?: boolean }): void;
  /** A short-lived bearer token for the remote's API. */
  getAccessToken(): Promise<string>;
  /** Called on every host navigation under `basename`. Returns an unsubscribe. */
  onLocationChange(listener: (location: MountLocation) => void): () => void;
}

/** Idempotent: aborts in-flight work, removes listeners and empties what it rendered. */
export type Unmount = () => void;

export interface RemoteModule {
  readonly contract: string;
  mount(el: HTMLElement, ctx: MountContext): Unmount;
}

If you come from Java, think of it as an SPI jar: one interface, implemented on the other side of a deployment boundary. Versioning is deliberately strict. The host accepts the same major version only. A minor version may add optional fields and nothing else. A breaking change becomes app-mfe/2, and the host then supports both versions while remotes migrate.

This is the one place in the post where a boundary is checked at run time instead of by the compiler. The compiler still checks each side against the contract. What it can’t check is that the code the host loads tomorrow was built against the same version. A version check and an integrity hash do that job instead.

One router

The island lives in the host’s page, so it must not fight the host over the URL. The host’s React Router owns the browser’s history, and the island never calls history.pushState itself. Its own paths are language-neutral (/ and /slips/:slipId). When it wants to move, it asks:

navigate: (to, options = {}) => {
  const target = withinBasename(basename, to);
  if (target === undefined) {
    console.warn(`refused a remote's navigation outside ${basename}`);
    return;
  }
  void latest.current.navigate(target, { replace: options.replace === true });
},

onLocationChange is there for the other direction. React Router’s pushState fires no popstate event, so without a callback the island couldn’t follow the host’s own links: the side navigation, back and forward. The host’s outlet watches useLocation() and tells the island whenever the path is still under its prefix.

The language toggle swaps only the bilingual prefix (/en/canada-revenue-agency becomes /fr/agence-du-revenu-du-canada), keeps the rest of the path and reloads the document. A new language is simply a new mount. The end-to-end tests check that the side navigation can move into and out of the island without reloading the document, and that the toggle keeps the slip that was open.

A different runtime, the same architecture

The island uses Preact, not React, and it uses neither Effect nor our design system. That’s on purpose. A different runtime proves the two sides really share nothing: no shared React, no clash between two copies of React’s hooks, and no import maps or Module Federation to keep in step. Preact is about 4 KB, and its TSX looks familiar.

Inside, though, it’s built the way everything else in this post is built: a domain/ (tax slips, tax years, money), an application/ with ports (TaxSlipsApi, AccessTokenProvider, Navigator) and use cases, infrastructure/ adapters, a ui/, and a composition root for each mount. The boundaries script’s layering rule now covers it too: no Preact in domain/ or application/.

The entry the host loads is tiny:

export const contract: string = MOUNT_CONTRACT;

export const mount = (el: HTMLElement, ctx: MountContext): Unmount =>
  createMount({ css, api: (tokens) => new HttpTaxSlipsApi(apiBase(), tokens) })(el, ctx);

createMount attaches an open shadow root to el and puts the island’s styles inside it. That keeps the island’s CSS from leaking out, and the host’s CSS from leaking in. The exceptions are inherited fonts, colours and CSS custom properties, which is what we want. To be clear, the shadow root only scopes styles. The island’s script can still reach document like any other script on the page.

Each mount also gets one AbortController, which Unmount aborts synchronously. Preact runs effect cleanups after the next paint, and I didn’t want a request from a page the citizen has already left to land after that.

Finding and loading code you didn’t compile

This is the part that needs the most care. The host is about to run JavaScript it didn’t build.

The trust starts in the host’s code, not in configuration. The host keeps a registry of approved remotes, and for each one it fixes the contract’s major version, the API audience and the scopes the island may be given. Only the URLs come from configuration, and only their origins are allowed. The island’s build publishes a manifest beside its one hashed entry file:

{
  "id": "cra-tax-slips",
  "contract": "app-mfe/1",
  "entry": "mount.CQsOWGlR.js",
  "integrity": "sha384-75dc/UUMp40U9yBX7sjtF7Uy243rZNhCyzB0JgHMMuNn7KqSWtEJYDOipLmBXWcR",
  "api": { "baseUrl": "api/v1/", "audience": "cra-tax-slips-api", "scopes": ["tax-slips:read"] }
}

On the server, the page’s loader runs a ResolveRemoteMount use case through run(). It reads the manifest through the ManifestSource port and treats it as untrusted input. It parses every field and checks the result against the registry: the same contract major version, the same audience, and an entry and API on the approved origin over HTTPS. A manifest can’t approve a new origin or ask for a wider scope.

The HTTP adapter for that port lives in the composition root, not in the module, because modules don’t touch the network. It allows 1.5 seconds, refuses redirects (so a manifest can’t send the host somewhere else), caps the size at 64 KB and caches a good answer for a minute.

Every way this can go wrong is a typed error, and the loader turns each one into a state the page can render:

ResolveRemoteMount('cra-tax-slips').pipe(
  Effect.map((remote): RemotePage => ({ state: 'ready', remote, basename, language })),
  Effect.catchTags({
    RemoteNotRegistered: () => unavailable('not registered'),
    RemoteUnavailable: ({ reason }) => unavailable(reason),
    ManifestInvalid: ({ reason }) => unavailable(`invalid manifest: ${reason}`),
    OriginNotApproved: ({ url }) => unavailable(`unapproved origin: ${url}`),
    RemoteIncompatible: () => incompatible(),
  }),
)

What reaches the browser is an entry URL and its integrity hash. There’s no token and nothing secret. Server rendering stops at the host’s chrome, the heading and a loading state. The island renders in the browser.

In the browser, the host’s outlet loads the entry in two steps:

// The one place in the repository allowed to import() a URL it doesn't know at build time.
await preload(entryUrl, integrity, timeoutMs); // <link rel="modulepreload" integrity="…" crossorigin>
const loaded: unknown = await import(/* @vite-ignore */ entryUrl);
if (!isRemoteModule(loaded)) throw new RemoteLoadFailed(`${entryUrl} does not export this host's mount contract`);

The browser checks the preloaded bytes against the hash before anything runs. If the hash doesn’t match, the network fails or the load times out, the outlet stops. None of the island’s code runs. This is what the boundaries script’s “no dynamic code” rule protects: a non-literal import() is allowed in exactly this one file.

Integrity checks are easy to oversell, so here’s exactly what this one covers. It stops a stale, swapped or tampered entry file from running in place of the one the manifest names. The island’s build enforces a single entry chunk, so that hash covers all of its code. It does not protect against someone who controls the island’s own server, because they could change the manifest and the entry together.

One React Router detail is worth stealing. The page’s descriptor doesn’t change while the citizen moves around inside the island, or when the island asks for a token. Neither should reload the loader, because that would remount the island:

export const shouldRevalidate: ShouldRevalidateFunction = ({ formAction, formMethod, currentUrl, nextUrl, defaultShouldRevalidate }) => {
  if (formAction?.startsWith(ACCESS_PREFIX) === true) return false; // a token request
  if (formMethod === undefined && currentUrl.href !== nextUrl.href) return false; // moving inside the island
  return defaultShouldRevalidate;
};

The one token that reaches the browser

Earlier I wrote that tokens from the identity provider never reach the browser. That’s still true, and neither does the session. But the island’s API is served by another deployment, and it needs to know who’s asking. So the island gets a different, much narrower token. It is the one documented exception to the rule.

Identity mints it. The identity module publishes a DelegatedTokenIssuer over a DelegationSigner port. The local adapter signs with an ES256 key of its own, which isn’t the session secret or the OIDC client key, and identity serves the public half as a JWKS. The subject always comes from the request’s CurrentUser. A caller can name only the audience and the scopes, and the host takes those from its registry. The host reaches all this through its own anti-corruption layer, just as jobs reaches profile.

The browser asks for a token with a React Router fetcher posting to a host route, POST /mfe-access/:remoteId, so the host module still never calls fetch itself. That route checks, in order:

1. The method is POST. Otherwise it answers 405.
2. The Origin header is the host’s own origin. Otherwise 403. This stops cross-site callers. It doesn’t, and can’t, tell the island apart from the rest of the page.
3. The body doesn’t try to choose a subject, an audience or a scope. Otherwise 400.
4. A citizen is signed in. Otherwise 401, as data and not a redirect, because a script asked, not a person.
5. The citizen has consented. Otherwise 403.

Then it runs GrantRemoteAccess through run(), with the same exhaustive onError you saw earlier: an unknown remote is a 404, a refusal a 403, and an unavailable signer a 503. Every answer is Cache-Control: no-store.

The token itself is as small as I could make it. It uses the at+jwt type from RFC 9068 and ES256 with a key ID. It names one audience (the island’s API) and one scope (tax-slips:read), and it lives for at most 120 seconds. It has a random jti and no name, email, session ID or identity-provider token. It never appears in loader data, HTML, URLs, web storage or logs. The island keeps it in a closure for one mount, reuses it until 15 seconds before it expires, and drops it when it unmounts.

The island’s API verifies the token against the host’s JWKS and trusts nothing else:

const { payload } = await jwtVerify(token, keys, {
  algorithms: ['ES256'],
  typ: 'at+jwt',
  issuer,
  audience,
  clockTolerance: 5,
  requiredClaims: ['sub', 'exp', 'iat', 'scope'],
});

It then checks the scope and selects records by the verified subject only. Asking for another citizen’s slip gets a “not found”, and there’s an end-to-end test for that.

Here’s what I accepted, stated plainly. This is a bearer token, not one bound to the sender. While it lives, any script on the page can read it. It can’t be revoked, so it stays valid for up to two minutes after the citizen signs out. The alternative is a backend-for-frontend in identity that proxies the island’s API. That keeps the token on the server, but it changes the contract and puts the island’s traffic through our deployment. For a proof of concept with synthetic data, two minutes was an acceptable price. Before production it gets another look, along with whether the subject should be a pairwise identifier per audience.

When the island is down

The island fails like any other part of the page: in its own space. If the manifest can’t be read, doesn’t parse, names an unapproved origin or speaks another major version, the page still answers 200. The chrome, the side navigation and the language toggle all work, and the page shows a localized notice with a Try again button. If the entry itself fails to load or throws while mounting, the outlet shows the same notice.

Two details make Try again actually work. A browser remembers a failed module URL for the life of the document, so a retry adds ?attempt=N to the URL. And a result that arrives after the citizen has left the page is never mounted.

By default the host doesn’t read any manifests at all, so it boots and stays ready without the island. In that mode the tax slips page simply shows its notice. The end-to-end tests cover the outage, the recovery, and a tampered entry that must fail closed.

A piece of the island on someone else’s page

The island owns a whole subtree of paths, and sometimes that’s more than you need. The dashboard wanted a “Latest tax slips” tile on the account’s home page, beside its own tiles for EI, jobs and payments. The tile’s data, code and release schedule are all CRA’s. The page around it is the dashboard’s.

So a remote can now export fragments as well: small pieces that a module’s page shows in a slot, with no path of their own.

Mounting one turned out to be the easy part. The hard part was the module graph. mfe-host publishes nothing, and that’s deliberate. The dashboard could import it without breaking a rule, but the host already depends on identity and profile. The day profile wanted a fragment, the graph would have a cycle. Besides, a module has no business knowing about manifests and entry URLs.

The way out is the same inversion the kernel already uses for its types. The kernel declares a slot, and the application fills it:

/** The fragments a module's page may show, as `<remote>/<fragment>`. */
export interface RemoteFragmentRegister {
  readonly 'cra-tax-slips/latest-slips': true;
}

export type RemoteFragmentId = keyof RemoteFragmentRegister;

/** Provided by the application's signed-in layout; absent in tests and outside it. */
export const RemoteFragmentContext = createContext<ComponentType<RemoteFragmentContentProps> | undefined>(undefined);

The dashboard renders the kernel’s RemoteFragment and names the fragment it wants. It owns the frame and the heading, and it passes the translated text:

<RemoteFragment id="cra-tax-slips/latest-slips" as="li" heading={t('home.tiles.slips.heading')} headingLevel={3} />

The account layout provides the host’s implementation, so every account page gets it and nothing else does:

<RemoteFragmentContext value={FragmentSlot}>
  <AppChrome user={loaderData.user}>{/* … */}</AppChrome>
</RemoteFragmentContext>

A module names a fragment. It never sees an entry URL, an integrity hash or a token. An identifier that isn’t in the register is a type error, just like a link to a page that doesn’t exist. The register lives in the kernel and belongs to the architecture group, so putting a fragment on a page is a reviewed decision. That’s governance, not authorization, though: the token route can’t tell which page asked. The boundaries script has tests for both halves. Any module may render the slot through the kernel with no new module edge, and a module that imports mfe-host is still refused.

Fragments are an optional addition to the remote’s entry, with a protocol of their own, app-mfe-fragment/1:

export interface FragmentContext {
  readonly language: 'en' | 'fr';
  /** The heading level the host's frame uses, so the fragment nests below it. */
  readonly headingLevel: 2 | 3 | 4 | 5 | 6;
  getAccessToken(): Promise<string>;
  /** A host-approved destination inside the remote's own page, as an href; undefined if not approved. */
  href(destination: string): string | undefined;
  navigate(destination: string): void;
}

export interface RemoteModule {
  readonly contract: string;
  mount(el: HTMLElement, ctx: MountContext): Unmount;
  readonly fragments?: Readonly<Record<string, RemoteFragment>>;
}

A fragment gets less than a page does. It owns no path, so it has no basename, no onLocationChange and no free-form navigate. It can only link into the remote’s own page, and the host refuses anything else. The page contract stays at app-mfe/1, so a page-only remote and an older host both keep working. The fragment protocol can change without forcing every page to migrate.

The slot resolves its fragment in the browser, after hydration. Server rendering produces the frame, the heading and a placeholder sized for the content, so the page barely shifts when the tile arrives. The dashboard’s loader doesn’t change at all, which keeps a slow manifest out of the page’s loader. Instead, the host’s outlet asks a host resource route, GET /mfe-fragments/:remoteId/:fragmentId, for a descriptor: the entry URL, its integrity hash, the protocol and a state. Never a token. That route runs a ResolveFragmentMount use case through run(), which adds three gates to the page’s checks:

1. The host’s registry approves the fragment. It’s listed in code, next to the remote’s audience and scopes, and it’s checked before any manifest is read.
2. The manifest declares it, with a fragment protocol the host supports.
3. The loaded entry exports it, again with a supported protocol.

A manifest can’t add a fragment on its own. From there, the entry loads through the same integrity-checked path as the page. One entry exports the page and every fragment, so the single-chunk rule and its hash still cover all of the island’s code. The browser downloads that entry once, however many slots (or the page) ask for it.

A fragment gets its token from the same POST /mfe-access/:remoteId route, with the remote’s scopes. That means its token is exactly as powerful as the page’s. That’s acceptable while CRA is read-only. The registry already reserves per-fragment scopes, checked at boot to be a subset of the remote’s, for the day a remote gains a write scope. There’s one React Router change here too. On the island’s own page, shouldRevalidate stopped a token request from re-running loaders. On the dashboard, nothing did, so the token fetcher now submits with defaultShouldRevalidate: false, and a token request re-runs no loader anywhere.

A fragment fails the way the island does, only in a smaller space. If the descriptor can’t be had, the hash doesn’t match, the mount throws or the fragment’s API call fails, the tile shows a localized notice with Try again, and the page still answers 200. The notice doesn’t announce itself as an alert or steal focus, because it’s one tile on a busy page. Signed out or without consent, the tile shows a plain message and never redirects. Even the host’s outlet code is loaded lazily, so if that download fails, only the slot notices.

Deploys needed one more piece of care. The entry’s file name is a hash, so every release replaces it. A dashboard opened before a deploy may still hold a descriptor that names the old entry. So the remote keeps serving previous releases’ entries from a retained directory, which a retain step fills in its release pipeline. Manifests are never served from there. Rollouts go remote first, host second, and MFE_FRAGMENTS=off turns every slot off without redeploying the host. A value that isn’t valid also means off.

Finally, every response now carries a Content Security Policy in report-only mode. Its script-src and connect-src come from the registry: 'self' plus each approved remote’s origin. It can’t be enforced yet, because 'unsafe-inline' stays in script-src until server-rendered scripts carry nonces. Until then, it reports violations to a host route, where they’re logged.

An integration boundary, not a sandbox

One last caveat, and it’s the most important. Once mounted, the island runs with the host origin’s privileges. It runs in the same document, with the same cookies, the same DOM and the same token route. In the cluster, its server is even served from the host’s origin, so it’s trusted as well. The mount contract is an integration boundary. It is not a sandbox.

The registry, the origin allow-list, the integrity check and the Content Security Policy (report-only, for now) all stop unapproved code from running. None of them stops approved code that turns malicious. Fragments widen that exposure: they run third-party-built code on the account’s busiest page, and they ask for tokens more often. That’s why only approved remotes from allow-listed origins are registered, and why the data is synthetic for now. A truly untrusted third party would need an iframe and a different contract.

The island is a deliberate trade. It buys one area its own release schedule, and it pays with a run-time contract, a token flow and a trust decision that someone has to own. That’s exactly the kind of cost the rest of this post avoids, which is why it’s an exception and not a pattern.

What we gave up, and what we got

The cost is real. Every team ships together, and one team’s broken build blocks everyone. Being disciplined about main and having a fast check command (typecheck, lint, boundaries, format and unit tests in one go) matter more here than they would elsewhere. The island is the escape hatch, and the previous section showed what it costs.

What we got back is everything that tends to make split deployments expensive: no per-area platform, no session format that several independently released apps have to agree on, no composition layer, and one developer experience. The boundaries didn’t go away. They moved somewhere cheaper to check.

This design is probably not right if most of your teams need independent release cadences. One or two areas can be islands, but each one adds a run-time contract, a token flow and a trust decision, and a dozen of them means you want a different architecture. It’s also not right if your teams work in different languages or runtimes on the server, or if one area needs to scale very differently from the others. In those cases the network is earning its keep.

Wrapping up

The ideas aren’t new: bounded contexts, published languages, anti-corruption layers, ports and adapters, and a composition root. What made them cheap enough to apply everywhere was the tooling:

• Packages and their exports turn bounded contexts into something Node, Vite and TypeScript enforce.
• Effect’s R parameter and its layers turn hexagonal architecture into something the compiler checks, with no container and no reflection.
• The Effect runtime owns the process and the HTTP edge: startup, configuration, shutdown, tracing and sessions.
• React Router 8 owns the page: routes from packages, layouts, middleware guards and thin loaders.
• A small bridge carries one typed request context from the socket, through Effect and React Router, into a use case and back, and it maps every expected failure exhaustively.
• One session, sliced per bounded context and per tab, so modules and tabs share a sign-in without sharing state.
• One explicit exception, an island with its own build and a versioned mount contract, lets the one area that must ship alone do so without a second router, a second session or a second account. Its fragments even let it lend a tile to a module’s page without either side importing the other.

If you take one thing from this post, I’d make it this: a boundary the compiler checks is cheaper than one the network enforces, and usually more honest too. When a boundary really does have to move to run time, make it one explicit exception, and write down exactly what its checks promise and what they don’t.

You need this any time the user’s identity has to carry across service boundaries. A gateway calls an orders API, and the orders API calls a CRM. Or a web app calls a backend, and that backend needs to read from a secure internal data service using the caller’s delegated permissions (“delegated” means the app acts with the user’s permissions, not its own). In each case the downstream system should get a token meant for it, not a token minted for something else.

In this post I’ll walk through a Spring Boot pattern that keeps the exchange logic out of your business code. The idea is simple. Put the OBO exchange behind a customized RestClient, let Spring Security fetch the token, and add a small cache so you don’t hit the token endpoint on every downstream request.

What the flow needs to do

At runtime, a request goes through these steps:

1. A user calls your API with a JWT access token.
2. Your application authenticates that token as usual.
3. A downstream client inside your API makes an HTTP call through a RestClient.
4. An OAuth2 interceptor asks for an access token for the downstream API.
5. A custom OBO provider takes the incoming JWT, sends it to Entra ID with requested_token_use=on_behalf_of, and gets back a new access token.
6. The RestClient sends the downstream request with that new token.

What I like here is where this happens. Your use case code stays boring: it calls a typed client. The typed client knows nothing about parsing JWTs or calling token endpoints. The infrastructure layer owns that problem.

Why RestClient is a good fit

You could do the OBO exchange in a service class, in a filter, or in a custom HTTP client wrapper that does everything itself. I don’t like any of those.

Putting it behind RestClient gives you a cleaner boundary. The application service depends on a downstream port or a typed client. Authentication stays in the infrastructure layer. A token is only fetched when you actually make a downstream call, and Spring Security still handles the OAuth2 protocol details.

That separation is why the pattern holds up. The domain code doesn’t know what Entra ID is. The controller doesn’t fetch tokens by hand. The HTTP client doesn’t contain business logic. Each layer has one job.

How the pieces fit together

In a typical hexagonal Spring Boot app (one where business logic talks to the outside world only through interfaces called ports), the pieces look like this:

• OrderService, or some other application service, calls a downstream port.
• DownstreamApiClient is a small infrastructure wrapper around RestClient.
• OAuth2ClientHttpRequestInterceptor gets tokens when requests leave the process.
• DownstreamOboTokenProvider teaches Spring Security how to do the Entra ID OBO exchange.
• OboTokenCache reuses exchanged tokens for the same source JWT until either token is close to expiring.

This gives you one narrow seam to test and one obvious place to put operational safeguards.

Start with a typed RestClient

First, hide the raw HTTP details behind a client that represents the downstream dependency. The business layer should call methods, not build URLs by hand.

public final class DownstreamApiClient {

    private final RestClient restClient;

    public DownstreamApiClient(
            String baseUrl,
            Collection<ClientHttpRequestInterceptor> interceptors) {
        this.restClient = RestClient.builder()
            .baseUrl(baseUrl)
            .requestInterceptors(chain -> chain.addAll(interceptors))
            .build();
    }

    public List<OrderSummary> getOrdersForCustomer(String customerId) {
        return restClient.get()
            .uri(uriBuilder -> uriBuilder
              .path("/orders")
              .queryParam("customerId", customerId)
              .build())
            .retrieve()
            .body(OrderSummary.class);
    }

}

This is thin on purpose. It only handles HTTP wiring and turning the response into objects. It knows nothing about Entra ID. That part comes from the interceptor you pass in.

Wire OBO into the RestClient, not your service layer

The cleanest place to put all of this together is an auto-configuration or a dedicated configuration class.

@ConfigurationProperties("app.downstream")
public record DownstreamApiProperties(
    String baseUrl,
    CacheProperties cache,
    OAuthProperties oauth
) {

    public record CacheProperties(Boolean enabled, Duration expirySkew, Integer maximumSize) {}
    public record OAuthProperties(String clientId, String clientSecret, String tokenUrl, String scope) {}

}

@AutoConfiguration
@EnableConfigurationProperties({ DownstreamApiProperties.class })
@ConditionalOnProperty(prefix = "app.downstream", name = "base-url")
public class DownstreamApiAutoConfiguration {

    @Bean
    protected DownstreamApiClient downstreamApiClient(
            ObjectProvider<OboTokenCache> cacheProvider,
            DownstreamApiProperties properties) {

        final var clientRegistration = ClientRegistration
            .withRegistrationId(DownstreamOboTokenProvider.CLIENT_REGISTRATION_ID)
            .clientId(requiredOauth(properties).clientId())
            .clientSecret(requiredOauth(properties).clientSecret())
            .clientAuthenticationMethod(ClientAuthenticationMethod.CLIENT_SECRET_POST)
            .authorizationGrantType(AuthorizationGrantType.JWT_BEARER)
            .scope(requiredOauth(properties).scope())
            .tokenUri(requiredOauth(properties).tokenUrl())
            .build();

        final var registrations = new InMemoryClientRegistrationRepository(clientRegistration);

        final var manager = new AuthorizedClientServiceOAuth2AuthorizedClientManager(
            registrations,
            new NoOpAuthorizedClientService()
        );

        manager.setAuthorizedClientProvider(
            new DownstreamOboTokenProvider(cacheProvider.getIfAvailable())
        );

        final var oauth2 = new OAuth2ClientHttpRequestInterceptor(manager);
        oauth2.setClientRegistrationIdResolver(_ -> DownstreamOboTokenProvider.CLIENT_REGISTRATION_ID);
        oauth2.setPrincipalResolver(new SecurityContextHolderPrincipalResolver());

        return new DownstreamApiClient(
            properties.baseUrl(),
            List.of(oauth2)
        );
    }

    private DownstreamApiProperties.OAuthProperties requiredOauth(DownstreamApiProperties properties) {
        final var oauth = properties.oauth();

        if (oauth == null) {
            throw new IllegalStateException(
                "Downstream OAuth properties must be configured when app.downstream.base-url is set"
            );
        }

        final var missing = new ArrayList<String>();
        addIfMissing(oauth.clientId(), "app.downstream.oauth.client-id", missing);
        addIfMissing(oauth.clientSecret(), "app.downstream.oauth.client-secret", missing);
        addIfMissing(oauth.tokenUrl(), "app.downstream.oauth.token-url", missing);
        addIfMissing(oauth.scope(), "app.downstream.oauth.scope", missing);

        if (!missing.isEmpty()) {
            throw new IllegalStateException(
                "Downstream OAuth properties must be configured. Missing or blank properties: "
                + String.join(", ", missing)
            );
        }

        return oauth;
    }

    private void addIfMissing(String value, String name, List<String> missing) {
        if (value == null || value.isBlank()) { missing.add(name); }
    }

}

A few details here are worth pointing out.

The client registration uses AuthorizationGrantType.JWT_BEARER. That’s the grant type Spring Security uses for the OBO exchange. The SecurityContextHolderPrincipalResolver tells the interceptor to use the currently authenticated user for the outgoing request. And the startup validation fails fast, listing exactly which properties are missing. That sounds minor until you’re debugging a bad deployment at 4 a.m. on a Saturday night.

I also prefer the no-op authorized-client service here. OBO is driven by the current request’s user token, so I want token reuse to be explicit and limited to the dedicated OBO cache, not hidden inside a generic client store.

Get the incoming token from the authenticated principal

After the resource server authenticates the request, the incoming JWT is already in the security context. Don’t dig it out of the request headers in your service code. Let Spring Security hand it to the authorized-client provider.

public final class DownstreamOboTokenProvider implements OAuth2AuthorizedClientProvider {

    public static final String CLIENT_REGISTRATION_ID = "downstream-api";

    private final JwtBearerOAuth2AuthorizedClientProvider delegate;

    private final OboTokenCache tokenCache;

    public DownstreamOboTokenProvider(OboTokenCache tokenCache) {
        this.tokenCache = tokenCache;

        final var messageConverter = new OAuth2AccessTokenResponseHttpMessageConverter();

        final var tokenRestClient = RestClient.builder()
            .configureMessageConverters(converters -> converters.addCustomConverter(messageConverter))
            .build();

        final var responseClient = new RestClientJwtBearerTokenResponseClient();
        responseClient.setRestClient(tokenRestClient);
        responseClient.setParametersCustomizer(parameters ->
            parameters.set("requested_token_use", "on_behalf_of")
        );

        this.delegate = new JwtBearerOAuth2AuthorizedClientProvider();
        this.delegate.setAccessTokenResponseClient(responseClient);
        this.delegate.setJwtAssertionResolver(context ->
            Optional.ofNullable(context.getPrincipal())
                .filter(JwtAuthenticationToken.class::isInstance)
                .map(JwtAuthenticationToken.class::cast)
                .map(JwtAuthenticationToken::getToken)
                .orElseThrow(() -> new IllegalStateException(
                    "No JwtAuthenticationToken found in authorization context for downstream OBO exchange"
                ))
        );
    }

    @Override
    public OAuth2AuthorizedClient authorize(OAuth2AuthorizationContext context) {
        Objects.requireNonNull(context, "context cannot be null");

        if (!CLIENT_REGISTRATION_ID.equals(context.getClientRegistration().getRegistrationId())) {
            return null;
        }

        if (!(context.getPrincipal() instanceof JwtAuthenticationToken authentication)) {
            return null;
        }

        if (tokenCache != null) {
            return tokenCache.get(authentication.getToken(), () -> delegate.authorize(context));
        }

        return delegate.authorize(context);
    }

}

Two things make this safe to run in production.

The first is the jwtAssertionResolver. It makes sure the token sent in the exchange (the “assertion”) comes from the authenticated JwtAuthenticationToken, not from some ad hoc thread-local or request attribute. If there’s no JWT-backed principal, the flow fails with a clear error.

The second is the parameter customizer. Entra ID expects requested_token_use=on_behalf_of on the token request. If you leave it out, you aren’t doing OBO. You’re just sending a JWT bearer token request and hoping Entra guesses what you meant.

What Entra ID actually receives

With this setup, the token request body looks roughly like this:

grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer
requested_token_use=on_behalf_of
assertion=<incoming user access token>
client_id=<your confidential client id>
client_secret=<your client secret>
scope=api://downstream-api/.default

Each field has a job. The assertion is the original user token. The client ID and secret identify your API as the confidential client making the exchange. The scope points at the downstream API, not the current one. And the on-behalf-of flag tells Entra ID what kind of exchange you want.

If the downstream API permissions are wrong, or the app registrations aren’t set up to trust each other, this request fails. That’s a configuration problem, not a code problem.

Add a cache or you’ll exchange too often

Without a cache, every downstream call can trigger a token exchange. It works, but it’s noisy, slower than it needs to be, and puts extra load on the token endpoint.

The cache I like is deliberately narrow. It stores exchanged authorized clients keyed by the source JWT’s issuer, its subject, and a SHA-256 fingerprint (hash) of the raw token. Each entry expires at whichever comes first: the source JWT’s expiry or the exchanged access token’s expiry. A small skew is subtracted from that time before the entry counts as reusable.

public final class OboTokenCache {

    private record CacheKey(String issuer, String subject, String tokenFingerprint) {}
    private record CachedAuthorizedClient(OAuth2AuthorizedClient client, Instant expiresAt) {}

    private final Cache cache;

    private final Duration expirySkew;

    private final Clock clock;

    public OAuth2AuthorizedClient get(
            Jwt jwt,
            Supplier<OAuth2AuthorizedClient> authorizedClientProvider) {
        final var sourceExpiresAt = Optional.ofNullable(jwt.getExpiresAt())
            .orElseGet(() -> Instant.now(clock).plus(Duration.ofHours(1)));

        return cacheKey(jwt)
            .map(key -> getOrExchange(key, sourceExpiresAt, authorizedClientProvider))
            .orElseGet(authorizedClientProvider);
    }

    private OAuth2AuthorizedClient getOrExchange(
            CacheKey key,
            Instant sourceExpiresAt,
            Supplier<OAuth2AuthorizedClient> authorizedClientProvider) {
        final var now = Instant.now(clock);
        final var cached = getCachedEntry(key, now).map(CachedAuthorizedClient::client);

        if (cached.isPresent()) { return cached.get(); }

        return getCachedEntry(key, Instant.now(clock))
            .map(CachedAuthorizedClient::client)
            .orElseGet(() -> {
                final var authorizedClient = authorizedClientProvider.get();
                cacheAuthorizedClient(key, sourceExpiresAt, authorizedClient);
                return authorizedClient;
            });
    }

    private void cacheAuthorizedClient(
            CacheKey key,
            Instant sourceExpiresAt,
            OAuth2AuthorizedClient authorizedClient) {
        if (authorizedClient == null || authorizedClient.getAccessToken() == null) {
            return;
        }

        final var accessTokenExpiresAt = authorizedClient.getAccessToken().getExpiresAt();
        if (accessTokenExpiresAt == null) {
            return;
        }

        final var earliestExpiresAt = sourceExpiresAt.isBefore(accessTokenExpiresAt)
            ? sourceExpiresAt
            : accessTokenExpiresAt;

        final var effectiveExpiresAt = earliestExpiresAt.minus(expirySkew);

        if (effectiveExpiresAt.isBefore(Instant.now(clock))) {
            return;
        }

        cache.put(key, new CachedAuthorizedClient(authorizedClient, effectiveExpiresAt));
    }

    private Optional<CacheKey> cacheKey(Jwt jwt) {
        if (!StringUtils.hasText(jwt.getTokenValue())) {
            return Optional.empty();
        }

        if (!StringUtils.hasText(jwt.getSubject())) {
            return Optional.empty();
        }

        final var issuer = Optional.ofNullable(jwt.getIssuer()).map(Object::toString).orElse("");
        if (!StringUtils.hasText(issuer)) {
            return Optional.empty();
        }

        return Optional.of(new CacheKey(issuer, jwt.getSubject(), sha256(jwt.getTokenValue())));
    }

}

There are three practical ideas in that code.

First, the cache key includes a fingerprint of the raw incoming token. When the user’s token rotates, the old cache entry stops being used. That’s what you want.

Second, the expiry is based on whichever token expires first. Once the source JWT has expired, the cached OBO token shouldn’t be reused, even if its own expiry is later.

Third, the second cache lookup right before the exchange is deliberate. It cuts down on duplicate token exchanges when several requests arrive at the same time.

Log enough to debug, but never log secrets

You only notice the token exchange code when it breaks, so good logging pays off. Here’s what I recommend:

• Log when a provider skips authorization because the registration ID doesn’t match.
• Log when the principal isn’t a JwtAuthenticationToken.
• Log cache reuse, miss, recheck hit, exchange, expiry, and store events.
• Include stable identifiers like the issuer and subject.
• Never log the raw JWT, the access token, the client secret, or the token request body.

Get this wrong and you either have nothing to go on when production fails, or you’ve written exactly the material an incident review will ask why you logged.

Make configuration explicit

Keep the required Entra settings together and validate them at startup.

app:
  downstream:
    base-url: https://api.example.internal
    api-key: 00000000-0000-0000-0000-000000000000
    cache:
      enabled: true
      expiry-skew: 30s
      maximum-size: 1000
    oauth:
      client-id: 00000000-0000-0000-0000-000000000000
      client-secret: 00000000-0000-0000-0000-000000000000
      token-url: https://login.microsoftonline.com/00000000-0000-0000-0000-000000000000/oauth2/v2.0/token
      scope: api://downstream-api/User.Read.All

Name the properties however you like. What matters is what they mean. client-id and client-secret identify your confidential client. token-url points at your tenant’s Entra token endpoint. scope targets the downstream API. The cache settings control how aggressively exchanged tokens get reused.

If your application makes both OBO calls and service-account calls, use separate client registrations for them, even if they point at the same downstream API. They authenticate in different ways, and your code should make that clear.

The service that uses the client stays simple

Once the client is wired up, your application code doesn’t carry any OAuth2 boilerplate.

public final class OrderService {

    private final DownstreamApiClient downstreamApiClient;

    public OrderService(DownstreamApiClient downstreamApiClient) {
        this.downstreamApiClient = Objects.requireNonNull(
            downstreamApiClient,
            "downstreamApiClient cannot be null"
        );
    }

    public List<OrderSummary> getOrdersForCustomer(String customerId) {
        return downstreamApiClient.getOrdersForCustomer(customerId);
    }

}

That’s the payoff. The OBO flow is there, but it doesn’t leak across the whole application.

Gotchas

These are the things that usually trip people up.

The scope must belong to the downstream API

The OBO token request isn’t asking for more access to the current API. It’s asking for a token for the next API. If your scope value is wrong, the code can look perfect and still fail.

requested_token_use=on_behalf_of is not optional

Spring Security gets you most of the way, but Entra ID still expects this parameter on the token request. Add it explicitly.

Fail fast on missing properties

Don’t let the application start with a base URL and half an OAuth2 config. It’s much better to crash at startup with a message that lists the missing property names.

Cache against both token lifetimes

If you only look at the downstream access token’s expiry, you can end up reusing an exchanged token after the user’s original token should no longer be allowed through.

Add a little expiry skew

Subtracting 30 seconds from the expiry is a cheap way to avoid failures in the middle of a request. Clock drift, thread scheduling, or a slow network hop can otherwise catch a token right as it expires.

Test the raw token request, not just the happy path

One of the most useful tests for this pattern checks that the token endpoint receives:

• grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer
• requested_token_use=on_behalf_of
• the incoming JWT as assertion
• the expected confidential-client credentials

That test catches the kind of regression that otherwise only shows up after you deploy.

Why I like this approach

It’s strict where it matters. The business layer never touches token plumbing. The infrastructure layer only customizes what it has to. Startup validation catches broken config early. The cache cuts down on repeated exchanges without trying to be clever, and the logging is useful without leaking credentials.

Most of the moving parts already exist in Spring Security. The trick is knowing where to put the Entra-specific pieces so the rest of the application stays boring. That’s usually a good sign you picked the right design.

Appendix: calling the same downstream API with a service account

Sometimes the same downstream API needs to be called in two different ways. Calls made as part of a user’s request should go through OBO, so the downstream API sees the caller’s delegated identity. Calls made by the system itself should use the client credentials flow, because there’s no user involved.

This is common in real systems. A normal API request might need OBO, while a nightly reconciliation job against the same downstream API runs as a service account. The target API is the same, but how you authenticate is not.

The clean way to model this is with two client registrations and two typed clients, even if they share a base URL.

Add a second provider for client credentials

The service-account side is much simpler, because there’s no incoming JWT to exchange.

public final class ServiceAccountAuthorizedClientProvider implements OAuth2AuthorizedClientProvider {

        public static final String CLIENT_REGISTRATION_ID = "downstream-api-service-account";

        private final ClientCredentialsOAuth2AuthorizedClientProvider delegate =
            new ClientCredentialsOAuth2AuthorizedClientProvider();

        @Override
        public OAuth2AuthorizedClient authorize(OAuth2AuthorizationContext context) {
            Objects.requireNonNull(context, "context cannot be null");

            final var registrationId = context.getClientRegistration().getRegistrationId();

            if (!CLIENT_REGISTRATION_ID.equals(registrationId)) {
                    return null;
            }

            return delegate.authorize(context);
        }

}

There’s no JwtAuthenticationToken requirement here because the client credentials flow isn’t tied to a user. Spring Security just needs a client registration with AuthorizationGrantType.CLIENT_CREDENTIALS.

Register a second RestClient

Don’t overload the OBO client with a second mode. Make the split explicit.

@Bean
ServiceAccountDownstreamApiClient serviceAccountDownstreamApiClient(DownstreamApiProperties properties) {
    final var clientRegistration = ClientRegistration
        .withRegistrationId(ServiceAccountAuthorizedClientProvider.CLIENT_REGISTRATION_ID)
        .clientId(requiredOauth(properties).clientId())
        .clientSecret(requiredOauth(properties).clientSecret())
        .clientAuthenticationMethod(ClientAuthenticationMethod.CLIENT_SECRET_POST)
        .authorizationGrantType(AuthorizationGrantType.CLIENT_CREDENTIALS)
        .scope(requiredOauth(properties).scope())
        .tokenUri(requiredOauth(properties).tokenUrl())
        .build();

    final var registrations = new InMemoryClientRegistrationRepository(clientRegistration);

    final var manager = new AuthorizedClientServiceOAuth2AuthorizedClientManager(
        registrations,
        new InMemoryOAuth2AuthorizedClientService(registrations)
    );

    manager.setAuthorizedClientProvider(new ServiceAccountAuthorizedClientProvider());

    final var oauth2 = new OAuth2ClientHttpRequestInterceptor(manager);
    oauth2.setClientRegistrationIdResolver(_ -> ServiceAccountAuthorizedClientProvider.CLIENT_REGISTRATION_ID);

    return new ServiceAccountDownstreamApiClient(
        properties.baseUrl(),
        List.of(oauth2)
    );
}

This looks a lot like the OBO setup, but it differs in two important ways. The grant type is CLIENT_CREDENTIALS, not JWT_BEARER. And the authorized-client service can be the normal in-memory one, because there’s no per-user token exchange cache to manage.

Keep the API shape the same, not the auth path

To keep your application code readable, expose two typed clients with the same downstream operations.

public final class ServiceAccountDownstreamApiClient {

    private final RestClient restClient;

    public ServiceAccountDownstreamApiClient(
            String baseUrl,
            Collection<ClientHttpRequestInterceptor> interceptors) {
        this.restClient = RestClient.builder()
            .baseUrl(baseUrl)
            .requestInterceptors(chain -> chain.addAll(interceptors))
            .build();
    }

    public List<OrderSummary> getOrdersForCustomer(String customerId) {
        return restClient.get()
            .uri(uriBuilder -> uriBuilder
                .path("/orders")
                .queryParam("customerId", customerId)
                .build())
            .retrieve()
            .body(OrderSummary.class);
    }

}

Yes, that duplicates a little transport code. I still prefer it. If one client acts as the user and the other acts as a service account, I want that difference to be visible in the types and in dependency injection. It makes code reviews easier, and it makes an accidental change in privileges much harder to miss.

Split the configuration on purpose

If both auth modes call the same downstream API, keep the shared settings together and split the auth settings by registration.

app:
    downstream:
        base-url: https://api.example.internal
        obo:
            client-id: 00000000-0000-0000-0000-000000000000
            client-secret: 00000000-0000-0000-0000-000000000000
            token-url: https://login.microsoftonline.com/00000000-0000-0000-0000-000000000000/oauth2/v2.0/token
            scope: api://downstream-api/user_impersonation
        service-account:
            client-id: FFFFFFFF-FFFF-FFFF-FFFF-FFFFFFFFFFFF
            client-secret: FFFFFFFF-FFFF-FFFF-FFFF-FFFFFFFFFFFF
            token-url: https://login.microsoftonline.com/00000000-0000-0000-0000-000000000000/oauth2/v2.0/token
            scope: api://downstream-api/.default

Sometimes those scopes are the same and sometimes they aren’t. The point isn’t to force one shape on every deployment. It’s to make the difference obvious, because delegated permissions and application permissions are different security contracts.

Choose the client based on why the call exists

This last part is about architecture, not mechanics. If the call is part of a user’s request and the downstream system should see the user’s delegated identity, use the OBO client. If it’s a background job, a scheduled sync, or some other system-to-system action, use the service-account client.

Don’t pick based on convenience. Pick based on who the downstream API should see as the caller. If the answer is “the user,” use OBO. If it’s “this application,” use client credentials.

I’ve run into this again and again when connecting a frontend to a protected API in a tenant where users can’t grant delegated permissions (letting an app act on their behalf) unless the API has pre-authorized that client app. Add tenant-wide admin approval for Microsoft Graph permissions on top of that, and even a basic sign-in can show warnings.

This post is practical advice for that kind of tenant. I describe the steps in the Azure Portal, but they’re the same if you automate with infrastructure as code (IaC).

The trust chain

Most teams think of this as two apps: a frontend app and an API app.

In a restricted tenant there’s a third piece you can’t skip: a pre-authorization link from the API to the client. Without it, the client can ask for scopes, but in practice users still can’t grant it access.

Here’s the mental model I use. Every piece has to be in place:

• The API app defines its scopes and app roles.
• The client app lists the API permissions it needs.
• The API app pre-authorizes that specific client for specific scopes.
• An admin grants consent wherever tenant policy requires it, for example for Microsoft Graph permissions.

If any one of these is missing, sign-in usually fails later on, and it looks like a bug in your code rather than a configuration problem.

Setting it up

Do things in this order. It saves a lot of trial and error.

1. Define the API first

Create the API app registration and publish the permissions it offers:

• Set the Application ID URI for the API.
• Define delegated scopes, with clear names and consent text.
• Define app roles if you need application permissions.
• Make sure the scope values are final before you wire up any clients.

The API comes first because every client’s configuration depends on its scope IDs and values staying the same.

2. Register each client with its permissions spelled out

For each client app (for example, your frontend and your CLI):

• Add the API scopes it needs as required permissions.
• Add the Microsoft Graph permissions it needs.
• Set up redirect URIs and auth settings for that type of client.

Keep this boring and explicit. “We’ll sort it out at consent time” is not a plan.

3. Pre-authorize clients on the API

This is the step people forget in restricted tenants. For each client that calls the API:

• Open the API app registration.
• Add the client app as an authorized client.
• Select the API scopes that client is allowed to request.

If your tenant blocks user delegation without pre-authorization, this is the step that turns a setup that “looks right” into one that actually works.

4. Get admin consent on purpose

In many organizations, Microsoft Graph permissions need admin approval, even delegated ones. So expect consent warnings at sign-in until an administrator grants consent for the Graph scopes you request.

Plan this as its own step. Don’t leave it as an afterthought.

Tenant quirks to expect

Delegated permissions fail without pre-authorization

You’ll see this when sign-in works but calls to the API fail with consent or “insufficient privileges” errors.

Usually the client asked for a valid API scope, but the API app hasn’t pre-authorized that client. To fix it, add the client as a pre-authorized client in the API app registration, then double-check that the exact scopes the client requests are selected.

Graph delegated permissions still need admin approval

You’ll see warnings or admin approval prompts at sign-in, even for basic sign-in scopes.

This happens because tenant policy requires admin consent for Microsoft Graph permissions. Have an admin grant consent for the Graph permissions the client requests. Keep your list of Graph scopes short so it’s easy for them to review.

Scope names match, but IDs differ between environments

Non-prod works, but another environment fails with what looks like a consent mismatch.

Usually the client is pointed at the wrong API registration, or it’s using scope IDs copied from somewhere else. Check the API app ID, the client app ID, and the target scopes in each environment. Then set up the pre-authorization link again for the right client and API pair.

Quick troubleshooting table

Habits that help

A few team habits make this a lot less painful. Treat API scopes as a contract and be careful when you change them. Keep a short checklist for every new client app. Make pre-authorization a required item in reviews. And talk to your tenant admins early about Graph consent.

None of these steps is hard on its own. The pain comes from missing one link in the chain and only finding out at sign-in.

Wrapping up

In a tenant with strict consent policy, setting up app registrations is less about flipping the right switches and more about building a complete trust chain.

Define the API scopes first. Give each client its permissions explicitly. Pre-authorize clients on the API. Plan for Graph admin consent from day one. Do it in that order and most of the guesswork goes away, and developers get a setup that behaves the same way every time.

What you need

• Podman, set up to run rootless
• k3d (you can install it with curl -s https://raw.githubusercontent.com/k3d-io/k3d/main/install.sh | bash)
• kubectl, to work with the cluster once it’s running

1. Let your user control CPU, cpuset, and I/O

Linux uses cgroups (control groups) to limit how much CPU, memory, and so on a group of processes can use. By default, systemd only hands a few of these controls to regular users. Kubernetes needs more of them, so we have to tell systemd to delegate them to user sessions.

Create /etc/systemd/system/user@.service.d/delegate.conf (you’ll need sudo) with this content:

[Service]
Delegate=cpu cpuset io memory pids

Then reload systemd:

sudo systemctl daemon-reload

This doesn’t apply to your current session. Log out and back in (or reboot) before going further.

2. Turn on the Podman socket

k3d talks to its container engine through the Docker API. Podman can provide that same API through a socket, but it’s off by default. Turn it on with:

systemctl --user enable --now podman.socket

3. Tell k3d where the socket is

Next, set two environment variables. The k3d CLI reads DOCKER_HOST to find the API. DOCKER_SOCK is the plain file path to the socket, which some scripts and tools expect instead.

export DOCKER_HOST="unix://$XDG_RUNTIME_DIR/podman/podman.sock"
export DOCKER_SOCK=$XDG_RUNTIME_DIR/podman/podman.sock

These only last for the current shell. To have them set every time you log in, add both lines to your shell profile, such as ~/.bashrc or ~/.zshrc.

4. Raise the inotify limits

inotify is the Linux feature that lets programs watch files for changes. Each Kubernetes node uses a lot of these watchers, and when you run several nodes (a server plus a few agents) as rootless containers on one machine, they all come out of the same per-user limit.

With the default limits, the kubelet’s cAdvisor (the part that collects container stats) quickly runs out and crashes with inotify_init: too many open files. It does this quietly. The agents never finish starting, and k3d just hangs forever waiting for the cluster to become “Ready”. This one is easy to miss.

To fix it for good, create /etc/sysctl.d/99-k3d.conf (again with sudo):

fs.inotify.max_user_instances=8192
fs.inotify.max_user_watches=524288

Then apply the new limits right away, without rebooting:

sudo sysctl -p /etc/sysctl.d/99-k3d.conf

5. Create the cluster

Now create the cluster. Rootless Podman runs everything inside a user namespace, where the kubelet doesn’t have the host-level privileges it normally expects. The KubeletInUserNamespace feature gate tells the kubelet about this so it doesn’t crash. We pass it to both the server and the agents:

k3d cluster create --servers 1 --agents 3 --k3s-arg '--kubelet-arg=feature-gates=KubeletInUserNamespace=true@server:*' --k3s-arg '--kubelet-arg=feature-gates=KubeletInUserNamespace=true@agent:*'

To check that it worked:

k3d cluster list
kubectl get nodes

Troubleshooting

AppArmor and user namespaces

Ubuntu 24.04 restricts unprivileged user namespaces, and that can stop rootless Podman from creating containers. If you see errors about user namespaces, AppArmor is the likely cause.

As a temporary workaround, you can turn the restriction off:

sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0

For a permanent fix, use a version of Podman that ships the AppArmor profiles it needs, or write a profile that allows userns.

cgroup version

This setup needs cgroup v2. That’s the default on Ubuntu 24.04, but you can check with:

podman info | grep "cgroup version"

You should see cgroup version: v2.

In this post I want to argue for the opposite: rich domain models that protect their own rules. I’ll lean on what Martin Fowler, Microsoft, and Amazon have said and done along the way.

What’s wrong with anemic domain objects

An anemic domain object is usually what you get when someone takes “separation of concerns” a step too far. The data lives in one class and the behavior lives somewhere else. The domain class ends up as a bag of getters and setters, and all the business rules, validation, and calculations move into service classes that push that data around.

Martin Fowler called this out back in 2003 in his article “Anemic Domain Model”. His point was that it works against encapsulation, the basic object-oriented idea of keeping data and the code that changes it together. An anemic model is really procedural code wearing an object costume. You pay the cost of building a domain model and get none of the payoff.

In practice this causes a few problems.

Validation gets scattered. If the object doesn’t enforce its own rules, every caller has to check things itself. Those checks drift apart over time and become hard to maintain.

Objects can be in an invalid state. Nothing prevents a half-built or nonsensical object from existing, so calling code always has to be on guard.

The code stops describing the business. The model doesn’t capture what the domain actually means, so the code is harder to read and reason about.

Services get bloated. All the domain logic piles up in services, which ties the business rules tightly to the application flow.

Putting the rules back in the object

A rich domain model puts the behavior inside the domain objects themselves. Those objects enforce invariants: rules about their state that must always be true. If an object never lets itself break an invariant, it can never end up in an invalid state.

Here’s a simple BankAccount:

public class BankAccount {

	private BigDecimal balance;
	private boolean frozen;

	public BankAccount(BigDecimal initialBalance) {
		if (initialBalance == null) {
			throw new IllegalArgumentException("Initial balance cannot be null");
		}

		if (initialBalance.compareTo(BigDecimal.ZERO) < 0) {
			throw new IllegalArgumentException("Initial balance cannot be negative");
		}

		this.balance = initialBalance;
		this.frozen = false;
	}

	public void deposit(BigDecimal amount) {
		if (amount == null) {
			throw new IllegalArgumentException("Deposit amount cannot be null");
		}

		if (amount.compareTo(BigDecimal.ZERO) <= 0) {
			throw new IllegalArgumentException("Deposit amount must be positive");
		}

		if (frozen) {
			throw new IllegalStateException("Cannot deposit to frozen account");
		}

		this.balance = this.balance.add(amount);
	}

	public void withdraw(BigDecimal amount) {
		if (amount == null) {
			throw new IllegalArgumentException("Withdrawal amount cannot be null");
		}

		if (amount.compareTo(BigDecimal.ZERO) <= 0) {
			throw new IllegalArgumentException("Withdrawal amount must be positive");
		}

		if (frozen) {
			throw new IllegalStateException("Cannot withdraw from frozen account");
		}

		if (this.balance.compareTo(amount) < 0) {
			throw new IllegalStateException("Insufficient funds");
		}

		this.balance = this.balance.subtract(amount);
	}

	public void freeze() {
		this.frozen = true;
	}

	public BigDecimal getBalance() {
		return balance;
	}

}

This class enforces a handful of rules:

• The balance can’t be negative.
• The initial balance and any amount passed in can’t be null.
• Deposits and withdrawals must be positive.
• You can’t deposit to or withdraw from a frozen account.
• You can’t withdraw more than the balance, so no overdrafts.

All of those rules live inside the class. There’s no way to create an account in a bad state or change it into one. So any code that gets a BankAccount can trust that it’s valid without checking.

Value objects

A good way to push invariants down even further is with value objects. A value object is a small, immutable type that’s defined by its value rather than by an identity, like an amount of money or an email address. Instead of passing raw BigDecimal or String values into your entities, you wrap them in a type that checks its own rules.

For example, instead of passing a raw BigDecimal to deposit, we could use a Money value object:

public record Money(BigDecimal amount) {
	public Money {
		if (amount == null || amount.compareTo(BigDecimal.ZERO) < 0) {
			throw new IllegalArgumentException("Money amount cannot be negative");
		}
	}

	public Money add(Money other) {
		return new Money(this.amount.add(other.amount));
	}
	// ... other operations
}

This makes BankAccount simpler. It no longer has to check for null or negative amounts itself, because a Money can’t be created with one.

What others have said

This is a core idea in Domain-Driven Design (DDD), from Eric Evans’ well-known book of the same name. Evans says the domain model is the “heart of business software”, and that it should carry real behavior and strict invariants.

Microsoft’s .NET architecture guidance says the same thing. Its docs on DDD-oriented microservices warn against anemic domain models and say domain entities should hold data plus behavior. Microsoft recommends Plain Old CLR Objects (POCOs), which are plain classes with no dependency on frameworks or infrastructure, that still contain the domain logic.

Amazon has used DDD for a long time to manage the complexity of its large microservice architecture. We can’t see their internal code, but their focus on bounded contexts (clear boundaries around each part of the domain) and on domain expertise suggests they build rich domains that enforce their own business rules at the core.

What you get out of it

Moving the rules into the domain pays off in a few ways.

Bad data stops spreading. If an invalid object can’t exist, it can’t leak into the rest of the system and cause bugs somewhere far away.

Changes get easier. Business rules live in one obvious place and are written down clearly, so changing them is less risky.

Testing gets simpler. You can test a domain object on its own, and the invariants tell you exactly what to test.

The code matches the business. When the code reads like the domain, it’s easier for developers and domain experts to talk about it.

Services get thinner. They coordinate work instead of holding business logic, which keeps the design more modular.

The hard parts

Switching to rich domain models isn’t free. If you’re used to anemic models, it can take a while to get a feel for where logic belongs.

Persistence

The most common pushback is about Object-Relational Mappers (ORMs) like Hibernate or Entity Framework. ORMs load rows from the database into objects, and many of them want a public no-argument constructor and public setters to do it. That undercuts encapsulation, because now anyone can build an empty object or change its fields.

There are a few ways around this:

• Use private constructors. Most modern ORMs can work with private or protected constructors and set fields directly, so your public API stays clean.
• Add a mapping layer. Keep a separate “dumb” persistence object for the database and map it to and from your rich domain entity. This lets your domain logic change without being tied to your database schema.
• Use the Memento pattern. The object hands out a snapshot of its state for saving, without exposing any setters.

Other things that help

• Start small. Add invariants to new classes, or to classes you’re already refactoring.
• Use aggregate roots (a DDD idea: one entity that controls access to a group of related objects) to manage complex object graphs.
• Use domain events to announce state changes.
• Use property-based testing, which throws lots of generated inputs at your code, to check that invariants hold.

Wrapping up

Anemic domain objects have given us fragile systems that are hard to maintain, with validation code spread everywhere. If we build rich domain models with strong invariants instead, the code can actually describe the business while keeping the data valid.

Fowler, Microsoft, and Amazon show this isn’t just theory. It works at scale. As our systems keep getting more complex, invariant domains give us more reliable, maintainable, and readable code. It’s time to bring encapsulation back and let our domain models do more than hold data.

You’ll need Podman installed and working. If you haven’t used it before, Podman is a container engine that doesn’t need a background daemon. It understands the same commands and image formats as Docker, so most Docker tooling can talk to it.

1. Let the builder reach the host

Spring Boot builds the image with Paketo buildpacks, and the buildpack runs inside a container. That container needs to reach the Podman socket on your machine. To allow it, set bindHostToBuilder to true in the Spring Boot plugin config.

For Maven, in pom.xml:

<plugin>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-maven-plugin</artifactId>
  <configuration>
    <docker>
      <bindHostToBuilder>true</bindHostToBuilder>
    </docker>
  </configuration>
</plugin>

For Gradle, in build.gradle:

tasks.named("bootBuildImage") {
    docker {
        bindHostToBuilder = true
    }
}

2. Turn on the Podman socket

Docker runs as a system-wide daemon that tools talk to through a socket file. Podman can run rootless (as your normal user, without root), so instead it gives each user their own socket. That socket is off by default. Turn it on with:

systemctl --user enable --now podman.socket

This starts the socket now and every time you log in. It lives at /run/user/${UID}/podman/podman.sock, where ${UID} is your user ID (usually 1000).

3. Point the build at Podman

The build-image goal talks to Docker, but it decides where Docker is by reading the DOCKER_HOST environment variable. Set that to the Podman socket and the build uses Podman instead.

With Maven:

DOCKER_HOST=unix:///run/user/${UID}/podman/podman.sock mvn spring-boot:build-image -Dmaven.test.skip=true

With Gradle:

DOCKER_HOST=unix:///run/user/${UID}/podman/podman.sock ./gradlew bootBuildImage -x test

Skipping the tests isn’t required. It just makes the build faster if you’ve already run them.

Running the image

When the build finishes, the image is stored in Podman’s local image storage. You can see it with:

podman images

And run it with:

podman run --interactive --rm --tty --network host your-app-name:latest

Troubleshooting and tips

SELinux on Fedora or RHEL

On systems with SELinux turned on, such as Fedora and RHEL, you might get “permission denied” errors when the builder tries to use the socket. You may need to make sure the socket has the right SELinux label. To check whether SELinux is the problem at all, you can temporarily switch it to permissive mode and try again.

Slow builds

Podman works best with the overlay storage driver. If your builds are very slow, check which driver you’re using:

podman info --format '{{.Store.GraphDriverName}}'

If it says vfs, set up fuse-overlayfs instead. It’s much faster.

Changing the image name

By default the image is named after your project’s artifact ID and version. You can change that in the plugin config.

Maven:

<configuration>
  <docker>
    <bindHostToBuilder>true</bindHostToBuilder>
  </docker>
  <image>
    <name>my-registry.com/my-org/${project.artifactId}:${project.version}</name>
  </image>
</configuration>

Gradle:

bootBuildImage {
    docker {
        bindHostToBuilder = true
    }
    imageName = "my-registry.com/my-org/${project.name}:${project.version}"
}

Common errors

If the build says the socket isn’t found, check that the socket file actually exists at the path you gave in DOCKER_HOST. If you get “permission denied”, make sure your user can access the socket. If the buildpack itself fails, run the build again with -X (Maven) or --debug (Gradle) to get detailed logs.

Wrapping up

That’s all it takes. Once the socket is on and DOCKER_HOST points at it, Spring Boot’s image building works the same with Podman as it does with Docker. It’s a good option anywhere you don’t want to run a Docker daemon.

Here’s the approach we use. We take the patch document, apply it to a copy of the object, validate the copy, and only save it if it passes. The patch formats are the two standard ones: JSON Patch (RFC 6902), which is a list of operations like “replace this field” or “remove that one”, and JSON Merge Patch (RFC 7396), which is a partial JSON object that gets merged into the original. Because we use existing implementations of both, we don’t have to write our own patch logic, and all the validation stays in one place.

The full code is at the end of the post. The sections before it explain how it works, what to watch out for, and how to test it.

What the processor does

JsonPatchProcessor takes a Java domain object and a patch document (either a JsonPatch or a JsonMergePatch). It then:

1. Serializes the object to JSON with Jackson’s ObjectMapper.
2. Applies the patch to that JSON using Jakarta JSON (jakarta.json).
3. Deserializes the patched JSON back into a new instance of the same class.
4. Validates the new instance with Jakarta Bean Validation (Validator).

If validation passes, you get the patched object back. If it fails, the processor throws a ConstraintViolationException. If the JSON can’t be parsed or the patch can’t be applied, Jackson or Jakarta JSON errors get wrapped in a JsonPatchException, so your controllers only have to deal with one exception type for those.

Why we like this design

Turning the object into JSON and back gives us a deep copy for free. The original object is never touched, so a bad patch can’t leave it half-modified.

Validating the whole patched object, not just the fields that changed, means every rule on the class gets checked the same way every time. Controllers don’t need their own copies of the validation logic.

The cost is that every patch goes through a full serialize and deserialize. That’s fine for typical payloads, but if you expect very high throughput or very large objects, benchmark it first.

To sum up the error handling:

• JsonPatchException means the JSON couldn’t be parsed or the patch couldn’t be applied. Map it to HTTP 400.
• ConstraintViolationException means the patched object failed validation. Map it to HTTP 422 with field-level messages.

Usage

In a Spring controller, inject the processor and pass it the existing object along with the parsed patch document. A merge patch endpoint might look like this:

@PatchMapping(path = "/users/{id}", consumes = "application/merge-patch+json")
public ResponseEntity<User> patchUser(@PathVariable Long id, @RequestBody JsonMergePatch mergePatch) {
	final var existing = userService.findById(id);
	final var patched = jsonPatchProcessor.patch(existing, mergePatch);
	final var saved = userService.save(patched);
	return ResponseEntity.ok(saved);
}

Here’s what the two kinds of payload look like. A JSON Merge Patch (RFC 7396):

{
  "email": "new.email@example.com",
  "profile": { "displayName": "New Name" }
}

And a JSON Patch (RFC 6902):

[
  { "op": "replace", "path": "/email", "value": "new.email@example.com" },
  { "op": "remove", "path": "/profile/oldField" }
]

Things to watch out for

The processor deserializes back into object.getClass(). If your model uses polymorphic types (for example @JsonTypeInfo, which tells Jackson which subclass to create) or abstract base classes, test that the subtype information survives the round trip. If it doesn’t, you’ll need to keep the type metadata during serialization or change the approach.

The example creates its own ObjectMapper. If your app already configures a shared one with date formats, modules, or mixins, inject that one instead so patching behaves the same as the rest of the app.

Validation always runs on the whole object after the patch is applied. If you need to validate only the fields that changed, you’ll need a different strategy.

Every patch does a serialize, a patch, and a deserialize. For large objects or high throughput, consider applying patches to Jackson JsonNode trees and only mapping to domain objects when you need to.

For error responses, use a @ControllerAdvice to turn ConstraintViolationException into an HTTP 422 (unprocessable content) with a structured list of field errors. Turn JsonPatchException into an HTTP 400 with a clear message about the JSON or patch problem, without leaking sensitive details.

Testing

These are the tests we’d write:

1. Happy path: a JsonMergePatch changes a field and the result passes validation.
2. Validation failure: a patch produces an invalid object and ConstraintViolationException is thrown.
3. Malformed patch: bad or incompatible operations produce a JsonPatchException.
4. Polymorphism: if your app uses @JsonTypeInfo or similar, subtype fields survive the round trip.

Here’s a JUnit test for the happy path:

@Test
void mergePatch_updatesField_andValidates() {
	final var user = new User(1L, "old@example.com", "Old Name");
	final var patch = Json.createMergePatch(
		Json.createObjectBuilder()
			.add("email", "new@example.com")
			.build());
	final var patched = jsonPatchProcessor.patch(user, patch);
	assertEquals("new@example.com", patched.getEmail());
}

Full implementation

import java.io.StringReader;
import java.util.Set;
import java.util.function.Function;

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.stereotype.Component;
import org.springframework.util.Assert;

import com.fasterxml.jackson.core.JsonProcessingException;
import com.fasterxml.jackson.databind.ObjectMapper;

import jakarta.json.Json;
import jakarta.json.JsonException;
import jakarta.json.JsonMergePatch;
import jakarta.json.JsonPatch;
import jakarta.json.JsonStructure;
import jakarta.json.JsonValue;
import jakarta.validation.ConstraintViolation;
import jakarta.validation.ConstraintViolationException;
import jakarta.validation.Validator;

/**
 * A component that applies JSON Patch and JSON Merge Patch operations to Java objects.
 * This class ensures that the patch operations are applied to a copy of the original
 * object and that the resulting object is validated before being returned.
 *
 * This component uses Jackson for serialization/deserialization and Jakarta JSON for patch operations.
 *
 * @see <a href="https://tools.ietf.org/html/rfc6902">RFC 6902: JSON Patch</a>
 * @see <a href="https://tools.ietf.org/html/rfc7396">RFC 7396: JSON Merge Patch</a>
 */
@Component
public class JsonPatchProcessor {

	private static final Logger log = LoggerFactory.getLogger(JsonPatchProcessor.class);

	private final ObjectMapper objectMapper = new ObjectMapper()
		.findAndRegisterModules();

	private final Validator validator;

	public JsonPatchProcessor(Validator validator) {
		this.validator = validator;
	}

	/**
	 * Applies a JSON Merge Patch to the given object.
	 *
	 * @param <T> the type of the object to patch
	 * @param object the object to patch
	 * @param jsonMergePatch the JSON Merge Patch to apply
	 * @return the patched object
	 * @throws ConstraintViolationException if the patched object is not valid
	 */
	public <T> T patch(T object, JsonMergePatch jsonMergePatch) {
		return patch(object, target -> jsonMergePatch.apply(target));
	}

	/**
	 * Applies a JSON Patch to the given object.
	 *
	 * @param <T> the type of the object to patch
	 * @param object the object to patch
	 * @param jsonPatch the JSON Patch to apply
	 * @return the patched object
	 * @throws ConstraintViolationException if the patched object is not valid
	 */
	public <T> T patch(T object, JsonPatch jsonPatch) {
		return patch(object, target -> jsonPatch.apply(target));
	}

	/**
	 * Generic JSON patching method that delegates the actual patch application to a passed-in function.
	 * <p>
	 * This method first creates a deep copy of the input object. The patch function is then applied to this copy.
	 * Finally, the patched copy is validated. If validation is successful, the patched copy is returned.
	 *
	 * @param <T> the type of the object to patch
	 * @param object the object to patch
	 * @param patchFn a function that receives a {@link JsonStructure} representing the original object and returns the patched {@link JsonValue}
	 * @return the patched and validated object
	 * @throws ConstraintViolationException if the patched object does not pass validation
	 * @throws JsonPatchException if an error occurs during JSON processing
	 */
	@SuppressWarnings({ "unchecked" })
	protected <T> T patch(T object, Function<? super JsonStructure, ? extends JsonValue> patchFn) {
		Assert.notNull(object, "object is required; it must not be null");
		Assert.notNull(patchFn, "patchFn is required; it must not be null");

		try {
			log.debug("Patching object of type {}", object.getClass().getSimpleName());

			final var originalJsonString = objectMapper.writeValueAsString(object);

			try (final var jsonReader = Json.createReader(new StringReader(originalJsonString))) {
				final var originalJsonStructure = jsonReader.read();
				final var patchedJsonValue = patchFn.apply(originalJsonStructure);
				final var patchedJsonString = patchedJsonValue.toString();
				final var patchedObject = objectMapper.readValue(patchedJsonString, object.getClass());

				log.debug("Performing JSON patch validation");
				final Set<ConstraintViolation<Object>> violations = validator.validate(patchedObject);
				if (violations.isEmpty() == false) { throw new ConstraintViolationException(violations); }
				log.debug("No validation errors for {}", object.getClass().getSimpleName());

				return (T) patchedObject;
			}
		}
		// JsonException can be thrown by Johnzon
		// JsonProcessingException can be thrown by Jackson
		catch (final JsonException | JsonProcessingException exception) {
			throw new JsonPatchException("An error occurred while JSON-Patching", exception);
		}
	}

}

Spring converters

Spring MVC doesn’t know how to turn a request body into a JsonMergePatch or JsonPatch on its own. These two message converters handle that.

JsonMergePatchHttpMessageConverter

import org.springframework.http.HttpInputMessage;
import org.springframework.http.HttpOutputMessage;
import org.springframework.http.converter.AbstractHttpMessageConverter;
import org.springframework.http.converter.HttpMessageNotReadableException;
import org.springframework.http.converter.HttpMessageNotWritableException;
import org.springframework.stereotype.Component;

import jakarta.json.Json;
import jakarta.json.JsonMergePatch;

/**
 * An {@link AbstractHttpMessageConverter} that can read and write {@link JsonMergePatch} objects.
 *
 * @see <a href="https://tools.ietf.org/html/rfc7396">RFC 7396: JSON Merge Patch</a>
 */
@Component
public class JsonMergePatchHttpMessageConverter extends AbstractHttpMessageConverter<JsonMergePatch> {

	public JsonMergePatchHttpMessageConverter() {
		super(JsonPatchMediaTypes.JSON_MERGE_PATCH);
	}

	@Override
	protected boolean supports(Class<?> clazz) {
		return JsonMergePatch.class.isAssignableFrom(clazz);
	}

	@Override
	protected JsonMergePatch readInternal(Class<? extends JsonMergePatch> clazz, HttpInputMessage httpInputMessage) {
		try (final var jsonReader = Json.createReader(httpInputMessage.getBody())) {
			return Json.createMergePatch(jsonReader.readValue());
		}
		catch (final Exception exception) {
			throw new HttpMessageNotReadableException("Could not read JSON merge-patch: " + exception.getMessage(), exception, httpInputMessage);
		}
	}

	@Override
	protected void writeInternal(JsonMergePatch jsonMergePatch, HttpOutputMessage httpOutputMessage) {
		try (final var jsonWriter = Json.createWriter(httpOutputMessage.getBody())) {
			jsonWriter.write(jsonMergePatch.toJsonValue());
		}
		catch (final Exception exception) {
			throw new HttpMessageNotWritableException("Could not write JSON merge-patch: " + exception.getMessage(), exception);
		}
	}

}

JsonPatchHttpMessageConverter

package ca.gov.dtsstn.vacman.api.json;

import org.springframework.http.HttpInputMessage;
import org.springframework.http.HttpOutputMessage;
import org.springframework.http.converter.AbstractHttpMessageConverter;
import org.springframework.http.converter.HttpMessageNotReadableException;
import org.springframework.http.converter.HttpMessageNotWritableException;
import org.springframework.stereotype.Component;

import jakarta.json.Json;
import jakarta.json.JsonPatch;

/**
 * An {@link AbstractHttpMessageConverter} that can read and write {@link JsonPatch} objects.
 *
 * @see <a href="https://tools.ietf.org/html/rfc6902">RFC 6902: JavaScript Object Notation (JSON) Patch</a>
 */
@Component
public class JsonPatchHttpMessageConverter extends AbstractHttpMessageConverter<JsonPatch> {

	public JsonPatchHttpMessageConverter() {
		super(JsonPatchMediaTypes.JSON_PATCH);
	}

	@Override
	protected boolean supports(Class<?> clazz) {
		return JsonPatch.class.isAssignableFrom(clazz);
	}

	@Override
	protected JsonPatch readInternal(Class<? extends JsonPatch> clazz, HttpInputMessage httpInputMessage) {
		try (final var jsonReader = Json.createReader(httpInputMessage.getBody())) {
			return Json.createPatch(jsonReader.readArray());
		}
		catch (final Exception exception) {
			throw new HttpMessageNotReadableException("Could not read JSON patch: " + exception.getMessage(), exception, httpInputMessage);
		}
	}

	@Override
	protected void writeInternal(JsonPatch jsonPatch, HttpOutputMessage httpOutputMessage) {
		try (final var jsonWriter = Json.createWriter(httpOutputMessage.getBody())) {
			jsonWriter.write(jsonPatch.toJsonArray());
		}
		catch (final Exception exception) {
			throw new HttpMessageNotWritableException("Could not write JSON patch: " + exception.getMessage(), exception);
		}
	}

}

How the workflow is set up

The workflow starts with a job called detect-changes. It checks whether any files changed under backend/, frontend/, and gitops/, and publishes the answer as three outputs: backend-changed, frontend-changed, and gitops-changed. (Job outputs are values one job can hand to the jobs that run after it.)

The actual change detection is done by the dorny/paths-filter@v3 action. Every other job looks at one of those outputs in an if condition, like if: ${{ needs.detect-changes.outputs.backend-changed == 'true' }}, and gets skipped if its folder didn’t change.

The full sample workflow is at the end of this post. It runs on push and pull_request for main and release/** branches, and you can also trigger it by hand. Change the event filters to fit your own branching and release setup.

Step by step

1. Check out the repo. The detect-changes job runs actions/checkout@v4 to fetch the commits for the event. The paths-filter action needs the repository contents to work out which files changed.

2. Run paths-filter. The job calls dorny/paths-filter@v3 with one named filter per folder, each using a glob pattern like backend/**. The action compares the current commits against the base branch (for pull requests) or the previous commit (for pushes) and checks whether any matching files were added, modified, or deleted.

3. Expose the outputs. The action sets an output for each named filter, for example steps.paths.outputs.backend. It’s true if something matched and false if not. The detect-changes job passes these on as its own outputs, so any job that declares needs: detect-changes can read them.

4. Skip what didn’t change. Jobs like test-backend, build-backend, test-frontend, and build-frontend declare needs: detect-changes and use an if condition that checks the matching output. If it’s true, the job runs. Otherwise it’s skipped.

Why bother

The main reason is cost. Compiling, testing, and building are the expensive parts of CI, and there’s no point paying for them when the code they cover hasn’t changed. It also means faster feedback: a pull request that only touches docs or one small part of the repo doesn’t have to wait on unrelated jobs.

It keeps things organized too. Each top-level folder can have its own CI jobs and build matrix, and they all share one place for change detection instead of each repeating it. This is a common pattern in monorepos that hold several services, SDKs, or components.

When to use it

It’s a good fit when your repo has several independent services or packages in separate folders, when builds or tests are slow enough that skipping them matters, or when you mix technologies (say a Java backend, a TypeScript frontend, and infrastructure manifests) and a change to one shouldn’t trigger CI for the others.

If your codebase is small and CI is already fast, the extra complexity probably isn’t worth it.

Branch protection and required checks

This pattern plays nicely with branch protection rules. You can mark the conditional jobs as required status checks, and they’ll only be enforced when they actually run.

For example, say you require ci/test-backend and ci/build-backend to pass. If a pull request only changes frontend code, those backend jobs are skipped, and GitHub doesn’t treat them as failing or blocking the merge. They show up as “skipped” in the pull request checks, not as failures. So you only run the checks you need, and the quality gates still apply to the parts that changed.

To set up required checks, go to your repository’s Settings > Branches, click Add rule (or edit the existing rule for your protected branch, e.g. main), and under Require status checks to pass before merging, add the names of the jobs you want to require. These need to match the job names in your workflow, such as ci/test-backend.

Things to get right

Fetch the full history. Change-detection actions like dorny/paths-filter may need the full Git history to compute diffs correctly. Set fetch-depth: 0 on actions/checkout to get it. The action’s documentation has the details. If you use a shallow clone that doesn’t include the previous commit, change detection can miss changes entirely. The sample workflow already sets fetch-depth: 0 in detect-changes.

Pull requests vs. pushes. For pull requests, the action compares the PR branch to the base branch. For pushes, it compares the new commit to the previous one. dorny/paths-filter handles both cases for you, but keep in mind that merge commits and squash merges can affect what shows up in the diff.

Be precise with globs. backend/** matches everything under backend/. If you only care about changes under backend/src, use backend/src/** instead.

One invocation or several. You can call dorny/paths-filter once per folder, each with a single filter, but the action also lets you define several named filters in one call. That’s what the sample does. It means fewer steps, it’s a little more efficient, and the outputs are cleaner.

Outputs are strings. The outputs from dorny/paths-filter are the strings "true" and "false", not booleans. Your if conditions need to compare them as strings, e.g. if: ${{ needs.detect-changes.outputs.backend-changed == 'true' }}.

Don’t forget needs. A job has to declare needs: detect-changes to read its outputs.

Edge cases

If a pull request touches several folders, several outputs will be true and several sets of jobs will run. That’s what you want, but it does mean one PR can still trigger a lot of jobs.

Sometimes the changes that matter aren’t in the folders you’re watching. If your CI depends on shared build scripts or on the GitHub Actions workflow files themselves, add those paths to your filters. Another option is a separate shared-changes filter matching things like .github/workflows/** or docker/* that makes every job run when shared infrastructure changes.

Finally, dorny/paths-filter is well maintained, but it’s still a third-party action. If you’d rather not depend on it, you can write the change detection yourself with git diff in a small script, or switch to a different action.

Other ways to do it

GitHub Actions has built-in paths and paths-ignore filters for push and pull_request events, but they work at the workflow level. They decide whether the whole workflow runs, so you can’t use them to turn individual jobs on and off from one shared detection step. They also can’t express cross-folder logic as flexibly as a dedicated detection job.

You can also skip third-party actions entirely and add a shell step that runs git diff --name-only $BASE...$HEAD, then sets outputs by writing to the GITHUB_OUTPUT file (e.g. echo "changed=true" >> $GITHUB_OUTPUT). That gives you full control over the logic.

For larger JavaScript monorepos, tools like Nx or Lerna can work out which projects are affected by a change and give you a list of them. They go well beyond what a simple folder check can do.

Wrapping up

A detect-changes job using dorny/paths-filter, plus if conditions on the other jobs, is a simple and easy to maintain way to run CI only for the parts of a monorepo that changed. It cuts CI costs and gets feedback to developers faster. For bigger or more specialized monorepos, you can pair it with monorepo tooling or a custom git diff script.

Here’s a complete example workflow. You can copy it into .github/workflows/ and adapt it to your repo.

name: Build and test solution
permissions: read-all

on:
  push:
    branches:
      - main
      - 'release/**'
  pull_request:
    branches:
      - main
      - 'release/**'
  workflow_call: {}
  workflow_dispatch: {}

env:
  CI: true

jobs:
  detect-changes:
    name: ci/detect-changes
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - id: paths
        uses: dorny/paths-filter@v3
        with:
          filters: |
            backend:
              - backend/**
            frontend:
              - frontend/**
            gitops:
              - gitops/**
    outputs:
      backend-changed: ${{ steps.paths.outputs.backend }}
      frontend-changed: ${{ steps.paths.outputs.frontend }}
      gitops-changed: ${{ steps.paths.outputs.gitops }}

  test-backend:
    name: ci/test-backend
    runs-on: ubuntu-latest
    needs: detect-changes
    if: ${{ needs.detect-changes.outputs.backend-changed == 'true' }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-java@v4
        with:
          java-version: '21'
          distribution: 'temurin'
      - run: mvn clean verify
        working-directory: backend/

  build-backend:
    name: ci/build-backend
    runs-on: ubuntu-latest
    needs: detect-changes
    if: ${{ needs.detect-changes.outputs.backend-changed == 'true' }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-java@v4
        with:
          java-version: '21'
          distribution: 'temurin'
      - run: mvn spring-boot:build-image
        working-directory: backend/

  test-frontend:
    name: ci/test-frontend
    runs-on: ubuntu-latest
    needs: detect-changes
    if: ${{ needs.detect-changes.outputs.frontend-changed == 'true' }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22.x
      - uses: pnpm/action-setup@v4
        with:
          version: 10
      - run: pnpm install --frozen-lockfile
        working-directory: frontend/
      - run: pnpm run typecheck
        working-directory: frontend/
      - run: pnpm run format:check
        working-directory: frontend/
      - run: pnpm run lint:check
        working-directory: frontend/
      - run: pnpm run test -- --coverage
        working-directory: frontend/
      - run: npx playwright install chromium --with-deps
        working-directory: frontend/
      - run: pnpm run test:e2e
        working-directory: frontend/

  build-frontend:
    name: ci/build-frontend
    runs-on: ubuntu-latest
    needs: detect-changes
    if: ${{ needs.detect-changes.outputs.frontend-changed == 'true' }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22.x
      - uses: pnpm/action-setup@v4
        with:
          version: 10
      - run: pnpm install
        working-directory: frontend/
      - run: podman build --file containerfile .
        working-directory: frontend/