Replicator Overview

Why we ship the bridge

• Mirror Entity Auth’s canonical state into a customer database in real time.
• Replay events and publish local mutations back upstream with idempotent guarantees.
• Keep humans and LLM agents on the same surface area via the Entity CLI engine.

What ships in the pack

• bridge/nodes.json registers template nodes (entityauth:bridge:postgres-prisma, entityauth:bridge:memory-demo).
• Each template includes a runner, config skeleton, adapter wiring, and documentation.
• The Bridge executor copies templates into your workspace, persists runtime state, and exposes scaffold/start/status/stop commands.

Quick start (Postgres + Prisma)

npx @entityauth/cli bridge scaffold entity-auth --node entityauth:bridge:postgres-prisma
cd entity-auth/templates/postgres-prisma
npm install
npx prisma generate
cp replicator.config.json replicator.config.local.json
npx @entityauth/cli bridge start entity-auth --node entityauth:bridge:postgres-prisma
npx @entityauth/cli bridge status entity-auth --node entityauth:bridge:postgres-prisma

Configuration fields

Key	Description
convexUrl	Convex deployment URL for your workspace
workspaceTenantId	Workspace tenant identifier
cursorId	Unique identifier per consumer
authToken	Replicator/workspace API token
eventsPerBatch	Max events pulled per request (default 100)
retry	Backoff settings for subscription polling
applyExternalMutationAction	Convex action path for inbound mutations

Runtime commands

• bridge scaffold – Copy template into workspace
• bridge start – Generate process descriptor + persist state
• bridge status – Inspect latest state file
• bridge stop – Mark state as stopped

Using runBridge

import { runBridge, createPrismaAdapter } from "@entityauth/replicator";

await runBridge({
  options: {
    convexUrl: process.env.CONVEX_URL!,
    workspaceTenantId: process.env.WORKSPACE_TENANT_ID!,
    cursorId: "postgres-prisma",
    authToken: process.env.CONVEX_REPLICATOR_TOKEN,
    adapter: createPrismaAdapter({ prisma, handlers }),
  },
  logPath: "./logs/replicator.log",
  name: "postgres-prisma",
});

Operational best practices

• Persist the offset store (replicator-offsets.db) across restarts.
• Use lifecycle hooks (onEvent, onBatchProcessed, onHeartbeat, onExit) for monitoring.
• Provide applyExternalMutationAction to push local changes upstream.
• Clean up .entitycli/bridge/state/*.json when decomissioning a workspace.