From 7a7fb23dac7254561626e20ac52a0c31a76c8ab2 Mon Sep 17 00:00:00 2001
From: "hinto.janai" <hinto.janai@protonmail.com>
Date: Wed, 4 Sep 2024 16:52:58 -0400
Subject: [PATCH] service diagram

---
 .../src/storage/common/service/intro.md       | 59 ++++++++++++++++++-
 1 file changed, 56 insertions(+), 3 deletions(-)

diff --git a/books/architecture/src/storage/common/service/intro.md b/books/architecture/src/storage/common/service/intro.md
index a853813..bba7486 100644
--- a/books/architecture/src/storage/common/service/intro.md
+++ b/books/architecture/src/storage/common/service/intro.md
@@ -1,12 +1,65 @@
 # tower::Service
 Both [`cuprate_blockchain`](https://doc.cuprate.org/cuprate_blockchain)
 and [`cuprate_txpool`](https://doc.cuprate.org/cuprate_txpool) provide
-[`tower::Service`](https://docs.rs/tower)s that define how other outside
-Cuprate crates access the database.
+`async` [`tower::Service`](https://docs.rs/tower)s that define database requests/responses.
+
+The main API that other Cuprate crates use.
 
 There are 2 `tower::Service`s:
 1. A read service which is backed by a [`rayon::ThreadPool`](https://docs.rs/rayon)
 1. A write service which spawns a single thread to handle write requests
 
 As this behavior is the same across all users of [`cuprate_database`](https://doc.cuprate.org/cuprate_database),
-it is extracted into its own crate: [`cuprate_database_service`](https://doc.cuprate.org/cuprate_database_service).
\ No newline at end of file
+it is extracted into its own crate: [`cuprate_database_service`](https://doc.cuprate.org/cuprate_database_service).
+
+## Diagram
+As a recap, here is how this looks to a user of a higher-level database crate,
+`cuprate_blockchain` in this example. Starting from the lowest layer:
+
+1. `cuprate_database` is used to abstract the database
+1. `cuprate_blockchain` builds on-top of that with tables, types, operations
+1. `cuprate_blockchain` exposes a `tower::Service` using `cuprate_database_service`
+1. The user now interfaces with `cuprate_blockchain` with that `tower::Service` in a request/response fashion
+
+```
+                         ┌──────────────────┐
+                         │ cuprate_database │
+                         └────────┬─────────┘
+┌─────────────────────────────────┴─────────────────────────────────┐
+│ cuprate_blockchain                                                │
+│                                                                   │
+│ ┌──────────────────────┐  ┌─────────────────────────────────────┐ │
+│ │ Tables, types        │  │ ops                                 │ │
+│ │ ┌───────────┐┌─────┐ │  │ ┌─────────────┐ ┌──────────┐┌─────┐ │ │
+│ │ │ BlockInfo ││ ... │ ├──┤ │ add_block() │ │ add_tx() ││ ... │ │ │
+│ │ └───────────┘└─────┘ │  │ └─────────────┘ └──────────┘└─────┘ │ │
+│ └──────────────────────┘  └─────┬───────────────────────────────┘ │
+│                                 │                                 │
+│                       ┌─────────┴───────────────────────────────┐ │
+│                       │ tower::Service                          │ │
+│                       │ ┌──────────────────────────────┐┌─────┐ │ │
+│                       │ │ Blockchain{Read,Write}Handle ││ ... │ │ │
+│                       │ └──────────────────────────────┘└─────┘ │ │
+│                       └─────────┬───────────────────────────────┘ │
+│                                 │                                 │
+└─────────────────────────────────┼─────────────────────────────────┘
+                                  │
+		                    ┌─────┴─────┐
+       ┌────────────────────┴────┐ ┌────┴──────────────────────────────────┐
+       │ Database requests       │ │ Database responses                    │
+       │ ┌─────────────────────┐ │ │ ┌───────────────────────────────────┐ │
+       │ │ FindBlock([u8; 32]) │ │ │ │ FindBlock(Option<(Chain, usize)>) │ │
+       │ └─────────────────────┘ │ │ └───────────────────────────────────┘ │
+       │ ┌─────────────────────┐ │ │ ┌───────────────────────────────────┐ │
+       │ │ ChainHeight         │ │ │ │ ChainHeight(usize, [u8; 32])      │ │
+       │ └─────────────────────┘ │ │ └───────────────────────────────────┘ │
+       │ ┌─────────────────────┐ │ │ ┌───────────────────────────────────┐ │
+       │ │ ...                 │ │ │ │ ...                               │ │
+       │ └─────────────────────┘ │ │ └───────────────────────────────────┘ │
+       └─────────────────────────┘ └───────────────────────────────────────┘
+                            ▲          │
+                            │          ▼
+                     ┌─────────────────────────┐
+                     │ cuprate_blockchain user │
+                     └─────────────────────────┘
+```
\ No newline at end of file