Composition

What "compose" means

To integrate usually means: system A calls system B, schema mapping is custom, assumptions are hidden in code, every new connection is a new implementation project.

In Blue, blocks compose because they already share a common shape: participants, rules, state, record. That means one block can reference, trigger, constrain, or reuse another — without becoming the same thing.

Four kinds of composition

1. Reference composition

One document mentions another by identifier — typically a BlueId or a session id — without copying its contents.

Example: An order document carries a payNote field whose value is a reference (e.g. { blueId: ... }) to the matching PayNote. Both blocks remain independent; they just point at each other.

2. Trigger composition

An event in one document causes a request in another. The two documents stay separate; only a request is delivered.

Example: A delivery confirmation document, when the courier marks status delivered, triggers a Complete Payment request on the linked PayNote. The PayNote then runs its own rules to decide whether to complete.

3. Constraint composition

One document acts as a precondition or boundary on actions taken inside another.

Example: A mandate constrains a payment: the payment's rules require any operation made by the agent to be valid under the mandate (allowed source, max amount, conditions). The mandate is not the payment, but no payment passes without it.

4. Reuse composition

A pattern (a contract type, a sub-document, a workflow) defined once is reused across many blocks via repo.blue.

Example: A service document accesses a shared linked folder of supporting docs (terms, change log, rate sheet). The folder pattern is reused everywhere a service exists. Each instance is a separate document, but the shape is the same.

Example composition chain

A simple commerce flow:

1. A shop exists.
2. An order is created and references the shop.
3. The order references a payment.
4. The payment is governed by a PayNote.
5. The payer's agent acts through a mandate that constrains the payment.
6. A delivery confirmation from the courier triggers the PayNote to complete.
7. The payment completes.

This is not one giant document. It is several blocks working together — references, triggers, constraints, and reused patterns.

Why this is better than one giant object

Different interactions have different participants, different trust requirements, different lifecycles, and may be reusable independently. For example:

• the payment logic can be reused
• the mandate can be reused
• the delivery confirmation pattern can be reused

Composition keeps those pieces independent.

The four blocks of a commerce world

Order

Participants: buyer, seller. Rules around acceptance and shipping.

Payment

Participants: payer, payee, bank. Conditions on completion.

PayNote

Participants: payer, payee, guarantor, maybe courier or verifier. Governs what happens with the funds.

Mandate

Participants: owner, agent. Defines what the agent is allowed to do.