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.
| Phase | Status |
|---|---|
| 1. Audit | Completed |
| 2. Documentation | Completed |
| 3. Console foundations and security | Completed |
| 4. Platform management | Completed |
| 5. Analytics and dashboard | Completed |
| 6. Testing and validation | Completed |
| 7. Final review | Completed |
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–0005run in the existing PRE_DEPLOY job (indexes build withoutCONCURRENTLY; see the deployment handbook). No new environment variables, services or infrastructure. Hourly usage starts collecting when0004is 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)
| Check | Result |
|---|---|
| Format, lint, types | oxfmt --check (only the uncommitted local CLAUDE.md differs), oxlint --deny-warnings and every workspace typecheck pass. |
| API tests | 123 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. |
| Docs | Build 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-end | pnpm --filter @lynkoria/admin test:e2e (Playwright, also in CI): 10 workflows against a seeded API, including read-only developer and cross-organization refusal. |
| Accessibility | axe (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. |
| Performance | Local 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 validated | Against 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)
| Item | Result |
|---|---|
| Hourly rollup | project_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. |
| Endpoints | GET /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). |
| Overview | Live tiles, 30-day tiles with sparklines, activity chart, projects table, recent activity. |
| Analytics | Shared 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-time | Polling 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). |
| Aggregation | Counts summed, peaks as maxima, error rate from summed counts; validated in console-admin.test.ts against inserted rollup rows. |
Phase 4 results (platform management)
| Area | Console | API (all audited when they change something) |
|---|---|---|
| Projects | List, create, rename, disable/enable (existing) | Deletion not offered (PD-3) |
| Environments, keys, webhooks secrets | Existing pages | Existing |
| Calls and livestreams | Calls tab: live state, quota meter, filtered list, detail drawer, End call, Remove participant | GET /calls, GET /calls/{id}, POST .../end, POST .../participants/{identity}/remove, GET /live |
| Webhooks | Pending, dead and delivered history with paging; backlog per environment | GET /webhook-events |
| Team | Last activity in this organization | GET /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 health | Not shown: no per-environment presence counter, socket metrics need PD-5 | — |
| Infrastructure | Not 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)
| Item | Result |
|---|---|
| Authentication | Unchanged model (password sessions, lockout, idle and absolute timeouts, origin check, optional Access). MFA and step-up re-authentication are PD-2. |
| Authorization | Every admin route documents its roles (x-console-roles); refused changes are audited. Tests check denial across organizations and roles. |
| Audit log | Append-only in the database (migration 0002 triggers); server-side filters (action prefix with *, actor, dates); sign-ins, refusals, exports and session ends recorded. |
| Exports | GET /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. |
| Decisions | ADR 024 (charts stay in-house SVG), ADR 025 (analytics data sources), ADR 026 (audience, authorization, audit). |
| Metrics catalog | METRICS in @lynkoria/contracts/catalog; docs/metrics-catalog.md generated; console info popovers read the same entries. |
| Shared UI | DataTable (cursor paging, sort, optional columns), useUrlState, RangePicker, TimeSeriesChart, Meter, StatTile, ChartCard, MetricInfo. |
Phase 2 results (documentation)
| Item | Result |
|---|---|
| HTTP API reference | Generated 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 reference | Generated 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 variables | apps/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 examples | Every 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 status | Mermaid diagrams (remarkMdxMermaid + a client renderer); capability marks render as labelled badges. |
| Developer vs operator docs | Kept as separate sidebar roots: Developer guides; Architecture, Deployment, Operations, Security for operators. |
| Versioned docs | Not needed yet: every package is 0.1.0 and unpublished; reference pages state the version they describe. Revisit at the first breaking release. |
| Not done | Kotlin (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)
| ID | Decision | Recommendation |
|---|---|---|
| PD-1 | Platform operator role for infrastructure and cross-tenant views | Add 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-2 | MFA and step-up re-authentication for console accounts | TOTP 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-3 | Project deletion | Keep 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-4 | Console user management in the UI (disable, revoke sessions) | After PD-1, expose to platform operators only; tenant owners keep role grants. |
| PD-5 | Monitoring 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.
| Phase | Status |
|---|---|
| 0. Dependency updates | Completed (hosted CI green on ce27d7c) |
| 1. Infrastructure | Implemented; remaining items blocked or moved |
| 2. Microservices | Completed |
| 3. JavaScript SDKs | Completed (CI green) |
| 4. Native mobile SDKs | Implemented; device validation pending |
| 5. Cross-cutting tests | Implemented locally; deployed load tests blocked |
| 6. Documentation/release | Completed (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
| Area | Files |
|---|---|
| npm workspace | root 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 |
| Android | sdks/android (Gradle wrapper, libs.versions.toml, 3 modules), packages/sdk-react-native/android/build.gradle |
| iOS | sdks/ios/Package.swift, packages/sdk-react-native/lynkoria-react-native.podspec |
| Images | infra/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).
| Check | Result |
|---|---|
pnpm install --frozen-lockfile | Pass |
pnpm format:check | Pass for committed files (only the locally modified, uncommitted CLAUDE.md is reported) |
pnpm lint, pnpm typecheck, pnpm build | Pass (18 typecheck tasks, 11 build tasks) |
pnpm test:infra and turbo run test | Pass: 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 audit | 1 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).
| Dependency | From | To | Major | Commit group |
|---|---|---|---|---|
| hono / @hono/node-server | 4.13.17 / 2.1.6 | 4.13.18 / 2.1.7 (security) | No | JS runtime deps |
| @aws-sdk/client-s3, s3-request-presigner | 3.1166.0 | 3.1167.0 | No | JS runtime deps |
| livekit-client | 2.23.0 | 2.24.0 | No | JS runtime deps |
esbuild under @esbuild-kit/core-utils | 0.18.20 | 0.25.12 (override) | n/a | Audit fix |
| JUnit (Android) | 5.13.4 | 6.1.3 | Yes | Android tests |
| Android compileSdk / sample targetSdk | 36 | 37 | n/a | Android build fix |
| Swift tools version | 5.9 | 6.0 (Swift 5 language mode) | Yes | iOS |
| Node image (API, scanner) | 26.13.0-trixie-slim | 26.13.1-trixie-slim | No | Images |
| ClamAV | 1.4 (floating) | 1.4.6 by digest | No | Images |
| Swift CI container | swift:6.1 | swift:6.4.2 | No | CI |
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
| Item | Held at | Reason and unblock step |
|---|---|---|
| OkHttp (Android) | 4.12.0 | livekit-android 2.30.0 depends on 4.12.0; 5.x would give apps two majors. Move when livekit-android does. |
| ClamAV | 1.4 LTS line | 1.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 mode | Swift 5 mode | LynkoriaClient.ack passes untyped Any JSON across a task group. Fix in Phase 4 (Sendable JSON or Data). |
| CI JDK | 21 (LTS) | JDK 25 not validated locally (JDK 17 used here). Bump after one green CI run on 25. |
| Peer ranges | unchanged | @lynkoria/react keeps react ^18.2.0 || ^19.0.0; @lynkoria/react-native keeps react-native >=0.82.0. |
Validation after upgrades
| Check | Result |
|---|---|
| Frozen install, format, lint, typecheck, build, all JS tests | Same as baseline (all pass); a fresh clone installs, builds and typechecks with no cache |
pnpm audit | No known vulnerabilities |
knip (dependencies, unlisted, binaries) | No unused dependencies (3 docs devDependencies flagged are used by apps/docs/examples) |
./gradlew build | Pass 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 images | Build; run as uid 1000 on Node 26.13.1 |
| Scanner real-engine suite | Pass 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
| ID | Finding | Status |
|---|---|---|
| P1-01 | Production 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-02 | Race: 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-03 | Local 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-04 | API 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-05 | Deploy 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-06 | Request 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-07 | No 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-08 | API 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-09 | Shutdown 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-10 | Media 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-11 | Egress/recording would share the SFU host if enabled. | Blocked on the REC-01 decision (where Egress runs). |
| P1-12 | No 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
| ID | Finding | Status |
|---|---|---|
| P2-01 | Webhook retries had exponential backoff without jitter (synchronized retry waves after an outage). | Fixed (b65e6e3): ±20% jitter, unit tests. |
| P2-02 | A 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-03 | The S3/Spaces client had no connection or socket timeout. | Fixed (fbc1dcd): 5 s connect, 30 s inactivity, 3 attempts. |
| P2-04 | Messaging independence from the media plane was claimed but untested. | Fixed (fbc1dcd): integration test with LiveKit unreachable (ready, realtime delivery, 503 on calls). |
| P2-05 | API → 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-06 | No 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-07 | One 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
| ID | Finding | Status |
|---|---|---|
| P3-01 | require('@lynkoria/…') failed with ERR_PACKAGE_PATH_NOT_EXPORTED (exports had only import). | Fixed (6ea0bb0): default condition, engines >=22.12, manifest test. |
| P3-02 | LynkoriaProvider 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-05 | Developer-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-06 | No 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-07 | Next.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-08 | Bundle 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-09 | tsdown 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
| ID | Finding | Status |
|---|---|---|
| P4-01 | Android: 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-02 | iOS: 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-03 | Swift 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-04 | Native 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-05 | No 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-06 | No Expo support. | Implemented: config plugin (iOS usage strings, background modes), unit-tested; not yet run in a real expo prebuild. |
| P4-07 | Public 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-08 | Swift 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)
| Workflow | Automated coverage |
|---|---|
| Join a call, publish/subscribe | Browser: 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). |
| Reconnect | Browser: 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 viewer | Host 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 messages | Browser 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 failures | Redis, 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 instances | Cross-instance delivery and suspension (multi-instance.test.ts); fan-out load across two instances (recorded). |
Findings and status
| ID | Finding | Status |
|---|---|---|
| P5-01 | A 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-02 | Requests 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-03 | Browser-level reconnection was untested. | Fixed: Playwright network-drop test with missed-message recovery. |
| P5-04 | Fan-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-05 | Capacity on deployed infrastructure (300-viewer livestream, group calls, socket fan-out, database contention). | Blocked: staging and separate load generators (LOAD-01). |
| P5-07 | Promoting 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-06 | Device, TURN/UDP and real-network media tests. | Blocked: devices, staging media node (testing completion criteria). |
Phase 6: documentation and release
| ID | Item | Status |
|---|---|---|
| P6-01 | Docs matched to the implementation (Node.js 22.12+, native build status, require() support, Android build) | Done |
| P6-02 | Versioning policy and release checklist | Done: package publishing (Changesets for npm, Gradle VERSION_NAME and Swift tags for native) |
| P6-03 | Clean 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-04 | Changelog for the program | Done: changelog |
| P6-05 | First publish to npm, Maven Central and SwiftPM | Blocked: 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.
| Area | Item | Unblocked by |
|---|---|---|
| Decisions | Egress placement (REC-01), monitoring backend and alert receivers, registries (PUB-01), shared database and Fidescript isolation (ADR 007/008) | Product, security and operations owners |
| Infrastructure | Staging and production provisioning (INFRA-01), deploys, alert delivery, backup restore drill | DigitalOcean/Cloudflare accounts and DNS |
| Capacity | Deployed load tests (LOAD-01), TURN/UDP on real networks | Staging and separate load generators |
| Devices | Android and iOS device tests, CallKit/foreground-service behavior, push delivery | Devices, Xcode, FCM/APNs credentials |
| Builds | iOS build of the Swift package (CallKit/PushKit), React Native host apps, Swift realtime test | macOS with Xcode; a React Native host app |
| Tests | Viewer 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:
@Pokoclasses 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
- Read this page, then the implementation tracker.
- Local checks:
pnpm install --frozen-lockfile && pnpm checkwithpnpm infra:up(ordocker compose ... --profile livekit --profile attachments up -d --wait) and.envexported for the API tests. - Native:
cd sdks/android && ./gradlew build(needsANDROID_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.