Add SPEC.md and a short description to the README

README.md

@@ -1 +1,13 @@
-# argh
+# argh net
+
+> **WARNING**  
+> This project is in an **EXPERIMENTAL** stage where things change all the time. Do not use (yet).
+
+This project aims to develop a specification and software suite for the easy creation of distributed networks on top of websockets, specifically for **broadcasting** text messages.
+
+The goal of this implementation is not to be very efficient or sophisticated, but instead attempts to "just work".
+
+See [SPEC.md](./SPEC.md) for the specification.
+
+> **NOTE**  
+> The specification and implementation are not always updated at the same time and may therefore be out of sync.

SPEC.md

@@ -0,0 +1,59 @@
+# argh Networking Specification
+
+This document describes how packets are sent through the network of nodes, how packets are structured, etc.
+
+
+## Overview
+
+### Underlying network protocol
+
+All connections are using unencrypted (TODO) websockets as the underlying network procol.
+
+### How a packet travels through the network
+
+(TODO)
+
+### Packet Flow
+
+```
+ Network A
+.~~~~~~~~~~~~~~~~~~~~~.
+(                     )
+(   Client ——> Node —————.
+(               |     )  |
+'~~~~~~~~~~~~~~~|~~~~~'  |
+                |        |
+ Network B      |        |
+.~~~~~~~~~~~~~~~|~~~~~~~~|~~~~~~~~~~~~~~~~.
+(               v        v                )
+(   Client <—— Node <=> Node ——> Client   )
+(               |        |                )
+'~~~~~~~~~~~~~~~|~~~~~~~~|~~~~~~~~~~~~~~~~'
+                |        |
+                |        '————.
+ Network C      |             |
+.~~~~~~~~~~~~~~~|~~~~~.       :———> other Networks
+(               v     )       |
+(   Client <—— Node ——————————'
+(   Client <————|     )
+(   Client <————|     )
+(      ... <————'     )
+(                     )
+'~~~~~~~~~~~~~~~~~~~~~'
+```
+
+## Packet Structure
+
+> **NOTE**  
+> Not yet implemented.
+
+A complete packet is a [MessagePack](https://msgpack.org/)-encoded dictionary with the following fields:
+
+| field  | type   | description |
+| ------ | ------ | ----------- |
+| `uuid` | bytes  | 16-byte big endian uuid |
+| `body` | bytes  | The message body |
+
+(TODO)
+
+The client who sends the packet to the first node must already provide a complete packet. Nodes solely verify & relay packets.