Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 5 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,9 @@
# NetGuardian — Network Diagnostics & Evidence-Based Troubleshooting Platform

Explore the fictional hotel dashboard on the web app home page after starting NetGuardian. It
requires no workspace token and uses only simulated observations. See
[Hospitality IT Operations](docs/product/HOSPITALITY_OPERATIONS.md).

**English** · [简体中文](README.zh-CN.md)

NetGuardian helps IT teams investigate why a service is unreachable by checking
Expand Down Expand Up @@ -92,7 +96,7 @@ $workspaceToken
uv run --locked python -m scripts.run_windows --migrate
```

Open [the local dashboard](http://127.0.0.1:3000), enter the test workspace token printed
Open [the local workspace](http://127.0.0.1:3000/workspace) and enter the test workspace token printed
in PowerShell. The empty origin list lets you explore the UI
without enabling probes. Use a fresh checkout or back up an existing database
before migration. Keep a stable Worker location ID when retaining observations
Expand Down
2 changes: 1 addition & 1 deletion README.zh-CN.md
Original file line number Diff line number Diff line change
Expand Up @@ -84,7 +84,7 @@ $workspaceToken
uv run --locked python -m scripts.run_windows --migrate
```

打开[本地控制台](http://127.0.0.1:3000),输入 PowerShell 显示的测试工作区令牌。目标白名单为空时可以浏览界面。请使用全新检出目录,或在迁移前备份现有数据库。如果要跨会话保留观测并进行比较,请保持 Worker 位置标识稳定。
打开[本地工作区](http://127.0.0.1:3000/workspace),输入 PowerShell 显示的测试工作区令牌。目标白名单为空时可以浏览界面。请使用全新检出目录,或在迁移前备份现有数据库。如果要跨会话保留观测并进行比较,请保持 Worker 位置标识稳定。

[本地开发与 Agent 注册指南](docs/operations/LOCAL_DEVELOPMENT.md) · [就绪检查、备份与故障排查手册](docs/operations/RUNBOOK.md)

Expand Down
2 changes: 1 addition & 1 deletion docs/operations/LOCAL_DEVELOPMENT.md
Original file line number Diff line number Diff line change
Expand Up @@ -59,7 +59,7 @@ pnpm install --frozen-lockfile
pnpm dev
```

Open [the local interface](http://127.0.0.1:3000) and enter the workspace token.
Open [the local workspace](http://127.0.0.1:3000/workspace) and enter the workspace token.
The Web proxy uses `http://127.0.0.1:8000` by default. Override `NETGUARDIAN_API_URL`
only with a trusted API origin. Browser users cannot select the proxy destination.
The API buffers at most 64 KiB per request before JSON parsing, with a 10-second
Expand Down
2 changes: 1 addition & 1 deletion docs/operations/RUNBOOK.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ PostgreSQL password or percent-encode URL-reserved characters in the connection

Run `docker compose config --quiet`, then `docker compose up --build -d`.
The migration service completes before API startup; worker and web wait for API health.
Open http://127.0.0.1:3000 and enter a configured workspace token. PostgreSQL has no host
Open http://127.0.0.1:3000/workspace and enter a configured workspace token. PostgreSQL has no host
port. `docker compose down` stops services while retaining the database volume.
Do not use `down -v` unless intentionally deleting all stored data.

Expand Down
47 changes: 47 additions & 0 deletions docs/product/HOSPITALITY_OPERATIONS.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,47 @@
# Hospitality IT operations UI

Open the home page (or /demo) to explore Aster Quay Hotel without a token. Every asset, connection,
incident and observation on that route is simulated. The route uses a checked-in
fixture and has no API client, credential state, or control actions. The /workspace
route is the authenticated workspace. Credentials stay in its component memory,
and navigating away aborts its in-flight requests.

## Data and display

- The workspace overview uses the existing monitor and incident list endpoints.
Trends use the selected monitor's existing runs endpoint on request. A probe
outcome is current only if its run matches the latest job ID in a current
collection snapshot. An earlier point remains historical evidence.
- Device online status is unknown because there is no device uptime telemetry.
Probe completion, endpoint response and collection freshness are independent.
HEAD 2xx–3xx describes endpoint response, while business workflow availability
remains unknown without a representative transaction check. A received 503 can
coexist with a successful transport probe and current collection.
- The charts use server job creation time in the workspace and sample timestamps
in the demo. No observation is plotted as a gap. A 0% sample is an observed
HTTP response outside the configured success range. The samples do not estimate
full-period uptime. HTTP duration and ICMP RTT have separate metric labels.
- The demo's React Flow map depicts configured logical links. A keyboard asset
selector provides access to the same details as pointer selection.
- Layered diagnostics read the existing Measurement contract. The existing
monitor history, investigation and evidence report views remain available.
Generic errors are not assigned to a particular network layer. Raw evidence
stays available alongside hypotheses and next checks.

## Connecting an authorized property

Start with an operator-approved list of targets and probe types. Configure exact
allowed origins for the workspace and enroll an Agent only if the target can
also be authorized by the Agent's local policy. Keep credentials out of UI code
and public data. Verify collection from the intended vantage before creating
schedules. Current target restrictions still apply, including restrictions on
private and special addresses. Do not widen them to make private hotel targets
work. A future private-network design should define isolated and explicitly
scoped Agent policy, audit and egress controls before enabling such targets.

For real topology, add a private, authenticated asset configuration tied to the
workspace, with explicit monitor-to-asset mappings and reviewed logical links.
Keep the public scenario separate. Device uptime and business transaction checks
need their own contracts, sampling policies and permission reviews. Avoid
sending guest data, payment records or real infrastructure identifiers to the
demo or model.
12 changes: 12 additions & 0 deletions packaging/source-files.txt
Original file line number Diff line number Diff line change
Expand Up @@ -98,3 +98,15 @@ packaging/README.md
docs/product/ACCEPTANCE_MATRIX.md
legacy_v2.py
.streamlit/config.toml
web/app/demo/page.tsx
web/app/demo/hospitality-dashboard.tsx
web/app/workspace/page.tsx
web/app/demo/scenario.ts
web/app/demo/topology.tsx
web/app/operations.css
web/app/operations/diagnostic-layers.tsx
web/app/operations/theme.tsx
web/app/operations/trend.tsx
web/app/operations/workspace-dashboard.tsx
web/lib/operations.ts
docs/product/HOSPITALITY_OPERATIONS.md
79 changes: 79 additions & 0 deletions web/app/demo/hospitality-dashboard.tsx
Original file line number Diff line number Diff line change
@@ -0,0 +1,79 @@
import Link from "next/link";
import {formatUtc} from "../../lib/time.mjs";
import {endpointStatus, observationStatus} from "../../lib/operations";
import DiagnosticLayers from "../operations/diagnostic-layers";
import ThemeControl from "../operations/theme";
import Trend from "../operations/trend";
import Topology from "./topology";
import {assets, diagnostic, incidents, property, runs, snapshot} from "./scenario";
import "@xyflow/react/dist/style.css";

const services = [
{name: "Guest Wi-Fi portal", zone: "Guest network", probe: "Succeeded", endpoint: "Responding", freshness: "Current"},
{name: "Front desk system", zone: "Front office", probe: "Succeeded", endpoint: "Responding", freshness: "Current"},
{name: "POS endpoint", zone: "Food & beverage", probe: observationStatus(runs.at(-1)), endpoint: endpointStatus(runs.at(-1)), freshness: "Current"},
{name: "Office services", zone: "Back office", probe: "Unknown", endpoint: "Unknown", freshness: "Stale"},
];

export default function HospitalityDashboard() {
return <div className="shell ops-shell">
<aside>
<div className="brand"><span className="mark">N</span>NetGuardian</div>
<p className="eyebrow">HOTEL IT OPERATIONS</p>
<nav aria-label="Demo sections">
<a className="active" href="#overview">Overview</a>
<a href="#services">Services</a>
<a href="#topology">Topology</a>
<a href="#incidents">Incidents</a>
<a href="#diagnosis">Troubleshooting</a>
</nav>

</aside>
<main className="ops-main" id="overview">
<header>
<div><p className="eyebrow">PROPERTY OPERATIONS</p><h1>{property}</h1><p className="ops-muted">Infrastructure Health Overview</p></div>
<div className="ops-header-actions">
<ThemeControl/>
<Link className="ops-workspace-link" href="/workspace" prefetch={false}>Open workspace</Link>
</div>
</header>
<div className="ops-demo-banner"><strong>DEMO / SIMULATED</strong><span>Fictional property and assets · Snapshot {formatUtc(snapshot)}</span></div>
<div className="ops-kpis">
<section className="ops-card"><span>Monitored devices / services</span><strong>{assets.filter(asset => asset.monitor !== "Unmonitored").length}</strong><small>Configured sample assets</small></section>
<section className="ops-card"><span>Active incidents</span><strong>{incidents.filter(incident => incident.state === "Open").length}</strong><small>POS endpoint HTTP 503</small></section>
<section className="ops-card"><span>Current collection</span><strong>{assets.filter(asset => asset.monitor === "Current").length}</strong><small>1 stale monitored segment</small></section>
<section className="ops-card"><span>Device online status</span><strong className="ops-kpi-text">Unknown</strong><small>No device uptime telemetry</small></section>
</div>
<div className="ops-grid">
<Trend title="Network Availability Trends · POS endpoint" unit="%" ceiling={100} points={runs.map(run => ({
id: run.id, time: run.created_at, value: run.http_status == null ? null : run.http_status < 400 ? 100 : 0,
detail: run.http_status == null ? undefined : `HTTP ${run.http_status}`,
}))}/>
<Trend title="Latency and Connectivity Trends · HTTP total" unit="ms" points={runs.map(run => ({
id: run.id, time: run.created_at, value: run.timings.http_total_ms ?? null,
detail: run.http_status == null ? undefined : `HTTP ${run.http_status}`,
}))}/>
</div>
<section className="ops-card" id="services"><h2>Business Service Health</h2>
<p className="ops-muted">Endpoint checks measure the HEAD response. Business workflow availability: Unknown (no transaction checks).</p>
<div className="table-wrap"><table><thead><tr><th scope="col">Service</th><th scope="col">Zone</th><th scope="col">Probe</th><th scope="col">Endpoint</th><th scope="col">Collection</th></tr></thead>
<tbody>{services.map(service => <tr key={service.name}><th scope="row">{service.name}</th><td>{service.zone}</td>
<td>{service.probe}</td><td><span className={`ops-chip ${service.endpoint === "HTTP failure" ? "ops-critical" : service.endpoint === "Responding" ? "ops-positive" : ""}`}>{service.endpoint}</span></td><td>{service.freshness}</td></tr>)}</tbody>
</table></div>
</section>
<Topology/>
<section className="ops-card" id="incidents"><h2>Recent Incident Timeline</h2>
{incidents.map(incident => <article className="ops-incident" key={incident.id} id={incident.id}>
<span className={`ops-chip ${incident.state === "Open" ? "ops-critical" : "ops-positive"}`}>{incident.state}</span>
<div><h3>{incident.title}</h3><small>{incident.id} · {formatUtc(incident.time)}</small></div>
{incident.asset === "pos" && <a href="#diagnosis">Inspect evidence</a>}
</article>)}
</section>
<section className="ops-card" id="diagnosis"><h2>POS troubleshooting</h2>
<p className="ops-muted">SIMULATED · POS endpoint · {formatUtc(snapshot)}</p>
<DiagnosticLayers result={diagnostic} raw={{simulation: true, ...diagnostic}}/>
</section>
<footer>NetGuardian · Hospitality IT Operations Demo</footer>
</main>
</div>;
}
1 change: 1 addition & 0 deletions web/app/demo/page.tsx
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
export {default} from "./hospitality-dashboard";
44 changes: 44 additions & 0 deletions web/app/demo/scenario.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,44 @@
import type {LayerInput, Observation} from "../../lib/operations";

export const property = "Aster Quay Hotel";
export const snapshot = "2026-10-14T10:45:00Z";

export const assets = [
{id: "internet", name: "Internet uplink", type: "External service", zone: "WAN", x: 230, y: 0, monitor: "Unmonitored"},
{id: "gateway", parent: "internet", name: "Gateway / Firewall", type: "Firewall", zone: "Edge", x: 230, y: 75, monitor: "Current"},
{id: "core", parent: "gateway", name: "Core switch", type: "Switch", zone: "Distribution", x: 230, y: 150, monitor: "Current"},
{id: "access", parent: "core", name: "Access network", type: "Logical segment", zone: "Access", x: 230, y: 225, monitor: "Unmonitored"},
{id: "guest", parent: "access", name: "Guest Wi-Fi", type: "Wireless service", zone: "Guest", x: 0, y: 310, monitor: "Current"},
{id: "desk", parent: "access", name: "Front desk", type: "Business service", zone: "Front office", x: 155, y: 310, monitor: "Current"},
{id: "pos", parent: "access", name: "POS terminals", type: "Business service", zone: "Food & beverage", x: 310, y: 310, monitor: "Current"},
{id: "office", parent: "access", name: "Office LAN", type: "Logical segment", zone: "Back office", x: 465, y: 310, monitor: "Stale"},
];

export const incidents = [
{id: "DEMO-104", asset: "pos", state: "Open", title: "POS endpoint returns HTTP 503", time: "2026-10-14T10:15:00Z"},
{id: "DEMO-103", asset: "guest", state: "Resolved", title: "Guest portal endpoint recovered", time: "2026-10-14T08:30:00Z"},
];

const elapsed = [74, 83, 78, 96, 82, 91, 86, 79, 93, 85, 118, 153, 161, 137, 148, 152];
export const runs: Observation[] = elapsed.map<Observation>((ms, index) => ({
id: `demo-run-${index}`,
created_at: new Date(Date.parse(snapshot) - (elapsed.length - 1 - index) * 300000).toISOString(),
status: index === 6 ? null : "success",
http_status: index === 6 ? null : index >= 9 ? 503 : 204,
timings: {http_total_ms: index === 6 ? null : ms, tcp_connect_ms: index === 6 ? null : 8 + index % 5},
}));

export const diagnostic: LayerInput = {
kind: "http", target: "https://pos.aster-quay.example", connected_ip: "192.0.2.10",
timings: {dns_lookup_ms: 7, tcp_connect_ms: 8, tls_handshake_ms: 31, http_total_ms: 152},
dns: {used_dns: true, answers: [{record_type: "A", addresses: ["192.0.2.10"],
ttl_seconds: 60, canonical_name: "pos.aster-quay.example"}]},
tls: {protocol: "TLSv1.3", cipher: "TLS_AES_128_GCM_SHA256", cipher_bits: 128,
hostname_verified: true, leaf_sha256: "0".repeat(64), not_before: "2026-10-01T00:00:00Z", not_after: "2027-01-01T00:00:00Z"},
http_status: 503,
};

export function assetObservation(id: string) {
if (id === "office") return "2026-10-14T07:00:00Z";
return assets.find(asset => asset.id === id)?.monitor === "Current" ? snapshot : null;
}
59 changes: 59 additions & 0 deletions web/app/demo/topology.tsx
Original file line number Diff line number Diff line change
@@ -0,0 +1,59 @@
"use client";
import {useState} from "react";
import {Background, Controls, ReactFlow, type Node, type NodeProps, Handle, Position} from "@xyflow/react";
import {formatUtc} from "../../lib/time.mjs";
import {assets, assetObservation, incidents} from "./scenario";

type AssetNode = Node<{label: string; monitoring: string}, "asset">;

function Asset({data, selected}: NodeProps<AssetNode>) {
return <div className={`ops-node ${selected ? "ops-node-selected" : ""}`}>
<Handle type="target" position={Position.Top} isConnectable={false}/>
<strong>{data.label}</strong><small>{data.monitoring}</small>
<Handle type="source" position={Position.Bottom} isConnectable={false}/>
</div>;
}

const nodeTypes = {asset: Asset};
const edges = assets.flatMap(asset => asset.parent
? [{id: `${asset.parent}-${asset.id}`, source: asset.parent, target: asset.id, type: "smoothstep"}] : []);

export default function Topology() {
const [id, setId] = useState("pos");
const selected = assets.find(asset => asset.id === id)!;
const observed = assetObservation(id);
const related = incidents.filter(incident => incident.asset === id);
const nodes: AssetNode[] = assets.map(asset => ({
id: asset.id, type: "asset", position: {x: asset.x, y: asset.y},
data: {label: asset.name, monitoring: asset.monitor},
ariaLabel: `${asset.name}, ${asset.monitor}`, selected: asset.id === id,
}));
return <section className="ops-card" id="topology">
<h2>Network topology</h2>
<p className="ops-muted">SIMULATED · Configured logical links</p>
<div className="ops-topology">
<div className="ops-flow" aria-label="Configured logical network map">
<ReactFlow nodes={nodes} edges={edges} nodeTypes={nodeTypes} fitView minZoom={0.25} maxZoom={1.75}
nodesDraggable={false} nodesConnectable={false} edgesFocusable={false} elementsSelectable={false}
onNodeClick={(_, node) => setId(node.id)} zoomOnScroll={false} panOnScroll={false}
colorMode="system">
<Background gap={18}/><Controls showInteractive={false}/>
</ReactFlow>
</div>
<div className="ops-node-detail" aria-label="Asset details">
<label>Inspect asset<select value={id} onChange={event => setId(event.target.value)}>
{assets.map(asset => <option key={asset.id} value={asset.id}>{asset.name}</option>)}
</select></label>
<dl>
<dt>Asset name</dt><dd>{selected.name}</dd>
<dt>Asset type</dt><dd>{selected.type}</dd>
<dt>Zone</dt><dd>{selected.zone}</dd>
<dt>Monitoring status</dt><dd>{selected.monitor}</dd>
<dt>Last observation</dt><dd>{observed ? formatUtc(observed) : "No Data"}</dd>
<dt>Related incidents</dt><dd>{related.length ? related.map(incident =>
<a key={incident.id} href={`#${incident.id}`}>{incident.id} · {incident.state}</a>) : "None recorded"}</dd>
</dl>
</div>
</div>
</section>;
}
1 change: 1 addition & 0 deletions web/app/layout.tsx
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
import type { Metadata } from "next";
import "./globals.css";
import "./operations.css";
export const metadata: Metadata = { title: "NetGuardian — Network observability", description: "Evidence-based network diagnostics" };
export default function Layout({children}: Readonly<{children: React.ReactNode}>) {
return <html lang="en"><body>{children}</body></html>;
Expand Down
Loading
Loading