Skip to Content
LYNKORIADocs

Architecture

Components, planes, data flows, endpoints and tenancy.

Lynkoria is Guildsman's shared communications platform for VibeLynk, Fidescript and LumoLynk. It is three planes plus the products' own backends:

PlaneRunsOwns
MediaSelf-hosted LiveKit (one CPU-Optimized Droplet, SGP1)Audio/video/screen tracks, ICE/TURN, room participants
Controlapps/api (Hono)Service-key auth, room creation, short-lived tokens, quotas, webhooks, console API
Messagingapps/api (Hono + Socket.IO)Conversations, sequenced messages, receipts, reactions, attachments, presence
File scanningapps/scanner + ClamAV (private host)Malware/type verdicts for attachments; holds no database or storage credentials
Product backendEach productUsers, friendships/blocks, appointments, workspace permissions, product auth

Service responsibilities, interfaces, timeouts and failure behavior: services.

flowchart LR
  client["App or browser"] -- "1. ask for access" --> product["Product backend"]
  product -- "2. service key" --> api["Lynkoria API"]
  product -- "3. short-lived tokens" --> client
  client -- "4. room token" --> livekit["LiveKit SFU and TURN"]
  client -- "4. messaging token" --> api
  api -- "create rooms, webhooks" --> livekit
  api --> pg[("PostgreSQL: source of truth")]
  api --> redis[("Redis: presence, rate limits, fan-out")]
  api --> spaces[("Spaces: attachments, recordings")]
  api -- "HTTPS, private CA" --> scanner["Scanner and ClamAV"]
  api -- "signed webhooks" --> product

The product backend authorizes the user; Lynkoria authorizes the product (from the key) and derives project, environment and grants server-side. Clients never hold service keys or LiveKit secrets.

Repository

PathWhat
apps/apiControl plane + messaging service (REST, Socket.IO, workers). Bundled with tsdown; workspace packages are inlined.
apps/docsFumadocs static site, content sourced directly from root docs/
apps/adminLynkoria Console (Vite + React + TanStack Router/Query + Tailwind), static; password sign-in, optional Access
apps/scannerIndependent malware-scanning service (Hono + ClamAV clamd INSTREAM)
apps/playgroundDemo app + a local stand-in product backend (dev server only)
packages/contractsZod schemas, event names, error codes (published)
packages/dbDrizzle schema, SQL migrations, migration runner
packages/authService keys, messaging JWTs (ES256), console passwords (scrypt), Access verification, webhook signing
packages/sdk-server@lynkoria/server for product backends
packages/sdk-client@lynkoria/client for browser/Electron: messaging, presence, calls (lazy livekit-client), push registration
packages/sdk-react@lynkoria/react hooks
packages/sdk-react-native@lynkoria/react-native (TurboModule + Fabric over the native SDKs; preview)
packages/scanner-client@lynkoria/scanner-client HTTP client and verdict types for the scanner
packages/brandDesign tokens, Tailwind theme and shared component layer for the three web apps
packages/configShared tsconfig presets
sdks/android, sdks/iosNative Kotlin and Swift SDKs (cores tested; media layers preview)
infra/Local Compose, LiveKit templates, scanner Compose, DigitalOcean spec/scripts, Prometheus rules
loadtest/k6 API scenarios, LiveKit lk load-test runner and recorded results

API service internals

apps/api/src
├── config.ts                 zod-validated env; fails fast, never echoes values
├── app.ts / server.ts        Hono app, Socket.IO, workers, graceful shutdown
├── middleware/               service-key, messaging JWT, admin identity (console session + optional Access)
├── modules/
│   ├── calls/                rooms, device-scoped tokens, moderation, LiveKit adapter, signaling
│   ├── sessions/             messaging tokens, user suspension
│   ├── webhooks/             inbound LiveKit (raw-body verify, dedupe), outbox enqueue
│   ├── messaging/            conversations, sequenced events, resync, read watermarks
│   ├── presence/             Redis sorted-set leases (Lua), sweeper, last_seen_at
│   ├── attachments/          presigned PUT to quarantine, scan, publish verified bytes, presigned GET
│   ├── recordings/           LiveKit Egress lifecycle, storage, retention
│   ├── push/                 device registration, FCM/APNs delivery worker
│   ├── admin/                console sign-in, console API, RBAC, audit, operations view
│   └── usage/                buffered daily rollups, last_used_at
├── sockets/                  origin check, handshake auth, per-event authz, revalidation
└── workers/                  outbox delivery, push delivery, call reconciler, retention

Key flows

Calls. POST /v1/calls creates a call_sessions row (advisory lock per environment enforces the concurrent-room quota) and the LiveKit room (auto_create: false). POST /v1/calls/:id/join-token returns a 5-minute token for identity project:user:device with grants derived from the role. LiveKit webhooks (raw-body signature, event-id dedupe) track participant sessions and usage; a reconciler closes calls/participants LiveKit no longer has.

Messaging. A send locks the conversation row, checks idempotency (client_message_id), allocates last_seq + 1, inserts the message and a conversation_events row and an outbox event, commits, then acks and fans out message:created to members' user rooms. Edits/deletes/reactions allocate a sequence too. Clients apply events in order, drop duplicates, and resync with after_seq on gaps or reconnects. Realtime delivery is an optimization; PostgreSQL is the source of truth.

Presence. Per-device leases in Redis sorted sets (presence:{env}:{tenant}:{user}) plus a global expiry set; heartbeat every ~25 s, 60 s lease; a sweeper (one instance via Redis lock) expires dead leases; a Lua recompute announces only real changes; offline writes last_seen_at. Audience: subscribers in the same project environment and tenant.

Outbound webhooks. Outbox rows are claimed with FOR UPDATE SKIP LOCKED, woken by LISTEN/NOTIFY (5 s polling fallback), signed t=<unix>,v1=<hmac>, retried 1 m → 24 h, then dead-lettered (console retry).

Tenancy

Every row is scoped by project environment (environment_id, derived from the key or token) and, for messaging, tenant_id (LumoLynk workspace, Fidescript organization, VibeLynk default). Composite foreign keys (conversation_id, environment_id, tenant_id) make cross-tenant references impossible at the schema level. Socket rooms are derived only from verified token claims.

Deployment (v1: Singapore only)

ComponentWhere
LiveKit + Caddy + TURN + local Redis1 CPU-Optimized Droplet, SGP1
API + Socket.IOApp Platform, SGP; 1 instance deployed, multi-instance capable (ADR 021)
PostgreSQLManaged, SGP1, private
Redis/ValkeyManaged, SGP1, private
AttachmentsSpaces, sgp1, private
Malware scanner + ClamAVPrivate Droplet on the VPC (infra/scanner)
Console, docsCloudflare Pages (console optionally behind Cloudflare Access)

Multi-region is a measured future option (ADR 016), not part of v1.

Deployment boundaries

A LiveKit key can sign a token for any room on its node. Keys do not provide SFU isolation; the API enforces the product boundary. Dedicated Fidescript media requires a separately configured API/media stack in the current implementation. Recording runs through LiveKit Egress when an Egress service is deployed (preview). Multi-region and Lynkoria-managed E2EE remain future work. The API can run several instances (ADR 021).

Endpoints and ports

EndpointExposurePort / protocolNotes
API (api.<domain>)Public HTTPS443 → App Platform 8080REST, Socket.IO (WebSocket only), LiveKit webhook ingress
API metricsPrivate9464 (internal_ports)Scraped by the monitoring worker; never routed publicly
LiveKit signaling (rtc.<domain>)Public WSS443 via Caddy → 7880Raw 7880 is never exposed
LiveKit mediaPublicUDP 50000-60000, TCP 7881ICE; restrict everything else in the firewall
TURN (turn.<domain>)Public TLS443 (TURN/TLS via Caddy), UDP 3478For clients behind restrictive networks
ScannerPrivate VPC only3344 HTTPS (TLS 1.3, private CA), bearer token per consumerclamd is on an internal network with no egress; ADR 023
PostgreSQL, ValkeyPrivate VPC onlyManaged endpoints, TLSTrusted sources: the App and operator IPs during setup
SpacesPublic HTTPS443, presigned URLs only (5 min)Bucket is private; CORS limited to product origins
Console, docsPublic HTTPSCloudflare PagesStatic; security headers in each app's public/_headers

Exact firewall rules are code in infra/opentofu/platform/{media,scanner}.tf; see the deployment handbook.

On this page