flowstate-db-replication Package Skill

Package: @epicdm/flowstate-db-replication Repository: epic-flowstate-community Path: packages/db-replication Version: 1.0.7

Use this published Dojo skill as the package-level entrypoint. For detailed workflows, use the package-local skills listed below.

Primary Package Workflow

FlowState DB Replication Core Sync

Status: Active Purpose: Teach agents how to operate the singleton replicationManager safely. Scope: App-level RxDB server replication in packages/db-replication/src/replicationManager.ts. Trigger: A task involves collection replication lifecycle, auth/domain changes, status streams, live streams, or manager configuration. Input: RxDatabase, collection names, server base URL, auth token, domain ID, and replication config. Output: Correct manager setup, lifecycle calls, status inspection, and verification.

Overview

Use replicationManager for application-wide replication orchestration. It owns active replication state, auth context, retry queues, event/status/metrics streams, periodic resync, and live stream controls.

Required Source Paths

• src/replicationManager.ts
• src/types.ts
• src/utils/logger.ts
• src/utils/timezone.ts
• src/__tests__/replicationManager.test.ts

Lifecycle

1. Initialize the manager with an RxDatabase.
2. Set auth context with a real authToken and domainId.
3. Start replications for configured collections.
4. Inspect status/events/metrics.
5. Stop or destroy during shutdown.

Example:

import { replicationManager } from '@epicdm/flowstate-db-replication';

replicationManager.initialize(db, {
  enabled: true,
  autoStart: false,
  baseUrl: 'https://sync.example.com',
  collections: ['projects', 'tasks'],
  periodicResync: {
    enabled: true,
    intervalMs: 10_000,
  },
});

replicationManager.setAuthContext({
  authToken,
  domainId,
  userId,
});

await replicationManager.startAllReplications();

const status = replicationManager.getReplicationStatus();

Endpoint Shape

The manager path calls replicateServer using:

{baseUrl}/{collectionName}/{schemaVersion}

Headers include:

Authorization: Bearer <authToken>
X-Domain-ID: <domainId>
Content-Type: application/json
Accept: application/json

Do not describe this path as /api/replication/{collection}/{version}/pull|push. That endpoint model belongs to enableReplication.

Auth And Domain Rules

replicationManager only starts when both authToken and domainId are present.

When setAuthContext receives a new domain ID:

• auth failure tracking is reset for that domain
• existing replications stop
• replications restart if still authenticated

When auth is removed:

• active replications stop

Collection Selection

collections: [] means all RxDB collections. A non-empty collections array limits replication to named collections.

Replication keys are built as:

{collectionName}-v{schema.version}

Manager Controls

Live Streams

Use live stream helpers when a collection needs live replication. The manager tracks live streams and supports priority enabling:

• enableLiveStream(collectionName)
• disableLiveStream(collectionName)
• enableLiveStreamsWithPriority([{ name, priority }])
• enableLiveReplicationForAllCollections()

The feature inventory records a maximum of 20 live streams. Check current source before changing that limit.

Status Inspection

getReplicationStatus() returns:

• authenticated
• enabled
• activeCount
• syncing
• collections
• replications
• overallStats
• memoryUsage
• periodicResync
• authContext
• alerting

Use collections for UI-friendly per-collection status and replications for manager internals.

Red Flags

Verification

yarn workspace @epicdm/flowstate-db-replication test --runInBand src/__tests__/replicationManager.test.ts
yarn workspace @epicdm/flowstate-db-replication typecheck

Run full package build after source edits:

yarn workspace @epicdm/flowstate-db-replication build

Composition Notes

• Use flowstate-db-replication-react for provider and hook wiring.
• Use flowstate-db-replication-observability when status/events/metrics need formatting or export.
• Use flowstate-db-replication-recovery-optimization when failures should be retried or circuit-broken.

Created: 2026-06-29

Package Skill Inventory

@epicdm/flowstate-db-replication Skill Inventory

Repository: epic-flowstate-community Package path: packages/db-replication

Skill Map

Composition Guidance

Use flowstate-db-replication first when the requested task is broad. It routes to the focused skills:

• Manager lifecycle and collection sync: flowstate-db-replication-core-sync
• React UI/provider integration: flowstate-db-replication-react
• Custom endpoint replication: flowstate-db-replication-low-level-http
• Metrics and event inspection: flowstate-db-replication-observability
• Recovery and performance work: flowstate-db-replication-recovery-optimization
• Docs/build/test/package upkeep: flowstate-db-replication-maintenance

Do not split future skills by every exported method unless an agent task repeatedly needs that method as an independent workflow. This package is dense, but its useful learning shape is workflow-based.

Baseline Failure Cases Addressed

Review Gate

The package skillset is publish-ready only when:

• Every skill has YAML name and trigger-focused description.
• Every skill teaches an executable workflow or dense reference, not a feature list.
• Verification commands are recorded in REVIEW.md.
• Drift and dependency risks are preserved for downstream maintainers.

Review Gate

@epicdm/flowstate-db-replication Skill Review

Review Summary

Created package-local operating skills for @epicdm/flowstate-db-replication under packages/db-replication/.flowstate/skills.

The skillset replaces generated feature-list style material with composable agent instructions for:

• Choosing the correct package workflow.
• Operating singleton replication manager sync.
• Integrating React provider and monitoring hooks.
• Maintaining low-level HTTP pull/push replication.
• Inspecting observability and metrics.
• Applying recovery and optimization helpers.
• Maintaining docs, dependency boundaries, and verification gates.

Evidence Reviewed

• package.json
• README.md
• CHANGELOG.md
• .flowstate/docs/index.md
• .flowstate/docs/quick-start.md
• .flowstate/feature-matrix/inventory.md
• .flowstate/dojo generated artifacts as non-source prototypes
• src/index.ts
• src/replicationManager.ts
• src/ReplicationProvider.tsx
• src/useReplicationMonitoring.ts
• src/useReplicationSync.tsx
• src/useRxdbServerReplication.ts
• src/useReplication.ts
• src/replicationMetrics.ts
• src/replicationRecovery.ts
• src/replicationOptimization.ts
• src/replicationUtils.ts
• src/types.ts
• src/utils/config.ts
• src/utils/logger.ts
• src/utils/metrics.ts
• src/utils/timezone.ts
• src/__tests__/replicationManager.test.ts
• src/__tests__/useReplicationMonitoring.test.ts

Quality Notes

The skills intentionally avoid one skill per feature-matrix row. The package has many public exports, but an agent learning the package needs the real operational boundaries:

• Manager path versus low-level HTTP path.
• Provider/hook naming and auth prop shape.
• Observability as an inspection/export workflow.
• Recovery and optimization as companion systems around replication health.

Known Drift Preserved

• Docs mention RxDB 16.19.1; package metadata uses 16.21.1.
• Quick-start docs use authContext; source ReplicationProvider accepts flattened auth props.
• Periodic resync defaults differ between manager default and config utility.
• replicationOptimization.ts imports lodash, but package metadata does not list it.
• No direct app source imports of this package were found during review.

Verification Status

Completed after authoring:

• ASCII scan: passed.
• yarn workspace @epicdm/flowstate-db-replication typecheck: passed.
• yarn workspace @epicdm/flowstate-db-replication test --runInBand: passed, 3 suites and 35 tests.
• yarn workspace @epicdm/flowstate-db-replication lint: passed with 723 warnings and 0 errors.
• yarn workspace @epicdm/flowstate-db-replication build: passed.
• yarn nx build @epicdm/flowstate-db-replication: passed; Nx Cloud reported the existing unconnected-workspace 401/setup notice.

Dojo publication remains deferred until the local package skills pass verification and review.

Start with this skill to understand the package purpose, then use the package-local focused skills for specific workflows. Keep this Dojo version aligned with packages/db-replication/package.json. Do not treat generated feature lists as lessons; use workflow evidence from CODE-REVIEW.md, SKILL-INVENTORY.md, and REVIEW.md.