explain how openkubsd should work internally

documentation/interface.md

@@ -0,0 +1,44 @@
+# About this document
+
+This document explains how OpenKuBSD works internally.
+
+It seems a daemon receiving instructions through a socket to interact with it would be practical to sequentially run the commands, and avoid race conditions.
+
+VMs manipulation should be done using transactions, but if something is wrong (like a crash, power outage), it should be easy to delete the transaction
+
+Identified transactions:
+
+- creating a new VM
+- creating a template
+- starting a VM
+- starting a VM with a program
+- stopping a VM
+- starting a disposable
+- stopping a disposable
+
+# Orchestration
+
+If an user quickly runs the following commands in that order:
+
+1. start VM foobar
+2. start VM foobar firefox
+3. start disposable
+4. start VM foobar2
+5. stop VM alreadystarted
+
+What should happen:
+
+1. start VM foobar, and wait until openkubsd can ssh into it to run a command, all other commands are on stand by
+2. VM foobar is already started, run firefox with ssh
+3. start a disposable VM, wait until openkubsd can ssh into it
+4. start the VM foobar, wait until openkubsd can ssh into it
+5. stop the VM alreadystarted, wait until vmctl reports it's finished
+
+# Problem handling
+
+If a problem occurs during a transaction:
+
+- Report it in a log file
+- Let the daemon stop
+
+Each kind of transaction should be documented to explain how to recover for an issue during it.