Core concepts

Document networks: Agreements, Orders, PayNotes, Mandates, and services

A Blue application is a graph of bounded documents with typed relationships, not one giant workflow and not a collection of unrelated private records.

Try in Playground

Why separate documents matter#

Separate documents create explicit boundaries for participants, authority, provider trust, lifecycle, visibility, payment, processing, retention, and audit.

A standing Agreement and one customer Order have different meanings. A PayNote and the Order that caused its payment have different truth owners. A Mandate and the target document it authorizes have different lifecycles. A provider service may need a Request and Response without becoming an embedded plugin.

A common network#

Agreement
  → authorizes creation of Orders
Offer
  → describes what a customer may accept
Order
  → records one customer occurrence
PayNote
  → governs one payment process
Mandate
  → authorizes one bounded agent or provider action
Provider service
  → answers typed Requests with attributable Responses

The documents connect through exact references, emitted Messages, bootstrap requests, operation calls, anchors, and subscriptions.

Bootstrap#

A bootstrap provider creates a new logical document through an authorized typed protocol. It validates the initial content, establishes participant mappings and sessions, initializes the document, and emits typed progress or completion Responses.

Bootstrap authority is separate from later operation authority inside the new document.

Subscriptions#

A subscription delivers selected events and optional snapshots from another document. Precise filter defaults matter: omitted events can mean all; an empty event list can mean none; initial and ongoing snapshots are separate choices.

Access and authority remain distinct. The ability to answer a subscription request does not automatically grant visibility to every source field.

Cross-document operation calls#

Document A may ask an intermediary such as MyOS Admin to place an Operation Request in Document B. The intermediary verifies source-side authority. The target feeder independently verifies the resulting target action. A source document cannot force the target processor by naming a Mandate.

Portals and operators#

Different portals can render participant-appropriate views of the same logical document network. Operators manage sessions, feeders, processing, storage, subscriptions, and evidence. Providers contribute the claims they control. The protocol and registries keep meaning portable.

Rule of thumb#

Use the smallest document boundary that keeps one coherent authority and lifecycle. Split when sharing, governance, participants, provider trust, retention, access, or scaling become independently meaningful.