Node Types & Shapes

Nodes are the primary building blocks of a topology. Each node represents a single process, service, or infrastructure component. The visual appearance is controlled by the shape property and a set of optional styling flags.

Available shapes

The shape property is set in addProcess (or createProcess) and controls the SVG geometry rendered inside the node card.

Shape value	Description	Typical use
`default`	Rounded rectangle	APIs, services, workers, any generic process
`cylinder`	Vertical cylinder	Databases, message brokers, caches, storage
`diamond`	Diamond / rhombus	Decision points, gateways, condition checks
`cloud`	Cloud silhouette	External cloud services, CDNs, SaaS providers
`hexagon`	Hexagon	Microservices, functions, specialized workers
`parallelogram`	Slanted rectangle	Data transformation, ETL steps
`circle`	Circle	Events, queues, lightweight signals

group
  .addProcess({ id: 'api',       label: 'REST API',      shape: 'default',       state: 'running' })
  .addProcess({ id: 'pg',        label: 'PostgreSQL',    shape: 'cylinder',      state: 'running' })
  .addProcess({ id: 'gateway',   label: 'API Gateway',   shape: 'diamond',       state: 'running' })
  .addProcess({ id: 'cdn',       label: 'CloudFront',    shape: 'cloud',         state: 'running' })
  .addProcess({ id: 'lambda',    label: 'Lambda Fn',     shape: 'hexagon',       state: 'running' })
  .addProcess({ id: 'transform', label: 'Transform',     shape: 'parallelogram', state: 'running' })
  .addProcess({ id: 'event',     label: 'Event',         shape: 'circle',        state: 'running' })
  .autoResize();

State indicators

The state property adds a colored indicator dot to the node label, making it easy to show the health of each component.

State	Indicator color	Meaning
`running`	Green	Service is healthy and operational
`warning`	Yellow	Service is degraded or approaching a limit
`error`	Red	Service is failing or has failed
`stopped`	Gray	Service is intentionally stopped or offline

group
  .addProcess({ id: 'healthy',  label: 'Healthy Service',  state: 'running' })
  .addProcess({ id: 'degraded', label: 'Degraded Service', state: 'warning' })
  .addProcess({ id: 'failed',   label: 'Failed Service',   state: 'error' })
  .addProcess({ id: 'offline',  label: 'Stopped Service',  state: 'stopped' })
  .autoResize();

External components

Setting external: true on a node marks it as an external dependency — a service that lives outside the system being described (a third-party SaaS, a public cloud API, a partner system).

External nodes receive a distinct orange border and a slightly different background fill to visually separate them from internal components.

group
  .addProcess({ id: 'stripe',   label: 'Stripe API',   shape: 'cloud', external: true, state: 'running' })
  .addProcess({ id: 'sendgrid', label: 'SendGrid',     shape: 'cloud', external: true, state: 'running' })
  .addProcess({ id: 'twilio',   label: 'Twilio SMS',   shape: 'cloud', external: true, state: 'running' })
  .autoResize();

Alternatively, use the addCloud shorthand on GroupBuilder, which sets shape: 'cloud' and external: true automatically:

group.addCloud({ id: 'stripe', label: 'Stripe API', state: 'running' });

Shard badges

For distributed databases and sharded systems, each node can display a shard identifier and role badge.

Property	Type	Values	Description
`shardId`	`string`	Any string	Shard identifier shown as a small badge (e.g. `'shard-0'`, `'p0'`)
`shardRole`	`string`	`'primary'`, `'replica'`, `'arbiter'`	Role badge with color coding

group
  .addProcess({ id: 'pg-primary', label: 'PostgreSQL', shape: 'cylinder', shardId: 'shard-0', shardRole: 'primary', state: 'running' })
  .addProcess({ id: 'pg-replica', label: 'PostgreSQL', shape: 'cylinder', shardId: 'shard-0', shardRole: 'replica', state: 'running' })
  .autoResize();

Centrality heatmap

The HUB button in the canvas toolbar activates the centrality heatmap. This feature analyzes the graph structure and colors nodes by their centrality score — how many edges connect to them relative to other nodes.

Darker / more saturated color = higher centrality = architectural bottleneck candidate
Lighter color = peripheral node with few connections

The heatmap is read-only and does not affect the script or the topology data. It is a diagnostic overlay to help identify single points of failure and over-connected nodes in complex diagrams.

The heatmap is most useful on diagrams with 10+ nodes. On small topologies, all nodes tend to have similar centrality scores and the overlay adds little value.

Replica naming

Node IDs ending with a numeric suffix are automatically treated as replicas of the base name. The FlowBuilder uses this to distribute animation packets across replicas via round-robin or random selection.

// These three nodes are replicas of 'api'
group
  .addProcess({ id: 'api-1', label: 'API Pod 1', state: 'running' })
  .addProcess({ id: 'api-2', label: 'API Pod 2', state: 'running' })
  .addProcess({ id: 'api-3', label: 'API Pod 3', state: 'running' })
  .autoResize();
 
// Animation targeting 'api' sends to one of api-1, api-2, api-3
flow.from('lb').to('api').showMessage('[ROUTED] Picked api-2');

IDs with non-numeric suffixes are distinct nodes — cb-counter and cb-state are not replicas of cb.

Layer System Proxy Pattern