From cf4e25b02b7f6e17a6a35c532137952de8ec4e1b Mon Sep 17 00:00:00 2001
From: thegamecracks <61257169+thegamecracks@users.noreply.github.com>
Date: Sat, 9 Mar 2024 12:58:57 -0500
Subject: [PATCH] docs: add summary of implementation and protocol

---
 README.md | 42 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 42 insertions(+)

diff --git a/README.md b/README.md
index 0ee3e9c..7b6180a 100644
--- a/README.md
+++ b/README.md
@@ -7,3 +7,45 @@ A handcrafted implementation of an internet relay chat without following
 any conventions or RFC standards.
 
 ![Two client windows side-by-side](/docs/images/demo.png)
+
+## Implementation
+
+Dumdum consists of two parts:
+
+1. The Sans-IO protocol, defined in [dumdum.protocol]
+2. The asyncio wrapper, defined in [dumdum.client] and [dumdum.server]
+
+The [Sans-IO] protocol is responsible for handling the generation and
+consumption of byte streams, along with producing events from received
+messages, while the asyncio wrapper is responsible for the actual network
+communication between the server and its clients.
+
+[Sans-IO]: https://sans-io.readthedocs.io/
+
+[dumdum.protocol]: /src/dumdum/protocol/
+[dumdum.client]: /src/dumdum/client/
+[dumdum.server]: /src/dumdum/server.py
+
+## Protocol
+
+Clients are able to send the following messages:
+
+1. AUTHENTICATE: `0x00 | 1-byte version | varchar nickname (32)`
+2. SEND_MESSAGE: `0x01 | varchar channel name (32) | varchar content (1024)`
+3. LIST_CHANNELS: `0x02`
+
+Clients must send an AUTHENTICATE command before they can begin chat
+communications.
+
+Servers are able to send the following messages:
+
+1. INCOMPATIBLE_VERSION: `0x00 | 1-byte version`
+2. ACKNOWLEDGE_AUTHENTICATION: `0x01 | 0 or 1 success`
+3. SEND_MESSAGE: `0x02 | varchar channel name (32) | varchar nickname (32) | varchar content (1024)`
+4. LIST_CHANNELS: `0x03 | 2-byte length | varchar channel name (32) | ...`
+
+When the client disconnects and reconnects, they MUST re-authenticate with the server.
+
+As this protocol has been intentionally designed to be simple (no timeouts
+or keep alives), I/O wrappers do not need a significant amount of work to
+implement it.