openvidu/openvidu-dashboard/openspec/changes/ui-review-fixes/design.md

Design

Context

• Charts: charts/chart-options.ts builds every time-series option.
  • The x-axis is an ECharts time axis whose labels are HH:mm, MM-dd HH:mm or MM-dd by span, with no minimum interval, so a 3-minute range ticks every 20–30 s.
  • The y-axis has no minimum interval either.
  • Step series use step: 'end': each value is drawn from its bucket start to the next point, so the last point has no segment.
• Skeletons: ovd-skeleton paints its bars at once and is removed on the first response, which flashes when the response takes tens of milliseconds.
• Durations: formatDuration() truncates at every unit. ovd-duration formats both running and stored durations with it.
• About storage: InfoService.storageEntry() lists each collection's indexes and dates it only when an index leads with ts, bucket or createdAt. The analytics indexes of the time fields are:
  • rooms.createdAt, ingresses.createdAt;
  • participants { joinedAt: -1, _id: -1 };
  • egresses { startedAt: -1, _id: -1 } and ingress_sessions { startedAt: -1, _id: -1 };
  • events.ts, analytics_5min.bucket, analytics_hourly.bucket;
  • analytics_daily { scope, bucket };
  • the track_stats time series, indexed on its metadata before ts;
  • nodes, with no time index and one document per node;
  • tracks and track_subscriptions, with their time field only behind participantSid, roomSid, subscriberSid or trackSid.
• Global search: exactIdTarget() recognises TR_ through entityIdKind() but drops it, because no route takes a track ID.
• Browser and OS labels: the rollups key browsers by family, and an empty browser falls into other until the writer change adds none. Pages that show a client's OS print the reported string (linux from the Go SDK, Linux from the JS SDK).

Goals / Non-Goals

Goals:

• One rule per chart property, applied in timeSeriesOption() for every chart of every edition.
• No new inputs on the chart, the skeleton or the duration components.

Non-Goals:

• Changing the label formats of the axes or the retention notices.
• New indexes for tracks and subscriptions.

Decisions

D1. The x-axis interval follows the label unit

minInterval is 60 000 ms when the labels show minutes (HH:mm, MM-dd HH:mm) and 86 400 000 ms when they show days. It comes from the same span rule as the label format.

Rejected: passing the bucket width from every chart. The labels are the constraint, and the granularity is already in the chart note.

D2. Integer data gets integer ticks

yAxis.minInterval is 1 when every non-null value of every series is an integer.

Rejected: an integer input on the chart, which every count chart of every edition would have to set.

D3. A step series is extended to to

When the last point of a step series is not null and starts before to, timeSeriesOption() appends [to, value], so step: 'end' draws the last bucket up to the end of the range. A dense series always ends in the bucket that holds to.

Rejected: step: 'start', which would draw every value one bucket early.

D4. The skeleton fades in after 300 ms

Every loading placeholder keeps its height from the start and carries the global class ovd-skeleton-reveal, whose CSS animation keeps its opacity at 0 for 300 ms and then shows it: ovd-skeleton, the skeleton rows of ovd-data-table and the KPI tile skeleton. Pages keep their loading logic. Under prefers-reduced-motion the global rule shortens the fade and the delay stays.

Rejected:

• delaying the loading flag in every loader, which touches every page and both loaders;
• keeping the previous content, which does not exist on a first load.

D5. Stored durations are rounded, running ones are not

formatDuration(ms, { mode }) rounds to the smallest unit it will show by default:

• it picks the unit from the magnitude, rounds, and formats again when rounding crosses a unit (59 600 ms → 60 s → "1 m 00 s");
• mode: 'floor' keeps the current truncation;
• ovd-duration passes floor while running is true, both for liveDurationMs and for liveTotalMs.

Rejected: rounding live durations, which would make a counter jump to the next second halfway through.

D6. A fixed time field per collection

InfoService holds one map from collection to field, and optional filter, and reads find(filter).sort({ field: 1 }) .limit(1) with a projection of the field. This replaces the index discovery and saves a listIndexes per collection.

Collection	Field
rooms, ingresses	createdAt
participants	joinedAt
egresses, ingress_sessions	startedAt
events	ts
analytics_5min, analytics_hourly	bucket
analytics_daily	bucket with { scope: 'global' }
nodes	firstSeenAt (one document per node, no index needed)

tracks, track_subscriptions and track_stats have no entry, and About explains the "—". The track_stats query was explained on a generated dataset: the time series has no index on its time alone, so the plan is a bounded sort over a scan of the buckets.

Rejected:

• new { publishedAt } and { subscribedAt } indexes, two more indexes on the most written collections for one About cell;
• a sort without an index, a collection scan every 60 s.

D7. Plain version text

sidenav-footer.ts renders the version in a span.

D8. The room averages say why they are missing

missingHint() takes the reason: roomsEnded === 0 gives "No room ended in this range", anything else "Not provided by this server version".

D9. Total duration tile

The Egress page tile is labelled "Total duration", with INFO_TEXTS.egressTotalDuration.

D10. Browser labels and the OS label

format/labels.ts gains:

• BROWSER_LABELS for chrome, firefox, safari, edge, none ("No browser") and other, used by the browser donut, which today prints the key;
• clientOsLabel(os), which compares the reported string, case-insensitively and trimmed, with the family names (windows, macos, mac os, linux, android, ios) and returns the OS_LABELS entry, or the string as reported.

The library exports both for the detail pages of every edition.

Rejected: mapping by substring as the writer does, which would turn "Chrome OS" into "Linux" on a page meant to show what the client reported.

D11. A locked track route

routes.ts adds tracks/:trackSid:

• with no navigation entry and page.feature: 'participant-detail';
• with the breadcrumb param trackSid, which titles the lock, as the route has no list above it;
• opening a locked page that reuses the participant lock.

exactIdTarget() maps track to /tracks. An edition with the feature replaces the route by path, as it does for the other detail routes.

API

No shape change: storage.<collection>.oldest exists and only covers more collections.

Performance budget

About reads at most eleven point queries every 60 s, with the existing cache. Each is verified in the info integration test with explain(): an IXSCAN with one document examined, and a COLLSCAN only on nodes.

track_stats has no entry: its plan scans the buckets of the time series.

Risks / Trade-offs

• [Rounding changes durations across the UI, by up to half a unit] → Unit tests of the formatter for both modes, and updated fixtures where a duration reads differently.
• [A running duration that ends shows one second more than it last counted] → Accepted: the stored value is the measured one.
• [The none browser key only appears in rollups written after the writer change] → Older rollups keep those sessions under other, which still reads "Other".

Migration Plan

Ships with the 3.10 dashboard. The browser label of none relies on the typings of writer-review-fixes, applied first.