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.

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();

Icons

The icon property displays a small pictogram inside the node, making it easy to identify component types at a glance. Icons are rendered as inline SVGs and scale with the node.

Usage

group
  .addProcess({ id: 'srv',  label: 'API Server',    icon: 'server',        state: 'running' })
  .addProcess({ id: 'pg',   label: 'PostgreSQL',    icon: 'database',      state: 'running' })
  .addProcess({ id: 'lb',   label: 'Load Balancer', icon: 'load-balancer', state: 'running' })
  .addProcess({ id: 'fw',   label: 'Firewall',      icon: 'firewall',      state: 'running' })
  .autoResize();

Available icons

The canonical list is SUPPORTED_NODE_ICONS in packages/domain/src/nodeIcons.ts; an unknown literal is a validation error.

Set icon on every process node. If icon is omitted, the tile shows only the first letter of the label, and the validator reports a NODE_WITHOUT_ICON warning (the script still runs).

Node rendering modes

Process nodes have two anatomies. The footprint is the same 200×80 in both, so layout, autoResize() and fit-view do not change between them.

The mode is a reader preference, not a script property: it is stored in the browser (localStorage) and applies to every diagram the reader opens. Switch it with the node-style button in the viewer’s control panel, or in Account settings on the workspace page. On /sandbox/kit a ?node=card or ?node=tile query parameter previews a mode without saving it. Readers who explicitly chose card keep it; readers who never touched the switch get tile.

State indicators

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

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.

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.

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.