Update ansible inventory to work with hyperledger.fabricx:0.3.11, add diagram (hyperledger#24)

#### Type of change

- Improvement (improvement to code, performance, etc)
- Documentation update

#### Description

Sample application:

- Updates to the inventory to work with the latest ansible scripts.
- Add some clarifications and a diagram to the readme.

#### Additional details

To update:
```
cd path/to/fabric-x-ansible-collection
git pull
make install
```

Before starting the application, do `make teardown; make clean; make
setup`.

Signed-off-by: Arne Rutjes <arne123@gmail.com>

Author: arner

samples/tokens/README.md

@@ -36,6 +36,12 @@ This sample helps you get familiar with Token SDK features and serves as a start
 - Configuration for a **Fabric-X** test network.
 - Configuration for a **Fabric v3** test network.
 
+Below is a high level overview of the components and how data flows in a token transfer transaction.
+The sequence diagram later in this readme provides more details about the token transaction.
+For a specification of the Fabric-X components and their interactions, refer to the main [README.md](../../README.md).
+
+![transfer: high level](./diagrams/components.png)
+
 ## Architecture Overview
 
 From now on, we’ll refer to the issuer, endorser, and owner services collectively as nodes (not to be confused with Fabric peer nodes).
@@ -105,18 +111,18 @@ export PATH=$(pwd)/fabric-samples/bin:$PATH
 
 > [!TIP]
 > The scripts assume you have run the script from the directory of this README. If you have them somewhere else,
-> just make sure to `export FABRIC_SAMPLES=/path/to/fabric-samples"` so the scripts can start the test network.
+> just make sure to `export FABRIC_SAMPLES="/path/to/fabric-samples"` so the scripts can start the test network.
 
 ## Getting Started
 
-The sample uses Fabric-X as the default network.
-If you want to run the application on Fabric v3, just set the PLATFORM to fabric3.
-
-```bash
-export PLATFORM=fabric3
-```
-
 > [!NOTE]
+> The sample uses Fabric-X as the default network.
+> If you want to run the application on Fabric v3, just set the PLATFORM to fabric3.
+>
+> ```bash
+> export PLATFORM=fabric3
+> ```
+> 
 > When switching between platforms, always make sure to *first* (before changing the platform) clean up all artifacts:
 > ```shell
 > make teardown
@@ -131,6 +137,22 @@ Create the configurations and crypto material for the network:
 make setup
 ```
 
+This creates:
+
+- Fabric
+  - config files and identities for the orderers and committers
+  - a genesis block
+  - users that can submit or query transactions
+  - endorser identity
+- Fabric Smart Client
+  - identities for the nodes (issuer, owner1, owner2, endorser)
+- Fabric Token SDK
+  - an idemix issuer for the token accounts
+  - idemix credentials signed by this issuer
+  - cryptographic parameters and configuration for the token network (see: `go tool tokengen pp print -i conf/namespace/zkatdlognoghv1_pp.json`).
+
+The relevant crypto material is copied to the folders in the conf/* directories.
+
 ### Start the Network and Application
 
 Start the Fabric network, create the namespace, and start the application services.
@@ -156,7 +178,7 @@ They also communicate over P2P websockets as shown below:
 | -------- | ---- | --------------------------- |
 | 8080     |      | API documentation (web)     |
 | 9100     | 9101 | Issuer                      |
-| 9300     | 9301 | Endorer 1                   |
+| 9300     | 9301 | Endorser 1                  |
 | 9400     | 9401 | Endorser 2 (Fabric v3 only) |
 | 9500     | 9501 | Owner 1 (alice and bob)     |
 | 9600     | 9601 | Owner 2 (carlos and dan)    |

samples/tokens/ansible/inventory/fabric-x.yaml

@@ -22,18 +22,17 @@ all:
     node_exporter_port: 9111
     container_client: docker
   children:
-    fabric-x:
+    fabric_x:
       children:
-        fabric-x-orderers:
+        fabric_x_orderers:
           vars:
-            container_network:
-              name: fabric_test
+            container_network: fabric_test
             organization:
               name: "OrdererOrg{{ orderer_group }}"
               domain: "ordererorg{{ orderer_group }}.example.com"
               role: orderer
           children:
-            fabric-x-orderer-1:
+            fabric_x_orderer_1:
               vars:
                 orderer_group: 1
               hosts:
@@ -50,7 +49,7 @@ all:
                 orderer-assembler-1:
                   orderer_component_type: assembler
                   orderer_rpc_port: 7053
-            fabric-x-orderer-2:
+            fabric_x_orderer_2:
               vars:
                 orderer_group: 2
               hosts:
@@ -67,7 +66,7 @@ all:
                 orderer-assembler-2:
                   orderer_component_type: assembler
                   orderer_rpc_port: 7153
-            fabric-x-orderer-3:
+            fabric_x_orderer_3:
               vars:
                 orderer_group: 3
               hosts:
@@ -84,7 +83,7 @@ all:
                 orderer-assembler-3:
                   orderer_component_type: assembler
                   orderer_rpc_port: 7253
-            fabric-x-orderer-4:
+            fabric_x_orderer_4:
               vars:
                 orderer_group: 4
               hosts:
@@ -102,11 +101,10 @@ all:
                   orderer_component_type: assembler
                   orderer_rpc_port: 7353
 
-        fabric-x-committer:
+        fabric_x_committer:
           vars:
             # committer_log_level: DEBUG
-            container_network:
-              name: fabric_test
+            container_network: fabric_test
             committer_use_postgres: true
           hosts:
             committer-db:
@@ -115,7 +113,6 @@ all:
               postgres_password: sc_secret_pwd
               postgres_db: sc_db
               postgres_port: 5435
-              postgres_exporter_port: 2110
             committer-validator:
               committer_component_type: validator
               committer_rpc_port: 5100

samples/tokens/diagrams/components.png

@@ -0,0 +1,44 @@
+' Copyright IBM Corp. All Rights Reserved.
+'
+' SPDX-License-Identifier: Apache-2.0
+'
+
+@startuml
+title Token transfer data flow (alice -> dan)
+
+skinparam componentStyle rectangle
+skinparam rectangle {
+  BorderColor Black
+  FontStyle bold
+  FontSize 12
+  RoundCorner 10
+}
+skinparam package {
+  BackgroundColor #F9F9F9
+  BorderColor #999999
+  FontColor #333333
+}
+
+package "Token nodes" as Applications {
+    component "Issuer\n* token issuer" as issuer #LightBlue
+    component "Owner 1\n* alice\n* bob" as owner1 #LightBlue
+    component "Owner 2\n* carlos\n* dan" as owner2 #LightBlue
+}
+
+[Endorser] #LightBlue
+package "Fabric (x)" {
+    component Committer
+    component Orderers
+}
+
+component "CA\n*Idemix credential issuer"
+
+issuer --> owner1
+owner1 --> owner2 : 1. request identity\nshare pending tx
+owner1 -r-> Endorser : 2. token tx for endorsement
+owner1 -r-> Orderers : 3. endorsed tx
+Orderers --> Committer : 4. ordered blocks
+Committer -> owner1 : 5. committed tx
+Committer -> owner2 : 5. committed tx
+
+@enduml