Admin GUI

The NOOSChain Admin GUI is the trusted operator dashboard for node management. It lives in:

apps/noos-admin-gui

The GUI uses the existing operator and observability APIs. It does not bypass consensus logic, execute private database writes, manage private keys, decrypt payloads, or expose raw sensitive material.

This is not the public Web GUI. Public explorer and user transaction flows belong to Web GUI App.

Mental Model

The Admin GUI is a browser surface over operator APIs:

Area	What the GUI does
Node health	Reads current health, storage, sync, payload, and runtime summaries.
Chain state	Shows head, protocol, checkpoints, verification summaries, and mempool status.
Consensus	Shows Raft/runtime membership state and guarded membership-plan actions.
Operations	Shows incidents, peer status, snapshot metadata, and local storage diagnostics.
Access visibility	Shows identities, buckets, and access rules as observability views.
Smart-contract runtime	Shows runtime readiness, sidecar status, launch evidence, alerts, and contract diagnostics where available.

Some screens expose guarded operator actions, such as peer actions, incident resolution, or membership-plan execution. Those actions still call node operator APIs and require explicit confirmation. Heavy local workflows such as snapshot export/import, restore, payload-store pruning, and backup drills belong in the Operator CLI.

Run

Install app dependencies:

npm --prefix apps/noos-admin-gui install

Start the development server:

npm run admin:dev

Run tests:

npm run admin:test

Build the app:

npm run admin:build

The app build is independent from the backend TypeScript project.

Configuration

Build-time defaults:

Variable	Default	Purpose
VITE_NOOS_API_BASE_URL	http://127.0.0.1:3000	Default node API URL shown to the operator.
VITE_NOOS_APP_NAME	NOOSChain Admin	App display name.

At runtime, the operator enters:

• node API base URL;
• operator bearer token.

The operator token is masked, stored in sessionStorage, and cleared on logout. Do not embed production operator tokens in a static build, checked-in configuration, browser extension, or public hosting environment.

CORS

The node API has built-in CORS support for the admin GUI during development. Outside production it allows common Vite dev origins:

• http://127.0.0.1:5173
• http://localhost:5173
• http://127.0.0.1:5174
• http://localhost:5174
• http://127.0.0.1:5175
• http://localhost:5175

If the GUI runs on another origin, start the node with an explicit allowlist:

$env:NOOS_CORS_ENABLED="true"
$env:NOOS_CORS_ALLOWED_ORIGINS="http://127.0.0.1:5175,http://localhost:5175"
npm run dev

In production, enabling CORS without NOOS_CORS_ALLOWED_ORIGINS is refused. For a hosted operator dashboard, include the exact browser origin, including scheme and port when non-default.

Security Posture

The Admin GUI should be served only to trusted operators. In production, connect to nodes over TLS or mTLS and restrict access at the network and identity layer.

The UI redacts sensitive-looking values before rendering raw JSON details, including:

• tokens;
• private keys;
• secrets;
• passwords;
• challenges;
• DEKs;
• plaintext payloads;
• encrypted payload bytes.

The GUI does not provide private-key custody. Signed consensus transactions, snapshot restore, and other high-risk workflows should use guarded CLI or dedicated operational tooling.

Pages And Workflows

Page	Use it for
Dashboard	Node health, chain head, consensus mode, state-root readiness, incidents, payload, and storage summary.
Chain	Head, genesis/protocol/checkpoint summaries, and chain verification trigger.
Buckets	Read-only bucket metadata and cached per-bucket counters.
Access Rules	Read-only explicit bucket permission rows, filterable by bucket, user, or organization.
Identities	Read-only organization and user metadata, cached counters, and public-key fingerprints.
Consensus/Raft	Runtime status, leader, term, governance/runtime warnings, active/scheduled state-root engine, sidecar readiness, and guarded membership-plan execution.
Governance	Read-only validator governance summary.
Peers	Peer table, score/status, quarantine/ban/reset actions with confirmation.
Incidents	Active incident/conflict view and guarded resolution.
Snapshots	Snapshot metadata. Export/import/restore are intentionally not exposed.
Storage	Key table row counts and storage summaries.
Payloads	Availability counts by policy/bucket, local payload-store size and age diagnostics, and dry-run GC previews. No payload bytes.
Mempool	Pending transaction counts and recent hashes.

Smart-Contract Runtime Views

The Admin GUI may show smart-contract runtime readiness, Wasmtime sidecar status, launch evidence, registry evidence, provenance summaries, contract alerts, and execution diagnostics. That information helps operators decide whether the node is ready to execute contracts and whether a runtime incident needs attention.

This page does not explain package descriptors, signatures, provenance policy, registry approval, or publishing flows. Use:

• Smart Contract Runtime Operations for operator runtime activation and preflight;
• Packages And Provenance for the package integrity chain;
• Package Provenance for descriptor signatures and provenance policy;
• Contract Registry for network package approval;
• Publishing for package build/sign/publish workflows.

Refresh Behavior

Auto-refresh is off by default and can be enabled from the footer refresh control. The cached payload availability endpoint may auto-refresh when the operator enables it.

The local payload-store stats panel remains manual-refresh only because it is a storage-pressure diagnostic. The default backend endpoint reads cached counters; exact realtime scans are reserved for operator troubleshooting and are not used by the GUI polling loop.

Deliberate Limits

The Admin GUI intentionally does not provide every operator capability:

• no snapshot export, import, or operator restore;
• no confirmed payload-store GC or payload-counter repair;
• no private key management;
• no payload decryption;
• no public or user-facing data browsing;
• no validator lifecycle transaction creation;
• no bucket access-rule mutation;
• no automatic membership mutation after governance changes.

Use Operator CLI for local snapshot operations, restore, backup drills, payload-store pruning, payload-counter repair, and signed transaction workflows.

Operational Handoffs

Need	Go to
CLI equivalent or local operation	Operator CLI
Alerting strategy	Monitoring And Alerting
Incident workflow	Incident Response
Fork or conflict response	Conflict Handling
Snapshot and restore procedure	Backup, Restore, And Recovery
API route inspection	Swagger / OpenAPI

Testing

Unit tests use mocked API fixtures and do not require a live NOOSChain node:

npm run admin:test

Build the app:

npm run admin:build