Migration from Agora
Rollout order, native SDK migration, breaking changes and go-live checklist.
Order
- 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/clientcalls.join(LiveKitMediaProvider). Compare join success and quality with Agora on staff devices and ISPs. - 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. - 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.
| Agora | Lynkoria |
|---|---|
| App ID + token server | Product backend calls POST /v1/calls and POST /v1/calls/{id}/join-token with its service key |
RtcEngine.joinChannel | Android LynkoriaCall.join, iOS LynkoriaCall.join, React Native joinCall |
| Channel profile live/broadcaster | type: livestream with host/speaker/viewer roles chosen by the backend |
| RTM messaging / presence | LynkoriaClient (Kotlin, Swift) or @lynkoria/client (React Native) |
| Product-owned push for incoming calls | Lynkoria push (/v1/push/devices); call:invited signals trigger FCM / APNs VoIP automatically |
| Cloud recording | POST /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
| Change | Why | Migration |
|---|---|---|
| Console requests need a password session | Cloudflare Access alone was the only application authentication | Create accounts with pnpm admin:user create --email … --role … for every existing console_roles email before deploying |
CF_ACCESS_* no longer required | Access becomes an optional additional layer | Keep it configured for defense in depth; identities must match console accounts |
| Production attachments require the scanner | Unscanned files must not be downloadable | Deploy 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 enabled | Fail closed for files that never passed a scan | Accept the change, or rescan legacy objects before enabling (no automatic backfill is provided) |
Call responses include e2ee | Recording policy depends on it | Additive; 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: falseverified; 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