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:
| Plane | Runs | Owns |
|---|---|---|
| Media | Self-hosted LiveKit (one CPU-Optimized Droplet, SGP1) | Audio/video/screen tracks, ICE/TURN, room participants |
| Control | apps/api (Hono) | Service-key auth, room creation, short-lived tokens, quotas, webhooks, console API |
| Messaging | apps/api (Hono + Socket.IO) | Conversations, sequenced messages, receipts, reactions, attachments, presence |
| File scanning | apps/scanner + ClamAV (private host) | Malware/type verdicts for attachments; holds no database or storage credentials |
| Product backend | Each product | Users, 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
| Path | What |
|---|---|
apps/api | Control plane + messaging service (REST, Socket.IO, workers). Bundled with tsdown; workspace packages are inlined. |
apps/docs | Fumadocs static site, content sourced directly from root docs/ |
apps/admin | Lynkoria Console (Vite + React + TanStack Router/Query + Tailwind), static; password sign-in, optional Access |
apps/scanner | Independent malware-scanning service (Hono + ClamAV clamd INSTREAM) |
apps/playground | Demo app + a local stand-in product backend (dev server only) |
packages/contracts | Zod schemas, event names, error codes (published) |
packages/db | Drizzle schema, SQL migrations, migration runner |
packages/auth | Service 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/brand | Design tokens, Tailwind theme and shared component layer for the three web apps |
packages/config | Shared tsconfig presets |
sdks/android, sdks/ios | Native 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, retentionKey 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)
| Component | Where |
|---|---|
| LiveKit + Caddy + TURN + local Redis | 1 CPU-Optimized Droplet, SGP1 |
| API + Socket.IO | App Platform, SGP; 1 instance deployed, multi-instance capable (ADR 021) |
| PostgreSQL | Managed, SGP1, private |
| Redis/Valkey | Managed, SGP1, private |
| Attachments | Spaces, sgp1, private |
| Malware scanner + ClamAV | Private Droplet on the VPC (infra/scanner) |
| Console, docs | Cloudflare 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
| Endpoint | Exposure | Port / protocol | Notes |
|---|---|---|---|
API (api.<domain>) | Public HTTPS | 443 → App Platform 8080 | REST, Socket.IO (WebSocket only), LiveKit webhook ingress |
| API metrics | Private | 9464 (internal_ports) | Scraped by the monitoring worker; never routed publicly |
LiveKit signaling (rtc.<domain>) | Public WSS | 443 via Caddy → 7880 | Raw 7880 is never exposed |
| LiveKit media | Public | UDP 50000-60000, TCP 7881 | ICE; restrict everything else in the firewall |
TURN (turn.<domain>) | Public TLS | 443 (TURN/TLS via Caddy), UDP 3478 | For clients behind restrictive networks |
| Scanner | Private VPC only | 3344 HTTPS (TLS 1.3, private CA), bearer token per consumer | clamd is on an internal network with no egress; ADR 023 |
| PostgreSQL, Valkey | Private VPC only | Managed endpoints, TLS | Trusted sources: the App and operator IPs during setup |
| Spaces | Public HTTPS | 443, presigned URLs only (5 min) | Bucket is private; CORS limited to product origins |
| Console, docs | Public HTTPS | Cloudflare Pages | Static; security headers in each app's public/_headers |
Exact firewall rules are code in infra/opentofu/platform/{media,scanner}.tf; see the deployment handbook.