Skip to Content
LYNKORIADocs

Services

What each deployable service owns, how services talk to each other, and how each call fails.

Lynkoria has three deployable services of its own plus LiveKit. The control plane, messaging and background workers deliberately share one process (apps/api): they share the database, authentication and tenancy rules, and splitting them would add network hops and deployments without an independent scaling need. Messaging does not depend on the media plane: with LiveKit unreachable the API stays ready and delivers messages (apps/api/test/media-independence.test.ts).

Catalog

ServiceResponsibilitiesOwns (data)ScalesWithout it
apps/apiControl plane (keys, rooms, tokens, quotas, console API), messaging, presence, workersPostgreSQL (all platform tables), Redis keys (rl:, lock:, presence, Socket.IO stream), Spaces objectsHorizontally (ADR 021)Nothing works
apps/scanner + ClamAVMalware and file-type verdictsNothing (stateless; keeps no file copy, no database or storage credentials)Vertically (clamd memory); more hosts behind one URL possibleUploads stay quarantined (fail closed); everything else works
LiveKit (+ local Redis)SFU, TURN, room participantsRoom state in its own Redis (never shared with the API's)One node (v1)Calls and livestreams fail with 503 on create/join; messaging, presence and webhooks continue
Console, docsStatic sitesNothingCDNNo admin UI; the API is unaffected

Each service owns its data; no service reads another's storage. The scanner and LiveKit never connect to PostgreSQL.

Interfaces between services

From → toProtocol and contractAuthenticationTimeout and retriesFailure handling
Product backend → APIREST /v1 (OpenAPI in docs/openapi.json), @lynkoria/serverService key (hashed with a pepper at rest)Client's choiceTyped error codes (errors), x-request-id
Client → APIREST /v1, Socket.IO (WebSocket only); events in @lynkoria/contractsShort-lived messaging JWT (ES256), revalidated per eventClient reconnect with backoff; resync by after_seqOrdered recovery from PostgreSQL; realtime is best effort
API → LiveKitlivekit-server-sdk (Twirp over HTTPS)Per-environment API key pairs10 s (rooms), 15 s (Egress); no automatic retry503 service_unavailable; the reconciler closes calls LiveKit no longer has
LiveKit → APIWebhooks POST /v1/webhooks/livekitSigned with a dedicated webhook key; raw-body verificationLiveKit's own deliveryEvent-id deduplication; reconciler covers lost webhooks
API → scannerREST /v1/scan, /v1/engine (@lynkoria/scanner-client), private VPC, TLS 1.3 with a pinned private CA (ADR 023)Per-consumer bearer token, constant-time compare; several per consumer during rotation60 s client timeout; no retry (the upload is marked failed and can be completed again)Fail closed: file stays quarantined; AttachmentScansFailing alert
Scanner → clamdclamd INSTREAM over TCP on an internal Docker networkNetwork isolation (no published port, no egress)SCANNER_TIMEOUT_MS (30 s)503; readiness fails on stale signatures
API → product webhooksJSON events with id, type, created_at; User-Agent: Lynkoria-Webhooks/1HMAC t=…,v1=… per environment secret, rotation with two secrets10 s; 12 attempts, 1 m doubling to 24 h, ±20% jitter; then dead-letteredAt-least-once; products dedupe by id; console retry
API → FCM / APNsHTTPS (HTTP/2 for APNs)Product credentials from PUSH_CREDENTIALS_JSON10 s; backoff from 2 s to 5 min, ±20% jitterRetries, then dead; invalid tokens are invalidated
API → PostgreSQLpg poolRuntime role (DML only); migrations use a separate role5 s connect, 30 s statement, 60 s idle-in-transaction (role settings)Readiness fails; requests return 503/500
API → Redis/Valkeyredis client (TLS with rediss://)Managed credentialsReconnect with backoff up to 5 s; no offline queue for the main clientRate-limited routes fail closed (503); readiness fails
API → SpacesS3 API, presigned URLs for clientsAccess key (bucket-scoped)5 s connect, 30 s socket inactivity, 3 attempts (SDK retry with jitter)503 on upload completion; clients retry

Contract versioning

  • Public REST and socket contracts are versioned under /v1; changes within v1 are additive (compatibility). Breaking changes need a /v2 and an approved migration window.
  • The scanner API is versioned under /v1 and released with @lynkoria/scanner-client. The scanner must accept every client version the API or other consumers run; new request headers are optional and ignored by older scanners (for example x-request-id).
  • Webhook payloads are additive within Lynkoria-Webhooks/1; receivers must ignore unknown fields and event types.

Open items

ItemWhy it is not done
One database for all products (ADR 007)Open security decision; Fidescript isolation depends on it (ADR 008)
Recording (Egress) placementREC-01: Egress must not share the SFU host

On this page