docs: architecture deep dive

docs/Guide.Architecture.md

@@ -0,0 +1,17 @@
+# Architecture Deep Dive
+To illustrate this, please see the sequence diagram below. It shows the general communication scheme between the software components.
+![architecture overview](img/action-sequence.mmd.png)
+
+To understand this topic more thoroughly we need to have a look at different actions / assertions directly in the code. The numbers in the listings below corelate with the ones in the diagram.
+
+### Action (`element.tap`)
+
+1. `element.tap()` in your test case is invoked.
+2. `TapAction` in [`expect.js`](https://github.com/wix/detox/blob/master/detox/src/ios/expect.js) gets invoked
+3.  `TapAction` instance gets passed to [`invoke.js`](https://github.com/wix/detox/blob/master/detox/src/invoke.js), where it gets transformed to JSON. The resulting JSON corelates more with the native code than with the JS code for better extensibility.
+4. JSON gets send to detox-server by [`Client.js`](https://github.com/wix/detox/blob/master/detox/src/client/Client.js)
+6. detox-server forwards it to the testee in [`DetoxServer.js`](https://github.com/wix/detox/blob/master/detox-server/src/DetoxServer.js)
+7. [`DetoxManager.m`](https://github.com/wix/detox/blob/master/detox/ios/Detox/DetoxManager.m) invokes the [`TestRunner.m`](https://github.com/wix/detox/blob/master/detox/ios/Detox/TestRunner.m). `TestRunner.m` uses [`MethodInvocation.m`](https://github.com/wix/detox/blob/master/detox/ios/Detox/MethodInvocation.m) to map the JSON representation of the native commands into the actual native command and executes it. *(8)*
+
+
+*NOTE: the images can be updated with [mermaid](http://knsv.github.io/mermaid/#mermaid). The files can be found under `img-src`*

docs/Guide.Contributing.md

@@ -1,6 +1,5 @@
 # Contributing to detox
 
-
 ### Clone detox and submodules
 
 ```sh
@@ -26,7 +25,7 @@ npm install -g react-native-cli
 
 For all the internal projects (detox, detox-server, detox-cli, demos, test) `lerna` will create symbolic links in `node_modules` instead of `npm` copying the content of the projects. This way, any change you do on any code is there immediately. There is no need to update node modules or copy files between projects.
 
-### Install `fbsimctl` 
+### Install `fbsimctl`
 
 ```sh
 brew tap facebook/fb
@@ -58,7 +57,7 @@ lerna run test
 
 Detox JS code is 100% test covered and is set to break the build if coverage gets below, so make sure you run unit tests (`lerna run test`) locally before pushing.
 
-Alternatively, to run only the JS tests, run the following from the `detox/detox` directory: 
+Alternatively, to run only the JS tests, run the following from the `detox/detox` directory:
 
 ```sh
 npm run unit
@@ -94,4 +93,8 @@ To run the e2e tests, after the application was built.
 npm run e2e
 ```
 
+### Architecture
+
+For more details on how Detox works under the hood, please see [our Architecture Guide](Guide.Architecture.md)
+
 **NOTE: The updated flow can always be found in [our CI build script](../scripts/ci.sh)**

docs/img-src/action-sequence.mmd

@@ -0,0 +1,19 @@
+sequenceDiagram
+  participant Test Runner(1)
+  participant Detox(3)
+  participant Detox Server(5)
+  participant Detox Client(7)
+  participant Earl Grey(9)
+
+  %% Note over Test Runner(1),Detox Server(5): Runs on your computer
+  %% Note over Detox Client(7),Earl Grey(9): Runs on the device
+
+  Test Runner(1)->>Detox(3): assertion / action (2)
+  Detox(3)->>Detox Server(5): native code as JSON (4)
+  Detox Server(5)->>Detox Client(7): Websocket connection (6)
+  Detox Client(7)-x+Earl Grey(9): native invocation (8)
+  Note left of Earl Grey(9): EarlGrey waits for device to become idle again
+  Earl Grey(9)->>-Detox Client(7): (10)
+  Detox Client(7)->>Detox Server(5): (11)
+  Detox Server(5)->>Detox(3): (12)
+  Detox(3)->>Test Runner(1): (13)

docs/img-src/build.sh

@@ -0,0 +1,3 @@
+#!/bin/sh
+
+mermaid -o '../img' *.mmd