From a45aad5ed7ef9d4d461b7a3bb8b00abb6a3dd003 Mon Sep 17 00:00:00 2001
From: Nick Daly <Nick.M.Daly@gmail.com>
Date: Sat, 31 May 2014 14:55:24 -0500
Subject: [PATCH] Wrote Plinth's design document.

This specs out the system and covers control flow through a user's interaction.
---
 doc/design.mdwn | 50 +++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 50 insertions(+)
 create mode 100644 doc/design.mdwn

diff --git a/doc/design.mdwn b/doc/design.mdwn
new file mode 100644
index 000000000..0c92efa43
--- /dev/null
+++ b/doc/design.mdwn
@@ -0,0 +1,50 @@
+<!-- -*- mode: markdown; mode: refill; fill-column: 80 -*- -->
+
+# Plinth's Design
+
+Struturally, Plinth is very simple.  It's nothing more than a modular system to
+hook a web UI to the command line and the underlying system.
+
+Users enable modules which turn on features on the box and run actions.  Theo
+nly data Plinth itself should store are the modules users have and haven't
+enabled.  The rest of the information that Plinth interacts with is read from
+and written to the appropriate system configuration files.
+
+The most important files in the Plinth project are the modules (in the
+`plinth/modules` directory).  Those files create web pages that present
+configuration options to the user and, when the user accepts the configuration,
+runs the relevant action scripts.
+
+In the simplest case, the user navigates to http://freedombox.lan/plinth/hello,
+which runs the `plinth/modules/hello` file and displays the output as a web
+page.  When the user hits "Submit" on the hello page's form, the hello module
+runs the `plinth/actions/hello` script, which takes the user's input, escapes
+it, removes any suspect input or dangerous options (by applying a **whitelist**
+to the user's input) and then passing the remaining, safe, options to the
+`/bin/hello` program.  The module chooses whether or not to display the output,
+and the process is complete.
+
+For example:
+
+1. User requests http://freedombox.lan/plinth/hello
+
+2. Plinth returns the response from `plint/modules/hello`.
+
+3. User submits Hello form.
+
+4. Hello module runs `plinth/actions/hello`.
+
+5. Hello action removes unsafe input.
+
+6. Hello action runs hello system binary with only safe input.
+
+7. Hello module may display output from hello binary.
+
+8. The hello configuration process is complete.
+
+In the above example, control flows in one of two ways:
+
+1. `URL -> Module -> User`, where the user hasn't performed an action.
+
+2. `URL -> Module -> Action -> Binary -> User`, where the user configures the
+system.