TopoViewer

Support status: Supported

Topology as Code for infrastructure, network, and service diagrams.

TopoViewer turns declarative YAML into interactive, validated topology diagrams. It keeps object identity, visual policy, and runtime state separate, so a topology can be reviewed in Git and rendered consistently in docs, products, and operational dashboards.

Open TopoViewer Studio · Explore the MkDocs examples · Install from npm

The Problem

Infrastructure diagrams often begin as useful drawings and end as stale screenshots. Names drift, links change, each dashboard invents a different object model, and visual conventions are copied by hand.

TopoViewer makes the diagram a semantic asset instead:

| File | Responsibility | |---|---| | topology.yaml | Stable objects and relationships: nodes, links, paths, regions, layers, labels, and data. | | stylesheet.yaml | Reusable visual policy: selectors, icons, labels, colors, geometry, and emphasis. | | mapper.yaml | Optional runtime binding from telemetry samples to topology objects. |

source-of-truth data or visual authoring
                    |
                    v
topology.yaml + stylesheet.yaml + optional mapper.yaml
                    |
                    v
             TopoViewer renderer
                    |
                    v
       MkDocs · Zensical · React · Grafana

One topology model can travel between surfaces without becoming a separate drawing in each one.

Author Visually, Keep The Source

TopoViewer Studio is the sole maintained authoring product and the project's production-grade UI direction. It provides direct canvas authoring, visual properties, YAML editing, mapper authoring, validation, project recovery, and portable bundle export in one workspace.

The visual and code workspaces edit the same project. Use the canvas for fast composition, use YAML when precision or bulk changes are faster, then export the same bundle for the target surface. Browser Studio is available as a Beta Preview for current desktop Chromium-family browsers. Desktop Studio is an Experimental Wails distribution with native directory projects. The exported YAML bundle is the durable contract; Studio internals and native bridge APIs are not public APIs.

Start In Documentation

MkDocs is the fastest supported integration for publishing live TopoViewer diagrams alongside infrastructure documentation.

pip install mkdocs-topoviewer

# mkdocs.yml
plugins:
  - search
  - topoviewer

```topoviewer
topology: examples/graph/basic/topology.yaml
stylesheet: examples/graph/basic/stylesheet.yaml
height: 420px
controls: true
title: Graph basic
```

The same authored source also drives the published Zensical adapter, proving that the topology bundle is portable rather than coupled to MkDocs.

Embed In React

Use the React package when topology belongs inside a product, portal, incident console, or customer-facing application.

npm install topoviewer @xyflow/react react react-dom

import { TopoViewer, type TopoDocument } from 'topoviewer';
import 'topoviewer/style.css';

export function Diagram({ document }: { document: TopoDocument }) {
  return (
    <TopoViewer
      document={document}
      selectedLayerIds={['physical']}
      style={{ height: 420 }}
    />
  );
}

Add Runtime State

The optional mapper binds telemetry to stable topology IDs without mutating the long-lived topology model.

stable topology model
  + runtime samples
  + telemetry mapper
  = operational topology overlay

The experimental Grafana panel demonstrates this contract with mounted bundles and mapper-driven overlays. Containerlab provides disposable demo telemetry; it is not a TopoViewer runtime dependency.

Why Teams Adopt It

Use TopoViewer when a topology should be:

• reviewable as YAML in pull requests;
• validated through schemas and semantic checks;
• reusable across docs, React products, and dashboards;
• layered so one model can expose physical, logical, service, or transport views;
• consistent through selector-based visual policy;
• operational when telemetry must map to known topology objects.

TopoViewer is not a general whiteboard. Mermaid, Excalidraw, diagrams.net, and PowerPoint remain better for one-off sketches. TopoViewer earns its place when topology identity must survive beyond one drawing.

Core Semantics

node       stable identity, labels, data, state, and position
link       endpoints, directionality, labels, data, and parallel lanes
path       ordered node sequence; Studio-created paths require graph reachability
region     logical grouping with computed bounds
layer      filtered views from one topology model
style      selector-driven visual policy
mapper     runtime telemetry binding to known objects

Project Status

| Surface | Status | Use today | |---|---|---| | React package | Supported | Install topoviewer from npm and embed TopoViewer. | | MkDocs plugin | Supported | Install mkdocs-topoviewer and render live YAML examples. | | Browser Studio | Beta Preview | Author, validate, recover, and export portable bundles in current desktop Chrome or Edge; export before moving work between browsers or machines. | | Desktop Studio | Experimental | Build platform-specific Wails artifacts for native directory projects; unsigned CI artifacts are internal. | | Zensical | Supported Adapter | Static generated-docs adapter, not an installable plugin. | | Grafana panel | Experimental | Mount bundles and apply mapper-driven runtime overlays. | | NetBox / Infrahub | Roadmap | Future source-of-truth integration surfaces. |

Local Development

Prerequisites:

Node.js >=24 <25
npm >=11.21.0 <12 (CI pins 11.21.0)
Python 3.9+
Go >=1.25 (Desktop Studio only)

git clone https://github.com/asadarafat/topoviewer.git
cd topoviewer
npm install --global [email protected]
npm ci

Run Studio:

npm run studio:dev

Build and verify Desktop Studio on the current platform:

npm run desktop:check
npm run desktop:smoke

Run the full local gate:

npm run ci

Useful focused checks:

npm run validate:schemas
npm run validate:semantics
npm run lint
npm run build
npm test
npm run pack:check

Preview the documentation and Studio:

npm run docs:preview

Studio:   http://127.0.0.1:8001/topoviewer/studio/
MkDocs:   http://127.0.0.1:8001/topoviewer/docs/mkdocs/
Zensical: http://127.0.0.1:8001/topoviewer/docs/zensical/

The Grafana panel demo runs through the Containerlab profile:

npm run grafana:clab:up

Release Screenshots

The README media shows one canonical bundle in the real Studio, MkDocs, Zensical, and Grafana surfaces. Every release must regenerate and verify the images after the version is set:

npm run docs:screenshots

The command builds every surface, starts a temporary pinned Grafana container, captures all documentation images from the canonical st-clos bundle, and checks the generated manifest. The manifest records the release version, canonical source hashes, surface, dimensions, scenario, and digest for every image, so stale, unowned, or silently replaced media fails the release gate.

Quality Bar

The repository is early, but it is built with production-shaped guardrails:

• JSON Schema validation;
• semantic topology linting;
• renderer limit and bundle budget checks;
• hostile-content tests for YAML, Markdown, SVG, mapper, and telemetry inputs;
• package and docs artifact inspection;
• renderer parity checks across MkDocs and Zensical;
• Playwright interaction and accessibility coverage;
• dependency advisory and Go vulnerability checks;
• public-readiness checks for install paths and generated docs.

Security Model

Treat topology inputs as untrusted unless the host application controls the source. Scrutinize topology, stylesheet, mapper, Markdown, SVG, image, and telemetry inputs. TopoViewer sanitizes and constrains supported content, but it is not a sandbox for arbitrary HTML or JavaScript. Host applications remain responsible for authentication, authorization, tenancy, and business policy.

See SECURITY.md for the supported-version and reporting policy.

Stability Note

TopoViewer is a serious early project. The core package and MkDocs plugin are published, Browser Studio is in Beta Preview, and operational integrations are still experimental. Studio workflows may change, but exported TopoViewer YAML remains portable and reviewable.

The project prioritizes stable install paths, validated inputs, predictable rendering, and one coherent authoring product over adding more competing surfaces.

Contributing

Issues and focused pull requests are welcome. Start with CONTRIBUTING.md, run the repository-local checks for the surface you change, and include evidence for user-visible Studio changes.

License

Apache-2.0