From 5b735bb528fab926a2135e8489ca9586a25f5c8d Mon Sep 17 00:00:00 2001
From: Matthew Meszaros <meszmatew@gmail.com>
Date: Wed, 10 Jun 2026 18:27:42 +0200
Subject: [PATCH] feat: replace ascii architecture diagrams in the realtime
 readme and resources docs with prose and tables

---
 realtime/README.md  | 12 +-----------
 resources/EMSG.md   | 21 ++++++---------------
 resources/Events.md | 12 +-----------
 3 files changed, 8 insertions(+), 37 deletions(-)

diff --git a/realtime/README.md b/realtime/README.md
index 53cad1def..11ca3e076 100644
--- a/realtime/README.md
+++ b/realtime/README.md
@@ -4,17 +4,7 @@ WebSocket gateway for real-time events in Warmbly. Built with Phoenix Channels a
 
 ## Architecture
 
-```
-┌─────────────┐     ┌─────────────────┐     ┌─────────────────┐
-│  Go Backend │────>│  Google Pub/Sub │────>│ Elixir Realtime │
-└─────────────┘     └─────────────────┘     └────────┬────────┘
-                                                     │
-                                                     │ WebSocket
-                                                     v
-                                            ┌─────────────────┐
-                                            │  React Frontend │
-                                            └─────────────────┘
-```
+The Go backend publishes events to Google Pub/Sub. The Elixir realtime service consumes them and fans each event out to the React frontend over Phoenix Channel WebSockets.
 
 ## Channels
 
diff --git a/resources/EMSG.md b/resources/EMSG.md
index 0c608e02b..38d27a695 100644
--- a/resources/EMSG.md
+++ b/resources/EMSG.md
@@ -11,21 +11,12 @@ EMSG provides a lightweight alternative to JSON for storing email bodies, with:
 
 ## Binary Layout
 
-```
-┌──────────────────────────────────────────┐
-│ Magic Number (4 bytes): "EMSG"           │
-├──────────────────────────────────────────┤
-│ Version (1 byte): 0x01                   │
-├──────────────────────────────────────────┤
-│ Flags (4 bytes): bitmask of sections     │
-├──────────────────────────────────────────┤
-│ Section 1: [Length 4B][Data...]          │
-├──────────────────────────────────────────┤
-│ Section 2: [Length 4B][Data...]          │
-├──────────────────────────────────────────┤
-│ ...                                      │
-└──────────────────────────────────────────┘
-```
+| Field | Size | Value |
+|-------|------|-------|
+| Magic number | 4 bytes | `"EMSG"` |
+| Version | 1 byte | `0x01` |
+| Flags | 4 bytes | Bitmask of the sections that follow |
+| Section 1..N | 4 bytes + data each | `[Length 4B][Data...]`, one per flag bit set |
 
 ## Flags
 
diff --git a/resources/Events.md b/resources/Events.md
index a90daa30d..fa2934622 100644
--- a/resources/Events.md
+++ b/resources/Events.md
@@ -4,17 +4,7 @@ Warmbly uses Apache Kafka for asynchronous event streaming between services, wit
 
 ## Overview
 
-```
-┌─────────────┐     ┌─────────────┐     ┌─────────────────┐
-│  Tracking   │────>│    Kafka    │────>│    Consumer     │
-│   Service   │     │             │     │                 │
-└─────────────┘     │             │     └─────────────────┘
-                    │             │
-┌─────────────┐     │             │     ┌─────────────────┐
-│   Backend   │────>│             │────>│     Worker      │
-│             │     │             │     │                 │
-└─────────────┘     └─────────────┘     └─────────────────┘
-```
+Two producers write to Kafka and two consumers read from it: the tracking service publishes events that the consumer processes, and the backend publishes commands that the workers execute.
 
 ## Kafka Topics