#Argus (xtnd-argus-web)

Repository: XTND-DYNAMICS/xtnd-argus-web Production: https://argus.xgi.io XAuth service: argus, licensed separately from Vantage Data: https://api.vantage.xgi.io/v1/dashboard/summary Hosting: Cloudflare Worker (static assets), deployed by CI on every merge to main

#1. Overview

XARGUS is the live operational dashboard for XTND Vantage. It shows the events Vantage holds, counted by priority and by source, and the newest of them as they arrive.

Argus is an XSuite app in its own right. It has its own XAuth service and its own licence, and it runs in two places:

• on its own page at argus.xgi.io;
• inside XWorkspace, as the web component <xtnd-argus-dashboard>.

Everything on the dashboard is the Vantage API's answer for the person signed in. Argus shows nothing the API does not return.

#2. Stack

Argus is built like every XSuite web app (the template is xtnd-url-web).

#Events on the hub

#3. Sign-in and licence

Argus signs in with XAuth using OAuth 2.1 authorization code with PKCE (S256), as its own client, argus.

An Argus licence is a role at argus. XAuth administrators grant it:

PUT https://api.auth.xgi.io/v1/admin/users/<guid>/grants
{ "grants": [{ "service": "argus", "roles": ["viewer"] }] }

The XAuth token names the person and nothing else. Its audience is https://xgi.io, and every XSuite API accepts it. Whether a person may read the dashboard is decided on every request by XAuth's Access Graph. The Vantage API admits a person to the dashboard summary with either permission, asked in this order:

1. events.read at vantage: Vantage's own operators and admins, answered exactly as before Argus had a service;
2. dashboard.read at argus: an Argus licence.

The summary's user.app names which of the two admitted the person, and user.roles are their roles there. The dashboard shows them as "Roles at Argus" or "Roles at Vantage".

#4. What the dashboard shows, and from where

Argus polls one route, every 3.5 s, while the dashboard is shown to someone signed in:

GET https://api.vantage.xgi.io/v1/dashboard/summary
Authorization: Bearer <XAuth token>

Every call is built on the one base https://api.vantage.xgi.io/v1. Only one request is out at a time, and the next is scheduled only after the last has answered.

Numbers and times follow the language chosen in the locale picker. The text itself is English.

#States

On a refusal, none of the data stays on the page.

#5. Websites and Replay (since 2.2.0)

The Websites tab shows the sites XRADAR reports from, read from the Vantage API's /v1/web/* routes (vantage-api.md, §2.4).

• /web and /web/:source. Pick a site and a range (24 hours, 7, 30 or 90 days; ?range= keeps it in the address) and see:
  • visitors, sessions, page views and clicks;
  • median time on a page and median read;
  • the visits, newest first, each opening in the replay;
  • counts by day and by page, and the site's own events;
  • referrers, languages, devices and browsers;
  • Core Web Vitals, rated by the ratings the samples carry, with no thresholds kept in Argus;
  • errors.
• /web/:source/sessions/:session. One visit's page loads in order, each played back with rrweb 2.1.7, the version XRADAR records with, beside every event in sequence. Choosing an event plays the replay from there, and the event the replay has reached is marked. Canvases and frames from other sites are not recorded and show empty.

The replay runs in a frame sandboxed without scripts, so nothing recorded can run. rrweb loads with the player only. Everything is styled with XUI's tokens (XUI 0.6.0 and later).

#6. The web component and the manifest

Argus serves its XSuite app manifest at https://argus.xgi.io/.well-known/xsuite-app.json, with CORS *:

{
  "schema": "xsuite-app/1",
  "id": "argus",
  "name": "XARGUS",
  "origin": "https://argus.xgi.io",
  "api": "https://api.vantage.xgi.io",
  "federation": { "remoteEntry": "https://argus.xgi.io/remoteEntry.json", "elements": "./elements" },
  "components": [{ "tag": "xtnd-argus-dashboard", "attributes": [], "events": [] }],
  "contributes": {
    "workspace.sections": [
      { "id": "telemetry", "label": "Telemetry", "icon": "chart", "component": "xtnd-argus-dashboard", "order": 90 }
    ]
  }
}

• Manifest id: the XAuth registry slug, argus, as xtnd-platform defines it.
• What a host does: XWorkspace imports remoteEntry.json and loads ./elements, which defines <xtnd-argus-dashboard> on the host's shared Angular.
• Contexts it reads: the component takes xtnd:auth (the person and their fetch) and xtnd:locale from the host. On argus.xgi.io, Argus's own shell provides both, so it is the same component in both places.
• Event hub: the component keeps its event hub off window, so it never replaces the host's.
• Not workspace-scoped: Vantage's events carry no workspace, so the Telemetry section shows the same Vantage-wide feed in every workspace.

XWorkspace finds an app through XAuth's registry (GET https://api.auth.xgi.io/v1/services). The argus entry's manifest is not set yet, so XWorkspace does not list the Telemetry section until it is.

#7. Version, build and deploy

• One version on every surface: package.json, the build stamp, /version.json ({ service: "xtnd-argus-web", version, sha, committedAt, dirty }) and the version widget.
• Build: ng build && xsuite-pwa dist/xtnd-argus-web/browser. This writes the service worker, its manifest and the cache headers.
• CI (.github/workflows/deploy.yml, self-hosted xtnd-ci runners):
  • on every PR: type check, unit tests (node --test), build, and the browser E2E (Playwright, with XAuth and the Vantage API faked at the network);
  • on merge to main, in addition: wrangler deploy, a check that /version.json reports the merged commit, and a read-only production smoke test.
• Deploys: CI only. Changes go branch → PR → green checks → merge.

#Local development

npm ci        # @xtnd-dynamics/* come from GitHub Packages
npm start     # http://localhost:3000
npm test && npm run check && npm run build && npm run e2e

Signing in works on argus.xgi.io only, so a local build shows the signed-out dashboard. The E2E suite covers the signed-in states against fakes.