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
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.
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.
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.
Use the React package when topology belongs inside a product, portal, incident console, or customer-facing application.
npm install topoviewer @xyflow/react react react-domimport { TopoViewer, type TopoDocument } from 'topoviewer';
import 'topoviewer/style.css';
export function Diagram({ document }: { document: TopoDocument }) {
return (
<TopoViewer
document={document}
selectedLayerIds={['physical']}
style={{ height: 420 }}
/>
);
}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.
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.
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
| 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. |
Prerequisites:
Node.js >=24 <25
Python 3.9+
Go >=1.25 (Desktop Studio only)
git clone https://github.com/asadarafat/topoviewer.git
cd topoviewer
npm ciRun Studio:
npm run studio:devBuild and verify Desktop Studio on the current platform:
npm run desktop:check
npm run desktop:smokeRun the full local gate:
npm run ciUseful focused checks:
npm run validate:schemas
npm run validate:semantics
npm run lint
npm run build
npm test
npm run pack:checkPreview the documentation and Studio:
npm run docs:previewStudio: 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:upThe 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:screenshotsThe 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.
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.
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.
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.
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.