﻿////
 *******************************************************************************
 * Copyright (c) 2018 Contributors to the Eclipse Foundation
 *
 * See the NOTICE file(s) distributed with this work for additional
 * information regarding copyright ownership.
 *
 * This program and the accompanying materials are made available under the
 * terms of the Eclipse Public License v. 2.0 which is available at
 * http://www.eclipse.org/legal/epl-2.0.
 *
 * SPDX-License-Identifier: EPL-2.0
 *******************************************************************************
////
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.
|========================================================