Skip to Content
LYNKORIADocs

Documentation and console audit (2026-11-14)

Phase 1 audit for the documentation and admin console upgrade. What changed in the platform, who the console serves, what data exists, and what is missing.

Audited on 2026-11-14 against main at 523459c, after the infrastructure, SDK and services program. The code is the source of truth; the program status is in Program status.

Summary

  • The documentation site (apps/docs, Fumadocs 16 rendering the root docs/ tree) is broadly current: the previous program updated most pages, and CI already checks frontmatter, relative links, anchors, sidebar entries and that examples/integration.tsx type-checks. What is missing is generated reference material (the HTTP reference is only the raw openapi.json, the SDK references are hand-written, environment variables have no drift check) and type-checking of the code blocks inside pages.
  • The admin console (apps/admin, Vite + React 19 + TanStack Router/Query + Tailwind 4 with the @lynkoria/brand tokens) already has password sign-in with server-side sessions, organization/project roles enforced by the API, an audit log, projects, environments, API keys, webhooks, per-project analytics and an operations tab. It has no visibility into calls, livestreams, participants or presence, no quota-utilization view, no aggregated (all-projects) analytics endpoint, no reusable server-paginated table, and no metric catalog.
  • Platform-wide infrastructure views have no authorized audience: every console role is scoped to an organization. Adding a platform operator role changes the permission model and needs approval (PD-1 below).

Who the console serves

From console_roles, apps/api/src/middleware/admin-identity.ts and Admin access:

Fact in the codeConsequence
Every role row has an organization_id; project_id is optionalEvery principal is a tenant member (organization or project scope)
Roles: owner, admin (manage), developer, auditor (read; auditor + log)Four tenant roles, deny by default (requireRole)
Accounts are created only by the operator CLI (pnpm admin:user)Platform operators act through the CLI and infrastructure, not the UI
No role, flag or table marks a platform operatorNothing in the console may show cross-organization or host-level data
projectFilter() limits every list to the caller's organizations and projectsTenant isolation is enforced in SQL, not in the UI

Decision: the console serves product teams (tenant users). Every new page and endpoint is scoped to the caller's organizations and projects. Platform-wide infrastructure pages are operator-only and not built until a platform operator role is approved (PD-1). Until then operators use the CLI, /health/ready, the internal /metrics listener and the runbooks.

Changes from the previous program that affect the docs

ChangeDocumentation state
Scanner TLS with a private CA (ADR 023)Deployment guide, env vars, runbook updated in the program
Kotlin models are @Poko classes (no copy/destructuring)android-sdk.md updated
Multi-instance API (ADR 021), WebSocket-only realtime (ADR 014)Architecture pages updated
JavaScript SDK architecture (ADR 022)sdk-architecture.md, SDK pages updated
Attachment quarantine and scanning (ADR 020)file-security-and-scanning.md
Console sign-in with sessions (replacing Access-only, ADR 003)security/console-access.md current; ADR 003 still describes Access as the authentication (stale; superseded in practice)
Capability matrixcapability-matrix.md exists; not rendered with status badges

Changes that affect the console

Platform capabilityConsole todayGap
Calls (call_sessions), participants (media_participant_sessions)Not visibleBrowse active/ended calls, participants, end call, remove participant, stale detection
Livestreams (calls of type livestream, viewer promotion)Not visibleLivestream list with live viewer counts, duration
Presence (user_presence, Redis leases)Not visibleRecently-active user counts per environment
Messaging (conversations, messages)Only messagesSent in analyticsConversation counts; content must stay hidden
Quotas (ProjectLimits: room size, concurrent rooms, tokens/min)Editable per environmentNo utilization (active rooms vs maxConcurrentRooms)
Recordings, push, scansOperations tabOK
Webhooks (outbox)Pending/dead deliveries, retry, secret rotateDelivered history not listed; no pagination
Usage (project_usage_daily)Per-project analytics, 7/30/90 daysOverview issues one request per project; no hourly data; no "collection started" marker
Console users and sessionsCLI onlyTeam page lists role grants only; no last-sign-in

Telemetry and data sources

SourceWhat it holdsGranularityRetentionReachable from the console
project_usage_dailycalls created, participant seconds, peak participants, API requests/errors, tokens issued, messagesPer environment per UTC dayNever deletedYes
UsageRecorder bufferSame counters before flush~15 s flushMemoryNo (source of the table)
call_sessionsEach call: type, status, start/end, max participants, E2EEPer callNever deletedYes
media_participant_sessionsEach participant session: identity, join/leavePer participant sessionNever deletedYes
user_presenceLast-seen time per userPer userNever deletedYes
Redis presence leases, socket roomsWho is online nowLiveLease TTLNot exposed (no aggregation)
outbox_eventsWebhook deliveries: attempts, last error, delivered/deadPer eventNever deletedYes
push_deliveries, recordings, attachmentsDelivery status, Egress status, scan verdictsPer itemRetention worker for messages/attachments onlyYes
audit_eventsConsole and CLI actions with actor, IP, user agent, request IDPer actionNever deletedYes
Prometheus registry (/metrics on METRICS_PORT)HTTP rate/latency histogram, auth failures, sockets, outbox backlog, webhooks, scans, push, recordingsPer instance, scrapeNo backend deployedNo
/health/readyDatabase and Redis reachability, drainingLive, per instanceNoneNot routed to the console
Logs (pino JSON to stdout)Requests, errorsPer eventPlatform log retentionNo (no log backend decided)

Missing metrics (need a monitoring backend, PD-5): API latency percentiles, error rate by route, CPU/memory, network, socket connections across instances, LiveKit node health, Redis/database performance, queue latency. Hourly usage is not recorded today; it can be added going forward but never backfilled.

Missing documentation

  • Generated HTTP API reference (operations, parameters, schemas) from docs/openapi.json.
  • Generated SDK API reference for @lynkoria/server, @lynkoria/client, @lynkoria/react, @lynkoria/react-native.
  • A check that every variable validated by apps/api/src/config.ts and apps/scanner/src/app.ts is documented, and nothing undocumented is read.
  • Type-checking of the TypeScript code blocks inside guide pages (only examples/integration.tsx is checked).
  • Console admin API reference: roles required per endpoint, pagination, errors.
  • A glossary shared by docs and console; a metrics catalog.
  • Support-status labels per platform rendered on SDK pages (the matrix exists as a table only).
  • Kotlin (Dokka) and Swift (DocC) generated references: not integrated; these need Gradle/Xcode tooling in CI.

Missing console functionality

  1. Calls and livestreams (list, filters, detail, participants, end, remove participant).
  2. Quota utilization per environment.
  3. Platform overview from a single aggregated endpoint, with live counts (active calls, participants, viewers, recently active users).
  4. Hourly usage (going forward) so 24-hour views exist; a "data since" marker.
  5. Reusable cursor-paginated table with URL state; URL-synced analytics filters.
  6. Metric definitions surfaced in the UI.
  7. Webhook delivery history with pagination.
  8. Team page: console users with last sign-in (read-only for tenant owners).
  9. Links from pages to the relevant docs.

Security review of the console

RequirementState
Strong authenticationscrypt passwords, lockout, rate limits; optional Cloudflare Access. No MFA, no step-up (PD-2)
Session handling__Host- HttpOnly SameSite=Strict cookie, hashed token, 30 min idle / 12 h absolute
CSRFMutations from origins other than CONSOLE_ORIGIN rejected; SameSite=Strict
RBAC, deny by defaultrequireRole on every route; SQL project filter
Audit logEvery mutation and sign-in recorded. Not append-only at the database level (runtime role has UPDATE/DELETE)
Secrets shown onceService keys and webhook secrets
PrivacyNo message content or files exposed
ExportsUsage CSV is built in the browser from already-authorized data; not audited
Rate limiting600 requests/min per console user

Outdated UI and terminology

  • apps/admin/src/lib/api.ts comment says Cloudflare Access authenticates the browser; sign-in sessions do.
  • ADR 003 says Access is the authentication; superseded by password sessions with Access as an optional layer.
  • "Calls" in analytics means calls created; elsewhere "rooms" is used. Glossary will fix: call is the product term, room is the LiveKit room behind it.

Dependencies and blockers

ItemBlocked by
Infrastructure and service pages (operator-only)PD-1 platform operator role
MFA / step-up re-authenticationPD-2
Project deletionPD-3 (destructive)
Console user management in the UIPD-1, PD-4
Latency, error-rate, CPU/memory, socket metricsPD-5 monitoring backend (existing decision)
Grafana/log link-outsPD-5
Kotlin/Swift generated referencesCI tooling for Dokka/DocC

Implementation plan

  1. Docs: generated HTTP reference and SDK reference, env-var drift test, code-block type-checking, glossary, metrics catalog, console admin reference, status badges.
  2. Foundations: append-only audit log (database trigger), audited exports, ADRs for chart library and analytics data architecture, shared table/filters/drawer components.
  3. Management: calls/livestreams/participants endpoints and pages, quotas, webhook history, team sign-in info.
  4. Analytics: hourly usage rollup, aggregated overview endpoint, live counts, URL filters, polling that pauses in background tabs.
  5. Validation: API authorization and tenant-isolation tests, Playwright and axe on key pages, analytics checked against source rows.

On this page