restructure docs

docs/federation.md

@@ -0,0 +1,23 @@
+# Federation
+
+This section will cover how federation works in Toolshed.
+
+## What is Federation?
+
+Since user of Toolshed you can search and interact the inventory of all their 'friends' that are potentially on
+different servers there is a need for a way to communicate between servers. We don't want to rely on a central server that
+stores all the data and we don't want to have a central server that handles all the communication between servers. This
+is where federation comes in. Toolshed uses a protocol that can not only exchange data with the server where the user
+is registered but also with the servers where their friends are registered.
+
+## How does it work?
+
+Any user can register on any server and creates a personal key pair. The public key is stored on the server and the private
+key is stored on the client. The private key is used to sign all requests to the server and the public key is used to
+verify the signature. Once a user has registered on a server they can send friend requests to other users containing
+their public key. If the other user accepts the friend request, the server stores the public key of the friend and
+uses it to verify access to the friend's inventory. While accepting a friend request the user also automatically sends
+their own public key to the friend's server. This way both users can access each other's inventory.
+
+The protocol is based on a simple HTTPS API exchanging JSON data that is signed with the user's private key. By default
+Toolshed servers provide a documentation of the API at [/docs/api](/docs/api).