Skip to Content
LYNKORIADocs

Program status

Progress, blockers, pending decisions and the next step for the documentation and console upgrade and the earlier infrastructure, SDK and services program.

Last updated: 2026-11-14. This page tracks the multi-phase improvement program (dependencies, infrastructure, services, SDKs, testing, docs). Platform findings and launch gates stay in the implementation tracker and blockers; this page links to them instead of repeating them.

Documentation and console upgrade (started 2026-11-14)

Second program: bring apps/docs and apps/admin up to date with the platform and make the console a complete management and analytics surface. Work happened on one branch per phase (docs-admin/phase-1-audit … docs-admin/phase-7-final), stacked, then merged into main and pushed once all phases were validated. Audit: Docs and console audit.

PhaseStatus
1. AuditCompleted
2. DocumentationCompleted
3. Console foundations and securityCompleted
4. Platform managementCompleted
5. Analytics and dashboardCompleted
6. Testing and validationCompleted
7. Final reviewCompleted

Console audience: product teams (tenant roles owner, admin, developer, auditor, scoped to an organization or project). There is no platform operator role, so no cross-organization or infrastructure page is built until PD-1 is decided.

Next concrete step: decide PD-1 (platform operator role) and PD-2 (MFA); both unblock the remaining console work (infrastructure views, account administration in the UI). PD-5 (monitoring backend) unblocks latency, error-rate and resource metrics. Everything else in this program is done and merged into main.

Final status

  • Done and verified locally: generated references and checked examples in the docs; append-only audit, audited exports, own-session management; calls, livestreams, participants, live state, webhook history; hourly and daily analytics with overview and analytics pages; WCAG AA fixes; API, end-to-end, accessibility and large-dataset checks (see the phase results below).
  • Deploy notes: migrations 0002–0005 run in the existing PRE_DEPLOY job (indexes build without CONCURRENTLY; see the deployment handbook). No new environment variables, services or infrastructure. Hourly usage starts collecting when 0004 is applied and is not backfilled; the retention job prunes it after 35 days.
  • Not done (needs a decision or infrastructure): PD-1 to PD-5 below; Kotlin and Swift generated references (CON-09); validation on deployed infrastructure (INFRA-01) and under real load (LOAD-01).

Phase 6 results (testing and validation)

CheckResult
Format, lint, typesoxfmt --check (only the uncommitted local CLAUDE.md differs), oxlint --deny-warnings and every workspace typecheck pass.
API tests123 passed against local PostgreSQL, Redis, LiveKit and S3, including console-admin.test.ts: role and cross-organization denials, append-only audit, exports, sessions, calls, live state, webhook history, rollups and analytics totals checked against inserted rows.
DocsBuild exports 115 pages with internal links, search and OpenAPI verified; 10 content tests (generated references current, env vars, links); 51 code blocks type-check.
Console end-to-endpnpm --filter @lynkoria/admin test:e2e (Playwright, also in CI): 10 workflows against a seeded API, including read-only developer and cross-organization refusal.
Accessibilityaxe (WCAG 2.x A/AA) on overview, calls, webhooks, analytics, account and audit pages: no serious or critical violations. Found and fixed: light-theme contrast of faint text and status colors, primary button contrast, unnamed dialogs, account-menu name mismatch, unfocusable scroll region, color-only links.
PerformanceLocal database with 500k calls, 1M participant sessions, 500k outbox events, 1M audit events, 35 days of hourly and 400 days of daily usage for 50 environments: call list 0.1 ms, call participant counts 0.9 ms, live summary 1-15 ms, hourly 7-day series 2.8 ms, daily 400-day per-project totals 7.5 ms, delivery history under 1 ms per environment (after migration 0005 and per-environment queries). Audit log page and team activity are about 120 ms at 1M events in one organization.
Not validatedAgainst deployed infrastructure or real traffic (INFRA-01, LOAD-01); dark-theme contrast was not re-measured by axe (tests run in the light theme).

Phase 5 results (analytics and dashboard)

ItemResult
Hourly rollupproject_usage_hourly (migration 0004), written in the same transaction as the daily row by the usage recorder, call peaks and participant minutes (split by hour). Pruned after 35 days by the retention job. Not backfilled.
EndpointsGET /v1/admin/usage (hourly up to 7 days within 35 days, daily up to 400 days; totals, per-project totals, first recorded bucket); GET /v1/admin/live (per readable project).
OverviewLive tiles, 30-day tiles with sparklines, activity chart, projects table, recent activity.
AnalyticsShared view for all projects and per project: presets, custom UTC range, local/UTC labels, previous-period comparison, project and environment filters, chart/table switch, per-project breakdown, server CSV export.
Real-timePolling through the admin API every 15 s for live data and 60 s for hourly charts, paused in background tabs (React Query default). No new streaming channel (ADR 025).
AggregationCounts summed, peaks as maxima, error rate from summed counts; validated in console-admin.test.ts against inserted rollup rows.

Phase 4 results (platform management)

AreaConsoleAPI (all audited when they change something)
ProjectsList, create, rename, disable/enable (existing)Deletion not offered (PD-3)
Environments, keys, webhooks secretsExisting pagesExisting
Calls and livestreamsCalls tab: live state, quota meter, filtered list, detail drawer, End call, Remove participantGET /calls, GET /calls/{id}, POST .../end, POST .../participants/{identity}/remove, GET /live
WebhooksPending, dead and delivered history with paging; backlog per environmentGET /webhook-events
TeamLast activity in this organizationGET /roles adds lastActivityAt (organization-scoped; a global sign-in time would let an owner probe any address by granting it a role)
Indexes—Migration 0003: call list and delivery history
Messaging and presence healthNot shown: no per-environment presence counter, socket metrics need PD-5—
InfrastructureNot built: operator-only (PD-1) and monitoring backend (PD-5)—

Tests: apps/api/test/console-admin.test.ts covers listing, paging, stale detection, live counts, role and cross-organization denials, end-call parity with the service API and audit entries.

Phase 3 results (console foundations and security)

ItemResult
AuthenticationUnchanged model (password sessions, lockout, idle and absolute timeouts, origin check, optional Access). MFA and step-up re-authentication are PD-2.
AuthorizationEvery admin route documents its roles (x-console-roles); refused changes are audited. Tests check denial across organizations and roles.
Audit logAppend-only in the database (migration 0002 triggers); server-side filters (action prefix with *, actor, dates); sign-ins, refusals, exports and session ends recorded.
ExportsGET /v1/admin/projects/{id}/usage/export: server-built CSV, 400-day cap, audited.
Own account/v1/admin/me/sessions (list, end) and /v1/admin/me/activity; console Account page.
DecisionsADR 024 (charts stay in-house SVG), ADR 025 (analytics data sources), ADR 026 (audience, authorization, audit).
Metrics catalogMETRICS in @lynkoria/contracts/catalog; docs/metrics-catalog.md generated; console info popovers read the same entries.
Shared UIDataTable (cursor paging, sort, optional columns), useUrlState, RangePicker, TimeSeriesChart, Meter, StatTile, ChartCard, MetricInfo.

Phase 2 results (documentation)

ItemResult
HTTP API referenceGenerated from openapi.json into docs/http-api/ by scripts/gen-api-reference.mjs; console routes carry x-console-roles, service routes their key scope. CI and apps/docs/test fail when stale.
SDK referenceGenerated from each package's bundled declarations into docs/sdk-reference/ with the documented version. TypeDoc was not used: the repository is on TypeScript 7, whose compiler API TypeDoc does not support.
Environment variablesapps/docs/test checks the reference against the API and scanner config schemas and direct process.env reads, both ways. Found and documented MIGRATIONS_DIR.
Code examplesEvery ts/tsx block in the guides is extracted and compiled against the real SDKs and frameworks (pnpm --filter @lynkoria/docs typecheck). 51 blocks checked, 2 TanStack file-route blocks opt out (their types come from a generated route tree). The check found 12 broken examples, all fixed.
Glossary@lynkoria/contracts/catalog holds the terms; docs/glossary.md is generated from it and the console uses the same entries.
Diagrams and statusMermaid diagrams (remarkMdxMermaid + a client renderer); capability marks render as labelled badges.
Developer vs operator docsKept as separate sidebar roots: Developer guides; Architecture, Deployment, Operations, Security for operators.
Versioned docsNot needed yet: every package is 0.1.0 and unpublished; reference pages state the version they describe. Revisit at the first breaking release.
Not doneKotlin (Dokka) and Swift (DocC) generated references need Gradle and Xcode tooling in the docs build; the Android and iOS guides remain hand-written.

Pending decisions for this program (need approval)

IDDecisionRecommendation
PD-1Platform operator role for infrastructure and cross-tenant viewsAdd console_users.platform_role (operator or null), granted only with pnpm admin:user grant-operator, audited, never assignable from the console. Unlocks Infrastructure pages (health per instance, worker backlog, LiveKit, scanner) and console user management.
PD-2MFA and step-up re-authentication for console accountsTOTP with recovery codes required for owner/admin, plus password re-entry within 5 minutes before key create/rotate/revoke, role grants and webhook-secret rotation. Alternative: make Cloudflare Access with IdP-enforced MFA mandatory in production.
PD-3Project deletionKeep disable (reversible, already supported). Add deletion later as an operator CLI command that exports and then removes a disabled project's data after a 30-day hold.
PD-4Console user management in the UI (disable, revoke sessions)After PD-1, expose to platform operators only; tenant owners keep role grants.
PD-5Monitoring backend (carried over)Managed Prometheus-compatible backend with Grafana. Needed for latency percentiles, error rates, CPU/memory, socket and LiveKit metrics in the console; until then the console shows them as unavailable.

Where things stand (infrastructure, SDK and services program)

All work is committed directly on main and pushed.

PhaseStatus
0. Dependency updatesCompleted (hosted CI green on ce27d7c)
1. InfrastructureImplemented; remaining items blocked or moved
2. MicroservicesCompleted
3. JavaScript SDKsCompleted (CI green)
4. Native mobile SDKsImplemented; device validation pending
5. Cross-cutting testsImplemented locally; deployed load tests blocked
6. Documentation/releaseCompleted (publishing blocked on registry decisions)

Next concrete step: every phase is implemented as far as this environment allows. What remains needs a decision, credentials, devices or deployed infrastructure: see Remaining work.

Phase 0: dependency updates

Inventory

AreaFiles
npm workspaceroot package.json, pnpm-workspace.yaml, pnpm-lock.yaml, 5 apps, 9 packages (pnpm 12.18.0, Turbo 2.11.11)
Node.js.nvmrc (26), engines (>=26), apps/api/Dockerfile, apps/scanner/Dockerfile, CI node-version-file
Androidsdks/android (Gradle wrapper, libs.versions.toml, 3 modules), packages/sdk-react-native/android/build.gradle
iOSsdks/ios/Package.swift, packages/sdk-react-native/lynkoria-react-native.podspec
Imagesinfra/local/compose.yaml, infra/scanner/compose.yaml, infra/opentofu/platform/app.tf (DOCR digests)
CI.github/workflows/{ci,deploy,release,release-native}.yml (actions pinned by SHA), .github/dependabot.yml

No Go, Rust, CocoaPods Podfile or Xcode project exists in the repository.

Baseline (before any change)

Run on macOS (arm64), Node 26.13.1, pnpm 12.18.0, JDK 17, Swift 6.4 command line tools (no Xcode), Android SDK with licences accepted, local Compose infrastructure (Postgres 18, Redis 8, LiveKit 1.13.11, RustFS).

CheckResult
pnpm install --frozen-lockfilePass
pnpm format:checkPass for committed files (only the locally modified, uncommitted CLAUDE.md is reported)
pnpm lint, pnpm typecheck, pnpm buildPass (18 typecheck tasks, 11 build tasks)
pnpm test:infra and turbo run testPass: API 82, auth 10, client 7, contracts 6, server 5, react 5, react-native 5, scanner-client 2, scanner 10 (+4 real-ClamAV tests skipped), docs content
pnpm audit1 moderate (esbuild via drizzle-kit, SEC-09)
./gradlew build (Android)Fail: audioswitch unresolvable (no JitPack), then compileSdk 36 < androidx.core 1.19 requirement, then AGP's built-in Kotlin used its bundled 2.2.0 compiler. lynkoria-core tests alone pass (6, 1 skipped).
swift test core (Linux swift:6.1)Pass (9 tests, 2 skipped)
swift build full package (macOS)Fail: ConnectionState ambiguous between LynkoriaCore and LiveKit
Scanner profile (clamav/clamav:1.4)Does not start on arm64 (image is amd64-only)

Note: a globally installed turbo 1.13 rejects the repository's turbo.json; use pnpm exec turbo.

Upgrades applied

Most dependencies were already at their latest stable versions; everything not listed was verified current on 2026-11-13 (pnpm outdated -r, Maven Central, Google Maven, Gradle, Docker Hub, GitHub releases).

DependencyFromToMajorCommit group
hono / @hono/node-server4.13.17 / 2.1.64.13.18 / 2.1.7 (security)NoJS runtime deps
@aws-sdk/client-s3, s3-request-presigner3.1166.03.1167.0NoJS runtime deps
livekit-client2.23.02.24.0NoJS runtime deps
esbuild under @esbuild-kit/core-utils0.18.200.25.12 (override)n/aAudit fix
JUnit (Android)5.13.46.1.3YesAndroid tests
Android compileSdk / sample targetSdk3637n/aAndroid build fix
Swift tools version5.96.0 (Swift 5 language mode)YesiOS
Node image (API, scanner)26.13.0-trixie-slim26.13.1-trixie-slimNoImages
ClamAV1.4 (floating)1.4.6 by digestNoImages
Swift CI containerswift:6.1swift:6.4.2NoCI

Structural changes: shared npm versions moved to a pnpm catalog: (resolved versions unchanged; pnpm pack emits concrete ranges); Dependabot now covers Gradle, SwiftPM, Compose and the scanner image.

Already current and unchanged: TypeScript 7.0, Oxlint/Oxfmt, Vite 8, Vitest 5, tsdown, React 19.3, Next 16.4.6, Fumadocs, TanStack, Tailwind 4.3, Zod 4, drizzle-orm 0.45 / drizzle-kit 0.31, pg, redis 6, socket.io 4.8, jose 6, pino 10, OpenTelemetry, livekit-server-sdk 2.19, react-native 0.88.1, Kotlin 2.4.21, AGP 9.5.1, Gradle 9.9.1, coroutines 1.11, serialization 1.13, livekit-android 2.30.0, Firebase Messaging 26.0.2, AndroidX, Compose BOM 2026.09.00, vanniktech publish 0.37.0, LiveKit Swift 2.19.0, LiveKit server 1.13.11, Postgres 18, Redis 8, Valkey 9, RustFS 1.0.5, all GitHub Actions.

Deliberately held

ItemHeld atReason and unblock step
OkHttp (Android)4.12.0livekit-android 2.30.0 depends on 4.12.0; 5.x would give apps two majors. Move when livekit-android does.
ClamAV1.4 LTS line1.5 is a non-LTS feature line; the scanner is a security control. Revisit when 1.4 support ends or 1.6 LTS ships.
Swift 6 language modeSwift 5 modeLynkoriaClient.ack passes untyped Any JSON across a task group. Fix in Phase 4 (Sendable JSON or Data).
CI JDK21 (LTS)JDK 25 not validated locally (JDK 17 used here). Bump after one green CI run on 25.
Peer rangesunchanged@lynkoria/react keeps react ^18.2.0 || ^19.0.0; @lynkoria/react-native keeps react-native >=0.82.0.

Validation after upgrades

CheckResult
Frozen install, format, lint, typecheck, build, all JS testsSame as baseline (all pass); a fresh clone installs, builds and typechecks with no cache
pnpm auditNo known vulnerabilities
knip (dependencies, unlisted, binaries)No unused dependencies (3 docs devDependencies flagged are used by apps/docs/examples)
./gradlew buildPass for lynkoria-core, lynkoria-android, sample (compile, lint, unit tests)
swift build (macOS, full package)Pass, including the Lynkoria target and LiveKit Swift
swift test core (swift:6.4.2)Pass (9 tests, 2 skipped)
API and scanner imagesBuild; run as uid 1000 on Node 26.13.1
Scanner real-engine suitePass 14/14 against clamav-debian:1.4.6 on arm64 (previously not runnable here)

Not validated here: hosted CI, iOS-device builds (needs Xcode), React Native native modules in a host app, image vulnerability scans (Trivy runs in CI), deployed environments.

Phase 1: infrastructure

Audit summary

Already in good shape (verified in code and config, not changed): every service validates its environment with Zod at startup and fails fast; images are multi-stage, digest-pinned, run as uid 1000 and are Trivy-scanned in CI; staging and production are separate apps, databases, buckets and keys; runtime and migration database roles are separate; App Platform uses /health/ready for routing and /health/live for restarts; metrics are on a private port; outbound webhook, push, scanner and LiveKit calls all have timeouts; LiveKit runs with auto_create: false, TURN/TLS through 443, private Prometheus port and its own Redis.

Single points of failure (accepted for v1, see blockers): one API instance, one media node, one scanner host. The API side is solved by P1-08; the rest needs provisioning.

Findings and status

IDFindingStatus
P1-01Production scanner Compose: clamd crash-looped (chown in the image's /init under cap_drop: ALL with a read-only volume). Predates this program.Fixed (5d89c6c): clamd runs directly and drops to User clamav. Verified from empty volumes under amd64: all services healthy in 31 s, EICAR detected, clean file passes.
P1-02Race: clamd loaded the image's baked database while freshclam replaced it; SelfCheck then never reloaded, so scans failed closed for up to 2 h after a fresh start.Fixed (5d89c6c): one-shot signatures-init before clamd (production and local), SelfCheck 60 s, scanner readiness healthcheck, updater process healthcheck.
P1-03Local scanner profile used an amd64-only image.Fixed: multi-arch Debian image locally (real-engine suite 14/14 on arm64 from an empty volume); production keeps Alpine (amd64 host).
P1-04API readiness probes had no timeout and stayed ready during shutdown.Fixed (5b786ea): 2 s per dependency, 503 with draining: true once shutdown starts. Unit and integration tests.
P1-05Deploy API failed on every push because staging is not provisioned.Fixed (4913468): preflight skips automatic deploys with a notice until the staging token and app id exist; manual runs still fail loudly. actionlint clean.
P1-06Request ids stopped at the API; scanner logs could not be correlated.Fixed (77dfcc8): @lynkoria/scanner-client requestId option (minor changeset), scanner accepts, echoes and logs it.
P1-07No connection-success SLI, no scrape-target-down alerts, no runbooks.Fixed (73c7eda): lynkoria_socket_connections_total, 6 new alerts (18 rules, promtool clean), runbooks with a test that every alert has one.
P1-08API could not run more than one instance: Socket.IO rooms and disconnects were process-local (ARCH-01).Fixed: Redis Streams adapter on the existing Redis with its own connection (ADR 021). Two-instance test covers delivery and suspension across instances and fails without the adapter. A Redis outage with the shared client settings pinned a CPU core; the dedicated connection avoids it (measured). Template stays at 1 instance until LOAD-01.
P1-09Shutdown flipped readiness and closed sockets at once; no drain for ingresses that route on readiness, and an early SIGTERM could crash on an unhandled adapter rejection.Fixed: SHUTDOWN_DRAIN_SECONDS (default 0), force-exit after drain + 15 s, explicit App Platform termination (drain 15 s, grace 60 s). Startup now waits for the adapter's pub/sub subscription, removing the crash. Verified with tests and a real SIGTERM on the built API (503 while draining, exit 0).
P1-10Media join success, join latency and reconnect rate are not measured server-side.Pending: needs SDK-side reporting (Phase 3) or LiveKit webhook-derived metrics.
P1-11Egress/recording would share the SFU host if enabled.Blocked on the REC-01 decision (where Egress runs).
P1-12No log shipping or alert receivers configured.Blocked: monitoring backend and on-call contacts (existing blocker).

Watch item: push.test.ts (retries transient provider failures, expired deliveries) failed once in a full local run and passed in the next six runs; deliverBatch claims deliveries database-wide, so a parallel test file creating deliveries could interfere.

Not validated here: anything on deployed infrastructure (App Platform health routing, VPC firewalls, TURN on real networks, alert delivery).

Phase 2: services

Audit summary

Topology: apps/api (control plane, messaging and workers in one process), apps/scanner (stateless, private), LiveKit (own Redis), static console and docs. No service reads another's storage. Keeping control plane and messaging together is deliberate: shared database, authentication and tenancy, no independent scaling need, and messaging already runs without the media plane. No topology change is recommended, so nothing needs approval here. The full catalog of responsibilities, interfaces, authentication, timeouts and failure behavior is in services.

Findings and status

IDFindingStatus
P2-01Webhook retries had exponential backoff without jitter (synchronized retry waves after an outage).Fixed (b65e6e3): ±20% jitter, unit tests.
P2-02A scanner consumer could hold only one token, so rotation needed coordinated downtime.Fixed (c11e552): up to four tokens per consumer; single-string config unchanged; rotation documented.
P2-03The S3/Spaces client had no connection or socket timeout.Fixed (fbc1dcd): 5 s connect, 30 s inactivity, 3 attempts.
P2-04Messaging independence from the media plane was claimed but untested.Fixed (fbc1dcd): integration test with LiveKit unreachable (ready, realtime delivery, 503 on calls).
P2-05API → scanner traffic is plain HTTP on the VPC; the bearer token is visible to anything on that network.Fixed (approved: private CA). TLS 1.3 on the scanner, CA pinned by the API, production refuses plain HTTP off-host; scripts/scanner-pki.sh, ADR 023. Verified with tests and the production Compose file locally; pending a real scanner host (INFRA-01).
P2-06No test pins compatibility between published @lynkoria/scanner-client versions and the scanner.Deferred: nothing is published yet (PUB-01), so the workspace client is the only consumer and the scanner suite already exercises it. Add a test against the previous release at the first publish.
P2-07One database for all products (ADR 007) and Fidescript media isolation (ADR 008).Existing open security decisions.

Phase 3: JavaScript SDKs

Audit summary

Packages: @lynkoria/contracts, @lynkoria/client (framework-independent core, livekit-client loaded lazily on calls.join, exposes the LiveKit Room), @lynkoria/react (provider and hooks over the client; useSyncExternalStore for connection state, per-hook subscriptions, stable context value), @lynkoria/server (typed API client and webhook verification; deliberately not a wrapper of livekit-server-sdk, because product backends never hold LiveKit secrets), @lynkoria/react-native (TypeScript layer over native modules). Architecture decision: ADR 022. Feature coverage per platform: capability matrix.

Findings and status

IDFindingStatus
P3-01require('@lynkoria/…') failed with ERR_PACKAGE_PATH_NOT_EXPORTED (exports had only import).Fixed (6ea0bb0): default condition, engines >=22.12, manifest test.
P3-02LynkoriaProvider closed and reopened the socket under Strict Mode.Fixed (cac00c6): deferred disconnect; RTL tests fail against the old provider.
P3-03@lynkoria/react had no "use client" directive, so Next.js Server Components could import hooks directly.Fixed (cac00c6): build banner, guarded by a test.
P3-04@lynkoria/server lacked notifications.send and recordings, and had no retries.Fixed: added; idempotent operations retry with backoff, jitter and Retry-After; unit tests.
P3-05Developer-facing SDK methods were mostly untested end to end (only send, history and presence on the client).Fixed: apps/api/test/sdk-surface.test.ts drives server and client methods against real infrastructure (calls, livestream tokens validated by LiveKit, suspension, members, signed webhooks, edits/reactions/deletes/reads, typing, presence status, attachments).
P3-06No device or audio-output hooks; call UI must use session methods or LiveKit components.By design (ADR 022): pass session.room to @livekit/components-react. Documented in the matrix.
P3-07Next.js and TanStack integration were undocumented and untested; SSR safety unverified in a real app.Fixed: apps/example-nextjs and apps/example-tanstack-start, each with a Playwright suite in CI (SSR, hydration without errors, one socket, realtime chat, bundle boundaries; Next.js adds a LiveKit call with fake media, TanStack adds navigation lifecycle). Guides: Next.js, TanStack.
P3-08Bundle sizes not measured; contracts bundled into one file so the client shipped zod and every schema (about 440 KB minified) without using them.Fixed: contracts build one file per module (unbundle), PushPayloadKeys moved out of the schema module. Client messaging now 51.6 KB / 16.8 KB gzip (with React 18.1 KB gzip, React Native layer 17.8 KB gzip, zero zod bytes); livekit-client stays a lazy ~143 KB gzip chunk. A browser test fails if zod reaches client chunks.
P3-09tsdown warns that its TypeScript 7.0 declaration generator is deprecated in favor of 7.1.Held: TypeScript 7.1 is beta only; upgrade when stable.

Phase 4: native mobile SDKs

Audit summary

The native SDKs already exist and follow the default architecture (no approval needed): lynkoria-core (Kotlin, coroutines/Flow, explicit API) and LynkoriaCore (Swift, actors, AsyncStream) implement messaging, presence and push on platform WebSockets; lynkoria-android and Lynkoria add calls on the official LiveKit Android and Swift SDKs; @lynkoria/react-native is a New Architecture TurboModule plus Fabric view over them. LiveKit handles audio focus and routing (AudioSwitch, AVAudioSession), simulcast, dynacast and media reconnection.

Findings and status

IDFindingStatus
P4-01Android: no foreground service for ongoing calls, so Android stops mic and camera capture when the app goes to the background; the unused FOREGROUND_SERVICE_PHONE_CALL permission was declared.Implemented, pending device validation: LynkoriaCallService (microphone/camera types limited to granted permissions, hang-up action), opt-in via LynkoriaCall.join(ongoingNotification = …); compiles, lint clean.
P4-02iOS: answering through CallKit left LiveKit free to start audio before CallKit activated the session (the classic "answered, no audio" failure).Implemented, pending device validation: engine held until didActivate, released on deactivate/reset; LiveKit calls type-check in the macOS build; the CallKit file needs an Xcode iOS build.
P4-03Swift 5 language mode; LynkoriaClient.ack passed untyped JSON across a task group, and its timeout could never fire (the group waited for an acknowledgement that never came).Fixed: Swift 6 language mode for the whole package; one-shot continuation with a real timeout; socket event payloads are Data. Full package builds on macOS; core tests pass on Linux.
P4-04Native core integration tests were skipped everywhere (no API in their CI job).Fixed: scripts/native-integration.sh runs the Kotlin and Swift core integration tests against a real API in CI; fails if the Kotlin test is skipped.
P4-05No binary-compatibility check.Partial: lynkoria-core has an ABI dump and checkKotlinAbi in check (verified to fail on change). lynkoria-android pending: Kotlin's ABI validation does not yet produce dumps for AGP 9 built-in Kotlin.
P4-06No Expo support.Implemented: config plugin (iOS usage strings, background modes), unit-tested; not yet run in a real expo prebuild.
P4-07Public Kotlin models are data classes, so adding a field later is a binary-breaking change (copy/componentN).Fixed (approved 2026-11-14): 22 public models are @Poko classes (value equals/hashCode/toString, no copy/componentN); ABI dump updated, a unit test guards against data classes returning. Source-breaking for callers of copy or destructuring; nothing is published yet.
P4-08Swift realtime integration test and all device behavior.Blocked: macOS with Xcode (XCTest), physical devices (blockers).

Phase 5: cross-cutting tests

Critical workflows and their automated coverage (all run in CI)

WorkflowAutomated coverage
Join a call, publish/subscribeBrowser: two users join a LiveKit call with fake media and see each other, then one leaves (apps/example-nextjs/e2e). API: tokens validated by LiveKit (sdk-surface.test.ts).
ReconnectBrowser: network drop, then exactly the missed messages replayed in order (example-nextjs). SDK: server-initiated disconnect and resync (sdk.test.ts). Native: Kotlin and Swift core gap recovery against a real API.
Livestream host and viewerHost and viewer tokens accepted by LiveKit (sdk-surface.test.ts); viewer tokens carry no publish grants (control-plane.test.ts). Promoting a viewer (calls.setRole) has no automated test yet: it needs a participant connected to LiveKit.
Send and receive messagesBrowser chat in both framework examples; SDK edits, reactions, deletes, read receipts and typing (sdk-surface.test.ts); fan-out across two API instances (multi-instance.test.ts).
Dependency failuresRedis, PostgreSQL and LiveKit outages: scripts/failure-drills.mjs (local, results recorded); pooled-connection termination regression test (resilience.test.ts); messaging with LiveKit down (media-independence.test.ts).
Multiple API instancesCross-instance delivery and suspension (multi-instance.test.ts); fan-out load across two instances (recorded).

Findings and status

IDFindingStatus
P5-01A PostgreSQL restart crashed the API process (unhandled pg pool error on 57P01).Fixed: pool error listener (logged); regression test fails without it; drill recovers in 52 ms.
P5-02Requests during a database outage returned 500, so clients and SDK retries treated them as bugs.Fixed: connection-class errors map to 503 service_unavailable with Retry-After: 1; unit tests.
P5-03Browser-level reconnection was untested.Fixed: Playwright network-drop test with missed-message recovery.
P5-04Fan-out across instances was unmeasured.Done locally: 100% delivery at 200, 500 and 999 receivers, p95 within a few ms of one instance (load testing). The load generator now batches token requests (macOS listen backlog).
P5-05Capacity on deployed infrastructure (300-viewer livestream, group calls, socket fan-out, database contention).Blocked: staging and separate load generators (LOAD-01).
P5-07Promoting a viewer to speaker (calls.setRole) is untested end to end.Pending: needs a test participant connected to LiveKit (a headless browser in the call e2e could do it).
P5-06Device, TURN/UDP and real-network media tests.Blocked: devices, staging media node (testing completion criteria).

Phase 6: documentation and release

IDItemStatus
P6-01Docs matched to the implementation (Node.js 22.12+, native build status, require() support, Android build)Done
P6-02Versioning policy and release checklistDone: package publishing (Changesets for npm, Gradle VERSION_NAME and Swift tags for native)
P6-03Clean installs of published artifacts (TEST-01)Partial: npm packages install, import, require(), type-check (TypeScript 5) and server-render in a fresh project in CI. RN, Compose and SwiftUI host apps pending
P6-04Changelog for the programDone: changelog
P6-05First publish to npm, Maven Central and SwiftPMBlocked: registry and namespace decisions (ADR 013, PUB-01) and publishing credentials

Remaining work

Everything below needs something outside the repository. Details and unblock steps are in blockers.

AreaItemUnblocked by
DecisionsEgress placement (REC-01), monitoring backend and alert receivers, registries (PUB-01), shared database and Fidescript isolation (ADR 007/008)Product, security and operations owners
InfrastructureStaging and production provisioning (INFRA-01), deploys, alert delivery, backup restore drillDigitalOcean/Cloudflare accounts and DNS
CapacityDeployed load tests (LOAD-01), TURN/UDP on real networksStaging and separate load generators
DevicesAndroid and iOS device tests, CallKit/foreground-service behavior, push deliveryDevices, Xcode, FCM/APNs credentials
BuildsiOS build of the Swift package (CallKit/PushKit), React Native host apps, Swift realtime testmacOS with Xcode; a React Native host app
TestsViewer promotion end to end (P5-07); Android module ABI dumps (P4-05)A livestream browser test; Kotlin ABI validation support for AGP built-in Kotlin

Pending decisions (need approval)

None open. Decided 2026-11-14:

  • P2-05, TLS between the API and the scanner: private CA (ADR 023). Implemented.
  • P4-07, Kotlin public models: @Poko classes instead of data classes. Implemented.

Phase 1 items waiting on existing decisions or provisioning: where LiveKit Egress runs (REC-01), the monitoring backend and alert receivers, and a second media node for high availability. Product and security decisions are listed in blockers.

How to resume

  1. Read this page, then the implementation tracker.
  2. Local checks: pnpm install --frozen-lockfile && pnpm check with pnpm infra:up (or docker compose ... --profile livekit --profile attachments up -d --wait) and .env exported for the API tests.
  3. Native: cd sdks/android && ./gradlew build (needs ANDROID_HOME); cd sdks/ios && swift build; Linux core tests: docker run --rm -e LYNKORIA_CORE_ONLY=1 -v "$PWD/sdks/ios:/pkg" -w /pkg swift:6.4.2 swift test.

On this page