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
| Service | What it does | Depends 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 workers | PostgreSQL, Valkey; LiveKit, Spaces and scanner for those features |
| Migrations | node dist/migrate.js from the API image. Runs as an App Platform pre-deploy job before each new version receives traffic | PostgreSQL (migration role) |
| LiveKit | The media server (SFU): audio, video, screen sharing, livestreams. Includes a TURN server for restrictive networks | Its 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 generator | Public ports 80 and 443 |
Scanner (apps/scanner) | Checks uploaded attachments with ClamAV before the API publishes them. Stateless, no database access | clamd and a signature updater on the same host |
| PostgreSQL | Source of truth for all platform data | — |
| Valkey | Rate limits, locks, presence and the Socket.IO cross-instance stream | — |
| Spaces | Private object storage for attachments (and recordings when Egress is deployed). Clients upload and download with short-lived presigned URLs | — |
| Admin console | Static single-page app for operators. Calls /v1/admin/* on the API with a session cookie | API |
| Documentation | Static export of this site, plus the landing page and /.well-known/security.txt | — |
| Monitoring worker | A pinned Prometheus worker inside the API's App Platform app; scrapes API and LiveKit metrics and remote-writes to your backend | Your 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 → to | How | Credential |
|---|---|---|
| Product backend → API | HTTPS REST /v1 through Cloudflare | Service key |
| Browser/app → API | HTTPS REST and Socket.IO (WebSocket only) through Cloudflare | Short-lived messaging JWT (ES256, MESSAGING_JWT_PRIVATE_KEY) |
| Operator → console → API | Static site, then /v1/admin/* with a session cookie | Console password session (+ Cloudflare Access) |
| Browser/app → LiveKit | WSS to rtc., media over UDP 50000–60000, TCP 7881 or TURN | LiveKit join token minted by the API |
| API → LiveKit | HTTPS (Twirp) to rtc. | LIVEKIT_KEYS_JSON key pairs |
| LiveKit → API | Webhooks to https://api.<domain>/v1/webhooks/livekit | Signed with LIVEKIT_WEBHOOK_KEY / LIVEKIT_WEBHOOK_SECRET |
| API → scanner | HTTPS on the private VPC, port 3344, pinned private CA | SCANNER_TOKEN, SCANNER_CA_CERT |
| API → PostgreSQL | TLS, private VPC: pooled runtime + direct runtime connections | lynkoria_app role |
| Migration job → PostgreSQL | TLS, private VPC, direct connection | lynkoria_migrate role |
| API → Valkey | rediss:// (TLS), private VPC | Managed credentials |
| API → Spaces / clients | S3 API; clients use presigned URLs (5 minutes) | SPACES_ACCESS_KEY_ID / SPACES_SECRET_ACCESS_KEY |
| API → product webhooks | HTTPS POST with HMAC signature | Per-environment webhook secret (WEBHOOK_SECRET_MASTER) |
| API → FCM / APNs | HTTPS | PUSH_CREDENTIALS_JSON (optional) |
Hostnames
| Host | Points to | Cloudflare proxy | Serves |
|---|---|---|---|
api.lynkoria.com | App Platform (CNAME) | Proxied (orange) | REST, Socket.IO, LiveKit webhooks |
console.lynkoria.com | Cloudflare Pages | Proxied + Access | Admin console |
lynkoria.com | Cloudflare Pages | Proxied | Landing page and documentation |
www.lynkoria.com | Redirect rule to the apex | Proxied | 301 redirect |
rtc.lynkoria.com | Media Droplet IP (A record) | DNS only | LiveKit signaling and media |
turn.lynkoria.com | Media Droplet IP (A record) | DNS only | TURN over TLS |
scanner.internal.lynkoria.com | Scanner private IP (A record) | DNS only | Scanner 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
| Where | Port(s) | Open to | Purpose |
|---|---|---|---|
| Media Droplet | TCP 22 | Your admin IPs only | SSH |
| Media Droplet | TCP 80 | Internet | Let's Encrypt HTTP challenge (Caddy) |
| Media Droplet | TCP 443 | Internet | WSS signaling and TURN/TLS (Caddy) |
| Media Droplet | TCP 7881 | Internet | WebRTC over TCP fallback |
| Media Droplet | UDP 3478 | Internet | TURN/UDP |
| Media Droplet | UDP 50000–60000 | Internet | WebRTC media |
| Media Droplet | 7880, 6379, 6789 | Nobody (localhost / VPC only) | LiveKit HTTP, its Redis, its metrics |
| Scanner Droplet | TCP 3344 | VPC CIDR only | Scanner API (HTTPS) |
| Scanner Droplet | TCP 22 | Your admin IPs only | SSH |
| App Platform (API) | 8080 (public via ingress), 9464 | Ingress / same app only | HTTP; Prometheus metrics (internal) |
| Managed PG / Valkey | Managed TLS ports | Trusted 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.andturn.. 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-nextjsandapps/example-tanstack-startare 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.