Flesh out new design

DESIGN.md

@@ -1,26 +1,46 @@
 # design
 
-## inputs
+## Overview
 
-What things the user will be giving us from the application repository side of
-things and therefore what we'll need to pipe into the provisioning and
-deployment process.
+The end-user will create an application repository which will contain a number
+of files which match the [autonomic dokku packaging format](https://git.autonomic.zone/autonomic-cooperative/organising/wiki/dokku-packaging-format)
+and will then create a dokku git remote and push to it. On the Dokku server
+side, this plugin, `ansible-dokku-deploy`, will intercept the dokku deployment
+process via the plugin interface and run a number of steps based on the standard
+dokku [plugin triggers](https://github.com/dokku/dokku/blob/master/docs/development/plugin-triggers.md).
 
-1. env vars to be `dokku_config` loaded
-1. persistence layer docker volume mounts
-1. application layer http port to be mapped on host layer
-1. nginx.conf.d customations
+The idea is that the end-user will only need to specify a few configuration
+details like the listening port and some application specific details like
+which database to use and so on and then the plugin will take care to provision
+and deploy end-to-end the application with port mappings, TLS certificates, DNS
+entries, databases, automated backups and monitoring.
 
-## post-extract
+This plugin will use Ansible to handle the provisioning and deployment process
+because the Dokku maintainers are actively developing an Ansible [library](https://github.com/dokku/ansible-dokku/)
+for this purpose and reduces maintenance burden of interacting with Dokku via
+the command-line which can be a bit tricky to script.
+
+The workings of Ansible should be completely unknown to the end-user **unless**
+they need to arrange some custom deployment steps beyond the standard ones we
+define. That can unfortunately often be the case with complicated applications
+like Gitea which requires the host system to pass SSH connections through into
+the container **but** at least this plugin has shown that it can allow for such
+flexibility. So, advanced application packagers can leverage Ansible if they
+need it and for simple applications or pre-packaged application, the work will
+already be done.
+
+## Triggers
+
+### post-extract
 
 1. Create a /var/lib/dokku/data/ansible/\$APP folder
 1. Copy over nginx.conf.d folder
 1. Copy over vault folder and and env.yml file
 
-## pre-deploy
+### pre-deploy
 
 TODO.
 
-## post-deploy
+### post-deploy
 
 TODO.