src/main/asciidoc/architectureDocumentation/mics.home_architectureDocumentation.adoc - openk-usermodules/org.eclipse.openk-usermodules.mics.homeService - Git at Google

 ////
 ******************************************************************************
 * Copyright © 2018 PTA GmbH.
 * All rights reserved. This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License v1.0
 * which accompanies this distribution, and is available at
 *
 *     http://www.eclipse.org/legal/epl-v10.html
 *
 ******************************************************************************
 ////
 openKonsequenz - Architecture of the module "mics.home@openK"
 ============================================================
 :Author: Frank Dietrich
 :Email: frank.dietrich@pta.de
 :Date: 2017-07-12
 :Revision: 1
 :icons:
 :source-highlighter: highlightjs
 :highlightjs-theme: solarized_dark

 This documentation bases on ARC42-Template (v7.0):

 *About arc42*

 arc42, the Template for documentation of software and system architecture.

 By Dr. Gernot Starke, Dr. Peter Hruschka and contributors.

 Template Revision: 7.0 EN (based on asciidoc), January 2017

 © We acknowledge that this document uses material from the arc 42 architecture template, http://www.arc42.de.
 Created by Dr. Peter Hruschka & Dr. Gernot Starke.

 <<<

 == Introduction and Goals

 === Requirements Overview

 TODO

 === Quality Goals

 The eLogbook represents a user module that bases on the architecture platform of openKONSEQUENZ. The main quality
 goals of the platform are:

 * *Flexibility* The reference platform shall grant that different systems and modules from different vendors/developers can interact and interoperate, and may be exchanged or recombined.
 * *Availability* All platform modules that are running on the platform can only be as available as the platform same for user modules that are based on platform modules.
 * *Maintainability* (and testability as part of maintainability)  The platform and its platform modules shall be used longer than 15 years.
 * *Integration performance* New implemented functionality of oK own modules and external modules shall be included fast / automatically.
 * *Security* The platform and its modules need to underly security-by-design

 The main quality goals of the user module eLogbook are:

 * *Functionality* The user module must fulfil the functional requirements mentioned in the section before
 * *Integration performance* The user module must be easy integratable in different production environments. * Modifiability (and testability as part of modifiability) Good documentation (i.e. code and architecture documentation) makes code changes easier and automatic tests facilitate rigorous verification. * Ergonomics The web interface must be realized according to oK-GUI-Styleguide.

 The following documents contain the quality goals in detail:

 * "Architecture Committee Handbook" v1.2 from 14-09-2016
 * "Quality Committee Handbook" v1.1 from 18-08-2016

 The architecture is based on the AC-Handbook. The
 quality demands are described in the QC-Handbook.
 Both specifications were fully complied with in the project, so that a high quality is given.

 The code quality regarding static code analysis and unit test code coverage on the backend side is ensured by the
 use of *sonarqube*. The rule set and the qualtity gate are defined by the default, the so called "sonar way".


 === Stakeholders

 .Stakeholders
 [options="header,footer"]
 |=========================================================
 |Role/Name|Contact|Expectations
 |=========================================================

 == Architecture Constraints

 The main architecture constraints are:

 * *Public License* The module must be available under the “Eclipse Public License 1.0”.
 * *Availability* The source code of the module must be accessible to any interested person/company. Therefore the project is published at https://projects.eclipse.org/projects/technology.elogbook
 * *Standardization* The module must use standardized data structures (CIM) [if available] and the reference platform.

 === Technical Constraints

 The following technical constraints are given:

 .Technical Contraints
 [options="header,footer"]
 |========================================================
 |Component|Constraints
 |Basis components of the reference platform|
 - Application Server Tomcat
 - JPA EclipseLink
 - Database PostgreSQL

 |Enterprise Service Bus|
 * ESB Talend
 * Communication via RESTful Webservices

 |Programming Language Frontend
 a|* Angular
 * Bootstrap
 * jQuery
 * REST/JSON Interfaces

 |GUI design
 a|* According to oK-GUI-Styleguide

 |Java QA environment|Sonarqube 5.6.6

 |Programming Language
 a|* Backend: Java 1.8
 * Frontend: Angular 4.0.0 (Javascript, Typescript, HTML5, CSS3)

 |IDE
 a|* Not restricted (Eclipse, IntelliJ, Microsoft Developer Studio, Microsoft Visual Code ...)

 |Build system
 a|* Backend: Maven
 * Frontend: NodeJS + Angular/cli

 |Libraries, Frameworks,Components
 a|* Used Libraries/Frameworks have to be compatible to the Eclipse Public License
 |Architecture Documentation|* According ARC42-Template
 |========================================================


 === Technical Dependencies

 == System Scope and Context

 === Business Context


 === Technical Context

 The following aspects have to be taken into account for external communication of the module eLogbook:

 * As interface-technology RESTful web services are used.
 * Each external interface (interfaces between modules or external systems) has to be documented.
 * Dependencies of modules to services realized by other modules have to be specified and documented explicitly.
 * When CIM is not appropriate (like access management), other standards in their respective domain shall be taken into account first to avoid proprietary and inaccurate interfaces. The interface has also be documented in the overall openKONSEQUENZ interface profile and it should use REST & XML.

 The interfaces of the module eLogbook are described in the documentation *"elogbook_interfaceDocumentation"*.

 === Solution Strategy

 == Building Block View

 === Whitebox Overall System


 == Runtime View


 == Deployment View


 === Deployment of the application components

 ==== Deployment of the frontend

 ==== Deployment of the backend


 ==== Configuration of the system


 ===== Configuration of the webserver

 There exists the file *context.xml* in the "conf" subdirectory (*<TOMCAT>/conf*) of the target apache tomcat installation.
 Add the following parameter and resource in order to access the correct backend configuration and to
 gain access to the database:

 .context.xml
 [source,xml]
 ----
 [...]
     <!-- Uncomment this to disable session persistence across Tomcat restarts -->

     <!--Manager pathname=""/>


     <Parameter name="environment" override="false" value="Development"/-->

     <Parameter name=""OK_MICS_HOME_ENVIRONMENT" override="false" value="Production"/>


     <!-- Uncomment this to enable Comet connection tacking (provides events
          on session expiration as well as webapp lifecycle) -->
 [...]
 ----


 ===== Configuration of the backend

 After the backend war file has been deployed and unpacked inside of the *<TOMCAT>/webapps* folder there are different
  backend config files to be found in the folder *<TOMCAT>/webapps/elogbook/WEB-INF/classes*

 * backendConfigCustom.json
 * backendConfigDevLocal.json
 * backendConfigDevServer.json
 * backendConfigProduction.json

 The active configuration is chosen by parameter *OK_MICS_HOME_ENVIRONMENT* (see context.xml above).
 Possible values are:

 * *Custom* (for backendConfigCustom.json)
 * *DevLocal* (for backendConfigDevLocal.json)
 * *DevServer* (for backendConfigDevServer.json)
 * *Production* (for backendConfigProduction.json)

 After choosing an environment the corresponding json file has to be configured:

 .backendConfigXXX.json
 [source,json]
 ----
 {
   "micsDistributionCluster" : "elogbook.openK",
   "micsCentralURL" : "http://localhost:9010/mics/central"
 }

 ----
 * *micsDistributionCluster* - TODO
 * *micsCentralURL* - TODO


 === CI- and CD-Components

 ==== GIT-Repository


 === Continuous Deployment


 == Design Decisions

 All architecture decisions based on the Architecture Committee Handbook. There are no deviations.

 == Risks and Technical Debts

 (Currently there aren't any known issues)

 <<<

 == Glossary

 .Abbreviations and glossary terms
 [options="header,footer"]
 |========================================================
 |Short|Long|German|Description
 |AC|Architecture Committee|Architektur-Komittee|Gives Framework and Constraints according to architecture for oK projects.
 |CNCU|Central Network Control Unit||
 |DAO|Data Access Objects||
 |DSO|Distribution System Operator|Verteilnetz-betreiber (VNB)|Manages the distribution network for energy, gas or water.
 |EPL|Eclipse Public License||Underlying license model for Eclipse projects like elogbook@openK
 |ESB|Enterprise Service Bus||Central instance for exchange of data to overcome point-to-point connections.
 |oK|openKONSEQUENZ|openKONSEQUENZ|Name of the consortium of DSOs
 |QC|Quality Committee|Qualitätskomitee|Gives framework and constraints according to quality for oK projects.
 |SCADA|Supervisory Control and Data Acquisition|Netzleitsystem|System, that allows DSOs view/control actual parameters of their power grid.
 |========================================================
	////
	******************************************************************************
	* Copyright © 2018 PTA GmbH.
	* All rights reserved. This program and the accompanying materials
	* are made available under the terms of the Eclipse Public License v1.0
	* which accompanies this distribution, and is available at
	*
	* http://www.eclipse.org/legal/epl-v10.html
	*
	******************************************************************************
	////
	openKonsequenz - Architecture of the module "mics.home@openK"
	============================================================
	:Author: Frank Dietrich
	:Email: frank.dietrich@pta.de
	:Date: 2017-07-12
	:Revision: 1
	:icons:
	:source-highlighter: highlightjs
	:highlightjs-theme: solarized_dark

	This documentation bases on ARC42-Template (v7.0):

	About arc42

	arc42, the Template for documentation of software and system architecture.

	By Dr. Gernot Starke, Dr. Peter Hruschka and contributors.

	Template Revision: 7.0 EN (based on asciidoc), January 2017

	© We acknowledge that this document uses material from the arc 42 architecture template, http://www.arc42.de.
	Created by Dr. Peter Hruschka & Dr. Gernot Starke.

	<<<

	== Introduction and Goals

	=== Requirements Overview

	TODO

	=== Quality Goals

	The eLogbook represents a user module that bases on the architecture platform of openKONSEQUENZ. The main quality
	goals of the platform are:

	* Flexibility The reference platform shall grant that different systems and modules from different vendors/developers can interact and interoperate, and may be exchanged or recombined.
	* Availability All platform modules that are running on the platform can only be as available as the platform same for user modules that are based on platform modules.
	* Maintainability (and testability as part of maintainability) The platform and its platform modules shall be used longer than 15 years.
	* Integration performance New implemented functionality of oK own modules and external modules shall be included fast / automatically.
	* Security The platform and its modules need to underly security-by-design

	The main quality goals of the user module eLogbook are:

	* Functionality The user module must fulfil the functional requirements mentioned in the section before
	* Integration performance The user module must be easy integratable in different production environments. * Modifiability (and testability as part of modifiability) Good documentation (i.e. code and architecture documentation) makes code changes easier and automatic tests facilitate rigorous verification. * Ergonomics The web interface must be realized according to oK-GUI-Styleguide.

	The following documents contain the quality goals in detail:

	* "Architecture Committee Handbook" v1.2 from 14-09-2016
	* "Quality Committee Handbook" v1.1 from 18-08-2016

	The architecture is based on the AC-Handbook. The
	quality demands are described in the QC-Handbook.
	Both specifications were fully complied with in the project, so that a high quality is given.

	The code quality regarding static code analysis and unit test code coverage on the backend side is ensured by the
	use of sonarqube. The rule set and the qualtity gate are defined by the default, the so called "sonar way".


	=== Stakeholders

	.Stakeholders
	[options="header,footer"]
	\|=========================================================
	\|Role/Name\|Contact\|Expectations
	\|=========================================================

	== Architecture Constraints

	The main architecture constraints are:

	* Public License The module must be available under the “Eclipse Public License 1.0”.
	* Availability The source code of the module must be accessible to any interested person/company. Therefore the project is published at https://projects.eclipse.org/projects/technology.elogbook
	* Standardization The module must use standardized data structures (CIM) [if available] and the reference platform.

	=== Technical Constraints

	The following technical constraints are given:

	.Technical Contraints
	[options="header,footer"]
	\|========================================================
	\|Component\|Constraints
	\|Basis components of the reference platform\|
	- Application Server Tomcat
	- JPA EclipseLink
	- Database PostgreSQL

	\|Enterprise Service Bus\|
	* ESB Talend
	* Communication via RESTful Webservices

	\|Programming Language Frontend
	a\|* Angular
	* Bootstrap
	* jQuery
	* REST/JSON Interfaces

	\|GUI design
	a\|* According to oK-GUI-Styleguide

	\|Java QA environment\|Sonarqube 5.6.6

	\|Programming Language
	a\|* Backend: Java 1.8
	* Frontend: Angular 4.0.0 (Javascript, Typescript, HTML5, CSS3)

	\|IDE
	a\|* Not restricted (Eclipse, IntelliJ, Microsoft Developer Studio, Microsoft Visual Code ...)

	\|Build system
	a\|* Backend: Maven
	* Frontend: NodeJS + Angular/cli

	\|Libraries, Frameworks,Components
	a\|* Used Libraries/Frameworks have to be compatible to the Eclipse Public License
	\|Architecture Documentation\|* According ARC42-Template
	\|========================================================


	=== Technical Dependencies

	== System Scope and Context

	=== Business Context



	=== Technical Context

	The following aspects have to be taken into account for external communication of the module eLogbook:

	* As interface-technology RESTful web services are used.
	* Each external interface (interfaces between modules or external systems) has to be documented.
	* Dependencies of modules to services realized by other modules have to be specified and documented explicitly.
	* When CIM is not appropriate (like access management), other standards in their respective domain shall be taken into account first to avoid proprietary and inaccurate interfaces. The interface has also be documented in the overall openKONSEQUENZ interface profile and it should use REST & XML.

	The interfaces of the module eLogbook are described in the documentation "elogbook_interfaceDocumentation".

	=== Solution Strategy

	== Building Block View

	=== Whitebox Overall System





	== Runtime View


	== Deployment View


	=== Deployment of the application components

	==== Deployment of the frontend

	==== Deployment of the backend


	==== Configuration of the system


	===== Configuration of the webserver

	There exists the file context.xml in the "conf" subdirectory (<TOMCAT>/conf) of the target apache tomcat installation.
	Add the following parameter and resource in order to access the correct backend configuration and to
	gain access to the database:

	.context.xml
	[source,xml]
	----
	[...]
	<!-- Uncomment this to disable session persistence across Tomcat restarts -->

	<!--Manager pathname=""/>


	<Parameter name="environment" override="false" value="Development"/-->

	<Parameter name=""OK_MICS_HOME_ENVIRONMENT" override="false" value="Production"/>


	<!-- Uncomment this to enable Comet connection tacking (provides events
	on session expiration as well as webapp lifecycle) -->
	[...]
	----


	===== Configuration of the backend

	After the backend war file has been deployed and unpacked inside of the <TOMCAT>/webapps folder there are different
	backend config files to be found in the folder <TOMCAT>/webapps/elogbook/WEB-INF/classes

	* backendConfigCustom.json
	* backendConfigDevLocal.json
	* backendConfigDevServer.json
	* backendConfigProduction.json

	The active configuration is chosen by parameter OK_MICS_HOME_ENVIRONMENT (see context.xml above).
	Possible values are:

	* Custom (for backendConfigCustom.json)
	* DevLocal (for backendConfigDevLocal.json)
	* DevServer (for backendConfigDevServer.json)
	* Production (for backendConfigProduction.json)

	After choosing an environment the corresponding json file has to be configured:

	.backendConfigXXX.json
	[source,json]
	----
	{
	"micsDistributionCluster" : "elogbook.openK",
	"micsCentralURL" : "http://localhost:9010/mics/central"
	}

	----
	* micsDistributionCluster - TODO
	* micsCentralURL - TODO



	=== CI- and CD-Components

	==== GIT-Repository


	=== Continuous Deployment


	== Design Decisions

	All architecture decisions based on the Architecture Committee Handbook. There are no deviations.

	== Risks and Technical Debts

	(Currently there aren't any known issues)

	<<<

	== Glossary

	.Abbreviations and glossary terms
	[options="header,footer"]
	\|========================================================
	\|Short\|Long\|German\|Description
	\|AC\|Architecture Committee\|Architektur-Komittee\|Gives Framework and Constraints according to architecture for oK projects.
	\|CNCU\|Central Network Control Unit\|\|
	\|DAO\|Data Access Objects\|\|
	\|DSO\|Distribution System Operator\|Verteilnetz-betreiber (VNB)\|Manages the distribution network for energy, gas or water.
	\|EPL\|Eclipse Public License\|\|Underlying license model for Eclipse projects like elogbook@openK
	\|ESB\|Enterprise Service Bus\|\|Central instance for exchange of data to overcome point-to-point connections.
	\|oK\|openKONSEQUENZ\|openKONSEQUENZ\|Name of the consortium of DSOs
	\|QC\|Quality Committee\|Qualitätskomitee\|Gives framework and constraints according to quality for oK projects.
	\|SCADA\|Supervisory Control and Data Acquisition\|Netzleitsystem\|System, that allows DSOs view/control actual parameters of their power grid.
	\|========================================================