Add draft ADR for adopting a component-based architecture.

This ADR provides an explicit write-up of how the UI is structured and
describes some changes we can make to the client to make this structure
more obvious and eliminate inconsistencies.

docs/arch/adr-001.md

+ADR 1: Component architecture for sidebar application
+=====================================================
+
+Context
+-------
+
+Historically front-end web frameworks, including Angular 1.x, used a variety of
+MVC-based patterns for structuring the user interface part of an application
+, which of course is much of the code for a web app.
+
+More recently (especially since React in 2013), web frameworks have generally
+moved to a simpler model where an application is structured as a tree of
+components with several key properties:
+
+ * Each component's internals are hidden from other components.
+ * Data is explicitly passed from one component to another and in one direction.
+ * Components have an explicitly declared API.
+ * Communication from child to parent happens via callback inputs.
+ * Components have a standard set of lifecycle hooks for creation, input changes
+   and destruction.
+
+A further pattern that emerged on top of this was to split components into those
+which purely reflect their inputs ("presentational" components) and those which
+are connected to services and state in the application ("container" or
+"connected" components).
+
+This pattern made it easier to reason about, re-use and change pieces of the
+application in isolation, as well as enabling important optimizations and
+simpler framework implementations.
+
+In Angular JS prior to v1.5, this pattern could be achieved by using a
+combination of features (element directives, isolate scope, bind-to-controller,
+controllerAs) and all of our new UI components written during 2016 followed this
+pattern. However, it isn't that obvious until you know the codebase well that
+this is the way the UI is structured.
+
+Angular JS 1.5x introduced [explicit
+support](https://docs.angularjs.org/guide/component) for this architecture via
+`.component()`.
+
+Decision
+--------
+
+We will convert all element directives in `src/sidebar/directive` to components
+and move them to `src/sidebar/components`. This change will be simple in most
+cases and will require some moderate refactoring for others.
+
+The top-level of the UI which consists of a mix of router, controller
+and templates unlike the rest of the UI will also be converted to this pattern.
+
+Status
+------
+
+In discussion
+
+Consequences
+------------
+
+In the short term, this change should improve the consistency of how UI
+components are defined and how they communicate with one another. It should also
+make it easier to understand and refactor parts of the client in isolation. It
+is hoped this will also make it easier for newcomers to understand how the UI is
+structured and reduce the number of concepts that they need to grok.
+
+In the medium term, this brings the architecture of the client more into
+alignment with how it would be structured in other frameworks and gives us the
+opportunity to incrementally migrate to a more actively developed (and
+potentially smaller, faster, simpler) library for building our UI in future.
+
+Presentational components can be potentially be extracted into their own
+packages for re-use in other parts of Hypothesis, though this is not an active
+priority.

docs/arch/index.md

+Architecture decision records
+=============================
+
+Here you will find documents which describe significant architectural decisions
+made or proposed when developing the Hypothesis client. We record these in
+order to provide a reference for the history, motivation, and rationale for past
+decisions.
+
+See [the
+introduction in the "h" repository](https://github.com/hypothesis/h/blob/master/docs/arch/index.rst)
+for more details.