#5 developer doc straightened out

docs/DevelopmentGuide.md

@@ -1,12 +1,77 @@
 ![Preview](../images/WheatFieldWithCrows.png)
 
+#Quickstart
+## Frontend
+### Requirements
+Kotlin/JS uses `Gradle` for the build, for the JS runtime `NodeJS`, and for the JS dependency management part `npm`.
+You should have installed:
+* node js (https://nodejs.org/en/download/current/)
+* Apache Gradle 
+* Google Chrome (72.0.3626.81 or higher)
+* Moesif CORS Plugin (for Chrome)
+
+### Build
+gradle is run under Windows with gitbash:
+
+* ./gradlew.bat tasks # list all gradle tasks
+* ./gradlew.bat webpack-bundle # create main.bundle.js
+* ./gradlew.bat test --exclude-task npm-install
+
+Internally gradle uses npm for the JS part.
+```
+ npm --verbose 
+``` 
+ If task npm-install hangs, try
+``` 
+ ./gradlew.bat npm-install --info --debug --stacktrace
+```
+Helps in identifying thing that may go wrong (eg. due to proxy settings).
+
+### Run
+```
+gradlew.bat -t run
+```
+
+## Backend
+### Requirements
+* (Oracle) JDK 1.8_181 (or higher)
+* Apache Maven 3.6.0
+
+### Create 
+Create from the Apache Isis SimpleApp archetype:
+```bash
+mvn archetype:generate \
+    -D archetypeGroupId=org.apache.isis.archetype \
+    -D archetypeArtifactId=simpleapp-archetype \
+    -D archetypeVersion=2.0.0-M2 \
+    -D groupId=org.my \ 
+    -D artifactId=myapp-2.0.0-M2 \ 
+    -D version=1.0.0 -B
+```
+### Build 
+```bash
+mvn clean install -DskipTests
+```
+### Run
+```bash
+cd webapp
+mvn -Djetty.port=8080 jetty:run -DPROTOTYPING
+```
+
 # Design
+In the following section you'll find information that likely helps understanding the implementation.  
 ## Overview
-![Preview](../images/uml-overview.png)
+![Preview](./uml-overview.png)
 ## Handler Chain
-![Preview](../images/uml-handler.png)
+![Preview](./uml-handler.png)
 
 ## Patterns 
+### Redux
+The implementation is an (independent) reinvention of Redux. 
+I prefer the name Aggregator over Reducer though - IIRC it's even older.
+### Half Object Protocol
+The HOP pattern dates back to the early 2000, namely CanooULC.
+IMO Naked Objects together with the RO API and kroViz resembles something similar.
 ### Transfer Object (JEE / EAA)
 TO's are created from JSON responses
 ### Event Sourcing (EAA)
@@ -31,50 +96,21 @@ UI elements are hierarchically grouped, cf. *layout.xml
 Used for building tables dynamically.
 ### Remote Facade
 The Restful Objects API.
-### Redux
-The implementaion here is an (independent) reinvention of Redux. 
-I prefer the name Aggregator over Reducer though - IIRC it's even older.
-### Half Object Protocol
-The HOP pattern dates back to the early 2000, namely CanooULC.
-IMO Naked Objects together with the RO API and kroViz resembles something similar.
-
-
-# Toolchain
-When you are accustomed to the well settled Java ecosystem with integrated development environments, prepare yourself for learning new tools and addressing new problems.
-
-Kotlin is straightforward and once you now it, you may not want to go back.
-
-![Preview](../images/dev-mindmap.png)
-
-# Setup the Back-end
-## Requirements
-* (Oracle) JDK 1.8_181 (or higher)
-* Apache Maven 3.6.0
 
+# Troubleshooting
 
-## Create a Sample Backend 
-Create from the Apache Isis SimpleApp archetype:
-```bash
-mvn archetype:generate \
-    -D archetypeGroupId=org.apache.isis.archetype \
-    -D archetypeArtifactId=simpleapp-archetype \
-    -D archetypeVersion=2.0.0-M2 \
-    -D groupId=org.my \ 
-    -D artifactId=myapp-2.0.0-M2 \ 
-    -D version=1.0.0 -B
-```
-Build via
-```bash
-mvn clean install -DskipTests
-```
+## CORS
+CORS stands for 'Cross Origin Resource Sharing' aka: 'Same Origin Policy' was designed to improve security and is implemented in browsers.
+In short it means: your browser will allow loading of resources only if host and port are identical to the url you are on.
+Ie. webpage loaded from http://localhost:8088/ resources from http://localhost:8080/restful will not be accessible.
 
-## Dealing with CORS
+### Solution 1 (Q&D):
+Disable CORS in your browser, eg. for Chrome with the MOESIF plugin.
 
 Nicely done introduction: 
 * https://www.moesif.com/blog/technical/cors/Authoritative-Guide-to-CORS-Cross-Origin-Resource-Sharing-for-REST-APIs/#how-is-origin-definedhttps://www.moesif.com/blog/technical/cors/Authoritative-Guide-to-CORS-Cross-Origin-Resource-Sharing-for-REST-APIs/#how-is-origin-defined
 
-### Amend web.xml 
-
+### Solution 2: 
 Add to webapp\src\main\webapp\WEB-INF\web.xml
 
 ```xml
@@ -109,124 +145,98 @@ Add to webapp\src\main\webapp\WEB-INF\web.xml
 	</filter-mapping>
 ```
 
-### Put into webapp/src/main/webapp/WEB-INF/lib
+Put into webapp/src/main/webapp/WEB-INF/lib:
 * https://search.maven.org/artifact/org.eclipse.jetty/jetty-util/9.4.12.v20180830/jar
 * https://search.maven.org/artifact/org.eclipse.jetty/jetty-servlets/9.4.12.v20180830/jar
 
-## Start the Backend
-```bash
-cd webapp
-mvn -Djetty.port=8080 jetty:run -DPROTOTYPING
-```
-
-# Build the Front-end
-## Build
-Build is done via gradle - under Windows with gitbash:
-
-* ./gradlew.bat tasks # list all gradle tasks
-* ./gradlew.bat webpack-bundle # create main.bundle.js
-* ./gradlew.bat test --exclude-task npm-install
-
-Internally gradle uses npm for the JS part.
-
- npm --verbose 
-
- If task npm-install hangs, try
-
- ./gradlew.bat npm-install --info --debug --stacktrace
-
-
-Helps in identifying thing that may go wrong (eg. due to proxy settings).
-
-
-
-## Setup
-proxy settings:
-https://jjasonclark.com/how-to-setup-node-behind-web-proxy/
-https://gist.github.com/EudesSilva/0329645b9c258e0495544b8a5ccd1454
-
-
-
-# Toolchain
-* node js (https://nodejs.org/en/download/current/)
-* Apache Gradle 
-* Google Chrome (72.0.3626.81)
-* Moesif CORS Plugin (for Chrome)
-
-Kotlin/JS uses `Gradle` for the build, for the JS runtime `NodeJS`, and for the JS dependency management part `npm`.
+### Solution 3:
+Incorporate kroviz.js eg. in the WAR containing your Apache Isis backend. 
 
+## Network Proxy
 Depending on the network you are in, you may need to configure the proxy settings. Among the relevant files are:
-```bash
-~/.npmrc
-~/.gitconfig
-~/.ssh/config
-~/.ssh/id_rsa
-```
-### Access to git from npm
-#### Problem
-```bash
-npm ERR! Error while executing:
-npm ERR! C:\Program Files\Git\bin\git.EXE ls-remote -h -t ssh://[email protected]/jarecsni/font-awesome-webpack.git
-npm ERR!
-npm ERR! [email protected]: Permission denied (publickey).
-npm ERR! fatal: Could not read from remote repository.
-npm ERR!
-npm ERR! Please make sure you have the correct access rights
-npm ERR! and the repository exists.
-npm ERR!
-npm ERR! exited with error code: 128
-```
-#### Solution
-`~/.ssh/config`
-```bash
-ProxyCommand /bin/connect.exe -H proxy.server.name:3128 %h %p
-
-Host github.com
-  User git
-  Port 22
-  Hostname github.com
-  IdentityFile "C:\users\username\.ssh\id_rsa"
-  TCPKeepAlive yes
-  IdentitiesOnly yes
-
-Host ssh.github.com
-  User git
-  Port 443
-  Hostname ssh.github.com
-  IdentityFile "C:\users\username\.ssh\id_rsa"
-  TCPKeepAlive yes
-  IdentitiesOnly yes
-```
-
-### Corporate Firewall with SSL 'inspection'
+   ```bash
+   ~/.npmrc
+   ~/.gitconfig
+   ~/.ssh/config
+   ~/.ssh/id_rsa
+   ```
+### References
+   * https://jjasonclark.com/how-to-setup-node-behind-web-proxy/
+   * https://gist.github.com/EudesSilva/0329645b9c258e0495544b8a5ccd1454
+
+## Corporate Firewall with SSL 'inspection'
 There are some questionable setups in coporate settings that are based on SSL replacement.
 In order to cope with it, you may try to import the Certificate into cacerts, 
 see https://intellij-support.jetbrains.com/hc/en-us/community/posts/115000094584-IDEA-Ultimate-2016-3-4-throwing-unable-to-find-valid-certification-path-to-requested-target-when-trying-to-refresh-gradle
 
-### Karma-Tests do not respond to code changes 
+## Access to git from npm
+### Problem
+   ```bash
+   npm ERR! Error while executing:
+   npm ERR! C:\Program Files\Git\bin\git.EXE ls-remote -h -t ssh://[email protected]/jarecsni/font-awesome-webpack.git
+   npm ERR!
+   npm ERR! [email protected]: Permission denied (publickey).
+   npm ERR! fatal: Could not read from remote repository.
+   npm ERR!
+   npm ERR! Please make sure you have the correct access rights
+   npm ERR! and the repository exists.
+   npm ERR!
+   npm ERR! exited with error code: 128
+   ```
+ ### Solution
+   `~/.ssh/config`
+   ```bash
+   ProxyCommand /bin/connect.exe -H proxy.server.name:3128 %h %p
+
+   Host github.com
+     User git
+     Port 22
+     Hostname github.com
+     IdentityFile "C:\users\username\.ssh\id_rsa"
+     TCPKeepAlive yes
+     IdentitiesOnly yes
+
+   Host ssh.github.com
+     User git
+     Port 443
+     Hostname ssh.github.com
+     IdentityFile "C:\users\username\.ssh\id_rsa"
+     TCPKeepAlive yes
+     IdentitiesOnly yes
+   ```
+ 
+ ### Karma-Tests do not respond to code changes 
+  Windows:
+ ```
+ taskkill /f /im node.exe 
+ ```
+  Linux:
+ ```
+ killall node 
+ ```
+
+# Misc
+## HowTo
+When you are accustomed to the well settled Java ecosystem with integrated development environments, prepare yourself for learning new tools and addressing new problems.
 
-Windows:
-```
-taskkill /f /im node.exe 
-```
+Kotlin is straightforward and once you now it, you may not want to go back.
 
-Linux:
-```
-killall node 
-```
+![Preview](./dev-mindmap.png)
 
-### Visualize JS dependencies
 
+## Visualize JS dependencies
 ```
 npm -g install dependo
 dependo -f amd ./build/js/kroviz.js > dependo.html
 ```
 
-### Measure Test Coverage
-
+## Measure Test Coverage
 ```
 nyc npm test
 
 ```
 #### References
 https://github.com/istanbuljs/nyc
+
+## Gradle Build Overview
+![Preview](./build-overview.png)

docs/build-overview.adoc

@@ -0,0 +1,36 @@
+.Build Overview Diagram
+[plantuml,file="build-overview.png"]
+--
+@startuml
+component gradle <<build.tool>> 
+
+component kotlin2js <<transpiler>> as K2JS
+component kotlinFrontend <<gradle.plugin>> as KF
+component npm
+
+package build {
+    rectangle karma.conf.js <<file>> as KC
+}
+
+rectangle package.json <<file>>
+
+package projectDir {
+    rectangle gradle.properties <<file>>
+    rectangle settings.gradle <<file>>
+    rectangle build.gradle <<file>> as BG
+}
+
+component DCE
+component webpack 
+
+gradle -> BG 
+gradle -> gradle.properties
+gradle -> settings.gradle
+
+gradle -> K2JS 
+BG->KF : uses 
+KF->KC : in order to generate 
+
+@enduml
+--
+