Platform Overview
=================


The Pipes API provides an SDK for managing peer-to-peer nodes on a
network.

The platform takes care of the complexities of connecting nodes,
routing data, synchronizing node state, and encrypting data en route
and at rest, leaving the developer an easy-to-use API for building
peer-to-peer applications. The platform supports:

- Creating a private and secure (virtual) network

- Broadcasting messages/objects to all nodes in a network

- Sending messages/objects to a specific node.  (All
  messages/objects are encrypted enroute; intermediate nodes
  cannot access.)

- Synchronization of long-term application state (history) between
  nodes on the network, including support for offline usage and
  synchronization at reconnection with peers

- Streaming audio, video, and screensharing connections between any
  nodes connected to the same network, including multiplexing and
  mixing

- Network port forwarding and general data connections between any
  nodes connected to the same network

- Storage, transfer/sharing, archival, and replication of files

- Presence status for identifying which nodes have joined the network and
  which are currently accessible/online

- Notification system for sending push notifications to users via
  configurable channels (mobile device, SMS, email, etc) upon certain
  events

- Identity management, including synchronization of user data across
  multiple devices/nodes


Terminology
-----------

Some terminology:

- Node: IP-enabled participant in a Pipes network

- Node ID: the identifier of a Node, which must be unique on the
  network

- Peer: a Node from the perspective of another Node to which it is
  directly connected (i.e., via direct establishment of a TCP
  connection)

- Network: a collection of transitively connected Nodes

- Packet: an atomic unit of communication that is communicated across
  the Network. Packets can contain arbitrary data.

- Packet ID: typically the SHA256 hash of the Packet data, used for
  identification of packets and error checking

- Pipeline: a communication channel that supports the broadcast of
  messages to all Nodes on a Network. Pipelines are either Persistent
  or Live.

- Persistent Pipeline: a Pipeline whose Packet history is maintained on,
  and synchronized across, all Nodes, and can be obtained by any new Node joining the
  Network. Used to guarantee delivery regardless of whether Peer is on
  the network when the Packet is first created.

- Live Pipeline: a Pipeline that only attempts delivery to active (online) Nodes.

- Point-to-Point Pipeline: a Pipeline that is used by only two Nodes
  in the Network. The Nodes do not have to be Peers, the Network takes
  care of the required routing.

The Pipes API is an asynchronous API: objects (messages) can be sent
from the client or back to the client at any time. Some objects will
be sent in response to an API request, but many will happen
asynchronously.

The API provides:

- Networks
    - maintaining the list of known networks
    - network discovery
    - network connection

- Network Metadata
    - connected peers
    - known and currently reachable nodes
    - security protocols
    - channels, services, applications

- Pipelines:
    - name, metadata (incl. live or persistent), encryption
    - real-time and persisted/synchronized state

- Messaging
    - ability to broadcast and send point-to-point messages
    - ability to subscribe to notifications for incoming messages
    - point-to-point connections for streaming audio, video, file transfer, and other network data