docs: add more orchestrator documentation (#346)

CHANGELOG.md

@@ -9,6 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Add user management doc ([#345](https://github.com/Substra/substra-documentation/pull/345))
 - Add link to python libraries documentation in Components page ([#347](https://github.com/Substra/substra-documentation/pull/347))
+- Add more orchestrator documentation ([#346](https://github.com/Substra/substra-documentation/pull/346))
 - Deactivate Binder ([#340](https://github.com/Substra/substra-documentation/pull/340))
 - Reorganise documentation according to [diataxis](https://diataxis.fr/) approach ([#330](https://github.com/Substra/substra-documentation/pull/330))
 - Added section about channels in the main concepts ([#344](https://github.com/Substra/substra-documentation/pull/344))

docs/source/documentation/orchestrator/index.rst

@@ -2,9 +2,31 @@
 Orchestrator
 ************
 
-The orchestrator has two functions.
-Its first role is to handle the ledger containing all known assets.
-It also dispatches tasks to the relevant :term:`Organizations<Organization>`.
+Performing a Federated Learning experiment implies a lot of different compute tasks: local training, aggregation, testing on different organizations, etc. The role of the orchestrator is to distribute ML tasks among organizations, while ensuring complete traceability of operations.
+
+The orchestrator registers the status of tasks; when a task is done (status ``Done``), it evaluates if some remaining tasks (status ``Waiting``) are now unblocked, and if it's the case, the status of those tasks is changed to ``To do``. The new status is sent to all the backends, who store the new tasks ``To do`` in the task queue (Celery). Then, the task queue will assign the task to one of the workers (if multiple) and handle retries if needed.
+
+In case of failure, it will store failure reports and  change the status of the faulty task to ``Failed``.
+In case of manual cancellation, it will change the status of the  the tasks to `Cancelled` on different backends.
+
+
+Centralized vs. decentralized orchestration
+===========================================
+
+Substra offers two types of orchestration: **distributed** and **centralized**.
+
+.. image:: /static/schemes/distributed-vs-centralized-orc.svg
+
+
+The distributed orchestration is based on a private blockchain using Hyperledger Fabric, while the centralized orchestration is hosted by a central Postgres database.
+
+In both cases, the orchestration stores only non-sensitive metadata of the Substra assets, making it possible to verify the integrity of the assets and ensures that the permissions on the assets are respected.
+
+Distributed orchestration enables trustless verification of the integrity of assets (functions, model, data), but it requires connections between organizations, and introduces a network overhead. It's not possible to upgrade a Substra network when using distributed orchestration.
+
+On the other hand, centralized orchestration requires trust in the central server, but it is faster and easier to deploy and maintain.
+
+As long as you trust whomever is operating the orchestrator DB not to tamper with it, both modes offer the same level of guarantees. The decentralized mode has nice theoretical guarantees, but the network overhead is very significant, and has a lot of operational drawbacks. That is why, the vast majority (if not all) of the current Substra deployments are using the centralized orchestration system as it is easier to operate and faster. However, the distributed orchestration is still maintained.
 
 .. _orc_kubernetes_pods: