add: architecture and workflow (#12)

gaukas · web-flow · commit 6f5e69dbac91 · 2024-04-01T09:48:05.000-06:00
* update: move comparison.md

Signed-off-by: Gaukas Wang &lt;i@gaukas.wang&gt;

* add: WATER ring architecture and workflow

Signed-off-by: Gaukas Wang &lt;i@gaukas.wang&gt;

---------

Signed-off-by: Gaukas Wang &lt;i@gaukas.wang&gt;
diff --git a/_config.yml b/_config.yml
@@ -60,4 +60,10 @@ callouts:
     color: purple
   warning:
     title: Warning
-    color: red
+    color: red
+  
+defaults:
+  - scope:
+      path: "assets/img"
+    values:
+      image: true
diff --git a/architecture.md b/architecture.md
@@ -0,0 +1,16 @@
+---
+layout: page
+title: Architecture
+permalink: /architecture.html
+nav_order: 2
+---
+
+# Architecture
+
+<p align="center">
+  <img src="/assets/img/ring.png" alt="WATER Ring" width="512"/>
+</p>
+
+As mentioned, WATER provides a familiar network programming interface for every supported programming language, and use WebAssembly as the underlying technology to build and execute transport protocols. The architecture of WATER could be illustrated as a ring. The inner-most ring (violet) stands for the WebAssembly* Transport Module (WATM), a WebAssembly binary module which defines the transport protocol. The middle ring (blue) stands for the WATER Runtime, which consists of a set of internal APIs interfacing the WATM, and external APIs providing the said network programming interface. The outer-most ring (grey) stands for the integrating application, which could be written in any programming language with a WATER Runtime library available.
+
+*That's why it is violet. 
diff --git a/assets/img/flows.png b/assets/img/flows.png
diff --git a/assets/img/ring.png b/assets/img/ring.png
diff --git a/comparisons.md b/comparisons.md
@@ -2,6 +2,7 @@
 layout: page
 title: Comparisons
 permalink: /comparisons.html
+nav_order: 1
 ---
 
 # Comparisons
diff --git a/index.md b/index.md
@@ -3,6 +3,8 @@
 # To modify the layout, see https://jekyllrb.com/docs/themes/#overriding-theme-defaults
 
 layout: home
+title: WATER
+nav_order: 0
 ---
 
 -- **WATER** -- <br> **W**eb**A**ssembly **T**ransport **E**xecutables **R**untime
@@ -11,11 +13,24 @@ layout: home
 {: .text-grey-dk-300}
 {: .text-center}
 
+WATER is all about a new way to **build**, **deploy**, and **execute** new and updated pluggable transports. With WebAssembly, transport protocols could be written in any language that compiles to WebAssembly, distributed via multiple channels, and run in a secure, sandboxed environment in a tool written in a different programming language on a wide range of platforms.
 
-This site hosts the online documentation for Project WATER: [refraction-networking/water](https://github.com/refraction-networking/water) and [refraction-networking/water-rs](https://github.com/refraction-networking/water-rs). 
+## Pluggable Transports and Censorship Circumvention
 
-## WATER
+Pluggable Transports provides a flexible and modular way for censorship circumvention tools to integrate new transport protocols and/or update existing ones. Multiple popular circumvention tools, such as Tor, Psiphon, and Lantern, have adopted the pluggable transport design. However, the flexibility of pluggable transports is still limited. For example, the host application and the transport protocol must be written in the same programming language, and the transport protocol must be compiled into the host application, which makes deploying new transport protocols and updating existing ones not so efficient. 
 
-WATER stands for WebAssembly Transport Executables Runtime, a novel approach to building pluggable network transports using WebAssembly. Comparing to other designs, WATER in general provides better flexibility and security, more consistent development and deployment experience, and better performance. 
+### A more pluggable transport
 
-A matrix comparing WATER with other pluggable transport designs is available [here](comparisons.html#water-vs-other-pluggable-transport-designs).
+WATER provides much more flexibility compared to existing pluggable transport designs. A matrix comparing WATER with other pluggable transport design approaches is available [here](comparisons.html#water-vs-other-pluggable-transport-designs).
+
+## How does WATER work?
+
+The ultimate goal of WATER is to provide familiar network programming interfaces in multiple different programming languages which are backed by the WebAssembly-based pluggable transport modules. 
+
+<p align="center">
+  <img src="/assets/img/flows.png" alt="WATER Workflow" width="512"/>
+</p>
+
+With a WebAssembly Transport Module (WATM), WATER can be configured for either client-side or server-side applications as it provides both dialer and listener implementations. It is worth noting that a WATM may be written in a way to support either client-side or server-side applications, or both. Please consult the provider of the WATM for more information.
+
+The architecture of WATER, especially how WATER is built, is available [here](architecture.html).
diff --git a/runtime/runtime.md b/runtime/runtime.md
@@ -1,7 +1,7 @@
 ---
 layout: default
 title: Runtime Library
-nav_order: 1
+nav_order: 3
 has_children: true
 permalink: /runtime.html
 ---
diff --git a/transport-module/transport-module.md b/transport-module/transport-module.md
@@ -1,7 +1,7 @@
 ---
 layout: default
 title: WebAssembly Transport Module
-nav_order: 2
+nav_order: 4
 has_children: true
 permalink: /transport-module.html
 ---
