KO
|
EN
gitlite — search
Search
#python
#java
#python3
#arduino
#golang
#machine-learning
#rust
#html
#flask
#javascript
#seismology
#nodejs
topoviewer
★ 24
Open GitHub ↗
No description available.
Download README (.md)
Explore Similar Repositories
medium-data-bakeoff
:
A python library bakeoff for medium sized datasets
assembly-press
:
No description available.
cpp2-syntax
:
cpp2 (cppfront) Syntax Highlighting for VSCode
telegram-downloader
:
Download all content from a Telegram channel
Baby-Care
:
tracker app to help you track your baby’s 🍼 growth, development and upcoming milestones. Plus read lots of supportive articles
// repository documentation
Was this content helpful?
★ 0
(0 ratings)
Select Rating:
★
★
★
★
★
Submit Feedback
Recent Feedback
×
Download README
Do you want to download the
README.md
file for
topoviewer
?
Download (.md)
<!-- Generated from packages/topoviewer/content/pages/_fragments/readme.md. Do not edit this file directly. --> # TopoViewer [](https://github.com/asadarafat/topoviewer/actions/workflows/ci.yml) [](https://asadarafat.github.io/topoviewer/docs/zensical/) [](https://www.npmjs.com/package/topoviewer) [](https://deepwiki.com/asadarafat/topoviewer) **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**](https://asadarafat.github.io/topoviewer/studio/) · [**Explore the MkDocs examples**](https://asadarafat.github.io/topoviewer/docs/mkdocs/topoviewer/examples/) · [**Install from npm**](https://www.npmjs.com/package/topoviewer) ## 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. | ```text 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](https://asadarafat.github.io/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. ```bash pip install mkdocs-topoviewer ``` ```yaml # mkdocs.yml plugins: - search - topoviewer ``` ````markdown ```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. ```bash npm install topoviewer @xyflow/react react react-dom ``` ```tsx 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. ```text 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 ```text 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: ```text Node.js >=24 <25 Python 3.9+ Go >=1.25 (Desktop Studio only) ``` ```bash git clone https://github.com/asadarafat/topoviewer.git cd topoviewer npm ci ``` Run Studio: ```bash npm run studio:dev ``` Build and verify Desktop Studio on the current platform: ```bash npm run desktop:check npm run desktop:smoke ``` Run the full local gate: ```bash npm run ci ``` Useful focused checks: ```bash 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: ```bash npm run docs:preview ``` ```text 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: ```bash 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: ```bash 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](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](CONTRIBUTING.md), run the repository-local checks for the surface you change, and include evidence for user-visible Studio changes. ## License [Apache-2.0](LICENSE)
