Gain early access and support Babbling Brook on Indiegogo

Developers and Documentation

This documentation provides technical details on how the Babbling Brook network functions. A non technical overview is available here. It is a draft and incomplete. Each section will be expanded over the coming weeks. Follow the Blog or Twitter for updates. The full version will be released with an open source package that implements it when Babbling Brook goes into open beta.

This document reflects the protocol as it is intended to be when the first beta is released. There are numerous differences between this documentation and the current alpha implementation. Notes with a yellow background have important information for alpha testers.


Babbling Brook is an internet based protocol with two main parts. The first is a standard set of urls and responses that sites that use Babbling Brook make available. The second consists of a series of nested iframes that communicate via the HTML5 postMessage feature. Since Babbling Brook is a subset of these two existing protocols, it might be easier to think of it as a two way API.

There are two kinds of websites that can use the Babbling Brook protocol. Datastores and client websites. The same website can serve both features.

Client Websites

Client websites provide the interface that end users utilise to access the Babbling Brook network. They can take on the guise of any kind of website. Behind the scenes the client website is essentially just a front end site, with nearly all data requests being passed to the users datastore via JavaScript. This makes client websites easy to implement using just some knowledge of HTML, JavaScript and the Babbling Brook protocol. The back end of the client can be very light, as it is essentially just serving up static templates. The only complexity being the providing of authenticity tokens.


Datastores are used to store all data in the network. All users who want to use a Babbling Brook client website need to sign up with a datastore. This is similar to how Open ID, Facebook and Google provide a single user account to access many websites. The difference being that Babbling Brook provides not just a universal point of login as with Open ID, or access to a locked, propriety data store - as is the case with Google and Facebook. Babbling Brook provides access to an open data platform that allows users to control who stores their data.

Each datastore has three main public faces, the first is the one that users see when they go to the domains address. This allows the user to log in and manage their account. The second is the hidden IFRAME that client websites communicate with, which is always accessed via the 'domus' subdomain. (Domus being latin for home). The third is an IFRAME that is nested in domus domains to enable it to access other domains in the network. This is always accessed via the 'scientia' subdomain. (Scientia being Latin for knowledge). The datastores home domain can start with anything except the sub domains 'domus.' and 'scientia.'

There is also a minimal amount of direct server to server communication. This is to facilitate the fetching of cached data and the authentication of secret tokens used to prevent spoofing.

User created algorithms, known as rhythms run in webworker processes that are sandboxed in iframes within the domus domain.

The alpha code currently runs rhythms in subdomains, but the recent introduction of the html5 sandbox attribute on iframes provides a superior method of isolating the rhythm processes.

As can be seen from the diagram, the domus subdomain is essentially the central controller of a users experience of the Babbling Brook network, with the client website just providing a UI for them to interact with the network in a particular way.

Cross Domain Communication

The different domains on the network communicate with each other via html5 postMessage commands.

Read more about cross domain communication.


Users have to be able to log in and out of the Babbling Brook network securely.

Read more about users.

Protocol features

The Babbling Brook network consists of a set of features that are interconnected with each other. When these features are combined with user interaction an open feedback loop is created. The result of this feedback loop is increasing social structure as people self organise around interests that they have in common. Many existing social networks take advantage of feedback loops, but they are closed in nature; they have a very tightly defined purpose. Babbling Brook's feedback loop is designed to be open ended, allowing for social structure to organically grow in any desired direction and with as much complexity as desired or until hardware limits are reached.

The topic headings below will be expanded in the following weeks.


All data in the Babbling Brook network has a home domain.

Read more about domains.


Users represent the people that are using the Babbling Brook network.

Read more about users.


Streams contain all the user posted content in the Babbling Brook network. They define the structure of the posts that are made in them.


Trees enable users to respond to posts.

Read more about streams.


Deltas combine multiple streams into one.

Read more about deltas.


Posts allow users to make content.

Read more about posts.


All posts can be taken - users can assign at least one numerical value to all posts. This can be represented as votes, liking, following, staring etc.

Read more about takes.


Kindred users are the users that are closest to each other in the Babbling Brook network.

Read more about kindred relationships.


Rhythms are algorithms - bits of code that perform specific functions - that can be created and selected by users.

Read more about rhythms.


Rings have two main functions. They enable users to group together. They allow users to negotiate between the public and private parts of the Babbling Brook network.

Read more about rings.


Suggestions help users find features and content that interest them.

Read more about suggestions.

Additional salient issues


Everything in the Babbling Brook network is either Public or Private. Rings are used to navigate the space between.

Read more about privacy.


All public content in the Babbling Brook network must be submitted under a Creative Commons CC-BY-SA-3.0 license.

Read more about copyleft.

Data retention

Defines when data can be deleted.

Read more about data retention.


All URLs on both clients and datastores follow a shared pattern for easy interoperability.

Read more about paths.


There is a set of standardised JavaScript models for protocol objects.

Read more about models.

Read more about authentication.

Odds and ends

Other protocol details that don't neatly fit anywhere else.

Read more about odds and ends.


Feedback enables Babbling Brook to grow from people sharing content to a structured peer based society.

Read more about feedback.


How datastores and client websites maintain profitability in a free market economy.

Read more about finance.


Client websites and rhythms have access to standard JavaScript libraries.

Read more about libraries.

Future Versions

Features that are being considered for future versions.

Read more about future versions.

Gain early access and support Babbling Brook on Indiegogo