BE-679 Create online documentation

* updated db services, and data model diagram * added logs images, sync, some updates * added diagrams, db description, etc Signed-off-by: nfrunza <nfrunza@gmail.com> Change-Id: I684f688a8d4b470697160f8880967ac3e9be6491
hyperledger-labs · Nov 8, 2019 · 48713ae · 48713ae
1 parent bfbf572
commit 48713ae
Show file tree

Hide file tree

Showing 56 changed files with 447 additions and 161 deletions.
diff --git a/docs/project_architecture/README.md b/docs/project_architecture/README.md
diff --git a/docs/project_functionalities/README.md b/docs/project_functionalities/README.md
diff --git a/docs/source/_static/css/styles.css b/docs/source/_static/css/styles.css
@@ -8,7 +8,8 @@ input[type='checkbox'] {
 	margin: 0px;
 	transition: transform 0.25s ease;
 	cursor: zoom-in;
-	overflow: auto;
+	overflow-y: auto;
+	overflow-x: auto;
 	display: block;
 }
 

diff --git a/docs/source/_static/images/db_model_diagram.png b/docs/source/_static/images/db_model_diagram.png
diff --git a/docs/source/_static/images/db_service_diagram.png b/docs/source/_static/images/db_service_diagram.png
diff --git a/docs/source/_static/images/diagram_client_app_components.png b/docs/source/_static/images/diagram_client_app_components.png
diff --git a/docs/source/_static/images/diagram_explorer_js.png b/docs/source/_static/images/diagram_explorer_js.png
diff --git a/docs/source/_static/images/diagram_gateway_class.png b/docs/source/_static/images/diagram_gateway_class.png
diff --git a/docs/source/_static/images/diagram_main_js.png b/docs/source/_static/images/diagram_main_js.png
diff --git a/docs/source/_static/images/diagram_persistence_package.png b/docs/source/_static/images/diagram_persistence_package.png
diff --git a/docs/source/_static/images/diagram_routes.png b/docs/source/_static/images/diagram_routes.png
diff --git a/docs/source/_static/images/diagram_sync_js.png b/docs/source/_static/images/diagram_sync_js.png
diff --git a/docs/source/_static/images/diagram_sync_package.png b/docs/source/_static/images/diagram_sync_package.png
diff --git a/docs/source/_static/images/diagram_synchronizer_js.png b/docs/source/_static/images/diagram_synchronizer_js.png
diff --git a/docs/source/_static/images/hl_block_filter.png b/docs/source/_static/images/hl_block_filter.png
diff --git a/docs/source/_static/images/hl_block_list.png b/docs/source/_static/images/hl_block_list.png
diff --git a/docs/source/_static/images/hl_chaincodes.png b/docs/source/_static/images/hl_chaincodes.png
diff --git a/docs/source/_static/images/hl_dark_theme.png b/docs/source/_static/images/hl_dark_theme.png
diff --git a/docs/source/_static/images/hl_dashboard.png b/docs/source/_static/images/hl_dashboard.png
diff --git a/docs/source/_static/images/hl_sync_diagram.png b/docs/source/_static/images/hl_sync_diagram.png
diff --git a/docs/source/_static/images/hl_tx_details.png b/docs/source/_static/images/hl_tx_details.png
diff --git a/docs/source/_static/images/host_sync.png b/docs/source/_static/images/host_sync.png
diff --git a/docs/source/_static/images/local_sync.png b/docs/source/_static/images/local_sync.png
diff --git a/docs/source/_static/images/logs_app.png b/docs/source/_static/images/logs_app.png
diff --git a/docs/source/_static/images/logs_console.png b/docs/source/_static/images/logs_console.png
diff --git a/docs/source/_static/images/logs_db.png b/docs/source/_static/images/logs_db.png
diff --git a/docs/source/_static/images/logs_subdirs.png b/docs/source/_static/images/logs_subdirs.png
diff --git a/docs/source/architecture/backend.rst b/docs/source/architecture/backend.rst
@@ -26,13 +26,13 @@ Main components of the HLExplorer back end can be listed as:
 .. toctree::
    :maxdepth: 1
 
+
+   webserver
    restapi
    gateway
    dbservices
-   metrics
    synchronizer
    websockets
-   configuration
    logs
 
 

diff --git a/docs/source/architecture/configuration.rst b/docs/source/architecture/configuration.rst
diff --git a/docs/source/architecture/databaselayer.html b/docs/source/architecture/databaselayer.html
@@ -0,0 +1,21 @@
+<!-- SPDX-License-Identifier: Apache-2.0 -->
+<!DOCTYPE html>
+<html>
+
+<head>
+	<meta name="viewport" content="width=device-width, initial-scale=1">
+	<link rel="stylesheet" href="../_static/css/styles.css">
+</head>
+
+<body>
+	<div class="container">
+		<input type="checkbox" id="hl_swagger_home">
+		<label for="hl_swagger_home">
+			<img src="../_static/images/db_model_diagram.png">
+		</label>
+	</div>
+
+	<br>
+</body>
+
+</html>
diff --git a/docs/source/architecture/databaselayer.rst b/docs/source/architecture/databaselayer.rst
@@ -3,11 +3,30 @@
 
 
 Database Layer
-===========================================
+==============
 
+Hyperledger Explorer uses `PostgreSQL <https://www.postgresql.org/>`__ database. The information about blocks,
+transactions, channels etc will be stored in this database. This is a mature database
+for real-time web applications as the updates will be retrieved from database instead of
+the application polling data from the Hyperledger Fabric network.
 
 
-.. TODO
+The following diagram shows a high level view of the Hyperledger Explorer data model.
+
+.. raw:: html
+     :file: ./databaselayer.html
+
+
+.. note::
+
+   Please note, the connecting lines are just for info purposes to illustrate the relation, there are no constraints defined in the current database.
+
+Physical schema
+~~~~~~~~~~~~~~~~~~
+
+The script `explorerpg.sql <https://github.com/hyperledger/blockchain-explorer/blob/master/app/persistence/fabric/postgreSQL/db/explorerpg.sql>`__ describes
+Hyperledger Explorer database. Creation of the database is a mandatory step and it is done by running the script `createdb.sh <https://github.com/hyperledger/blockchain-explorer/blob/master/app/persistence/fabric/postgreSQL/db/createdb.sh>`__,
+detailed steps and instructions are provided in the `README.md <https://github.com/hyperledger/blockchain-explorer/tree/master#Database-Setup>`__ file.
 
 
 

diff --git a/docs/source/architecture/dbconfig.rst b/docs/source/architecture/dbconfig.rst
diff --git a/docs/source/architecture/dbservices.html b/docs/source/architecture/dbservices.html
@@ -0,0 +1,21 @@
+<!-- SPDX-License-Identifier: Apache-2.0 -->
+<!DOCTYPE html>
+<html>
+
+<head>
+	<meta name="viewport" content="width=device-width, initial-scale=1">
+	<link rel="stylesheet" href="../_static/css/styles.css">
+</head>
+
+<body>
+	<div class="container">
+		<input type="checkbox" id="db_service_diagram">
+		<label for="db_service_diagram">
+			<img src="../_static/images/db_service_diagram.png">
+		</label>
+	</div>
+
+	<br>
+</body>
+
+</html>
diff --git a/docs/source/architecture/dbservices.rst b/docs/source/architecture/dbservices.rst
@@ -5,4 +5,19 @@
 Database Services
 ===========================================
 
-.. TODO
+This module is a set of API's that handle the interactions with the database. The layer is isolated from the HTTP request and response.
+Hyperledger Explorer at this time persisting data from the Hyperledger Fabric only, no delete operations involved.
+
+The following API's are part of the database services:
+	1. `PersistenceFactory <https://github.com/hyperledger/blockchain-explorer/blob/master/app/persistence/PersistenceFactory.js>`__, responsible for platform based blockchain.
+	2. `Persist <https://github.com/hyperledger/blockchain-explorer/blob/master/app/persistence/postgreSQL/Persist.js>`__, has a set of getters, and setters to get services such as CRUDService, MetricServices, and PgService.
+	3. `PgService <https://github.com/hyperledger/blockchain-explorer/blob/master/app/persistence/postgreSQL/PgService.js>`__ is responsible to connect, and perform any data manipulation.
+	4. `CRUDService <https://github.com/hyperledger/blockchain-explorer/blob/master/app/persistence/fabric/CRUDService.js>`__, has a set of platform specific, and interacts with models that are storing data related to Hyperledger Fabric network blockchain.
+	5. `MetricService <https://github.com/hyperledger/blockchain-explorer/blob/master/app/persistence/fabric/MetricService.js>`__, is in charge of computing statistics of the blockchain activity, per hours, minutes, and organizations.
+
+Below diagram shows above mentioned API's.
+
+.. raw:: html
+     :file: ./dbservices.html
+
+
diff --git a/docs/source/architecture/gateway.html b/docs/source/architecture/gateway.html
@@ -0,0 +1,21 @@
+<!-- SPDX-License-Identifier: Apache-2.0 -->
+<!DOCTYPE html>
+<html>
+
+<head>
+	<meta name="viewport" content="width=device-width, initial-scale=1">
+	<link rel="stylesheet" href="../_static/css/styles.css">
+</head>
+
+<body>
+	<div class="container">
+		<input type="checkbox" id="diagram_gateway_class">
+		<label for="diagram_gateway_class">
+			<img src="../_static/images/diagram_gateway_class.png">
+		</label>
+	</div>
+
+	<br>
+</body>
+
+</html>
diff --git a/docs/source/architecture/gateway.rst b/docs/source/architecture/gateway.rst
@@ -9,7 +9,74 @@ Due to the fact that Hyperledger Fabric network channel can constantly change, t
 different organizations in the network, will come and go, the need of reconfiguration for the Hyperledger Explorer becomes very difficult to maintain
 and get real time updates of the fabric network.
 
-Hypeledger Explorer took another approach to connect to Hyperledger Fabric after the introduction of the "fabric-network" module by the
-`Hyperledger Fabric SDK for NodeJS <https://fabric-sdk-node.github.io/release-1.4/module-fabric-network.html>`__.
+After the introduction of the "fabric-network" module by the
+`Hyperledger Fabric SDK for NodeJS <https://fabric-sdk-node.github.io/release-1.4/module-fabric-network.html>`__. Hyperledger Explorer uses
+Gateway, and a connection profile to connect to the fabric network. Read more about `Gateway <https://hyperledger-fabric.readthedocs.io/en/release-1.4/developapps/gateway.html>`__.
+
+`FabricGateway <https://github.com/hyperledger/blockchain-explorer/blob/master/app/platform/fabric/gateway/FabricGateway.js>`__ shown in the diagram below.
+
+
+.. raw:: html
+     :file: ./gateway.html
+
+
+Configuration using Gateway and connection profile
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+One of the requirements to connect to a Hyperledger Fabric network to receive blocks, transactions, and other is to configure Hyperledger Explorer
+to be able to connect to the default fabric network. For this we tried to have a minimal as possible configuration by taking advantage of the latest
+Hyperledger Fabric `Service Discovery <https://hyperledger-fabric.readthedocs.io/en/release-1.4/discovery-overview.html>`__,
+and `Gateway <https://hyperledger-fabric.readthedocs.io/en/release-1.4/developapps/gateway.html>`__.
+As of now Hyperledger Explorer is able to connect only to a single Hyperledger Fabric network, and we believe that in the next releases we may be
+able to have more than one network connected.
+
+In previous versions we had a single file
+`config.json <https://github.com/hyperledger/blockchain-explorer/blob/v0.3.8/app/platform/fabric/config.json>`__ file that was used to configure
+Hyperledger Explorer, after the minimal configuration we divided in two parts, `config.json <https://github.com/hyperledger/blockchain-explorer/blob/master/app/platform/fabric/config.json>`__,
+and `connection-profile <https://github.com/hyperledger/blockchain-explorer/blob/master/app/platform/fabric/connection-profile/first-network.json>`__, that described the network properties.
+
+Sample Hyperledger Explorer configuration with one of the fabric sample network first-network, described below:
+
+On another terminal:
+
+.. code-block:: bash
+
+   cd blockchain-explorer/app/platform/fabric
+
+Modify config.json to point to your first-network network `connection-profile <https://github.com/hyperledger/blockchain-explorer/blob/master/app/platform/fabric/connection-profile/first-network.json>`__:
+
+.. code-block:: json
+
+			{
+				"network-configs": {
+					"first-network": {
+						"name": "first-network",
+						"profile": "./connection-profile/first-network.json"
+					}
+				},
+				"license": "Apache-2.0"
+			}
+
+::
+
+	"first-network" is the name of your connection profile, and can be changed to any name.
+
+	"name" is a name you want to give to your fabric network, you can change only value of the key "name".
+
+	"profile" is the location of your connection profile, you can change only value of the key "profile"
+
+	Modify connection profile in the JSON file first-network.json:
+	Change "fabric-path" to your fabric network disk path in the first-network.json file:
+	/blockchain-explorer/app/platform/fabric/connection-profile/first-network.json
+	Provide the full disk path to the adminPrivateKey config option, it usually ends with "_sk", for example:
+
+	* "/fabric-path/fabric-samples/first-network/crypto-config/peerOrganizations/org1.example.com/users/Admin@org1.example.com/msp/keystore/aaacd899a6362a5c8cc1e6f86d13bfccc777375365bbda9c710bb7119993d71c_sk"
+
+	* "adminUser" is the the admin user of the network, in this case it's fabric CA or an identity user.
+
+	* "adminPassword" is the password for the admin user.
+
+	* "enableAuthentication" is a flag to enable authentication using a login page, setting to false
+	will skip authentication.
+
 
-.. TODO
diff --git a/docs/source/architecture/hl_ui_high_level.rst b/docs/source/architecture/hl_ui_high_level.rst
@@ -3,11 +3,28 @@
 
 
 
-Front End
+Presentation Layer / Front End
 ========================================
 
-When choosing a framework, or a library in most of the cases we look at the performance, maturity, and support this is where ReactJs was a benefit
-to us and used in our HLExplorer front end.
+When choosing a framework, or a library in most of the cases we look at the performance, maturity, and support this is where ReactJs
+was a benefit to us and used in our HLExplorer front end.
+
+Why ReactJs?
+~~~~~~~~~~~~~
+
+- Plainness
+   - Component-based approach
+			- Use of well-defined lifecycle
+			- JavaScript makes React very simple to learn, build professional web.
+			- Use of a special syntax called JSX that allows to mix HTML with JavaScript.
+- Data Binding
+   - One-way data binding, control of the flow of data to components through the dispatcher, a one control point.
+- Performance
+   - React uses several clever techniques to minimize the number of costly DOM operations required to update the UI.
+- Testing
+   - Easy to test, rich set of libraries, like Jest, and React Testing Library
+- Straightforward to learn
+   -  Easily understand React knowing JavaScript, and the good part: for react you just need basic knowledge of HTML and CSS.
 
 The high-level architecture of presentation layer
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

diff --git a/docs/source/architecture/hlfabricconfig.rst b/docs/source/architecture/hlfabricconfig.rst
diff --git a/docs/source/architecture/index.html b/docs/source/architecture/index.html
@@ -18,6 +18,4 @@
 	<br>
 </body>
 
-
-
 </html>
diff --git a/docs/source/architecture/index.rst b/docs/source/architecture/index.rst
@@ -7,6 +7,6 @@ Hyperledger Explorer Architecture
 
 The high-level architecture of Hyperledger Explorer
 
-
 .. raw:: html
      :file: ./index.html
+