docs: add builder flow docs and diagram (#7348)

Co-authored-by: Alexey Shekhirin <a.shekhirin@gmail.com>

crates/node-builder/Cargo.toml

@@ -46,6 +46,7 @@ tokio = { workspace = true, features = [
 ] }
 
 ## misc
+aquamarine.workspace = true
 eyre.workspace = true
 fdlimit = "0.3.0"
 confy.workspace = true

crates/node-builder/docs/mermaid/builder.mmd

@@ -0,0 +1,23 @@
+graph TD;
+    CLI::parse-->NodeCommand
+    NodeCommand--execute-->NodeBuilder
+    subgraph "Builder"
+        NodeBuilder--"with_types"-->NodeBuilderT
+        NodeBuilderT("NodeBuilder(Types)")--"with_components"-->NodeBuilderC
+        NodeBuilderC("NodeBuilder(Types, Components)")--"extend_rpc_modules"-->NodeBuilderC
+        NodeBuilderC--"on_rpc_started"-->NodeBuilderC
+    end
+    NodeBuilderC--"launch"-->launch
+    subgraph launch
+        database("database init")-->tree("blockchain tree init")
+        tree--BuilderContext-->components{"build_components"}
+        subgraph components
+            ComponentsBuilder--"first creates"-->Pool
+            Pool--"then creates"-->PayloadService
+            Pool--"then creates"-->Network
+        end
+        components--"launch rpc"-->RpcContext
+        RpcContext--invokes-->extend_rpc_modules
+        RpcContext--invokes-->on_rpc_started
+    end
+    launch--"FullNode"-->NodeHandle

crates/node-builder/src/builder.rs

@@ -61,6 +61,7 @@ type RethFullProviderType<DB, Evm> =
 type RethFullAdapter<DB, N> =
     FullNodeTypesAdapter<N, DB, RethFullProviderType<DB, <N as NodeTypes>::Evm>>;
 
+#[cfg_attr(doc, aquamarine::aquamarine)]
 /// Declaratively construct a node.
 ///
 /// [`NodeBuilder`] provides a [builder-like interface][builder] for composing
@@ -113,6 +114,26 @@ type RethFullAdapter<DB, N> =
 /// All hooks accept a closure that is then invoked at the appropriate time in the node's launch
 /// process.
 ///
+/// ## Flow
+///
+/// The [NodeBuilder] is intended to sit behind a CLI that provides the necessary [NodeConfig]
+/// input: [NodeBuilder::new]
+///
+/// From there the builder is configured with the node's types, components, and hooks, then launched
+/// with the [NodeBuilder::launch] method. On launch all the builtin internals, such as the
+/// `Database` and its providers [BlockchainProvider] are initialized before the configured
+/// [NodeComponentsBuilder] is invoked with the [BuilderContext] to create the transaction pool,
+/// network, and payload builder components. When the RPC is configured, the corresponding hooks are
+/// invoked to allow for custom rpc modules to be injected into the rpc server:
+/// [NodeBuilder::extend_rpc_modules]
+///
+/// Finally all components are created and all services are launched and a [NodeHandle] is returned
+/// that can be used to interact with the node: [FullNode]
+///
+/// The following diagram shows the flow of the node builder from CLI to a launched node.
+///
+/// include_mmd!("docs/mermaid/builder.mmd")
+///
 /// ## Internals
 ///
 /// The node builder is fully type safe, it uses the [NodeTypes] trait to enforce that all

crates/node-builder/src/lib.rs

@@ -37,3 +37,5 @@ pub use reth_node_core::node_config::NodeConfig;
 
 // re-export API types for convenience
 pub use reth_node_api::*;
+
+use aquamarine as _;