SDK architecture
How the web, React Native, Android, iOS and server SDKs fit together and what each owns.
Every Lynkoria SDK talks to the same API and event contracts (@lynkoria/contracts, /openapi.json). Media always flows between the client and LiveKit; the Lynkoria API never relays audio or video. The API owns authentication, authorization, rooms, tokens, messaging, push, recording jobs and file scanning.
Packages
| Package | Platform | Owns | Status |
|---|---|---|---|
@lynkoria/server | Node.js product backends | Service-key calls: rooms, join tokens, messaging tokens, conversations, webhooks | Tested against the local API |
@lynkoria/client | Browsers, React Native (JS) | Messaging, presence, typing, call signals, push registration; browser media (LiveKit) | Tested against the local API |
@lynkoria/react | React (web) | Hooks over @lynkoria/client | Unit tested |
@lynkoria/react-native | React Native ≥ 0.82 | Native media via TurboModule + Fabric view; re-exports @lynkoria/client messaging | TS layer and codegen verified; native code not compiled or device-tested |
io.lynkoria:lynkoria-core | JVM / Android | Messaging, presence, push payloads, tokens (Kotlin coroutines + Flow) | Unit and integration tested against the local API |
io.lynkoria:lynkoria-android | Android | LiveKit calls, screen share, audio routing, incoming-call notifications, lifecycle | Compiles (./gradlew build); not device-tested |
LynkoriaCore (SwiftPM) | iOS, macOS, Linux | Messaging, presence, push payloads, tokens (async/await + AsyncStream) | Unit tested; REST integration tested on Linux |
Lynkoria (SwiftPM) | iOS, macOS | LiveKit calls, CallKit, PushKit, screen share | Compiles for macOS (swift build); iOS build needs Xcode |
@lynkoria/scanner-client | Node.js services | Typed client for the malware-scanning service | Tested against the scanner |
Shared contracts
- Tokens. Apps receive short-lived messaging tokens and call join credentials from their own backend, which uses a service key. No SDK accepts a service key.
- Messages. Every conversation event has a sequence number. All SDKs apply
last + 1, drop duplicates (<= last) and fill gaps withGET /v1/conversations/{id}/messages?after_seq=last. Every (re)connect replays tracked conversations, so missed events are recovered after network loss or backgrounding. - Sends are idempotent on
clientMessageId; retry with the same id. - Realtime uses Socket.IO v4 over WebSocket only. The Kotlin and Swift cores implement the small subset Lynkoria uses (connect with auth, ping/pong, events, acknowledgements) on the platform WebSocket, avoiding third-party socket libraries.
- Errors carry the contract
code(unauthorized,not_found,feature_disabled, …), HTTP status and request id:LynkoriaError(TS, Swift) andLynkoriaException(Kotlin). - Push payloads use the same keys everywhere (
lynkoria_kind,lynkoria_call_id, …); each SDK exposes a parser.
Native conventions
| Concern | Android | iOS | React Native |
|---|---|---|---|
| Async | suspend functions | async throws | Promises |
| Event streams | StateFlow / SharedFlow | AsyncStream | listener functions returning unsubscribe |
| Client lifetime | bindToProcessLifecycle() | connect in .task, disconnect on background | AppState in the app |
| Incoming calls | CallStyle notification + full-screen intent | PushKit + CallKit | incomingCalls over the native layer |
See native media, React Native, Android and iOS.