Section on instances

1 files changed, 27 insertions, 0 deletions

diff --git a/php/doc/tutorial.texi b/php/doc/tutorial.texi
index 3b2a341..61a95e1 100644
--- a/php/doc/tutorial.texi
+++ b/php/doc/tutorial.texi
@@ -502,6 +502,7 @@ transaction IDs paid by the wire transfer:
 @end smallexample
 
 
+@node History
 @section Listing all transactions
 
 In order to track transactions, transaction IDs are needed as input.
@@ -539,6 +540,10 @@ See below both parts:
 @verbatiminclude ../history.js
 @end smallexample
 
+Please note that because of the ``instances'' mechanism, and the use of the
+default backend, the list of transactions may include entries related to other
+frontends, see @ref{Instances}.
+
 @node Advanced topics
 @chapter Advanced topics
 
@@ -939,6 +944,28 @@ the payment as "payed".  Finally, the wallet points again the browser
 to the fulfillment URL which now delivers the claimed product to the
 customer.
 
+@node Instances
+@section Instances
+@cindex instances
+
+Taler's design allows a single backend to manage multiple frontends.
+In other words, we might have multiple shops relying on the same backend.
+As of terminology, we call @emph{instance} any of the frontends accounted
+by the same backend.
+
+The backend's RESTful API allows frontends to specify which instance they are.
+However, this specification is optional, and a ``default'' instance will be
+used whenever the frontend does not specify one.
+
+Please note that in this stage of development, the backend's REST call @code{/history}
+returns records for @emph{any} instance.  The rationale behind is to allow grouping
+``public'' business entities under the same backend.
+
+This way, a single frontend can expose multiple donation buttons for multiple
+receivers, and still operate against one backend. So in this scenario, there is no
+harm if the operator of instance `a' sees history entries related to instance `b'.
+
+See @code{https://donations.demo.taler.net/}, which uses this functionality.
 
 
 @c **********************************************************