Skip to main content

Local Dev Setup

:::info Source Sourced from services/sync-service/LOCAL_DEV_SETUP.md in the documentation repo. :::

1. Prerequisites​

Node 20, pnpm 9, Docker 24.

2. Quick Start​

cd services/sync-service
cp .env.example .env.local
pnpm install
docker compose -f docker-compose.dev.yml up -d
pnpm db:migrate
pnpm seed
pnpm dev                    # :3090
pnpm dev:projector
pnpm dev:router

3. Dependencies​

ServicePort
postgres5432
redis6379
nats4222
identity-service (mock)3001
progress-service (mock)3030
assessment-service (mock)3050
enrollment-service (mock)3055
content-service (mock)3080
ai-gateway-mock3020

4. Environment​

PORT=3090
DATABASE_URL=postgres://sync:sync@localhost:5432/sync
REDIS_URL=redis://localhost:6379/90
NATS_URL=nats://localhost:4222
NATS_STREAM=SYNC

DELTA_RETENTION_DAYS=30
CURSOR_STALE_THRESHOLD_DAYS=30
PUSH_MAX_MUTATIONS_PER_BATCH=100
PUSH_MAX_PAYLOAD_BYTES=10485760     # 10 MB
PULL_MAX_PAGE_SIZE=1000
HEALTH_CHECK_INTERVAL_SECONDS=300
DEVICE_STALE_THRESHOLD_HOURS=48

AI_GATEWAY_URL=http://localhost:3020

5. Seed Data​

  • 3 registered entity types (Statement, Enrollment, Certificate).
  • 2 devices with cursors at various positions.
  • 50 pre-materialized deltas per scope.
  • 2 pending conflicts (for conflict resolution testing).
  • 10 sample mutations in various states.

6. Commands​

pnpm dev
pnpm test
pnpm test:integration
pnpm test:property               # VectorClock + cursor property tests
pnpm test:chaos                  # chaos injection scenarios
pnpm sync:push-sim --device ... --mutations 50
pnpm sync:pull-sim --device ... --scope ...
pnpm sync:conflict-inspect <id>
pnpm sync:device-health <deviceId>
pnpm delta:project-replay        # replay domain events → rebuild deltas
pnpm registrations:list
pnpm openapi:check

7. Debugging​

  • pnpm sync:trace <clientMutationId> — trace mutation from client to owning service and back.
  • pnpm delta:tail <scope> — watch live delta materialization.
  • pnpm cursor:inspect <deviceId> — show all cursors for device.
  • pnpm conflict:resolve <id> --keep server|client — CLI conflict resolution.

8. Multi-Device Testing​

# Simulate two devices for same user
pnpm sync:push-sim --device dev1 --mutations 20 --user u_01H...
pnpm sync:push-sim --device dev2 --mutations 20 --user u_01H... --conflict-overlap 5
pnpm sync:pull-sim --device dev1 --scope progress:user:u_01H...
pnpm sync:pull-sim --device dev2 --scope progress:user:u_01H...
# Both should see consistent state