Add more documentation, more diagrams (#130)

* add diagram of NetKernel/Proto

* update workflow file

* add file into lfs

* add more diagrams and network architecture

.gitattributes

@@ -1 +1,2 @@
 *.info filter=lfs diff=lfs merge=lfs -text
+*.png filter=lfs diff=lfs merge=lfs -text

.github/workflows/deploy.yml

@@ -24,7 +24,6 @@ jobs:
       - uses: Avarok-Cybersecurity/gh-actions-deps@master
       - name: Compile documentation
         run: cargo make docs
-
       - name: Deploy documentation
         if: success()
         uses: crazy-max/[email protected]

Makefile.toml

@@ -14,9 +14,19 @@ args = ["clippy"]
 command = "cargo"
 args = ["fmt", "--all"]
 
+[tasks.git_lfs_fetch]
+command = "git"
+args = ["lfs", "fetch"]
+
+[tasks.git_lfs]
+command = "git"
+args = ["lfs", "pull"]
+dependencies = ["git_lfs_fetch"]
+
 [tasks.docs-html]
 command = "cargo"
-args = ["doc", "--package", "citadel_sdk", "--features", "webrtc", "--no-deps", "--release"]
+args = ["doc", "--package", "citadel_sdk", "--features=webrtc,doc-images", "--no-deps", "--release"]
+dependencies = ["git_lfs"]
 
 [tasks.pr]
 dependencies = ["fmt", "clippy"]

citadel_sdk/Cargo.toml

@@ -28,8 +28,11 @@ localhost-testing = ["citadel_proto/localhost-testing", "tracing", "citadel_logg
 localhost-testing-assert-no-proxy = ["citadel_proto/localhost-testing-assert-no-proxy"]
 localhost-testing-loopback-only = ["citadel_proto/localhost-testing-loopback-only"]
 
+doc-images = ["embed-doc-image"]
+
 [dependencies]
 citadel_proto = { version = "0.1.0", path = "../citadel_proto", default-features = false }
+embed-doc-image = { version = "0.1.4", optional = true }
 tokio = { version = "1.24", default-features = false }
 futures = { version = "0.3.25", default-features = false }
 parking_lot = { default-features = false, version = "0.12.1" }

citadel_sdk/src/lib.rs

@@ -45,7 +45,46 @@
 //! the ciphertext before using the AES key. Since every 32 bytes of input into the Kyber encryption scheme produces over a 1KB output ciphertext, and, each quasi-OTP is 32 bytes long,
 //! the size of each packet is increased at a minimum constant value, helping keep packet sizes minimal and security very high.
 //!
+//! # Network Architecture
+#![cfg_attr(
+    feature = "doc-images",
+    doc = ::embed_doc_image::embed_image!(
+    "network_direct_p2p",
+    "../resources/network_direct_p2p.png"
+    )
+)]
+//! ![Network Architecture w/ direct P2P][network_direct_p2p]
+//! Each network has a central node that peers may connect to. This central node helps facilitate P2P connections, and, can itself serve
+//! as a peer on a network if the program implementation on the central server so chooses.
+//!
+//! The peers Alice and Bob can only connect to each other after they use the central server to **register** to each other. Once registered, the two peers
+//! may begin attempting connecting to each other via NAT traversal. Each peer begins NAT traversal by attempting to determine what type of NAT
+//! they're each behind by communicating to 3 different STUN servers to find a predictable pattern in their internal/external socket mappings.
+//! If at least one has a predictable pattern, a direct P2P connection bypassing the central server may be facilitated.
+//!
+//! If, however, both Alice and Bob do not have predictable internal/external socket mappings (e.g., both are behind symmetric NATs), then, both will use
+//! their central server to relay their packets to each other using endpoint to endpoint encryption, preventing the central server from
+//! decrypting the packets.
+//!
+#![cfg_attr(
+    feature = "doc-images",
+    doc = ::embed_doc_image::embed_image!(
+    "network_relay_p2p",
+    "../resources/network_relay_p2p.png"
+    )
+)]
+//! ![Network Architecture w/ relay P2P][network_relay_p2p]
+//!
+//!
 //! # Executor Architecture: The [`NetKernel`]
+#![cfg_attr(
+    feature = "doc-images",
+    doc = ::embed_doc_image::embed_image!(
+        "proto_kernel_iface",
+        "../resources/proto_kernel_iface.png"
+    )
+)]
+//! ![Protocol/Executor/NetKernel Architecture][proto_kernel_iface]
 //! Any node in the network may act as **both** a server and a client/peer (except for when [`NodeType::Peer`] or the default node type is specified). Since multiple parallel connections may exist, handling events is necessary. When the lower-level protocol produces events,
 //! they are sent to the [`NetKernel`]. The [`NetKernel`] is where your application logic must be written.
 //!