Start working on some design principles and concepts
very much work in progress, but better to get some of this
stuff saved before it gets lost.
diff --git a/docs/source/_static/images/diagram-general-principles.png b/docs/source/_static/images/diagram-general-principles.png
new file mode 100644
index 0000000..2e75ebf
--- /dev/null
+++ b/docs/source/_static/images/diagram-general-principles.png
Binary files differ
diff --git a/docs/source/_static/images/diagram-node-server-relation.png b/docs/source/_static/images/diagram-node-server-relation.png
new file mode 100644
index 0000000..a86d9af
--- /dev/null
+++ b/docs/source/_static/images/diagram-node-server-relation.png
Binary files differ
diff --git a/docs/source/_static/images/diagram-node-server-verification.png b/docs/source/_static/images/diagram-node-server-verification.png
new file mode 100644
index 0000000..dd8491a
--- /dev/null
+++ b/docs/source/_static/images/diagram-node-server-verification.png
Binary files differ
diff --git a/docs/source/design-general.rst b/docs/source/design-general.rst
new file mode 100644
index 0000000..1250b57
--- /dev/null
+++ b/docs/source/design-general.rst
@@ -0,0 +1,77 @@
+General Design Principles
+=========================
+
+.. toctree::
+ :maxdepth: 2
+ :caption: Contents:
+
+
+****************************
+Client/Server breakdown
+****************************
+
+(Work in progress!)
+This section shows the basic three applications of Warble.
+
+.. image:: _static/images/diagram-general-principles.png
+ :height: 80pc
+ :alt: diagram of general design principles
+ :align: center
+
+
+***********************************
+Agent/Node and Server data flows
+***********************************
+
+(Work in progress!)
+This section shows the various components inside the Warble
+Server and how they interact. More to come :)
+
+
+.. image:: _static/images/diagram-node-server-relation.png
+ :height: 80pc
+ :alt: diagram of general node/server communication
+ :align: center
+
+
+***********************************
+Client and Server communication
+***********************************
+
+Agents and Nodes (referred to in this segment as `clients`) communicate
+with the Warble Server using a three-stage protocol:
+
+1. First time a client is started, it generates an async key pair for
+ encryption and subsequent verification/signing. The private key is
+ stored on-disk on the client host, and the public key is sent to the
+ node registry on the master, along with a request to add the client to
+ the node registry as a verified client. The Server registers a unique
+ API key for each client, and binds the public key to this API key.
+
+2. Once verified, a client can request test targets and parameters from
+ the node registry at the Server. This data is sent back to the client
+ in encrypted form, using the previously sent public key. Thus, only
+ a verified client can get test targets, and only the client should be
+ able to decrypt the payload and get clear-text target data.
+
+
+3. Once a client has completed a test (or a batch of tests), the result
+ is sent to the server and signed using the private key. Thus, the
+ server can use the public key to verify that the test results came from
+ the client.
+
+Once test data has been successfully verified and stored on the server,
+both the alerting system and the visualization system can retrieve and
+process it, ensuring that what they (and you) see is genuine.
+
+.. figure:: _static/images/diagram-node-server-verification.png
+ :height: 80pc
+ :alt: diagram of general node/server comms verification
+ :align: center
+
+ This figure shows the communication channels as outlined in the
+ above paragraph.
+
+
+################
+Server Component
diff --git a/docs/source/index.rst b/docs/source/index.rst
index abed454..2375041 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -7,6 +7,7 @@
:caption: Contents:
setup
+ design-general
Indices and tables
