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
| Service | Responsibilities | Owns (data) | Scales | Without it |
|---|---|---|---|---|
apps/api | Control plane (keys, rooms, tokens, quotas, console API), messaging, presence, workers | PostgreSQL (all platform tables), Redis keys (rl:, lock:, presence, Socket.IO stream), Spaces objects | Horizontally (ADR 021) | Nothing works |
apps/scanner + ClamAV | Malware and file-type verdicts | Nothing (stateless; keeps no file copy, no database or storage credentials) | Vertically (clamd memory); more hosts behind one URL possible | Uploads stay quarantined (fail closed); everything else works |
| LiveKit (+ local Redis) | SFU, TURN, room participants | Room 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, docs | Static sites | Nothing | CDN | No 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 → to | Protocol and contract | Authentication | Timeout and retries | Failure handling |
|---|---|---|---|---|
| Product backend → API | REST /v1 (OpenAPI in docs/openapi.json), @lynkoria/server | Service key (hashed with a pepper at rest) | Client's choice | Typed error codes (errors), x-request-id |
| Client → API | REST /v1, Socket.IO (WebSocket only); events in @lynkoria/contracts | Short-lived messaging JWT (ES256), revalidated per event | Client reconnect with backoff; resync by after_seq | Ordered recovery from PostgreSQL; realtime is best effort |
| API → LiveKit | livekit-server-sdk (Twirp over HTTPS) | Per-environment API key pairs | 10 s (rooms), 15 s (Egress); no automatic retry | 503 service_unavailable; the reconciler closes calls LiveKit no longer has |
| LiveKit → API | Webhooks POST /v1/webhooks/livekit | Signed with a dedicated webhook key; raw-body verification | LiveKit's own delivery | Event-id deduplication; reconciler covers lost webhooks |
| API → scanner | REST /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 rotation | 60 s client timeout; no retry (the upload is marked failed and can be completed again) | Fail closed: file stays quarantined; AttachmentScansFailing alert |
| Scanner → clamd | clamd INSTREAM over TCP on an internal Docker network | Network isolation (no published port, no egress) | SCANNER_TIMEOUT_MS (30 s) | 503; readiness fails on stale signatures |
| API → product webhooks | JSON events with id, type, created_at; User-Agent: Lynkoria-Webhooks/1 | HMAC t=…,v1=… per environment secret, rotation with two secrets | 10 s; 12 attempts, 1 m doubling to 24 h, ±20% jitter; then dead-lettered | At-least-once; products dedupe by id; console retry |
| API → FCM / APNs | HTTPS (HTTP/2 for APNs) | Product credentials from PUSH_CREDENTIALS_JSON | 10 s; backoff from 2 s to 5 min, ±20% jitter | Retries, then dead; invalid tokens are invalidated |
| API → PostgreSQL | pg pool | Runtime role (DML only); migrations use a separate role | 5 s connect, 30 s statement, 60 s idle-in-transaction (role settings) | Readiness fails; requests return 503/500 |
| API → Redis/Valkey | redis client (TLS with rediss://) | Managed credentials | Reconnect with backoff up to 5 s; no offline queue for the main client | Rate-limited routes fail closed (503); readiness fails |
| API → Spaces | S3 API, presigned URLs for clients | Access 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/v2and an approved migration window. - The scanner API is versioned under
/v1and 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 examplex-request-id). - Webhook payloads are additive within
Lynkoria-Webhooks/1; receivers must ignore unknown fields and event types.