Skip to Content
LYNKORIADocs

Architecture overview

Every deployable service, what it depends on, how services talk to each other, and which ports and hostnames are public.

Read this once before deploying. It explains what each piece does so the later steps make sense. The deeper design (failure modes, timeouts, contracts) is in architecture and services.

The services

ServiceWhat it doesDepends on
API (apps/api)One Node.js process: control plane (projects, keys, rooms, tokens, quotas), console API, messaging over Socket.IO, presence, product webhooks, push and background workersPostgreSQL, Valkey; LiveKit, Spaces and scanner for those features
Migrationsnode dist/migrate.js from the API image. Runs as an App Platform pre-deploy job before each new version receives trafficPostgreSQL (migration role)
LiveKitThe media server (SFU): audio, video, screen sharing, livestreams. Includes a TURN server for restrictive networksIts own local Redis on the same Droplet
Caddy (media Droplet)Terminates TLS for rtc. and turn. with Let's Encrypt certificates and forwards to LiveKit. Configured by OpenTofu (media.tf), same layout as LiveKit's VM generatorPublic ports 80 and 443
Scanner (apps/scanner)Checks uploaded attachments with ClamAV before the API publishes them. Stateless, no database accessclamd and a signature updater on the same host
PostgreSQLSource of truth for all platform data—
ValkeyRate limits, locks, presence and the Socket.IO cross-instance stream—
SpacesPrivate object storage for attachments (and recordings when Egress is deployed). Clients upload and download with short-lived presigned URLs—
Admin consoleStatic single-page app for operators. Calls /v1/admin/* on the API with a session cookieAPI
DocumentationStatic export of this site, plus the landing page and /.well-known/security.txt—
Monitoring workerA pinned Prometheus worker inside the API's App Platform app; scrapes API and LiveKit metrics and remote-writes to your backendYour monitoring provider

Messaging, presence and signaling are not separate services: they are part of the API process. Each API instance runs the workers too. There is no separate messaging deployment.

Who talks to whom

From → toHowCredential
Product backend → APIHTTPS REST /v1 through CloudflareService key
Browser/app → APIHTTPS REST and Socket.IO (WebSocket only) through CloudflareShort-lived messaging JWT (ES256, MESSAGING_JWT_PRIVATE_KEY)
Operator → console → APIStatic site, then /v1/admin/* with a session cookieConsole password session (+ Cloudflare Access)
Browser/app → LiveKitWSS to rtc., media over UDP 50000–60000, TCP 7881 or TURNLiveKit join token minted by the API
API → LiveKitHTTPS (Twirp) to rtc.LIVEKIT_KEYS_JSON key pairs
LiveKit → APIWebhooks to https://api.<domain>/v1/webhooks/livekitSigned with LIVEKIT_WEBHOOK_KEY / LIVEKIT_WEBHOOK_SECRET
API → scannerHTTPS on the private VPC, port 3344, pinned private CASCANNER_TOKEN, SCANNER_CA_CERT
API → PostgreSQLTLS, private VPC: pooled runtime + direct runtime connectionslynkoria_app role
Migration job → PostgreSQLTLS, private VPC, direct connectionlynkoria_migrate role
API → Valkeyrediss:// (TLS), private VPCManaged credentials
API → Spaces / clientsS3 API; clients use presigned URLs (5 minutes)SPACES_ACCESS_KEY_ID / SPACES_SECRET_ACCESS_KEY
API → product webhooksHTTPS POST with HMAC signaturePer-environment webhook secret (WEBHOOK_SECRET_MASTER)
API → FCM / APNsHTTPSPUSH_CREDENTIALS_JSON (optional)

Hostnames

HostPoints toCloudflare proxyServes
api.lynkoria.comApp Platform (CNAME)Proxied (orange)REST, Socket.IO, LiveKit webhooks
console.lynkoria.comCloudflare PagesProxied + AccessAdmin console
lynkoria.comCloudflare PagesProxiedLanding page and documentation
www.lynkoria.comRedirect rule to the apexProxied301 redirect
rtc.lynkoria.comMedia Droplet IP (A record)DNS onlyLiveKit signaling and media
turn.lynkoria.comMedia Droplet IP (A record)DNS onlyTURN over TLS
scanner.internal.lynkoria.comScanner private IP (A record)DNS onlyScanner certificate name; reachable only inside the VPC

OpenTofu creates and updates all of these records. The full list, including staging and email records, is in Cloudflare zone.

Ports

WherePort(s)Open toPurpose
Media DropletTCP 22Your admin IPs onlySSH
Media DropletTCP 80InternetLet's Encrypt HTTP challenge (Caddy)
Media DropletTCP 443InternetWSS signaling and TURN/TLS (Caddy)
Media DropletTCP 7881InternetWebRTC over TCP fallback
Media DropletUDP 3478InternetTURN/UDP
Media DropletUDP 50000–60000InternetWebRTC media
Media Droplet7880, 6379, 6789Nobody (localhost / VPC only)LiveKit HTTP, its Redis, its metrics
Scanner DropletTCP 3344VPC CIDR onlyScanner API (HTTPS)
Scanner DropletTCP 22Your admin IPs onlySSH
App Platform (API)8080 (public via ingress), 9464Ingress / same app onlyHTTP; Prometheus metrics (internal)
Managed PG / ValkeyManaged TLS portsTrusted sources (VPC, the App)Databases

Reverse proxies and TLS, in one place

There is no Nginx in this deployment, and you do not need to write one.

  • API: Cloudflare terminates the visitor's TLS, then connects to App Platform over TLS (SSL mode Full (strict)). App Platform issues the origin certificate for api.<domain>.
  • Console and docs: Cloudflare Pages serves them with Cloudflare certificates.
  • Media: Caddy (with the layer4 plugin) on the media Droplet gets Let's Encrypt certificates for rtc. and turn.. OpenTofu writes its configuration through cloud-init. That is why those records must be DNS only.
  • Scanner: serves HTTPS itself with a certificate from a private CA that OpenTofu generates (ADR 023). Its certificate names scanner.internal.lynkoria.com, a DNS-only record that points at the scanner's private IP. It is never public.
  • Databases: managed TLS; the API verifies the DigitalOcean CA (DATABASE_CA_CERT).

What is not deployed

  • apps/playground, apps/example-nextjs and apps/example-tanstack-start are development and sample apps. They are not part of a production deployment.
  • LiveKit Egress (recording) is preview and has no deployment template. See status and gaps.

On this page