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:
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:
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.