diff --git a/doc/source/design.rst b/doc/source/design.rst
new file mode 100644
index 0000000000000000000000000000000000000000..574edbf630d53b0541251535d9e5208d7ba62ddf
--- /dev/null
+++ b/doc/source/design.rst
@@ -0,0 +1,37 @@
+Design
+------
+
+The application is based on three entities, as written in the introduction:
+
+- Multi Criteria Optimizer (MCO)
+- DataSources
+- Key Performance Indicator (KPI) Calculators
+
+There are a few core assumptions about each of these entities:
+
+- The MCO design must honor the execution model of Dakota, that is, spawn
+  a secondary process that performs a computation starting from a given set
+  of input parameters, and produces a resulting set of output parameters.
+  In our code, this secondary process is ``force_bdss`` itself, invoked with
+  the option ``--evaluate``.
+- The DataSources are entities that, given the MCO parameters, provide some
+  numerical result. This result is passed to the KPI calculators.
+- The KPI calculators now compute the final KPIs that are then returned to
+  the invoker MCO.
+
+
+The result can be represented with the following data flow
+
+
+1. The MCO produces and, by means of a Communicator, injects...
+2. ...DataSourceParameters, that are passed to...
+3. one or more DataSources, each performing some computation or data
+   extraction and produces
+4. DataSourceResult, one per DataSource, are then passed (together with the
+   DataSourceParameters) to...
+5. one or more KPICalculators, which perform final data evaluation on the
+   obtained values, eac producing KPIResult...
+6. Whose values are then returned to the MCO via the Communicator.
+
+The resulting pipeline is therefore just two layers (DataSources, then
+KPICalculators).
diff --git a/doc/source/index.rst b/doc/source/index.rst
index 2c604ad0e31baae9effe30724964b4e18244c5e1..467b4ca39d68e477b4a57f4f7f20188f44b4a1e5 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -10,6 +10,8 @@ User Manual
    :maxdepth: 1
 
    Introduction <introduction>
+   Design <design>
+   Plugin development <plugin_development>
 
 
 API Reference
diff --git a/doc/source/introduction.rst b/doc/source/introduction.rst
index 1914d9dc1f45c5e83ba16f087f858eecc2414463..70d16fe0d02d1acd48902d2ba7ae5ff837b532a9 100644
--- a/doc/source/introduction.rst
+++ b/doc/source/introduction.rst
@@ -1,2 +1,23 @@
 Introduction
 ------------
+
+The Business Decision System is the CLI support for the evaluation of
+Pareto front computations. It is a single executable ``force_bdss`` that
+interprets a workflow specification file, normally generated via the GUI
+workflow manager.
+
+By itself, the executable and the code implementing it provides no
+functionality. All functionality comes from external plugins, extending the
+API to provide new entities, specifically:
+
+- Multi Criteria Optimizer (MCO)
+- DataSources
+- Key Performance Indicator (KPI) Calculators
+
+Plugin support requires compliancy to the Force BDSS api for plugins.
+Extensions are registered via setuptools entry points.
+
+Execution of the force bdss executable is simple. Invoke with::
+
+    force_bdss workflow.json
+
diff --git a/doc/source/plugin_development.rst b/doc/source/plugin_development.rst
new file mode 100644
index 0000000000000000000000000000000000000000..231161baa9bca63d69ca55868abd8f40805e4173
--- /dev/null
+++ b/doc/source/plugin_development.rst
@@ -0,0 +1,25 @@
+Plugin Development
+------------------
+
+A single Plugin can provide one or more of the pluggable entities
+described elsewhere (MCO/KPICalculators/DataSources). Multiple plugins can
+be installed to provide a broad range of functionalities.
+
+Plugins must return "Bundles". Each Bundle acts as a Factory, providing
+factory methods for one of the above pluggable entities and its associated
+classes.
+
+To implement a new plugin, you must
+
+- define the entity you want to extend (e.g. ``MyOwnDataSource``) as a derived
+  class of the appropriate class (e.g. BaseDataSource), and reimplement
+  the appropriate methods.
+- Define the model that this DataSource needs, by extending
+  ``BaseDataSourceModel`` and adding, with traits, the appropriate data that
+  are required by your data source to perform its task.
+- Define the Bundle, by reimplementing BaseDataSourceBundle and reimplementing
+  its ``create_*`` methods to return the above entities.
+- Define a ``Plugin`` by reimplementing ``BaseExtensionPlugin`` and
+  reimplementing its initialization defaults methods to return your bundle.
+- add the plugin class in the setup.py entry_point, under the namespace
+  ``force.bdss.extensions``