> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Data Platform

Modern.js Effect API runtime now supports a request-envelope based data platform contract for safer and more predictable data orchestration in complex applications such as Module Federation and micro frontends.

## What it solves

- Stable operation identity across host and remote applications.
- Cache key isolation by namespace, origin, and user/tenant scope.
- Envelope integrity checks for request payload + selection plan.
- Optional strict envelope enforcement at the server boundary.
- Safer cross-namespace invalidation (opt-in only).
- Trace context continuity for distributed observability.

## Runtime contract helpers

Use `@modern-js/bff-effect/data-platform` helpers to build and validate contracts:

```ts
import {
  createOperationId,
  buildScopeKey,
  buildQueryKey,
  createRequestEnvelope,
  validateRequestEnvelope,
  createHydrationEnvelope,
  validateHydrationEnvelope,
  createInvalidationEvent,
  shouldApplyInvalidation,
} from '@modern-js/bff-effect/data-platform';
```

## Effect runtime validation

Enable strict server-side envelope validation in `modern.config.ts`:

```ts title="modern.config.ts"
export default defineConfig({
  bff: {
    runtimeFramework: 'effect',
    effect: {
      dataPlatform: {
        requireEnvelope: true,
        expectedNamespace: 'my-app',
        selection: {
          maxDepth: 6,
          maxFields: 200,
        },
      },
    },
  },
});
```

Envelope validation is enabled by default but does not require an envelope unless `requireEnvelope` is set. Origin validation is enabled by default; set `validateOrigin: false` to skip comparing the envelope origin against the incoming `Origin` header, or the request URL origin when the header is absent.

## Generated API client behavior

When using the generated API client (`@api/index`), Modern.js automatically attaches a serialized data envelope header (`x-modernjs-data-envelope`) for same-origin requests.

The generated client is loader-materialized. Import it from `@api/index` in browser or client-bundled code; direct imports of the server entry (`api/index`) expose the Effect API definition and only provide a placeholder `client`.

The envelope includes:

- operation metadata
- scoped cache identity
- request mode
- selection plan hash
- optional trace context

For browser cross-origin requests, envelope headers are skipped by default to avoid unintended CORS preflight breakage in cross-project/micro-frontend setups.

If you need envelope headers across origins, set `request.dataPlatform.allowCrossOriginEnvelope = true` and configure CORS to allow the envelope header.

## Network batching

Effect generated clients include micro-batching for GET requests by default. Requests in the same short window are merged into one POST call to `/_data/batch` (under your BFF prefix), while preserving per-item response semantics.

Batching behavior:

- GET-only by default (`allowedMethods` can be adjusted).
- In-flight dedupe for identical requests.
- Automatic fallback to single requests when batch endpoint is unavailable.
- Per-item isolation: one item failure does not fail sibling items.
- Trace continuity: batch gateway forwards `traceparent` from item headers or envelope metadata.

Server controls are configured in `bff.effect.dataPlatform.batch`:

```ts title="modern.config.ts"
export default defineConfig({
  bff: {
    runtimeFramework: 'effect',
    effect: {
      dataPlatform: {
        batch: {
          endpoint: '/_data/batch',
          maxBatchSize: 16,
          maxBatchBytes: 64 * 1024,
          flushIntervalMs: 8,
          maxConcurrency: 4,
          requestTimeoutMs: 10000,
          allowedMethods: ['GET'],
        },
      },
    },
  },
});
```

## Recommended policy

- Keep `validateOrigin` enabled.
- Use `expectedNamespace` for each deployed app/remote.
- Enable `requireEnvelope` in production once all clients are migrated.
- Keep batching GET-only unless you have strong mutation ordering guarantees.
- Keep host/remote batch endpoints on each origin; do not route all MF traffic to a single shared batch origin.
- Use explicit `targetNamespaces` and opt-in subscribers for cross-app invalidation.