Documentation on goal and efficacy

In this changeset, I wrote a documentation detailing how one can
implement a new goal plugin. I also mention to define the efficacy
specification for a given goal.

Partially Implements: blueprint efficacy-indicator

Change-Id: Iba267ae312f248b49d4600504f11678cdc225622

doc/source/architecture.rst

@@ -150,12 +150,14 @@ This database stores all the Watcher domain objects which can be requested
 by the :ref:`Watcher API <archi_watcher_api_definition>` or the
 :ref:`Watcher CLI <archi_watcher_cli_definition>`:
 
+-  :ref:`Goals <goal_definition>`
+-  :ref:`Strategies <strategy_definition>`
 -  :ref:`Audit templates <audit_template_definition>`
 -  :ref:`Audits <audit_definition>`
 -  :ref:`Action plans <action_plan_definition>`
+-  :ref:`Efficacy indicators <efficacy_indicator_definition>` via the Action
+   Plan API.
 -  :ref:`Actions <action_definition>`
--  :ref:`Goals <goal_definition>`
--  :ref:`Strategies <strategy_definition>`
 
 The Watcher domain being here "*optimization of some resources provided by an
 OpenStack system*".
@@ -210,10 +212,10 @@ view (Goals, Audits, Action Plans, ...):
 .. image:: ./images/functional_data_model.svg
    :width: 100%
 
-Here below is a class diagram representing the main objects in Watcher from a
+Here below is a diagram representing the main objects in Watcher from a
 database perspective:
 
-.. image:: ./images/watcher_class_diagram.png
+.. image:: ./images/watcher_db_schema_diagram.png
    :width: 100%
 
 
@@ -297,9 +299,11 @@ This method finds an appropriate scheduling of
 :ref:`Actions <action_definition>` taking into account some scheduling rules
 (such as priorities between actions).
 It generates a new :ref:`Action Plan <action_plan_definition>` with status
-**RECOMMENDED** and saves it into the
-:ref:`Watcher Database <watcher_database_definition>`. The saved action plan is
-now a scheduled flow of actions.
+**RECOMMENDED** and saves it into the:ref:`Watcher Database
+<watcher_database_definition>`. The saved action plan is now a scheduled flow
+of actions to which a global efficacy is associated alongside a number of
+:ref:`Efficacy Indicators <efficacy_indicator_definition>` as specified by the
+related :ref:`goal <goal_definition>`.
 
 If every step executed successfully, the
 :ref:`Watcher Decision Engine <watcher_decision_engine_definition>` updates
@@ -308,6 +312,11 @@ the current status of the Audit to **SUCCEEDED** in the
 on the bus to inform other components that the :ref:`Audit <audit_definition>`
 was successful.
 
+This internal workflow the Decision Engine follows to conduct an audit can be
+seen in the sequence diagram here below:
+
+.. image:: ./images/sequence_from_audit_execution_to_actionplan_creation.png
+   :width: 100%
 
 .. _sequence_diagrams_launch_action_plan: