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 rootdocs/tree) is broadly current: the previous program updated most pages, and CI already checks frontmatter, relative links, anchors, sidebar entries and thatexamples/integration.tsxtype-checks. What is missing is generated reference material (the HTTP reference is only the rawopenapi.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/brandtokens) 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 code | Consequence |
|---|---|
Every role row has an organization_id; project_id is optional | Every 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 operator | Nothing in the console may show cross-organization or host-level data |
projectFilter() limits every list to the caller's organizations and projects | Tenant 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
| Change | Documentation 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 matrix | capability-matrix.md exists; not rendered with status badges |
Changes that affect the console
| Platform capability | Console today | Gap |
|---|---|---|
Calls (call_sessions), participants (media_participant_sessions) | Not visible | Browse active/ended calls, participants, end call, remove participant, stale detection |
Livestreams (calls of type livestream, viewer promotion) | Not visible | Livestream list with live viewer counts, duration |
Presence (user_presence, Redis leases) | Not visible | Recently-active user counts per environment |
Messaging (conversations, messages) | Only messagesSent in analytics | Conversation counts; content must stay hidden |
Quotas (ProjectLimits: room size, concurrent rooms, tokens/min) | Editable per environment | No utilization (active rooms vs maxConcurrentRooms) |
| Recordings, push, scans | Operations tab | OK |
| Webhooks (outbox) | Pending/dead deliveries, retry, secret rotate | Delivered history not listed; no pagination |
Usage (project_usage_daily) | Per-project analytics, 7/30/90 days | Overview issues one request per project; no hourly data; no "collection started" marker |
| Console users and sessions | CLI only | Team page lists role grants only; no last-sign-in |
Telemetry and data sources
| Source | What it holds | Granularity | Retention | Reachable from the console |
|---|---|---|---|---|
project_usage_daily | calls created, participant seconds, peak participants, API requests/errors, tokens issued, messages | Per environment per UTC day | Never deleted | Yes |
UsageRecorder buffer | Same counters before flush | ~15 s flush | Memory | No (source of the table) |
call_sessions | Each call: type, status, start/end, max participants, E2EE | Per call | Never deleted | Yes |
media_participant_sessions | Each participant session: identity, join/leave | Per participant session | Never deleted | Yes |
user_presence | Last-seen time per user | Per user | Never deleted | Yes |
| Redis presence leases, socket rooms | Who is online now | Live | Lease TTL | Not exposed (no aggregation) |
outbox_events | Webhook deliveries: attempts, last error, delivered/dead | Per event | Never deleted | Yes |
push_deliveries, recordings, attachments | Delivery status, Egress status, scan verdicts | Per item | Retention worker for messages/attachments only | Yes |
audit_events | Console and CLI actions with actor, IP, user agent, request ID | Per action | Never deleted | Yes |
Prometheus registry (/metrics on METRICS_PORT) | HTTP rate/latency histogram, auth failures, sockets, outbox backlog, webhooks, scans, push, recordings | Per instance, scrape | No backend deployed | No |
/health/ready | Database and Redis reachability, draining | Live, per instance | None | Not routed to the console |
| Logs (pino JSON to stdout) | Requests, errors | Per event | Platform log retention | No (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.tsandapps/scanner/src/app.tsis documented, and nothing undocumented is read. - Type-checking of the TypeScript code blocks inside guide pages (only
examples/integration.tsxis 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
- Calls and livestreams (list, filters, detail, participants, end, remove participant).
- Quota utilization per environment.
- Platform overview from a single aggregated endpoint, with live counts (active calls, participants, viewers, recently active users).
- Hourly usage (going forward) so 24-hour views exist; a "data since" marker.
- Reusable cursor-paginated table with URL state; URL-synced analytics filters.
- Metric definitions surfaced in the UI.
- Webhook delivery history with pagination.
- Team page: console users with last sign-in (read-only for tenant owners).
- Links from pages to the relevant docs.
Security review of the console
| Requirement | State |
|---|---|
| Strong authentication | scrypt 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 |
| CSRF | Mutations from origins other than CONSOLE_ORIGIN rejected; SameSite=Strict |
| RBAC, deny by default | requireRole on every route; SQL project filter |
| Audit log | Every mutation and sign-in recorded. Not append-only at the database level (runtime role has UPDATE/DELETE) |
| Secrets shown once | Service keys and webhook secrets |
| Privacy | No message content or files exposed |
| Exports | Usage CSV is built in the browser from already-authorized data; not audited |
| Rate limiting | 600 requests/min per console user |
Outdated UI and terminology
apps/admin/src/lib/api.tscomment 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
| Item | Blocked by |
|---|---|
| Infrastructure and service pages (operator-only) | PD-1 platform operator role |
| MFA / step-up re-authentication | PD-2 |
| Project deletion | PD-3 (destructive) |
| Console user management in the UI | PD-1, PD-4 |
| Latency, error-rate, CPU/memory, socket metrics | PD-5 monitoring backend (existing decision) |
| Grafana/log link-outs | PD-5 |
| Kotlin/Swift generated references | CI tooling for Dokka/DocC |
Implementation plan
- Docs: generated HTTP reference and SDK reference, env-var drift test, code-block type-checking, glossary, metrics catalog, console admin reference, status badges.
- Foundations: append-only audit log (database trigger), audited exports, ADRs for chart library and analytics data architecture, shared table/filters/drawer components.
- Management: calls/livestreams/participants endpoints and pages, quotas, webhook history, team sign-in info.
- Analytics: hourly usage rollup, aggregated overview endpoint, live counts, URL filters, polling that pauses in background tabs.
- Validation: API authorization and tenant-isolation tests, Playwright and axe on key pages, analytics checked against source rows.