diff --git a/docs/Guide.Architecture.md b/docs/Guide.Architecture.md
new file mode 100644
index 0000000000..54868930e8
--- /dev/null
+++ b/docs/Guide.Architecture.md
@@ -0,0 +1,17 @@
+# Architecture Deep Dive
+The sequence diagram below shows the general communication scheme between the components in Detox.
+![architecture overview](img/action-sequence.mmd.png)
+
+To understand this topic more thoroughly we need to have a look at an example action in detail. The numbers in the listing 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`*
diff --git a/docs/Guide.Contributing.md b/docs/Guide.Contributing.md
index 7ca7d46c99..df2852e4aa 100644
--- a/docs/Guide.Contributing.md
+++ b/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)**
diff --git a/docs/img-src/action-sequence.mmd b/docs/img-src/action-sequence.mmd
new file mode 100644
index 0000000000..4e431daf0b
--- /dev/null
+++ b/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)
diff --git a/docs/img-src/build.sh b/docs/img-src/build.sh
new file mode 100755
index 0000000000..15bec021d6
--- /dev/null
+++ b/docs/img-src/build.sh
@@ -0,0 +1,3 @@
+#!/bin/sh
+
+mermaid -o '../img' *.mmd
diff --git a/docs/img/action-sequence.mmd.png b/docs/img/action-sequence.mmd.png
new file mode 100644
index 0000000000..449451753b
Binary files /dev/null and b/docs/img/action-sequence.mmd.png differ