Add readme file explaining the code organization in //blimp/client.

blimp/client/README.md

Index: blimp/client/README.md
diff --git a/blimp/client/README.md b/blimp/client/README.md
new file mode 100644
index 0000000000000000000000000000000000000000..2f9108eaa4445f8efe328cea2fe29f9796578d54
--- /dev/null
+++ b/blimp/client/README.md
@@ -0,0 +1,175 @@
+# Blimp Client
+
+This document contains documentation for the blimp client code organization.
+
+For a quick guide for how to add Java files to an existing directory, see
+[Adding Java files](#adding-java-files) below.
+
+[TOC]
+
+## Code Organization
+
+The blimp client has two main directories to be used for code, `core` and
+`public`. Embedders should only ever have to deal with the `public` directory.
+
+There are sub-directories resembling the ones in `core` for parts that needs to
+be exposed to embedders, such as `BlimpContents`.
+
+All Java-code is put in the `public/android` directory, with a package
+organization that resembles the one in `core`.
+
+Within `//blimp/client`, the `visibility` feature of GN is heavily used to
+ensure that embedders and dependencies are correctly set up. Currently, the
+`app` directory is not fully extracted out as an embedder, so it does sometime
+depend directly on code in `core`, but that should change when the migration to
+`core` is finished.
+
+### The core directory
+
+The `core` directory is to be used for all business logic code, and is an
+internal concept of the client code.
+
+There are sub-directories for logically separate parts, such as `contents` for
+code that relate to the contents of a web page. All Android code is put into
+their respective directories, so Android and Java-code related to `contents`
+is put in `contents/android`.
+
+Each of the sub-directories have their own `BUILD.gn` file, which includes
+targets for both C++ and Java.
+
+*   `//blimp/client/core/`
+    *   `android/` All Android-related code, including Java-code, that are for
+        the code living directly in `//blimp/client/core`.
+    *   `compositor/` Code related to the Chrome Compositor.
+    *   `contents/` Code related to the contents of a web page.
+    *   `contents/android/` JNI bridges and Java-code for `contents`.
+    *   `session/` Code related to the session with the engine.
+
+Most code in `core` do not need any Java counterparts unless the embedder is
+written for Android and it is typically only needed for things that relate to
+the embedder UI.
+
+#### Actual and dummy implementations of core
+
+The `core` directory has two implementations of the public API, a dummy one
+and a real one. The default is to use the dummy API, but an embedder can choose
+to enable full blimp support by setting the GN arguments `enable_blimp_client`
+to `true`.
+
+Basically only the implementation of BlimpClientContext has been split out into
+two parts (both in C++ and Java), and the choice of which backing implementation
+to be used is selected by the `enable_blimp_client` flag.
+
+### The public directory
+
+The `public` directory represents the public API of the blimp client, to be
+used by the embedders.
+
+Embedders should be able to depend on `//blimp/client/public` for C++ code,
+and for Java they should depend on `//blimp/client/public:public_java`. This
+automatically pulls in the dependencies on the code in `core`.
+
+*   `//blimp/client/public/`
+    *   `android/` All Android-related code, including Java-code. This includes
+        also code from all the sub-directories such as `contents`.
+    *   `contents/` Code from `//blimp/client/core/contents/` that needs to be
+        exposed to embedders.
+    *   `session/` Code from `//blimp/client/core/session/` that needs to be
+        exposed to embedders.
+
+### Other directories
+
+#### The app directory
+
+The `app` directory represents the directory that contains embedder code for
+a Blimp application on its own. Under a transition period, this directory
+also contains code that depends directly on `core`, until everything can be
+updated to depend only on `public`.
+
+#### The feature directory
+
+The `feature` directory is from the old directory organization, and all the
+content of this will move over to the `core` directory. The feature-specific
+code will move together with the usage of the feature itself, such as
+`core/contents`.
+
+#### The session directory
+
+The `session` directory is from the old directory organization, and all the
+content of this will move over to the `core/session` directory.
+
+#### The test directory
+
+The `test` directory contains tools helpful for testing client code.
+
+### Adding Java files {#adding-java-files}
+
+Most of Blimp is written in C++, but some parts have to be written in Java for
+the Android platform. For those parts of the code, it is required to add an
+`android` sub-directory, and put JNI-bridges and Java files within there.
+
+This will mostly happen in a sub-directory of `core`, so the following section
+explains how to add a Java file with JNI hooks for the imaginary sub-directory `//blimp/client/core/foo`. Conceptually, it's adding a Java-version of the C++
+class `Foo`, that lives in `//blimp/client/core/foo/foo.[cc|h]`.
+
+*   The file Foo.java should be added at:
+    `//blimp/client/core/foo/android/java/src/org/chromium/blimp/core/foo/Foo.java`
+
+*   The JNI-bridge should live in:
+    `//blimp/client/core/foo/android/foo_android.[cc|h]`
+
+*   Add the JNI-bridge JNI registration to:
+     `//blimp/client/core/android/blimp_jni_registrar.cc`
+
+*   Add this to the top of `//blimp/client/core/foo/BUILD.gn`:
+
+    ```python
+    if (is_android) {
+      import("//build/config/android/config.gni")
+      import("//build/config/android/rules.gni")
+    }
+    ```
+
+*   Add the following targets to `//blimp/client/core/foo/BUILD.gn`:
+
+    ```python
+    android_library("foo_java") {
+      visibility = [ "//blimp/client/*" ]
+
+      java_files = [
+        "android/java/src/org/chromium/blimp/core/foo/Foo.java",
+      ]
+
+      deps = [
+        ...
+      ]
+    }
+
+    generate_jni("jni_headers") {
+      visibility = [ ":*" ]
+
+      sources = [
+        "android/java/src/org/chromium/blimp/core/foo/Foo.java",
+      ]
+
+      jni_package = "blimp/client/core/contents"
+    }
+    ```
+
+*   Edit the target `//blimp/client/core/foo:foo` to add this Android-part:
+
+    ```python
+    source_set("foo") {
+
+      ...
+
+      if (is_android) {
+       sources += [
+         "android/foo.cc",
+         "android/foo.h",
+       ]
+
+       deps += [ ":jni_headers" ]
+      }
+    }
+    ```