Skip to Content
LYNKORIADocs

Migration from Agora

Rollout order, native SDK migration, breaking changes and go-live checklist.

Order

  1. LumoLynk (internal). Replace only the call engine behind a feature flag; keep existing messaging and presence. Backend uses @lynkoria/server (calls.create, calls.joinToken); the app uses @lynkoria/client calls.join (LiveKitMediaProvider). Compare join success and quality with Agora on staff devices and ISPs.
  2. VibeLynk. 1:1/group calls and incoming-call signaling (POST /v1/calls/:id/signal → call:* socket events plus FCM/APNs push when push is enabled for the environment). 10–300 viewer livestreams (type: livestream, roles host/speaker/viewer, promotion via permissions). Benchmark on the target Droplet. Cohort rollout behind flags; Agora remains the fallback chosen at app start — no mid-session provider switching.
  3. Fidescript. Privacy/security/legal review first; appointment-bound authorization in the product backend; recording decision (ADR 009); dedicated media infrastructure if justified (ADR 008); one internal appointment flow first.

Native apps

Agora's native SDKs map to Lynkoria's as follows. Each product keeps its own backend authorization; apps never hold a Lynkoria service key.

AgoraLynkoria
App ID + token serverProduct backend calls POST /v1/calls and POST /v1/calls/{id}/join-token with its service key
RtcEngine.joinChannelAndroid LynkoriaCall.join, iOS LynkoriaCall.join, React Native joinCall
Channel profile live/broadcastertype: livestream with host/speaker/viewer roles chosen by the backend
RTM messaging / presenceLynkoriaClient (Kotlin, Swift) or @lynkoria/client (React Native)
Product-owned push for incoming callsLynkoria push (/v1/push/devices); call:invited signals trigger FCM / APNs VoIP automatically
Cloud recordingPOST /v1/calls/{id}/recordings (LiveKit Egress); not available for E2EE calls

Migrate one product at a time, behind its existing feature flag, and keep Agora as the start-of-session fallback until the device checklist in testing completion criteria passes for that product.

Breaking changes in this release

ChangeWhyMigration
Console requests need a password sessionCloudflare Access alone was the only application authenticationCreate accounts with pnpm admin:user create --email … --role … for every existing console_roles email before deploying
CF_ACCESS_* no longer requiredAccess becomes an optional additional layerKeep it configured for defense in depth; identities must match console accounts
Production attachments require the scannerUnscanned files must not be downloadableDeploy apps/scanner and set SCANNER_URL/SCANNER_TOKEN, or explicitly set ATTACHMENT_SCANNING=disabled
Existing ready attachments with not_scanned stop being served once scanning is enabledFail closed for files that never passed a scanAccept the change, or rescan legacy objects before enabling (no automatic backfill is provided)
Call responses include e2eeRecording policy depends on itAdditive; typed clients should update @lynkoria/contracts

Migration 0001_platform_extensions is additive (new tables and nullable/defaulted columns) and safe to apply before deploying the new API.

Messaging (Phase 3)

Default: no historical migration. Old history stays in product backends; new conversations go to Lynkoria after cutover. If needed later, dual-read (new messages central, old history read from the legacy store) before considering a full backfill (ID mapping, sequence assignment in original order, attachment re-authorization, retention review). Never dual-write live messages without deterministic reconciliation.

Rollback criteria

Roll back a cohort if join failures exceed baseline, media degradation persists past the error budget, any cross-project or cross-tenant defect occurs, message loss or unrecoverable duplication occurs, missed-call delivery regresses, or Fidescript security/availability is affected.

Go-live checklist

  • Staging mirrors production networking and credential isolation
  • TLS, DNS, TURN and blocked-UDP tests pass in production
  • auto_create: false verified; unknown rooms rejected
  • 1:1 and group calls work on real browsers, desktop and mobile; multi-device behavior matches ADR 006
  • 300-viewer benchmark passes on deployed infrastructure (local single-host results do not count); measured GiB per viewer-hour recorded
  • Security negative tests pass (CI)
  • Inbound webhooks verified and deduplicated; reconciler running
  • Messages survive restarts, Redis outages, offline devices, retries; no sequence gaps
  • Presence correct across devices and lease expiry
  • Backup restore and rollback drills done
  • Alerts, dashboards, transfer billing alerts, owners assigned
  • Privacy assessment, notices, retention and recording policies approved
  • SDK clean install tested in all three product repos
  • Feature-flag kill switch and Agora fallback tested
  • Pilot cost (including transfer) measured; savings approved

On this page