docs: add initial architecture diagrams for js-libp2p (#2121)

Author: maschad

doc/ARCHITECTURE.md

@@ -0,0 +1,217 @@
+# Libp2p Architecture
+
+js-libp2p is comprised of a number of components that work together to provide functionality such as dailling peers, managing connections, registering protocols, storing information about peers and much more. This document aims to provide a high level overview of the components and how they interact with each other.
+
+- [Libp2p Architecture](#libp2p-architecture)
+	- [Component Diagram](#component-diagram)
+	- [Sequence Diagrams](#sequence-diagrams)
+		- [Dialing a Peer](#dialing-a-peer)
+		- [Opening a stream on a connection](#opening-a-stream-on-a-connection)
+
+## Component Diagram
+
+```mermaid
+flowchart TB
+    direction TB
+    subgraph Components
+        direction TB
+        PeerId ~~~
+        Events ~~~
+        ConnectionGater ~~~
+        Upgrader
+        AddressManager ~~~
+        ConnectionManager ~~~
+        TransportManager ~~~
+        Registrar
+        PeerStore ~~~
+        Datastore ~~~
+        PeerRouting ~~~
+        _xx[ ]
+        ContentRouting ~~~
+        Metrics ~~~
+        ConnectionProtector ~~~
+        _x[ ]
+
+        style _x opacity:0;
+        style _xx opacity:0;
+
+    end
+
+    subgraph Connections[Connection Configuration]
+        direction TB
+
+        subgraph Transports
+            direction TB
+            TCP
+            WebRTC
+            Websocket
+            Webtransport
+        end
+
+        subgraph Encryption[Connection Encryptions]
+            direction TB
+            Noise
+            Plaintext
+        end
+
+        subgraph Multiplexer[Stream Multiplexers]
+            direction TB
+            Yamux
+            Mplex
+        end
+
+        Multiplexer ~~~ Encryption ~~~ Transports
+
+    end
+```
+
+```mermaid
+---
+title: Components Dependency Graph
+---
+flowchart TD
+    PeerId
+    Events
+    ConnectionGater
+    Upgrader
+    AddressManager
+    ConnectionManager
+    TransportManager
+    Registrar
+    PeerStore
+    Datastore
+    PeerRouting
+    ContentRouting
+    Metrics
+    ConnectionProtector
+
+    %% AddressManager
+    PeerId --> AddressManager
+    TransportManager --> AddressManager
+    PeerStore --> AddressManager
+    Events --> AddressManager
+
+    %% ConnectionManager
+    PeerId --> ConnectionManager
+    Metrics --> ConnectionManager
+    PeerStore --> ConnectionManager
+    TransportManager --> ConnectionManager
+    ConnectionGater --> ConnectionManager
+    Events --> ConnectionManager
+
+    %% TransportManager
+    Metrics --> TransportManager
+    AddressManager --> TransportManager
+    Upgrader --> TransportManager
+    Events --> TransportManager
+
+    %% Upgrader
+    PeerId --> Upgrader
+    Metrics --> Upgrader
+    ConnectionManager --> Upgrader
+    ConnectionGater --> Upgrader
+    ConnectionProtector --> Upgrader
+    Registrar --> Upgrader
+    PeerStore --> Upgrader
+    Events --> Upgrader
+
+    %% Registrar
+    PeerId --> Registrar
+    ConnectionManager --> Registrar
+    PeerStore --> Registrar
+    Events --> Registrar
+
+    %% PeerStore
+    PeerId --> PeerStore
+    Datastore --> PeerStore
+    Events --> PeerStore
+
+    %% PeerRouting
+    PeerId --> PeerRouting
+    PeerStore --> PeerRouting
+
+    %% ContentRouting
+    PeerStore --> ContentRouting
+```
+
+## Sequence Diagrams
+
+These diagrams show the interactions between the components in common scenarios. They are not exhaustive and are intended to provide a high level overview of the interactions between the components.
+
+### Dialing a Peer
+
+This illustrates an outbound connection being established to a peer.
+
+```mermaid
+%% how an outbound connection is opened when a user calls .dial(),
+%% assuming user is not connected to the PeerId for the
+%% Multiaddr that was dialed.
+%%
+%% This is
+%%
+sequenceDiagram
+    User->>+libp2p: dial a multiaddr `.dial()`
+    libp2p->>+Connection Manager: open a connection for me to MA `.openConnection()`
+    %% obfuscating the dial queue.
+    %% Connection Manager->>+Transport Manager: Choose transport to use for Multiaddr
+    Connection Manager->>+Transport Manager: Network level reach out `.dial()`
+    Transport Manager->>+Transport: Get MultiaddrConn `socket + multiaddr`
+    %% Transport->>+Transport Manager: Return MultiaddrConn `socket + multiaddr`
+    %% how the upgrade happens is transport specific, so transports directly call upgrader
+    Transport-->>+Upgrader: upgrade my connection??
+    Upgrader-->>+Upgrader: Perform upgrade (see other diagram)
+    Upgrader->>+Connection Manager: Connection (link to interface)
+    %% Connection Manager->>+Connection Manager: Connection (link to interface)
+    Connection Manager->>+User: Connection (link to interface)
+```
+
+
+### Opening a stream on a connection
+
+This illustrates a stream being opened on an existing connection that will echo a message back to the sender. This assumes that a stable connection has been established between the two peers.
+
+```mermaid
+%% pushing data over stream
+%% register stream handler, local opens a stream for proto, send data,
+%% remote receives data and sends data back
+%% local receives data
+%% stream may or may not then be closed.
+%% Local is the node sending data, Remote is other peer the conn is with
+%% Echo protocol
+sequenceDiagram
+    box Local side
+    participant Local
+    participant Connection
+    participant LocalMuxer
+    end
+    participant Stream
+    box pink Connection
+    end
+    box Remote side
+    participant Remote
+    participant RemoteMuxer
+    participant RemoteUpgrader
+    participant RemoteRegistrar
+    participant RemoteStreamHandler
+    end
+
+    Remote->>RemoteRegistrar: Register Stream Handler `libp2p.handle`
+    %% only register stream handlers when you want to listen for protocols. SENDERs do not need to listen
+    Local->>Connection: Open outbound stream
+    Connection->>LocalMuxer: Open stream
+    LocalMuxer->>RemoteMuxer: Open stream
+    RemoteMuxer->>RemoteUpgrader: notify Stream created
+    Note over Connection,RemoteUpgrader: multi stream select handles protocol negotiation
+    Connection->>Local: return Stream
+    RemoteUpgrader->>RemoteRegistrar: select stream handler
+    RemoteRegistrar->>RemoteStreamHandler: handle stream
+    Note over RemoteStreamHandler,Local: Stream data flow & control is dictated by protocol, below is example of "echo"
+    activate Stream
+    Local->>Stream: send bytes "hello world"
+    Stream->>RemoteStreamHandler: receive bytes "hello world"
+    %% RemoteStreamHandler->>+RemoteStreamHandler: [echo] pipe back received bytes
+    RemoteStreamHandler->>Stream: echo bytes back to sender
+    Stream->>Local: receive echoed bytes
+    deactivate Stream
+
+```

doc/CONFIGURATION.md

@@ -44,6 +44,8 @@ libp2p is a modular networking stack. It's designed to be able to suit a variety
 
 Regardless of how you configure libp2p, the top level [API](./API.md) will always remain the same. **Note**: if some modules are not configured, like Content Routing, using those methods will throw errors.
 
+To get a high-level overview of the js-libp2p architecture, please read the [Architecture](./ARCHITECTURE.md) document.
+
 ## Modules
 
 `js-libp2p` acts as the composer for this modular p2p networking stack using libp2p compatible modules as its subsystems. For getting an instance of `js-libp2p` compliant with all types of networking requirements, it is possible to specify the following subsystems: