Merge pull request #3276 from energywebfoundation/master

common/autoinstallers/rush-prettier/package.json

@@ -4,6 +4,6 @@
     "private": true,
     "dependencies": {
         "prettier": "2.5.1",
-        "pretty-quick": "3.1.2"
+        "pretty-quick": "3.1.3"
     }
 }

common/autoinstallers/rush-tools/package.json

@@ -3,7 +3,7 @@
     "version": "1.0.0",
     "private": true,
     "dependencies": {
-        "concurrently": "6.4.0",
+        "concurrently": "6.5.1",
         "wait-on": "6.0.0",
         "ganache-cli": "6.12.2",
         "lerna": "4.0.0"

common/config/rush/command-line.json

@@ -56,6 +56,15 @@
             "shellCommand": "lerna run test:e2e --stream --ignore @energyweb/exchange-irec --ignore @energyweb/issuer-api && lerna run test:e2e --stream --scope @energyweb/exchange-irec && lerna run test:e2e --stream --scope @energyweb/issuer-api",
             "allowWarningsInSuccessfulBuild": true
         },
+        {
+            "name": "test:ui:e2e",
+            "commandKind": "global",
+            "summary": "Run all ui test:e2e in packages",
+            "safeForSimultaneousRushProcesses": false,
+            "autoinstallerName": "rush-tools",
+            "shellCommand": "concurrently --restart-tries 3 --restart-after 1500 -n ganache,backend,ui \"yarn run:ganache\" \"wait-on tcp:8545 && yarn migrate:demo && yarn run:backend\" \"wait-on tcp:3030 && yarn run test:ui:e2e\"",
+            "allowWarningsInSuccessfulBuild": true
+        },
         {
             "commandKind": "bulk",
             "name": "build:container:canary",

docs/architecture.md

@@ -1 +1,41 @@
-# Architecture
+# Energy Web Origin Architecture
+Energy Web Origin is comprised of a user interface, a backend, and multiple SDKs that can be used individually, or in conjunction with each other. Each SDK is composed of one or several NPM packages. 
+
+![origin-architecture](./images/panels/origin-architecture.png)
+
+ ## SDK API Packages
+Each SDK has an API package:  
+
+- [Device Registry API](./device-registry/device-registry-api.md) (@energyweb/origin-device-registry-api)
+- [Issuer API](./traceability/packages/issuer-api.md) (@energyweb/issuer-api)
+- [Exchange API](./trade/exchange.md) (@energyweb/exchange)  
+
+The API package has one or several NestJS modules in the /pods directory. Each module contains code relevant for a specific feature. In general, each NestJS module has:  
+
++ A [controller](https://docs.nestjs.com/controllers) that manages requests and responses to the client
++ A .entity file that maps an entity to the database repository
++ A .service file that provides methods to fetch and transform data
++ [Data Transfer Object (DTO) file(s)](https://docs.nestjs.com/controllers#request-payloads) that provide Data Transfer Objects, which are representations of the data that are exposed to the endpoint consumer  
++ A [module](https://docs.nestjs.com/modules) class that is used by NestJS to structure the application 
+
+### Data Persistence
+API services fetch, update and persist data. Data is persisted using [PostgreSQL](https://www.postgresql.org/), and [TypeORM](https://typeorm.io/#/) is used to integrate the database into the NestJS application. You can view the SDK's database connection configuration in each SDK's typmeorm.ts file. 
+
+### Events and Commands
+In addition to services, the NestJS modules use [Commands](https://docs.nestjs.com/recipes/cqrs#commands) and [Events](https://docs.nestjs.com/recipes/cqrs#events) to encapsulate logic and, in the case of an event, respond asynchronously to something that has occured in the application. Events and commands are emitted and responded to within and between an SDK's packages using the [NestJS CQRS module](https://docs.nestjs.com/recipes/cqrs). 
+
+
+## Smart Contracts
+The Issuer (@energyweb/issuer) and Exchange Token Account (@energyweb/exchange-token-account) packages contain their respective SKD's smart contracts. 
+
+- See documentation for Issuer smart contracts [here](./traceability/contracts/Issuer.md#smart-contracts)
+- See documentation for the Exchange Token Account smart contract [here](./trade/exchange-token-account.md)
+
+### Deployment
+The Issuer and Exchange Token Account packages use [Truffle to compile](https://trufflesuite.com/docs/truffle/getting-started/compiling-contracts.html) and migrate smart contracts. 
+
+### Blockchain Libraries
+- Packages use [ethers](https://docs.ethers.io/v5/) to interact with smart contracts on the blockchain.  
+
+- The Issuer and Exchange Token Account packages use [typechain](https://github.com/dethcrypto/TypeChain#readme) to generate TypeScript classes for smart contracts.
+

docs/backend.md

@@ -1,6 +1,7 @@
 # Origin Backend - @energyweb/origin-backend
 [**Source code on GitHub**](https://github.com/energywebfoundation/origin/tree/master/packages/origin-backend)
 
+## Overview
 The Origin Backend is a [NestJS](https://nestjs.com/) application that provides services for user and organization authorization and management. The Backend application can be used in conjunction with one, several or all of the [Origin SDKs](./index#origin-sdks) to provide integrated user management and authorization. 
 
 The below gives an overview the of the package architecture, however the NestJS documentation provides further detail into the fundamentals of NestJS Architecture that may help to understand the elements of this application:  

docs/device-registry.md

@@ -1,4 +1,6 @@
 # Device Registry SDK
+
+## Overview
 The Device Registry SDK is used to register and fetch devices and meter data.  
 
 ‘Devices’ are electricity generating assets (e.g solar pv, hydroelectric dam, steam turbine). Because [Energy Attribute Certificates](././user-guide-glossary.md.md#energy-attribute-certificate) are always tied to the device for which generation evidence was submitted, generation devices must be registered with Origin. Read more about the role of devices on the platform [here](./user-guide-reg-onboarding.md#devices). 
@@ -9,7 +11,7 @@ The Device Registry SDK has two core packages:
 ### 1. [Device Registry API - @energyweb/origin-device-registry-api](./registry/device-registry-api.md)
 A [NestJS](https://nestjs.com/) application to fetch and persist devices.
 
-See the documentation for this package [here](./registry/device-registry-api.md). 
+See the documentation for this package [here](./device-registry/device-registry-api.md). 
 
 ### 2. [Origin Energy API - @energyweb/origin-energy-api](https://github.com/energywebfoundation/origin/tree/master/packages/devices/origin-energy-api)
 A [NestJS](https://nestjs.com/) application to fetch and aggregate meter readings using a Meter Id. 

docs/device-registry/device-registry-api.md

@@ -1,6 +1,7 @@
 # Device Registry API - @energyweb/origin-device-registry-api
 [**Source code on GitHub**:](https://github.com/energywebfoundation/origin/tree/master/packages/devices/origin-device-registry-api)
 
+## Overview
 The Device Registry API is a [NestJS](https://nestjs.com/) package that provides restful endpoints for fetching and creating/persisting Devices.  
 
 The below gives an overview the of the package architecture, however the NestJS documentation provides further detail into the fundamentals of NestJS Architecture that may help to understand the elements of this application:  

docs/index.md

@@ -11,11 +11,17 @@ The main purpose of EACs is to act as an accounting vehicle to prove that consum
 
 We provide more information on EACs in the glossary [here](./user-guide-glossary.md#energy-attribute-certificate).  
 
-**This site provides technical documentation for each SDK's generic implementations (i.e. not I-REC specific implementations), as well as [user guides](./user-guides.md) on how to navigate the [reference implementation platform's](#origin-platform-reference-implementation) user interface.**   
+## Documentation Overview
+This site provides technical documentation for each SDK's generic implementations (i.e. not I-REC specific implementations), as well as [user guides](./user-guides.md) on how to navigate the reference implementation platform's user interface (read more about the reference implementation [below](#origin-platform-reference-implementation)).  
 
-*Note* that although this documentation only covers the packages built for generic (i.e. not IREC compliant) implementation, each SDK does contain I-REC specific packages that comply and integrate with the I-REC registry. You can find those packages in the SDK's GitHub repository. 
+<div class="admonition note">
+  <p class="first admonition-title">Note</p>
+  <p class="last">
+   Although this documentation only covers the packages built for generic (i.e. not I-REC compliant) implementation, each SDK does contain I-REC specific packages that comply and integrate with the I-REC registry. You can find those packages in the SDK's GitHub repository. 
+  </p>
+</div>
 
-# Origin SDKs
+## Origin SDKs
 Origin is comprised of [multiple SDKs](./packages.md) that can be used individually or in unison.
 
 The core SDKs are: 
@@ -28,26 +34,26 @@ The SDKs integrate with the [Origin Backend](#origin-backend), which provides au
 
 Below we provide a brief description of each SDK's core functionality and a link to further documentation.
 
-## [**Device Registry SDK**](./device-registry.md)
+### [**Device Registry SDK**](./device-registry.md)
 The Device Registry SDK is used to register, manage and fetch devices. ‘Devices’ are electricity generating assets (e.g solar pv, hydroelectric dam, steam turbine). Because Energy Attribute Certificates are always tied to the device for which generation evidence was submitted, generation devices must be registered with Origin. Read more about the role of devices on the platform [here](./user-guide-reg-onboarding.md#devices).
 
 See documentation for the Device Registry SDK [here](./device-registry.md). 
 
-## [**Traceability SDK**](./traceability.md)
+### [**Traceability SDK**](./traceability.md)
 The Traceability SDK is used to enable certificate issuing bodies to mint on-chain EAC's upon request based on provided generation evidence, and to manage the on-chain lifecycle (transferring, claiming) of certificates. This SDK contains the smart contracts for certificate issuance, as well as methods to interact with and manage certificates on the blockchain after issuance.  
 
 The Traceability SDK ensures that the certificate lifecycle and its owners are in compliance with regulation at all times. Each issuing standard (e.g. I-REC) has its own implementation of the traceability SDK to meet its regulatory needs. To ensure compliance with widely adopted standards EW Origin team is working directly with regulators and standardization bodies.  
 
 See documentation for the Traceability SDK [here](./traceability.md). 
 
-## [**Trade SDK**](./trade.md)
+### [**Trade SDK**](./trade.md)
 The Trade SDK is used to facilitate trading of EACs between buyers and sellers, and to manage EACs that are active on the Exchange (transferring, withdrawing, claiming).    
 
 This SDK is built on the basis of the [order book](./user-guide-glossary.md#order-book) system, where sellers post [asks](./user-guide-glossary.md#ask) and buyers post [bids](./user-guide-glossary.md#bid). When there is a match based on [EAC criteria](./trade/matching-criteria.md) and price, a trade is executed. 
 
 See documentation for the Trade SDK [here](./trade.md). 
 
-## Implementing Origin SDKs
+### Implementing Origin SDKs
 The Origin SDKs are developed to be agnostic of registry and certificate standard implementation. Depending on implementation needs, users can implement one or all of the SDKs. By design, the SDK packages are loosely coupled, which enables the possibility to implement solutions that consist of only part of the Origin features, such as:
 
 -   Issuance only
@@ -56,20 +62,20 @@ The Origin SDKs are developed to be agnostic of registry and certificate standar
 
  The [Origin Backend package](#origin-backend) provides authorization and user/organization management, however users can integrate their backend implementation. 
 
-# [**Origin Backend**](./backend.md)
+## [**Origin Backend**](./backend.md)
 The Origin Backend is a [NestJS](https://docs.nestjs.com/) application that provides services to manage authorization and user and organization management. The Origin Backend application can be used in conjunction with one, several or all of the [Origin SDKs](#origin-sdks) to provide integrated user management and authorization. 
 
 See documentation for the Origin Backend application [here](./backend.md). 
 
-# **Origin UI**
+## **Origin UI**
 [Source code on GitHub](https://github.com/energywebfoundation/origin/tree/master/packages/ui/apps/origin-ui)
 
-The Origin UI package provides the code for the full, end-to-end I-REC-compliant reference implementation (see the source code [here](https://github.com/energywebfoundation/origin/tree/master/packages/ui/apps/origin-ui)), as well as modularized libraries for each interface component. **Note that the UI components use the I-REC implementation of the SDKs,** so these serve more as a reference guide for generic implementations rather than for direct use. See an overview of the reference implementation [here](./user-guides.md)in the User Guides section. 
+The Origin UI package provides the code for the full, end-to-end I-REC-compliant reference implementation (see the source code [here](https://github.com/energywebfoundation/origin/tree/master/packages/ui/apps/origin-ui)), as well as modularized libraries for each interface component. **Note that the UI components use the I-REC implementation of the SDKs,** so these serve more as a reference guide for generic implementations rather than for direct use. See an overview of the reference implementation [here](./user-guides.md) in the User Guides section. 
 
 All UI components are built with [React](https://reactjs.org/). For data fetching, UI components use [React Query](https://react-query.tanstack.com/overview) to access each SDK's controller methods. 
 
-## UI Libraries
-UI libraries provide that is modularized according to each reference implementation view:  
+### UI Libraries
+UI libraries provide packages that are modularized according to each reference implementation view:  
 
 + [certificate](https://github.com/energywebfoundation/origin/tree/master/packages/ui/libs/certificate)
 + [device](https://github.com/energywebfoundation/origin/tree/master/packages/ui/libs/device)
@@ -78,7 +84,7 @@ UI libraries provide that is modularized according to each reference implementat
 + [user](https://github.com/energywebfoundation/origin/tree/master/packages/ui/libs/user)
 + [main UI](https://github.com/energywebfoundation/origin/tree/master/packages/ui/libs/ui)  
 
-# Origin Platform Reference Implementation
+## Origin Platform Reference Implementation
 The [Origin repository](https://github.com/energywebfoundation/origin) provides a full reference implementation for an end-to-end, I-REC-compliant platform for device and organization registry, user management and Certificate issuance and trading.  
 
 + See documentation on how to install, build and run Origin's reference implementation platform locally [here](getting-started.md)

docs/traceability.md

@@ -1,6 +1,7 @@
 # Traceability SDK
 [**Source code on GitHub**](https://github.com/energywebfoundation/origin/tree/master/packages/traceability)
 
+## Overview
 The Traceability SDK is responsible for the **request**, **issuance** and **exchange** of [Energy Attribute Certificates](./user-guide-glossary.md#energy-attribute-certificate) on the Origin platform. Certificates are requested by device owners, and approved by issuers. The issuer is the entity that is responsible for reviewing the energy generation evidence and issuing the certificate in a way that conforms with legislative and industry standards.  
 
 ## Traceability SDK Packages  
@@ -80,7 +81,7 @@ Certificate owners can claim their certificates for reporting purposes. The 'cla
 
 Claimed certificates are locked and cannot be moved on to the Exchange, withdrawn to another wallet address, or transferred to another user. Claiming prevents any other entity from performing any action with the certificate. The issuer cannot suspend or revoke a claimed certificate. Certificates that have been kept private by the owner, concealing volume information, are made public before they are claimed as only public certificates can be claimed to ensure transparency and prevent double counting. 
 
-See documentation on the claim process [here](./traceability/contracts/Issuer.md#claiming-certificates).
+See documentation on the claim process [here](./traceability/packages/issuer.md#claiming-certificates).
 
 
 ### Additional Reading