diff --git a/Readme.md b/Readme.md
index 53c1ce3bd53308886eb9408c6faa074964c43fc5..aa43a861211d2b7e60c8427eda861f0b200de87f 100644
--- a/Readme.md
+++ b/Readme.md
@@ -1,15 +1,113 @@
-**Maven build configuration for local and jenkins builds**
-
-***Structure***
-
-* bundles
-  Holds the sources to compile the product. Each repository added here as a git
-  submodule (see .gitmodules) must contain a generic pom.xml file to enable
-  pomless builds. Please see https://git.fortiss.org/af3/af3.git for an example
-  of such a pom file.
-* docker
-  Contains the build specification for the docker container used in the CI Jobs.
-  Build & Update instructions:
+#Repository Structure
+
+the repository is structured as follows
+
+    <code class="text">
+    bundles  --- contains any standard eclipse plugin and the emf code generator.
+    features --- contains any tooling kernel or af3 feature definition (set of plugins).
+    products --- contains product descriptions (set of features): produces the resulting zips.
+    releng   --- common build configuration and p2 update sites.
+    tests    --- junit integration or module tests of the application, or single fragments respectively.
+    
+* **bundles**
+
+the bundle folder is composed of the following repositories:
+
+    <code class="text">
+    af3           --- git submodule of the af3 plugins.
+    af3-rcp       --- git submodule containing the org.fortiss.af3.rcapplication plugin.
+    emf-generator --- contains the emf code generator and its launch configuration.
+    kernel        --- git submodule of the tooling kernel plugins.
+    
+two maven pom files are found in this folder:
+
+    <code class="text">
+    pom.xml               --- specifies the to-be-compiled eclipse plugins activated by the given build flags.
+    pom-bundle-parent.xml --- compilation-specific configuration: currently, it only adds the required openjfx libraries to the tycho classpath.
+    
+the pom.xml file is the entry point for the compilation, whereas the
+pom-bundle-parent.xml is included from bundle repos (such as af3).
+
+note that all plugins are build pom-less: this means that no pom.xml
+config file is needed within standard eclipse plugins. it is only
+required at the level above. therefore, a maven extension is specified
+within the “.mvn” folder within the root of the maven-releng repository.
+
+* **docker**
+
+Contains the build specification for the docker container used in the CI Jobs.
+
+* **features**
+
+contains the tooling kernel and af3 feature as git submodules. each of
+these features contains the full set of plugins as of now. however they
+might be regrouped acc. to functionality groups in future.
+
+* **products**
+
+contains the af3 phoenix product as git submodule.
+
+* **releng**
+
+contains the following modules:
+
+    <code class="text">
+    org.fortiss.af3.configuration --- Common configuration of all maven modules such as maven plugin versions and configuration. Moreover, commonly used variables are specified here.
+    org.fortiss.af3.target        --- Target definition file that specifies all available plugins of the compilation and runtime platform. The definition of p2 sites is only allowed here. (There is only one exception in the product)
+    org.fortiss.af3.update        --- Contains the configuration to produce the AF3 p2 update site.
+    org.fortiss.tooling.update    --- Contains the configuration to produce the Tooling kernel update site.
+    
+* **Tests**
+
+Contains a git submodule containing the AF3 JUnit tests.
+  
+#Updating references of submodules
+
+To update references to AF3 in order to build a new release 
+ * execute `git submodule update --remote` in root maven-releng and
+ * commit and push changes
+
+#Build flags
+
+The build itself is controlled by environment variables passed by
+invoked maven commands. These variables activate build profiles in the
+maven configuration.  
+The following build flags are configured:
+
+    
+```text">
+    build.emf     --- activates the emf code generation. required when setting "build.af3" or "build.kernel".
+    build.af3     --- activates the compilation of af3 plugins.
+    build.tooling --- activates the compilation of tooling kernel plugins.
+    build.tests   --- runs the junit integration tests on the resulting product.
+    
+```
+
+  
+the build flags are used for a modular build configuration. for
+instance, another project could only depend on the tooling and implement
+a product that is totally different from af3.  
+the flag “build.tooling” just produces a p2 update site that can be
+reused by subsequent builds. this update site is ignored if the flag is
+specified. thus, the combination of “build.af3” and “build.tooling” will
+not use the tooling update site.  
+an equivalent mechanism is implemented for “build.tests” that
+additionally uses an af3 p2 update site.
+
+*notes*
+
+ - we use the maven phase “verify” for building, not “package”, which
+    is the default. we are forced to use this phase, since we must
+    perform post-package product patching (no other phase qualifies).
+    this is also the reason to introduce the “build.tests” flag to skip
+    the testing phases that are located between the “packaging” and
+    “verify” phases.
+ - the flag “build.emf” is required to avoid triggering the code
+    generation multiple times.  
+  
+  
+#Updating the Docker build container
+
   * Clone the repository.
   * Navigate to the cloned directory in a UNIX shell and apply the following
     commands.
@@ -17,21 +115,10 @@
   * `docker build -t git.fortiss.org:5001/af3/maven-releng docker/`
   * Delete the outdated 'af3/maven-releng' container
   * `docker push -t git.fortiss.org:5001/af3/maven-releng`
-* features
-  Holds the feature descriptions that compose a product. Each source bundle must
-  be listed here.
-* products
-  Contains the product descriptions by they are built, such as AF3.
-* releng
-  Contains common configuration shared by all plugins, update site configs, and
 
-***Updating references***
 
-To update references to AF3 in order to build a new release 
- * execute `git submodule update --remote` in root maven-releng and
- * commit and push changes
 
-***Debugging Build Failures***
+#Debugging Build Failures
 
 Whenever a CI job fails, it may be caused by a problematic source code change, a
 bug in the maven-releng configuration, the docker image, or related to the