Skip to content

Cairn Documentation

Interfaces & Signals

Interfaces define how nodes connect and communicate. They're the contracts between subsystems — what flows across boundaries and under what conditions.

What an Interface Represents

An interface connects exactly two nodes. It represents a physical connection, a data exchange, a power transfer, or a material flow. Interfaces are bidirectional containers — the direction of individual flows is defined by the signals inside them.

Signals

A signal is a single flow within an interface:

  • Name: What's being transferred ("position_data", "motor_power")
  • Type: data, power, physical, or thermal
  • Direction: source → target, target → source, or bidirectional
  • Unit: Engineering unit (V, A, Mbps, L/min)

An interface might carry multiple signals:

Interface: Power Subsystem ↔ Drivetrain ├─ motor_power (power, 48V, →) ├─ motor_current (power, 0-120A, →) ├─ fault_status (data, boolean, ←) └─ temperature (data, °C, ←)

Creating Interfaces

Architecture lens: right-click a block and choose Connect to…, click an empty cell in the N² view, or use + Interface.

⌘K command:

"Add interfaces to the power subsystem"
"Create a data interface between navigation and control"

Decomposition side effect: When AI decomposes a node, it often proposes interfaces between the new children.

Interfaces Across Levels

Interfaces usually run between the lowest-level parts, but you read a model one level at a time. Seen from a node, every interface falls into one of four places:

  • Between two of its children: drawn as a solid connector.
  • Through their parts: the ends sit inside two different children. The two children are connected, so the Architecture lens draws a dashed connector between them.
  • Across its boundary: one end is inside the node and the other outside. The outside node appears on the edge of the diagram.
  • Inside one child: shown when you open that child.
  • On the node itself: drawn on the node rather than on one of its parts. Once a node is decomposed, route each of these to the part that carries it. The Architecture lens lists them so you can.

A signal's direction is relative to the interface's source: out is sent by the source, in is received by it. The diagram's arrows and the N² cells follow the signals, so an interface drawn from A to B that only carries feedback flows from B to A.