 ;; -- lookup and call -----------------------------------------------------------------------------
 
 (defn- handle
-  "Look up the handler for the given event, then call it, passing in 2 parameters."
+  "Given an event vector, look up the right handler, then call it.
+  By default, handlers are not assumed to be pure. They are called with
+  two paramters:
+  - the `app-db` atom and
+  - the event vector
+  The handler is assumed to side-effect on the atom, the return value is ignored.
+   To write handlers that are pure functions, use the \"pure\" middleware at handler
+   registration time."
   [event-v]
   (let [event-id    (first-in-vector event-v)
         handler-fn  (get @id->fn event-id)]


;; -- router loop ---------------------------------------------------------------------------------
;;
;; In a loop, read events from the dispatch channel, and route them
;; to the right handler.
;;
;; Because handlers occupy the CPU, before each event is handled, hand

;; -- The Event Conveyor Belt  --------------------------------------------------------------------
;;
;; Moves events from "dispatch" to the router loop.
;; Allows for the aysnc handling of events.
;;
(def ^:private event-chan (chan))    ;; TODO: how big should we make the buffer?

