isoflow

Isoflow is an open-core React library that makes embedding professional-grade network and architecture diagrams into web applications straightforward. Rather than building a standalone diagramming tool, it ships as an npm package you drop into any React project, exposing a controlled component that accepts an initial data model and fires callbacks when the model changes.

At its core, Isoflow renders diagrams using a custom isometric grid projection — every node, connector, and text box is positioned on a tile coordinate system that translates to pixel-perfect isometric placement. Zoom, scroll, and pan state are all tracked in a Zustand store that components subscribe to selectively, keeping re-renders minimal as diagrams grow.

The icon system is deliberately decoupled from the editor itself. The companion @isoflow/isopacks package provides ready-made icon libraries for AWS, Azure, GCP, and Kubernetes, and developers can define entirely custom icon sets by passing an icons array to the component. This separation means the core bundle stays lean while teams can ship only the icon packs they need.

Isoflow operates in two modes: a full editable mode with drag-and-drop, context menus, and item controls, and a read-only explorable mode suitable for documentation viewers and dashboards. Both modes share the same rendering engine, so diagrams look identical whether a user is editing or just viewing. The project is open-core under MIT for the community edition, with additional features available in Isoflow Pro.

What You Get

• A single <Isoflow /> React component that renders a complete, interactive isometric diagram editor inside any React app with zero backend requirements
• Dual editor modes — fully editable with drag-and-drop and item controls, or read-only explorable mode for documentation and dashboards
• Pathfinding-based connector routing that automatically avoids nodes and rectangles, with configurable connector styles (solid, dashed) and anchor points
• An extensible, decoupled icon system: use the @isoflow/isopacks package for AWS, Azure, GCP, and Kubernetes icons, or define fully custom icon libraries
• Serializable model state via onModelUpdated callback, enabling save/load workflows and real-time collaboration integrations
• Export to image (PNG) via the built-in export dialog, and export as structured JSON for version-controlled diagram-as-code workflows
• Docker image for running the standalone Isoflow editor without integrating it into a host application

Common Use Cases

• Internal developer portals — embed live, editable architecture diagrams inside docs sites so engineers can update network topology without switching tools
• Cloud cost and compliance dashboards — render read-only explorable diagrams showing infrastructure layout using AWS or Azure icon packs, linked to live resource data
• Diagramming SaaS products — use Isoflow as the editor engine inside a product that adds persistence, sharing, and team collaboration on top
• Education and training platforms — present interactive isometric network diagrams of concepts like OSI layers or datacenter layouts with explorable-readonly mode
• Documentation generation — store diagrams as JSON in version control and render them at build time in Astro, Next.js, or similar static-site frameworks

Under The Hood

Architecture Isoflow follows a layered, provider-based architecture that separates three distinct concerns into independent Zustand context stores: the serializable model (nodes, connectors, text boxes, icons, colors, views), the derived scene (computed connector paths, resolved icon components), and ephemeral UI state (zoom, scroll, interaction mode, cursor position). The main <Isoflow /> component composes these three providers and mounts a Renderer plus a UI overlay — a clean separation where the Renderer is entirely stateless with respect to user intent and the UiOverlay never touches model data directly. Interaction handling is delegated to a mode-based manager that dispatches mouse events to one of eight pluggable mode objects (Cursor, DragItems, Connector, Pan, PlaceIcon, Rectangle, TextBox, Lasso), each implementing the same ModeActions interface. This design means adding a new interaction type is additive and isolated, with no risk of breaking existing modes.

Tech Stack The library is written in TypeScript 5 and compiled with Webpack 5 (separate dev, prod, and Docker configs) plus tsc for declaration file emission. The rendering layer is built on React 18 with MUI v5 (Material UI) providing the component primitives and theming system, augmented with Emotion for CSS-in-JS. Zustand 4 powers all state management via the context-store pattern rather than a singleton, enabling multiple independent editor instances on the same page. Animation is handled by GSAP 3. Connector pathfinding uses the pathfinding library, and color manipulation uses chroma-js. Model validation is enforced at runtime via Zod 3 schemas. The build outputs a CommonJS bundle targeting browsers with a >0.2% share, with React 17+ declared as a peer dependency.

Code Quality The codebase has meaningful but limited test coverage: unit tests exist for model reducers (create, update, delete item operations), utility functions (renderer math, coordinate transforms), and Zod schema validation, using Jest with ts-jest and jsdom. There are no integration or end-to-end tests, and component-level testing is absent. Type safety is comprehensive — all state is typed via Zod-inferred TypeScript types, the interaction mode system is fully typed, and the public API surface exposes well-defined interfaces. The ESLint configuration uses the Airbnb TypeScript ruleset combined with Prettier, enforcing consistent style. Error handling is defensive in key spots (missing provider throws explicitly, schema validation catches cross-reference issues), though not uniformly applied across all layers. CI runs on CircleCI.

What Makes It Unique Isoflow’s most distinctive technical choice is the isometric tile coordinate system: every element is positioned on a grid of (x, y) tile coordinates that are projected to screen pixels using fixed multipliers derived from isometric geometry (width ×1.415, height ×0.819). This means layout is quantised and predictable — nodes snap to the grid, connector pathfinding operates in tile space, and z-ordering for depth sorting is computed directly from tile coordinates (order = -tile.x - tile.y). Most browser-based diagramming tools work in free-form pixel coordinates; Isoflow’s tile grid enforces a visual consistency that makes diagrams look intentionally architectural rather than freehand, which is a meaningful aesthetic differentiation for infrastructure and network use cases.

Self-Hosting

Isoflow Community Edition is released under the MIT License, one of the most permissive open-source licenses available. You can use it commercially, modify it freely, embed it in proprietary products, and redistribute it without any copyleft obligation — the only requirement is retaining the copyright notice. There are no contributor license agreements or dual-licensing traps; the community edition is genuinely free for any use.

Because Isoflow is a client-side React component rather than a server application, the operational burden of self-hosting is minimal. You bundle it into your own frontend, which means there is no Isoflow server to keep running, no database to manage, and no separate process to monitor. Infrastructure responsibility lies entirely with how you persist and serve diagram data — that is your application’s concern, not Isoflow’s. Upgrades are standard npm package bumps, and the component accepts a versioned model schema, so schema migrations are manageable.

The trade-off versus Isoflow Pro centres on features rather than operational complexity. The Pro tier adds capabilities such as additional diagramming primitives, advanced export options, and priority support — details are published at isoflow.io/pro-vs-community-edition. There is no cloud-hosted managed version of Isoflow itself; the Pro license is a commercial software license for the expanded feature set, not a SaaS offering. Teams that need professional support contracts or guaranteed SLAs on the library will need to purchase a Pro license; community support is available via the Discord server.