From 0158ee569e1db28b8c8c41f6f96ef24144e1b52a Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Sun, 29 Mar 2026 11:00:16 +0000
Subject: [PATCH 1/5] Initial plan


From 645b02f77c9ce7530ec39edc14c67c57b1512473 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Sun, 29 Mar 2026 11:01:55 +0000
Subject: [PATCH 2/5] docs: simplify architecture diagram to focus on layers
 and key relationships

Agent-Logs-Url: https://github.com/albe/node-event-storage/sessions/a97367eb-8db7-4f33-9781-3d4c6aa03014

Co-authored-by: albe <4259532+albe@users.noreply.github.com>
---
 docs/architecture.md | 68 +++++++++++---------------------------------
 1 file changed, 16 insertions(+), 52 deletions(-)

diff --git a/docs/architecture.md b/docs/architecture.md
index 22e8c2c..9d62400 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -49,9 +49,9 @@ Writable  ──extends──▶  Readable / Base
 ReadOnly  ──extends──▶  Readable / Base
 ```
 
-The diagram below shows the full dependency graph. **Solid arrows** (`──▶`) indicate a *uses / instantiates* relationship; **dashed arrows** (`- -▶`) indicate *extends / inherits*.
+The diagram below shows the key relationships between the four layers. **Arrows** (`──▶`) indicate a *uses / coordinates* relationship.
 
-> **Note:** `util` is a shared helper module imported by almost every component and is omitted from the diagram for readability.
+> **Note:** Each layer box represents all variants within that layer (Writable, Readable, ReadOnly). The per-variant inheritance chain and utility components are detailed in the tables above and the component descriptions below.
 
 ```mermaid
 graph TD
@@ -63,67 +63,31 @@ graph TD
     end
 
     subgraph storageLayer["Storage Layer"]
-        WritableStorage
-        ReadableStorage
-        ReadOnlyStorage
+        Storage
     end
 
     subgraph partitionLayer["Partition Layer"]
-        WritablePartition
-        ReadablePartition
-        ReadOnlyPartition
+        Partition
     end
 
     subgraph indexLayer["Index Layer"]
-        WritableIndex
-        ReadableIndex
-        ReadOnlyIndex
+        Index
     end
 
-    subgraph utilities["Utilities"]
-        Clock
-        IndexEntry
-        Watcher
-        WatchesFile
-    end
-
-    %% API Layer
-    EventStore     --> WritableStorage
-    EventStore     --> EventStream
-    EventStore     --> JoinEventStream
-    EventStore     --> Consumer
+    %% API relationships
+    EventStore --> Storage
+    EventStore --> EventStream
+    EventStore --> Consumer
     JoinEventStream --> EventStream
-    Consumer       --> ReadableStorage
-
-    %% Storage inheritance
-    WritableStorage -.-> ReadableStorage
-    ReadOnlyStorage -.-> ReadableStorage
-
-    %% Storage → Partition / Index
-    WritableStorage --> WritablePartition
-    WritableStorage --> WritableIndex
-    ReadableStorage --> ReadOnlyPartition
-    ReadableStorage --> ReadOnlyIndex
-    ReadOnlyStorage --> Watcher
-
-    %% Partition inheritance
-    WritablePartition -.-> ReadablePartition
-    ReadOnlyPartition -.-> ReadablePartition
-
-    %% Partition → utilities
-    WritablePartition --> Clock
-    ReadOnlyPartition --> WatchesFile
-
-    %% Index inheritance
-    WritableIndex -.-> ReadableIndex
-    ReadOnlyIndex -.-> ReadableIndex
+    Consumer --> Storage
 
-    %% Index → utilities
-    ReadOnlyIndex --> WatchesFile
-    ReadableIndex --> IndexEntry
+    %% Storage coordinates Partition and Index
+    Storage --> Partition
+    Storage --> Index
 
-    %% Watcher plumbing
-    WatchesFile --> Watcher
+    %% EventStream is the bridge: resolves positions via Index, reads data from Partition
+    EventStream --> Index
+    EventStream --> Partition
 ```
 
 ---

From 520ebed209a91e84e2fa737e37795a1b60b16be7 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Sun, 29 Mar 2026 12:05:07 +0000
Subject: [PATCH 3/5] docs: address review feedback on architecture diagram

Agent-Logs-Url: https://github.com/albe/node-event-storage/sessions/ce3bbabf-39c2-420b-a4f9-8a3c3237cc13

Co-authored-by: albe <4259532+albe@users.noreply.github.com>
---
 docs/architecture.md | 24 ++++++++++++++----------
 1 file changed, 14 insertions(+), 10 deletions(-)

diff --git a/docs/architecture.md b/docs/architecture.md
index 9d62400..44d1118 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -58,7 +58,6 @@ graph TD
     subgraph api["API Layer"]
         EventStore
         EventStream
-        JoinEventStream
         Consumer
     end
 
@@ -74,20 +73,25 @@ graph TD
         Index
     end
 
+    Disk["💾 Disk"]
+
     %% API relationships
-    EventStore --> Storage
-    EventStore --> EventStream
-    EventStore --> Consumer
-    JoinEventStream --> EventStream
-    Consumer --> Storage
+    EventStore -->|"single ordered log"| Storage
+    EventStore -->|"exposes"| EventStream
+    EventStore -->|"exposes"| Consumer
+    Consumer -->|"iterates"| EventStream
+    Consumer -->|"persists state"| Disk
 
     %% Storage coordinates Partition and Index
-    Storage --> Partition
-    Storage --> Index
+    Storage -->|"made up of multiple"| Partition
+    Storage -->|"primary index"| Index
+
+    %% Partition has a secondary index (1:1 with a stream)
+    Partition -->|"secondary index (1:1 with stream)"| Index
 
     %% EventStream is the bridge: resolves positions via Index, reads data from Partition
-    EventStream --> Index
-    EventStream --> Partition
+    EventStream -->|"iterates"| Index
+    EventStream -->|"encompasses one partition (by default)"| Partition
 ```
 
 ---

From 45edb0ff948280634c65f890fe2f2baf7f49c16c Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Sun, 29 Mar 2026 12:48:04 +0000
Subject: [PATCH 4/5] docs: fix arrow crossing and clarify write vs read stream
 paths

Agent-Logs-Url: https://github.com/albe/node-event-storage/sessions/71818551-b500-4e96-97a3-efd34c6613d8

Co-authored-by: albe <4259532+albe@users.noreply.github.com>
---
 docs/architecture.md | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)

diff --git a/docs/architecture.md b/docs/architecture.md
index 44d1118..d1e37a6 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -79,7 +79,7 @@ graph TD
     EventStore -->|"single ordered log"| Storage
     EventStore -->|"exposes"| EventStream
     EventStore -->|"exposes"| Consumer
-    Consumer -->|"iterates"| EventStream
+    EventStore -->|"writes to (default partition)"| Partition
     Consumer -->|"persists state"| Disk
 
     %% Storage coordinates Partition and Index
@@ -89,9 +89,8 @@ graph TD
     %% Partition has a secondary index (1:1 with a stream)
     Partition -->|"secondary index (1:1 with stream)"| Index
 
-    %% EventStream is the bridge: resolves positions via Index, reads data from Partition
+    %% EventStream iterates an index (independent of which partitions are visited)
     EventStream -->|"iterates"| Index
-    EventStream -->|"encompasses one partition (by default)"| Partition
 ```
 
 ---

From 843c5081476fd2027237511c8881ce7351321e4f Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Sun, 29 Mar 2026 13:13:09 +0000
Subject: [PATCH 5/5] docs: relabel arrows and reverse index arrows per review
 feedback

Agent-Logs-Url: https://github.com/albe/node-event-storage/sessions/31dbe211-571c-45d7-89a4-a856e9f7e23d

Co-authored-by: albe <4259532+albe@users.noreply.github.com>
---
 docs/architecture.md | 11 +++++------
 1 file changed, 5 insertions(+), 6 deletions(-)

diff --git a/docs/architecture.md b/docs/architecture.md
index d1e37a6..c44b6de 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -62,7 +62,7 @@ graph TD
     end
 
     subgraph storageLayer["Storage Layer"]
-        Storage
+        Storage["Storage<br/><i>single ordered log</i>"]
     end
 
     subgraph partitionLayer["Partition Layer"]
@@ -76,18 +76,17 @@ graph TD
     Disk["💾 Disk"]
 
     %% API relationships
-    EventStore -->|"single ordered log"| Storage
+    EventStore -->|"writes to stream=partition"| Storage
     EventStore -->|"exposes"| EventStream
     EventStore -->|"exposes"| Consumer
-    EventStore -->|"writes to (default partition)"| Partition
     Consumer -->|"persists state"| Disk
 
     %% Storage coordinates Partition and Index
     Storage -->|"made up of multiple"| Partition
-    Storage -->|"primary index"| Index
+    Index -->|"primary index (over all partitions)"| Storage
 
-    %% Partition has a secondary index (1:1 with a stream)
-    Partition -->|"secondary index (1:1 with stream)"| Index
+    %% Index covers 1-n partitions as a secondary index (per stream)
+    Index -->|"secondary index (stream) over 1-n"| Partition
 
     %% EventStream iterates an index (independent of which partitions are visited)
     EventStream -->|"iterates"| Index