From b0d7b6047049f86eaa99e08b23d85a2e78d6d62e Mon Sep 17 00:00:00 2001
From: ChaoticByte <contact@chaoticbyte.net>
Date: Sat, 27 Sep 2025 21:46:13 +0200
Subject: [PATCH] Add SPEC.md and a short description to the README

---
 README.md | 14 ++++++++++++-
 SPEC.md   | 59 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 72 insertions(+), 1 deletion(-)
 create mode 100644 SPEC.md

diff --git a/README.md b/README.md
index a15aeb3..4a4b025 100644
--- a/README.md
+++ b/README.md
@@ -1 +1,13 @@
-# argh
\ No newline at end of file
+# 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.
diff --git a/SPEC.md b/SPEC.md
new file mode 100644
index 0000000..4c0ca5b
--- /dev/null
+++ b/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.