Skip to content

docs: simplify architecture diagram to layers only#278

Merged
albe merged 5 commits intomainfrom
copilot/simplify-architecture-diagram
Mar 29, 2026
Merged

docs: simplify architecture diagram to layers only#278
albe merged 5 commits intomainfrom
copilot/simplify-architecture-diagram

Conversation

Copy link
Copy Markdown
Contributor

Copilot AI commented Mar 29, 2026

The architecture diagram was overloaded — 13 nodes, 20+ mixed-type arrows (uses + inheritance), and a utilities subgraph — making it hard to extract signal about how the layers relate.

Changes

  • Collapsed variants: Each layer (Storage, Partition, Index) is now a single node. The Writable/Readable/ReadOnly split is already covered by the text and tables immediately surrounding the diagram.
  • Removed utilities subgraph: Clock, Watcher, WatchesFile, IndexEntry removed from diagram; they remain documented in the component descriptions.
  • Removed JoinEventStream: Omitted to keep focus on the core stream concepts.
  • Labelled arrows: Every arrow carries a caption describing the relationship (e.g. "writes to stream=partition", "exposes", "made up of multiple", "iterates", "persists state").
  • Write vs. read path distinction: EventStore →|"writes to stream=partition"| Storage surfaces the write-stream concept (a stream name maps to a specific partition). EventStream only connects to Index ("iterates"), reflecting that a read stream traverses an index independently of which partitions it visits.
  • Storage node annotated: "single ordered log" appears as an italic subline inside the Storage node, conveying how EventStore accesses it.
  • Consumer exposed by EventStore: Consumer is shown as exposed by EventStore with a "persists state" arrow to a Disk node.
  • Index arrows reversed and annotated: Index →|"primary index (over all partitions)"| Storage and Index →|"secondary index (stream) over 1-n"| Partition, making it clear that a single index can cover 1-n partitions.

⚡ Quickly spin up Copilot coding agent tasks from anywhere on your macOS or Windows machine with Raycast.

Copilot AI changed the title [WIP] Update architecture diagram for clarity and focus docs: simplify architecture diagram to layers only Mar 29, 2026
Copilot finished work on behalf of albe March 29, 2026 11:02
Copilot AI requested a review from albe March 29, 2026 11:02
Comment thread docs/architecture.md Outdated
Comment thread docs/architecture.md Outdated
Comment thread docs/architecture.md Outdated
Comment thread docs/architecture.md Outdated
Comment thread docs/architecture.md Outdated
Comment thread docs/architecture.md Outdated
Comment thread docs/architecture.md Outdated
Comment thread docs/architecture.md Outdated
Comment thread docs/architecture.md Outdated
@albe
Copy link
Copy Markdown
Owner

albe commented Mar 29, 2026

@copilot work on my last review comments

Copilot finished work on behalf of albe March 29, 2026 12:06
Copilot AI requested a review from albe March 29, 2026 12:06
@albe
Copy link
Copy Markdown
Owner

albe commented Mar 29, 2026

@copilot the arrow between consumer and EventStream crossing the Eventstore to EventStream arrow is suboptimal. Try to find a solution, but if mermaid doesn't allow to fix that, instead remove the consumer->EventStream arrow again.

More importantly, I'd like to show the subtle distinction between write stream, which is just a name that translates to a specific partition in the commit/write path of EventStore, vs the readonly EventStream which is the class exposed by EventStore. Therefore it makes sense to remove the EventStream->Partition link, as the read stream iterates an index, independent of the partitions it might visit. Meanwhile an EventStore.commit will write to one partition only in the default partitioning scheme.

Copy link
Copy Markdown
Contributor Author

Copilot AI commented Mar 29, 2026

@copilot the arrow between consumer and EventStream crossing the Eventstore to EventStream arrow is suboptimal. Try to find a solution, but if mermaid doesn't allow to fix that, inst...

Done in 45edb0f:

  • Removed Consumer → EventStream (no more crossing arrow)
  • Removed EventStream → Partition (read stream iterates index, independent of which partitions it visits)
  • Added EventStore →|"writes to (default partition)"| Partition to make the write path explicit

diagram

Copilot finished work on behalf of albe March 29, 2026 12:49
Comment thread docs/architecture.md Outdated
Comment thread docs/architecture.md Outdated
Copilot finished work on behalf of albe March 29, 2026 13:14
Copilot AI requested a review from albe March 29, 2026 13:14
@coveralls
Copy link
Copy Markdown

Coverage Status

coverage: 98.004%. remained the same
when pulling 843c508 on copilot/simplify-architecture-diagram
into 04fbba6 on main.

@albe albe marked this pull request as ready for review March 29, 2026 13:36
@albe albe merged commit de1c33a into main Mar 29, 2026
10 checks passed
@albe albe deleted the copilot/simplify-architecture-diagram branch March 29, 2026 13:36
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants